Skip to content

CLI Reference

The recon CLI is the operator interface. It is not agent-facing — agents interact via MCP tools.

Server Lifecycle

recon up

Start the global multi-repo daemon (foreground).

recon up [OPTIONS]
Option Default Description
--port, -p 7654 Port to bind to
--stdio off Start in stdio mode (child process of SDK). Mutually exclusive with --port.
--home ~/.coderecon Override CodeRecon home directory. Also configurable via $CODERECON_HOME.
--dev-mode off Enable development tools (recon_raw_signals endpoint)

The daemon activates all repos already in the catalog on startup. Press Ctrl+C to stop.

recon down

Stop the running daemon.

recon down [PATH]

PATH is accepted but ignored — the daemon is global, not per-repo.

recon restart

Restart the daemon (stop + start with same config).

recon restart [OPTIONS]
Option Default Description
--port, -p — Server port
--dev-mode off Enable development tools

recon status

Show daemon status and per-repo index health.

recon status [PATH] [OPTIONS]
Option Default Description
PATH current dir Repository path (auto-detected by walking up to find git root)
--json off Output as JSON for machine consumption

Repository Management

recon register

Register a repository in the global catalog. Builds the index if needed and activates the repo immediately if the daemon is running.

recon register [PATH] [OPTIONS]
Option Default Description
PATH current dir Repository path
--reindex, -r off Wipe and rebuild the index from scratch
--mcp-target, -t auto AI tool(s) to write MCP config for. Repeatable.

--mcp-target choices:

Value Effect
auto Detect installed tools automatically (default)
all Write config for every supported tool
vscode VS Code / GitHub Copilot (.vscode/mcp.json)
claude Claude Code (.mcp.json)
cursor Cursor (.cursor/mcp.json)
opencode OpenCode (~/.config/opencode/config.json)

Examples:

# Current directory, auto-detect tools
recon register

# Specific path, both VS Code and Claude Code
recon register ~/projects/myapp --mcp-target vscode --mcp-target claude

# Force rebuild
recon register --reindex

# Write for every supported tool
recon register --mcp-target all

recon unregister

Remove a repository from the catalog and deactivate its live daemon slot.

recon unregister [PATH]

If the daemon is running, deactivation happens immediately without a restart.

recon catalog

List all registered repositories and their worktrees.

recon catalog

Example output:

  myapp
    git:        /home/dave/projects/myapp/.git
    storage:    /home/dave/projects/myapp/.recon
    worktrees:  main* feature-auth

  backend
    git:        /home/dave/projects/backend/.git
    storage:    /home/dave/projects/backend/.recon
    worktrees:  main*

recon worktrees

List worktrees for a repository.

recon worktrees [NAME]

NAME is the repository name (as shown in recon catalog). If omitted, auto-detects from the current directory.

recon register-worktree

Register a specific git worktree that was added after the main repo was registered.

recon register-worktree [PATH]

PATH must be a linked worktree directory (created by git worktree add). The parent repo must already be registered with recon register. If the daemon is running, the worktree is activated immediately.

recon global-status

Show daemon health summary across all registered repos.

recon global-status

Displays PID, port, catalog/health endpoints, and lists all active repos with their MCP endpoints.

Per-Repo Utilities

recon clear

Remove CodeRecon artifacts from a repository (.recon/ directory and any XDG index directory). Does not touch your source code.

recon clear [PATH] [OPTIONS]
Option Default Description
PATH current dir Repository path
--yes, -y off Skip confirmation prompt

Warning

This deletes the index, config, and all stored artifacts. recon register can rebuild everything.

recon init (internal)

Low-level repo initialization. Use recon register instead. init is hidden from help output.

recon init [PATH] [--reindex] [--port PORT] [--mcp-target TARGET]

Global Flags

Flag Description
--version Show installed version
-v, --verbose Enable DEBUG logging