packages coding agent cli

CLI

Active contributors: Mario Zechner, kt, Seth Karten

Purpose

The prime-agent command is the user-facing entry point for the coding agent. It parses the command line, decides which run mode to start (interactive terminal UI, single-shot print, JSON lines, RPC, ACP, or the headless daemon), dispatches administrative commands (agents, attach, status, doctor, update, shutdown, web, schedule, send, and others), and either drives the session runtime in-process or connects to a background daemon. All of this lives under packages/coding-agent/src/cli/ plus two entry files (src/cli.ts, src/cli-main.ts) and the mode dispatcher packages/coding-agent/src/main.ts.

Directory layout

packages/coding-agent/src/cli.ts                      # Node version guard + shebang entry
packages/coding-agent/src/cli-main.ts                 # runCli(): startup, early daemon kick, owned-worker frontend
packages/coding-agent/src/main.ts                     # parse args, resolve app mode, run the selected mode
packages/coding-agent/src/cli/
  args.ts                      # Argument parsing (parseArgs) and Mode type
  command-registry.ts          # COMMAND_SPECS, top-level help, command suggestions
  config-selector.ts           # TUI selector for the `config` command
  daemon-command.ts            # Internal `daemon <subcommand>` client plus the attach REPL
  daemon-launch.ts             # Cold daemon spawn, version probe, stale-daemon takeover
  daemon-list-format.ts        # Session table formatting for `list`
  daemon-ps-format.ts          # Daemon table formatting for `status` / `doctor`
  daemon-ps.ts                 # Daemon discovery (ss/lsof), status, reap, shutdown-all
  daemon-stop-confirm.ts       # Shared busy-session confirmation before stopping a daemon
  daemon-update-restart.ts     # Self-update coordinator: drain, stop, restore sessions
  file-processor.ts            # @file argument handling (text + images)
  initial-message.ts           # Combines stdin, @file text, and first message
  list-models.ts               # `model list` output
  node-version-check.ts        # Dependency-free Node >= 22.8 guard
  owned-session-worker.ts      # Isolated worker child for print/json/rpc/ephemeral runs
  public-command.ts            # Public command dispatch (agents, attach, status, web, ...)
  session-resolver.ts          # Re-export of core/session-resolver.js
  subprocess-launch.ts         # Launch specs and env for CLI-spawned children
  web-command.ts               # Launches the packaged web frontend

The mode implementations live under packages/coding-agent/src/modes/ and are selected by main.ts: interactive/ (terminal UI), daemon/ (headless service), rpc/ (JSON over stdio), acp/ (agent client protocol), agents-view/ (session browser), print-mode.ts (single shot), session-worker/ (private framing for worker channels), and agent-connection/ (the AgentConnection seam all clients share).

Key abstractions

Type	Path	One-line description
`Args`, `Mode`	`packages/coding-agent/src/cli/args.ts`	Parsed command-line shape and the `text \| json \| rpc \| acp \| daemon` output mode union
`CommandSpec`, `COMMAND_SPECS`	`packages/coding-agent/src/cli/command-registry.ts`	Declarative command table that drives help, completion, and unknown-command suggestions
`PublicCommandResult`	`packages/coding-agent/src/cli/public-command.ts`	Result of public command dispatch; `handled` when the CLI should stop
`handleDaemonCommand`	`packages/coding-agent/src/cli/daemon-command.ts`	Internal `daemon <subcommand>` client over `DaemonClient`, plus `DaemonAttachTerminal` (the plain attach REPL)
`ensureInteractiveDaemonRunning`	`packages/coding-agent/src/cli/daemon-launch.ts`	Memoized per-socket spawn/probe of a current-version daemon
`discoverDaemons`, `runPs`, `runReap`, `runShutdownAll`	`packages/coding-agent/src/cli/daemon-ps.ts`	Machine-wide daemon discovery and the status/doctor/shutdown actions
`runWebCommand`	`packages/coding-agent/src/cli/web-command.ts`	Spawns `dist/web/launcher.mjs` for the packaged Qredence web UI
`runOwnedSessionWorkerFrontend`	`packages/coding-agent/src/cli/owned-session-worker.ts`	Runs print/json/rpc/ephemeral work in an isolated child with recovery
`processFileArguments`	`packages/coding-agent/src/cli/file-processor.ts`	Expands `@file` arguments into text and image attachments
`assertNodeVersion`	`packages/coding-agent/src/cli/node-version-check.ts`	Pre-import guard rejecting Node older than 22.8
`DaemonUpdateRestartCoordinator`	`packages/coding-agent/src/cli/daemon-update-restart.ts`	File-backed coordinator that drains, stops, and restores the daemon after `update`

How it works

