Reticle Docs: verification for AI coding agents

reticle kill frees the bridge port. It asks who is listening on the port and signals that one process, which is the whole difference between this command and the shell pipeline everybody reaches for.

npx reticle kill [--port N] [--force]

Never free the port with lsof -ti tcp:4400 | xargs kill -9. reticle mcp holds a client socket on that port, so -ti lists the proxy right beside the daemon and the pipeline kills both. When the proxy dies, the agent’s next tool calls get no reply at all — not an error, not a timeout — and nothing is written to the proxy log, because the process that writes it is the one that died. That is the mechanism behind most “my MCP disconnected” reports.

Flags

Flag	Type	Default	What it does
`--port N`	number	`4400` (or `RETICLE_PORT`, or the port in `.reticle.json`)	Which port to free
`--force`	boolean	`false`	Kill the listener even when it is not a Reticle daemon

kill or stop?

They target different things, and the distinction matters exactly when you are stuck.

	`reticle stop`	`reticle kill`
Finds the process by	the pid recorded in Reticle’s own state	the listener on the port
Works when the pid file is stale or was never written	no	yes
Works on a daemon from another checkout	no	yes
Works without `lsof` (Windows, slim containers)	yes	yes, falling back to the recorded pid and saying so

Reach for stop in a script that shuts down a daemon it started. Reach for kill when the port is held and you want it back.

How it decides

Look up the listener with lsof -nP -iTCP:<port> -sTCP:LISTEN. Client sockets are excluded by construction, so the proxy is never a candidate.
It is Reticle’s if it answers /status, or if it is the pid Reticle recorded for the port. /status outranks the pid file, so a daemon started from another checkout is still recognised as ours.
Anything else is refused, by name, unless --force.
SIGTERM, then SIGKILL after 5 seconds, then report that it survived and exit 1.

What it prints

Real captures. Killed:

{"event":"reticle_killed","port":4499,"pid":84420,"escalated":true,"listenerIdentified":true,"note":"only the listener was signalled. Any `reticle mcp` proxy on this port holds a client connection, not the port, and was left alone — it goes dormant and starts a fresh daemon on the next tool call."}

Refused, because the listener is not ours:

{"event":"reticle_kill_refused","port":4498,"reason":"pid 84346 (\"Python\") is listening, and it is not a Reticle daemon — it never answered /status and it is not the pid Reticle recorded. Killing it would be killing someone else's process. Run it again with --force if that is what you meant, or start Reticle on another port.","holder":"Python"}

Nothing to free:

{"event":"reticle_kill_nothing_to_do","port":4499,"presence":"free"}

Event	When
`reticle_killed`	The listener is gone. `escalated: true` means it took a `SIGKILL`; `forced: true` means `--force` overrode a refusal
`reticle_kill_refused`	The listener is not a Reticle daemon and `--force` was not given. Exits `1`
`reticle_kill_survived`	It survived `SIGKILL`. The port is still held. Exits `1`
`reticle_kill_nothing_to_do`	No listener, and no live recorded pid

listenerIdentified: false means lsof could not run and the pid came from Reticle’s records rather than from an observed listener. Those are different claims, so the field says which one you got.

Exit codes

Code	Meaning
`0`	The port is free
`1`	The port is still held: refused, or the process survived `SIGKILL`

Worked example

npx reticle kill            # free 4400
npx reticle status          # confirm

Tools

Beyond the loop

CLI commands

Packages

Grammar

Long form

reticle kill

Flags

kill or stop?

How it decides

What it prints

Exit codes

Worked example

​Flags

​kill or stop?

​How it decides

​What it prints

​Exit codes

​Worked example

Flags

kill or stop?

How it decides

What it prints

Exit codes

Worked example