Local daemon lifecycle
Let stateful commands manage the daemon automatically, and use lifecycle commands only for observation or recovery.
You do not install, configure, or manage the daemon. A stateful command such as search, sync, get, or source add verifies the exact local runtime, starts it when absent, and uses typed local RPC. The daemon keeps the registry and SQLite ownership in one process, streams long-running work such as sync, and exits after five idle minutes. It is not a system service and does not start at login.
ctxindex command -> ensure exact daemon -> local RPC -> result
└-> idle for five minutes -> exitThe five minutes count from the moment the last running command finishes. While any command is in flight, including a long sync, the daemon stays up however long it takes. ctxindex daemon status does not count as activity, so polling it never keeps an otherwise idle daemon alive. After an idle exit, the next stateful command starts the daemon again; a command that races with the shutdown waits for it and retries the start once.
Observe or stop it
ctxindex daemon status
ctxindex daemon stopUse status to inspect readiness, process identity, protocol version, and active request count. Use stop before diagnosing a stuck local runtime or when you explicitly want no background process; the next normal stateful command starts it again.
Start it explicitly only when useful
ctxindex daemon startExplicit start is useful for smoke tests and lifecycle diagnosis. It is not an installation step and there is no foreground serve mode to keep running in another terminal.
Once a command selects the daemon, it never falls back to opening the same database directly. A startup, protocol, or shutdown failure is reported with a stable exit instead of creating competing owners.
Commands that stay client-side
init, docs get-skill, and the extension catalog commands never start the daemon. extension install, update, and uninstall stop a running daemon, change installed Extension records while holding the database, and start the daemon again so it loads the new registry. Before init, describe and extension list read bundled definitions without creating state.
Supported platforms
The daemon runs on macOS and Linux. Other platforms, including Windows, are not supported for it: daemon status prints unsupported, daemon start fails with exit 50, and stateful commands open the local database directly because no daemon can own it there.
For malformed config or startup diagnostics, see Troubleshooting. For the process boundary, see Architecture.