packages/coding-agent/src/cli.ts runs a dependency-free Node version guard first (the ESM module graph fails at link time on old Node), then dynamically imports cli-main.ts. runCli() in packages/coding-agent/src/cli-main.ts enables the compile cache, sets PI_CODING_AGENT=true, installs the owned-session-worker owner watch, and hands off. main.ts then resolves the app mode and either dispatches a public command or builds a session.

graph TD
    A[cli.ts shebang entry] --> B[assertNodeVersion guard]
    B --> C[cli-main.ts runCli]
    C --> D{owned session worker?}
    D -->|yes| E[runOwnedSessionWorkerFrontend]
    D -->|no| F[maybeStartDaemonEarly]
    F --> G[main.ts]
    G --> H[handlePublicCommand]
    H -->|handled command| Z[exit]
    H -->|not handled| I[parseArgs + resolveAppMode]
    I --> J{appMode}
    J -->|daemon| K[runDaemonSupervisorMode or runDaemonMode]
    J -->|rpc| L[runRpcModeWithConnection]
    J -->|acp| M[runAcpModeWithConnection]
    J -->|json or print| N[runPrintModeWithConnection]
    J -->|interactive| O{use daemon client?}
    O -->|yes| P[DaemonAgentConnection attach or create]
    O -->|no| Q[InProcessAgentConnection]
    P --> R[InteractiveMode]
    Q --> R

Mode selection (resolveAppMode in packages/coding-agent/src/main.ts):

--mode daemon starts the headless service itself: runDaemonSupervisorMode when run normally, runDaemonMode with a worker authentication token when spawned as a per-session worker.
--mode rpc and --mode acp run the JSON-RPC and agent-client-protocol transports over stdio.
--mode json and --print / non-TTY stdin run single-shot print mode (runPrintMode), which prints text or a JSON event stream and exits.
The default (TTY, no mode flag) is interactive. Interactive and the headless modes run against the daemon whenever shouldUseDaemonClientRuntime passes (not in --mode daemon, not under a startup benchmark, not with --list-models, not in an owned worker, and not when the process injected local extension factories); otherwise they use an in-process runtime with InProcessAgentConnection. A cold daemon is spawned concurrently with heavy imports by maybeStartDaemonEarly in packages/coding-agent/src/cli/daemon-launch.ts.

Command dispatch (handlePublicCommand in packages/coding-agent/src/cli/public-command.ts) recognizes the commands below, and also rewrites a few old forms: --export/--list-models now route through session export and model list (they are kept only as internal markers prefixed by INTERNAL_RUNTIME_COMMAND_MARKER), and attach is rewritten into --resume <agent>. prime-agent agents is not consumed here: it returns explicitAgentsView so main.ts opens the agents view (runAgentsViewMode). list, stop, rename, send, and schedule delegate to the internal daemon client in packages/coding-agent/src/cli/daemon-command.ts.

Main CLI commands

From COMMAND_SPECS in packages/coding-agent/src/cli/command-registry.ts and packages/coding-agent/docs/usage.md:

Command	What it does
`prime-agent [options] [@files...] [message...]`	Interactive chat by default; see modes above
`agents`	Open the unified agents view (running, idle, and saved sessions)
`list [--all] [--json]`	List agents against the daemon
`attach <agent>`	Attach the interactive UI to a running agent
`stop <agent> [--json]`	Stop one agent
`rename <agent> <name> [--json]`	Rename an agent
`send [--from <agent>] <agent> <message>`	Send a message to another agent; `--steer` / `--follow-up` choose delivery
`schedule <list\|add\|cancel>`	Manage cron-style and one-time prompts
`status [--json]`	Show background service state (machine-wide daemon discovery)
`doctor [--fix] [--json]`	Inspect and safely clean up background services
`shutdown [--force] [--json]`	Stop every agent and background service
`web [--host <host>] [--port <port>] [--cwd <dir>]`	Run the packaged Qredence web frontend
`package <install\|remove\|list\|update>`	Manage capability packages (extensions, skills, prompts, themes)
`update [--force]`	Update Prime Agent itself
`model list [search]`	List available models
`session export <file> [output]`	Export a saved session to HTML
`config`	Configure package resources (TUI)

Removed and rejected with a hint: app, daemon, install, manage, remove, uninstall (REMOVED_COMMAND_NAMES).

Environment variables

packages/coding-agent/src/cli/args.ts itself reads no environment; the CLI-relevant variables are consumed in packages/coding-agent/src/config.ts and documented in packages/coding-agent/docs/usage.md:

