Start and Stop an Agent

Start

Default startup runs the agent in the background:

city agent start

If you do not pass a path and the current directory is not already an initialized agent project, the CLI may prompt you to select one from registered agents.

The decision rule is:

1. explicit path wins
2. if the current directory is already initialized, use it
3. otherwise prompt interactively if possible

Foreground mode

If you want to watch runtime behavior in the current terminal:

city agent start --foreground

Foreground mode is for debugging, not long-running production usage.

When background startup fails but the cause is unclear, foreground mode is often the fastest way to see the actual error.

Check status

city agent status

Common states:

• running
• stopped
• stale
• not initialized

Understanding these states is more useful than repeatedly running start.

Stop

city agent stop

This stops the target project's daemon and cleans up the corresponding state files.

If the target is already stopped, the command remains idempotent.

Restart

city agent restart

Restart is usually the safest move after changing:

• model binding
• channel configuration
• prompts
• environment variables

Some of those values are loaded during startup, so editing files alone does not automatically refresh the running process.

Good habits

• prefer restart after config changes
• check status before guessing
• if you see stale, use doctor --fix

A safe daily sequence

For most runtime changes, this is a stable pattern:

city agent status
city agent restart
city agent status

Next:

• Chat with an Agent
• First troubleshooting steps