Prime Agent sessions are persistent workspaces that can be resumed, forked, or navigated as a tree of branches — controlled via CLI flags at startup (-c, -r, --fork) or commands within a session (/tree, /fork, /clone). The daemon maintains only active sessions in memory; saved sessions load on-demand, and the CLI provides status, attachment, and management commands (agents, attach, status, doctor, shutdown) for controlling the background service. A session tree is the branching history of a Prime Agent session; each /fork, /clone, or resume-from-an-earlier-point creates a new branch, letting users explore alternative paths while preserving all prior work.
Prime Agent sessions can be managed from the CLI: -c continues the most recent session, -r [path|id] browses or resumes past sessions, --no-session runs in ephemeral mode (no save), and --fork <path|id> forks a specific session into a new one.[1] As of v0.2.4, the daemon no longer auto-restores on-disk sessions on startup; sessions return only via /resume or --resume, and the agents view lists only sessions the daemon is actively holding.[2] The --resume CLI flag is implemented in main.ts with routing logic also in interactive-mode.ts; the /resume slash command is implemented in command-registry.ts and slash-commands.ts. Both paths are covered by regression tests. The agents view (agents-view-state.ts) orders sessions by most-recent message timestamp, so the most recently active session surfaces at the top of the list automatically. The interactive agents view (interactive-mode.ts) displays the hint text "type to search sessions" when no session is selected, guiding users to filter existing sessions via the input field rather than create new ones. Empty sessions (those that have never received a prompt) report an accurate idle status rather than being misclassified; this behavior is implemented in daemon-session-list.ts and daemon-supervisor.ts. The daemon supervisor evicts empty sessions (those that have never received a prompt) from memory when the client detaches, freeing roster slots; eviction logic lives in daemon-supervisor.ts. Subagent token usage and cost roll up to the parent session view; new agent capabilities should report usage through src/core/usage.ts to ensure costs appear in the agents view. Usage data is aggregated in src/core/usage.ts, propagated through src/core/context-tree.ts and src/core/compaction/, and persisted via daemon-protocol.ts, daemon-session-list.ts, daemon-supervisor.ts, rlm-ledger.ts, and saved-session-info.ts so that cost data survives session restarts. The agents view (agents-view-state.ts, agents-view-mode.ts) displays per-session token counts and accumulated cost on each agent row. The agent roster (agent-roster.ts) exposes a descendant-busy count so that the TUI (agents-view-state.ts, agents-view-mode.ts) and daemon-protocol consumers share a consistent busy status across all session-tree levels, including multi-level RLM hierarchies.
Prime Agent CLI reference: key subcommands for managing sessions and background services.
prime-agent agents # Browse running, idle, and saved sessions
prime-agent attach <agent> # Reattach to a running session
prime-agent --resume <path|id> # Resume a saved session
prime-agent status # Inspect background service state
prime-agent doctor [--fix] # Inspect or repair background services
prime-agent update [--force] # Update Prime Agent
prime-agent shutdown [--force] # Stop every agent, worker, and background service
The /tree command lets users navigate the session tree in-place, select any previous point, continue from there, and switch between branches — all history preserved in a single session file. Pressing Escape twice also opens /tree (see TUI and interactive use for keyboard shortcut details).[1] /fork creates a new session file from a previous user message on the active branch; /clone duplicates the current active branch into a new session file at the current position.[1] Added in v0.2.9, /btw and /side support one-turn inline side questions that use the current context without changing the main session.[4]
The /traces command supports sub-commands status, on, off, preview, upload-current, upload-all, and login; upload is an alias for upload-current.[1]
Sources