Variable	Description
`PRIME_AGENT_CODING_AGENT_DIR`	Override config dir (default `~/.prime/agent`)
`PRIME_AGENT_SESSION_DIR`	Override session storage dir; `--session-dir` wins
`PRIME_AGENT_CODING_AGENT_SESSION_DIR`	Legacy alias for the session dir
`PI_PACKAGE_DIR`	Override package dir (Nix/Guix store paths)
`PI_OFFLINE`	Disable startup network operations, including update checks
`PI_SKIP_VERSION_CHECK`	Skip the version update check and release manifest request
`PRIME_AGENT_DOWNLOAD_BASE_URL`	Release manifest and tarball base URL for self-update
`PRIME_AGENT_KERNEL_PYTHON`	Use an existing Python env with `ipykernel` for the kernel runtime
`VISUAL`, `EDITOR`	External editor used by the interactive editor's Ctrl+G
`PRIME_AGENT_WORKSPACE_ROOT`	Workspace dir for the `web` command when `--cwd` is absent

The CLI also sets and consumes internal PRIME_AGENT_INTERNAL_* variables that mark owned workers, daemon roles, and recovery journals; these are implementation details and are stripped from child daemon environments in packages/coding-agent/src/cli/subprocess-launch.ts and packages/coding-agent/src/cli/daemon-update-restart.ts.

Integration points

All non-interactive session work and the agents view talk to the daemon through DaemonClient (packages/coding-agent/src/modes/daemon/daemon-client.ts) and DaemonAgentConnection (packages/coding-agent/src/modes/agent-connection/daemon-agent-connection.ts); the daemon wire contract is versioned in packages/coding-agent/src/modes/daemon/daemon-protocol.ts.
Interactive mode reuses the same InteractiveMode class whether its connection is in-process or daemon-backed; main.ts picks the AgentConnection implementation.
The web command launches the built runtime at packages/coding-agent/dist/web/launcher.mjs; the source dev command is the pnpm workspace under web/ (see overview/architecture.md).
prime-agent update funnels through the package manager CLI and the daemon update-restart coordinator so live sessions survive a daemon replacement.

Entry points for modification

Add a new top-level command: extend COMMAND_SPECS in packages/coding-agent/src/cli/command-registry.ts and add a dispatch arm in packages/coding-agent/src/cli/public-command.ts; if it needs daemon access, add a case to handleDaemonCommand in packages/coding-agent/src/cli/daemon-command.ts and a matching DaemonCommand union member in packages/coding-agent/src/modes/daemon/daemon-protocol.ts with a compatibility entry.
Add a CLI flag: parseArgs in packages/coding-agent/src/cli/args.ts, the top-level help groups in command-registry.ts, and the AgentSessionRuntimeConfig mapping in packages/coding-agent/src/main.ts (runtimeConfigFromArgs).
Change the mode selection rules: resolveAppMode, shouldUseDaemonClientRuntime, and resolveAppMode callers in packages/coding-agent/src/main.ts, plus the early-launch exclusion sets in packages/coding-agent/src/cli/daemon-launch.ts.

Key source files

File	Why it matters
`packages/coding-agent/src/cli.ts`	Shebang entry and Node version guard
`packages/coding-agent/src/cli-main.ts`	Process setup, early daemon kick, owned-worker frontend handoff
`packages/coding-agent/src/main.ts`	Mode resolution and session creation for every mode
`packages/coding-agent/src/cli/args.ts`	Full argument grammar and diagnostics
`packages/coding-agent/src/cli/public-command.ts`	Public command dispatch and rewriting
`packages/coding-agent/src/cli/daemon-command.ts`	Internal daemon client commands and attach REPL
`packages/coding-agent/src/cli/daemon-launch.ts`	Cold daemon spawn, probe, and stale takeover
`packages/coding-agent/src/cli/daemon-ps.ts`	Machine-wide daemon discovery, status, reap, shutdown
`packages/coding-agent/src/cli/web-command.ts`	Packaged web frontend launcher
`packages/coding-agent/src/cli/owned-session-worker.ts`	Isolated worker child execution with recovery

Related pages

Daemon : the background service these commands drive
Interactive mode : the terminal chat UI
Package overview : SDK surface and package layout
Session runtime : AgentSession lifecycle and compaction
Architecture : how the CLI, daemon, and web fit together
Daemon protocol : the wire contract in detail

Prime Agent overview

By the numbers

Lore

Fun facts

How to contribute

Packages

Agent core
AI
- Models
- Providers
Coding agent
- Session runtime
- Agent tools
- CLI
- Daemon
- Interactive mode
- Skills
- Extensions
- Refinement
- RLM runtime
Python runtime
TUI
Web app
Web design
Web protocol
Web server

Design decisions

Cleanup opportunities

Reference

Maintainers

Uh oh!

packages coding agent cli

CLI

Purpose

Directory layout

Key abstractions

How it works

Main CLI commands

Environment variables

Integration points

Entry points for modification

Key source files

Related pages

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally