arch-monorepo
As a contributor, I want separable UI, model, loop, host, and Python-runtime layers.
The workspace builds TUI, AI adapters, agent core, coding-agent host, and a Python runtime as distinct packages.
Evidence
arch-process
As a user, I want one broken session not to terminate every session.
A detached supervisor routes clients; each root tree has a worker; IPython runs separately; a catalog subprocess scans saved sessions.
Evidence
Caveats
- Process isolation is lifecycle/failure isolation, not a security sandbox.
arch-connection
As a client author, I want the same runtime behind TUI and headless clients.
Clients render and send commands through AgentConnection; daemon-backed and in-process implementations expose coherent snapshots/events.
Evidence
- AgentConnection · packages/coding-agent/src/modes/agent-connection/types.ts:47
- DaemonAgentConnection · packages/coding-agent/src/modes/agent-connection/daemon-agent-connection.ts:205
agent-loop
As a user, I want streamed model output and iterative tool use until the task turn settles.
The loop emits lifecycle/message/tool events, streams provider deltas, executes tool calls, then processes steering, follow-ups, and host continuations.
Evidence
- agentLoop · packages/agent/src/agent-loop.ts:181
- runLoop · packages/agent/src/agent-loop.ts:307
parallel-tools
As an extension/tool author, I want tools to declare safe execution ordering.
Tool batches execute in parallel by default, but a global sequential setting or any sequential tool forces ordered execution; results preserve source order.
Evidence
abort-retry
As a user, I want cancellation to stop active provider/tool work and transient failures to retry within policy.
Abort signals race provider/tool operations and produce aborted messages; the session has configurable exponential retry and retry events.
Evidence
ipython
As an agent, I want one programmable environment for files, shell commands, skills, and delegation.
The built-in tool lazily provisions a persistent IPython kernel, executes cells, captures stdout/results/errors/diffs/attachments, and retains namespace state.
Evidence
Caveats
- The kernel executes with the user account permissions.
kernel-snapshot
As a long-running user, I want Python variables and imports to survive session revival.
Persisted sessions can write dill/JSON kernel snapshots and restore them after worker/kernel restart.
Evidence
Caveats
- Exact artifact files exist only after the feature is used.
tui
As a terminal user, I want streaming chat, editor, overlays, menus, and status in one interface.
Interactive mode renders messages/tool calls, a multiline editor, selectors/overlays, image previews, notifications, and usage/context views.
Evidence
- InteractiveMode · packages/coding-agent/src/modes/interactive/interactive-mode.ts:815
- TUI · packages/tui/src/tui.ts:244
editor
As a user, I want file mentions, completion, multiline input, pasted/dragged images, shell shortcuts, and an external editor.
The editor supports @ file search, tab path completion, multiline keys, clipboard/drag images, !/!! shell execution, and $VISUAL/$EDITOR.
Evidence
- editor features · packages/coding-agent/docs/usage.md:20
- custom editor · packages/coding-agent/src/modes/interactive/components/custom-editor.ts:21
Caveats
- Terminal image/paste behavior varies by terminal and OS.
slash-commands
As a user, I want discoverable in-session controls for auth, models, sessions, long-running work, exports, and configuration.
Autocomplete exposes canonical commands plus aliases; session-owned commands are parsed separately for daemon execution.
Evidence
public-cli
As a shell user, I want commands to list, attach, stop, message, schedule, diagnose, update, and manage packages.
The public dispatcher validates and maps agents/list/attach/stop/rename/send/schedule/status/doctor/shutdown/package/update/model/session/config commands.
Evidence
modes
As an integrator, I want human and machine interfaces over the same session runtime.
The CLI selects interactive TUI, one-shot print, JSON event stream, Prime-specific RPC, or standard ACP JSON-RPC.
Evidence
- mode table · packages/coding-agent/docs/usage.md:187
- ACP mode · packages/coding-agent/docs/acp.md:6
Caveats
- ACP deliberately supports one session per connection.
typescript-sdk
As a TypeScript integrator, I want to create and control AgentSession directly without spawning a CLI process.
createAgentSession wires settings, authentication, model selection, tools, resources, extensions, persistence, MCP, and autonomous policy, then returns the session and extension load result.
Evidence
Caveats
- The in-process SDK shares the caller process and is not daemon process isolation.
message-queue
As a user, I want to redirect active work or queue later work without waiting.
Enter/steer injects after the current assistant tool batch; Alt+Enter/follow-up waits for the agent to become idle; delivery can be all or one-at-a-time.
Evidence
session-jsonl
As a user, I want conversations recoverable and inspectable on disk.
Sessions append flat JSONL under the configured session directory, record cwd and tree entries, and support ephemeral no-session mode.
Evidence
session-tree
As a user, I want to revisit prior turns without destroying history.
Users can navigate the session tree, summarize abandoned branches, fork before a user message, clone at the current position, import JSONL, or resume by path/ID.
Evidence
- switchSession · packages/coding-agent/src/core/agent-session-runtime.ts:426
- fork · packages/coding-agent/src/core/agent-session-runtime.ts:517
session-export
As a user, I want portable or shareable session records.
/export writes styled HTML or JSONL; /share uploads a secret GitHub gist; export sanitizes untrusted content.
Evidence
- HTML exporter · packages/coding-agent/src/core/export-html/index.ts:235
- share command · packages/coding-agent/src/core/slash-commands.ts:105
Caveats
- GitHub gist sharing requires GitHub authentication and creates an external copy.
side-questions
As a user, I want to ask a tangent without polluting the main session.
/btw and /side create inline side conversations whose messages are excluded from the persisted main conversation branch.
Evidence
usage-context
As a user, I want to understand cost and context pressure across parent and child work.
/context and /usage report model context, token/cost totals, and own-versus-attributed child usage.
Evidence
themes-keybindings
As a user, I want accessible appearance and remappable controls.
Built-in dark/light/Prime themes and project/global theme resources pair with configurable editor/app keybinding maps.
Evidence
rlm
As an agent, I want to delegate bounded context to independent child agents.
await rlm(prompt, name, model) returns an admission handle immediately; the host starts a child AgentSession and answers arrive through agent messages or files.
Evidence
Caveats
- Default max depth is 1; descendants cannot recurse unless raised.
rlm-registry
As a parent agent, I want to list, message, and delete retained children after compaction or restart.
The parent-scoped registry persists child identity/status, rehydrates completed daemon children, supports exact selector deletion, and leaves transcript artifacts on disk.
Evidence
Caveats
- Deletion tombstones/removes runtime addressing but does not erase artifacts.
a2a
As an agent or user, I want active family members to coordinate directly.
Messages target parent/child/sibling/family members, support auto/steer/follow_up delivery, and enforce size/rate/pending-queue safety limits.
Evidence
- message input · packages/coding-agent/src/core/agent-messages.ts:151
- rate limiter · packages/coding-agent/src/core/agent-messages.ts:463
observe
As an operator, I want to inspect another active root or child session without attaching as its owner.
Agent observation returns snapshots and streams wrapped observed-session events; closing the target emits a close signal.
Evidence
daemon-continuity
As a user, I want work to continue after closing the terminal and recover after supervisor/worker failure.
Resident workers outlive the TUI, supervisors adopt live workers, per-root crashes retry on a bounded schedule, and snapshots/replay resynchronize clients.
Evidence
leases-journal
As an operator, I want concurrent clients and reconnects not to duplicate writes or side effects.
Canonical-path leases prevent concurrent transcript writers; clientId+commandId journals return completed results but mark uncertain mutations instead of replaying them.
Evidence
compaction
As a long-running user, I want old context summarized before the model window overflows.
Manual, threshold, and overflow compaction summarize older history, preserve recent context and kernel state, emit lifecycle events, and can retry overflowed prompts.
Evidence
Caveats
- A successful summary is not a completion signal.
goals
As a user, I want an objective to remain active across turns with budget accounting.
/goal creates/edits/pauses/resumes/clears a durable objective; only goal.complete() marks success; tokens/time/continuations and optional budget are tracked.
Evidence
Caveats
- Goals are explicit user/host actions, not inferred from every prompt.
autonomous
As a user, I want unattended work to continue only within budgets and objective checks.
Autonomous mode injects continuations until all shell gates pass or continuation/turn/token/time limits stop it; unchanged failed workspaces are not rerun blindly.
Evidence
Caveats
- A limit stopping the loop does not imply success; a gate proves only what its command checks.
heartbeats
As a user or agent, I want periodic prompts to re-enter an existing session.
/heartbeat manages one user heartbeat; rlm_heartbeat manages multiple agent-owned jobs with independent labels/delivery modes; both persist per session.
Evidence
schedules
As an automation user, I want prompts delivered at a future time or cron cadence.
prime-agent schedule adds/lists/cancels jobs targeted at agents; due ticks are claimed before delivery and missed ticks coalesce.
Evidence
Caveats
- Claim-before-delivery avoids duplicate uncertain prompts but can skip an uncertain crash-boundary tick.
refine
As a user, I want evidence-backed lessons persisted without rewriting the base prompt.
/refine reviews a trajectory and applies small updates to supplemental prompts, memories, skill descriptions, or subagent specs; snapshots support rollback and optional global scope.
Evidence
Caveats
- It does not rewrite the immutable base system prompt or substitute for packaging executable skills.
settings
As a user, I want defaults globally and narrower overrides per project.
~/.prime/agent/settings.json is deep-merged with .prime/agent/settings.json; CLI/env settings have documented precedence for selected fields.
Evidence
- Settings · packages/coding-agent/src/core/settings-manager.ts:122
- SettingsManager · packages/coding-agent/src/core/settings-manager.ts:304
context-prompts
As a project owner, I want repository conventions injected predictably.
Prime Agent walks global/ancestor/cwd AGENTS.md or CLAUDE.md files; SYSTEM.md replaces and APPEND_SYSTEM.md extends the default prompt; CLI can disable or override.
Evidence
skills
As a user, I want reusable workflows loaded progressively and executable from IPython.
Agent Skills SKILL.md metadata is progressively disclosed; pyproject-backed skills install editable packages and expose importable/callable Python modules; /skill:name forces invocation.
Evidence
Caveats
- Skills are trusted instructions/code and run with user permissions.
builtin-skills
As a new user, I want key workflows available without installing separate packages.
Built-in skills ship at lowest precedence and can be disabled/overridden; Python-backed skills bridge host features and services.
Evidence
extensions
As a developer, I want custom tools, commands, UI, policies, providers, and lifecycle hooks.
jiti-loaded TypeScript factories register tools/commands/shortcuts/flags/providers, intercept lifecycle/model/tool/input events, render custom TUI, and persist entries.
Evidence
Caveats
- Extensions execute arbitrary trusted code with full user permissions.
packages
As a user, I want installable bundles of extensions, skills, prompts, and themes.
package install/remove/list/update resolves npm or git sources, persists global/project configuration, installs production dependencies, and loads declared resources.
Evidence
- package manager · packages/coding-agent/src/core/package-manager.ts:87
- package CLI · packages/coding-agent/src/package-manager-cli.ts:73
Caveats
- Installed packages are trusted code/instructions.
prompt-themes-resources
As a user, I want project-scoped reusable prompts and presentation assets.
ResourceLoader discovers package/global/project/explicit paths with precedence and exclusions; /reload refreshes keybindings, extensions, skills, prompts, themes, and context.
Evidence
mcp
As a user, I want Linear, Notion, and custom remote MCP services callable from IPython.
OAuth or bearer-authenticated HTTP MCP servers expose discovered tools as async Python methods through McpIntegration; built-ins enable by login.
Evidence
Caveats
- stdio MCP servers are not wired through this integration path; only remote HTTP is supported.
- Server tool names/schemas can change and should be discovered at runtime.
trace-sharing
As a researcher, I want to inspect and explicitly share current/all traces.
/traces controls opt-in sharing, previews sanitized trace payloads, and uploads with a Prime API key scoped for agent_traces.
Evidence
Caveats
- Trace sharing is distinct from default aggregate telemetry and requires explicit configuration/action.
providers
As a user, I want one agent over subscription, API-key, cloud, and OpenAI-compatible providers.
The AI package normalizes streaming text/thinking/tool calls/usage across built-in provider adapters and a generated model catalog.
Evidence
auth
As a user, I want login for subscriptions and secure local API-key fallback.
/login supports ChatGPT/Codex, Claude, Copilot, providers, and MCP; auth.json is mode 0600; key resolution is CLI, auth file, env, then models.json.
Evidence
Caveats
- External OAuth/provider policy and subscription billing remain provider-controlled.
models-config
As a self-hosting user, I want Ollama, LM Studio, vLLM, or custom endpoints.
models.json can define supported API-compatible providers/models; extensions can register custom implementations and OAuth flows; model resolution supports provider/id and thinking suffixes.
Evidence
thinking-model-scope
As a user, I want model-specific reasoning control and a curated cycle list.
/effort selects supported levels, /fast toggles OpenAI service tier, /scoped-models filters cycling, and unsupported levels are clamped.
Evidence
- effort command · packages/coding-agent/src/core/slash-commands.ts:90
- scoped models · packages/coding-agent/src/core/slash-commands.ts:92
images
As a user, I want to attach screenshots and send them only to compatible models.
File args, paste, and drag produce image content; images can resize/block; adapters route image tool results according to provider limits.
Evidence
Caveats
- Provider image limits and supported MIME types differ.
prime-env
As a researcher, I want to discover, scaffold, install, and publish verifiers environments.
The bundled prime-intellect skill documents prime env list/info/install/init/push and points to the official prime CLI.
Evidence
Caveats
- Implemented by the external prime CLI/service, not by the Prime Agent host itself.
prime-evals
As a researcher, I want small local smoke evals before hosted scale.
The bundled skill documents prime eval run with model/sample controls and --hosted --follow; ACP also supports evaluation harnesses.
Evidence
- eval commands · packages/coding-agent/skills/prime-intellect/SKILL.md:58
- ACP harness · packages/coding-agent/docs/acp.md:3
Caveats
- No first-party eval runner is implemented in this repository; the surface delegates to the external prime CLI/verifiers ecosystem.
prime-training
As a researcher, I want to launch hosted post-training or use self-managed RL.
The bundled skill documents prime lab setup, prime train model/capacity/config/run workflows, and identifies prime-rl as the power-user self-managed path.
Evidence
Caveats
- Training execution is external to this repository.
prime-sandbox-compute
As a user, I want optional external isolation and infrastructure around agent work.
The bundled skill routes to prime sandbox, inference, availability/pods, storage, and tunnel products.
Evidence
Caveats
- Prime Agent workers/kernels are not themselves sandboxes; external sandboxes must be chosen for untrusted work.
acp-eval
As an evaluator, I want standards-based prompting, streaming, cancellation, stop reasons, and Prime metadata.
ACP exposes initialize/session new/prompt/cancel/close, maps text/reasoning/tools, and places subagents/gates/goals/heartbeats/refinement metadata under a namespaced _meta key.
Evidence
Caveats
- One session per ACP connection; richer Prime-only operations remain in RPC.
trust
As an operator, I want clear boundaries before allowing autonomous code execution.
README/docs warn that model Python, shell commands, skills, and extensions run with user permissions; workers/kernels isolate lifecycle, not security.
Evidence
Caveats
- Use a disposable clone/checkpoint and an external restricted sandbox for untrusted code or instructions.
telemetry
As a privacy-conscious user, I want to know what is collected and disable it.
Default aggregate events include version/OS/mode/outcomes/performance/counts but exclude prompts, code, paths, commands, credentials, raw errors, and identity/hardware; settings/env/offline can disable.
Evidence
Caveats
- Enabled by default at inspected commit; project settings can only restrict a global setting.
installer-update
As a user, I want reproducible installation and updates without manually managing npm.
The published installer resolves channel/version, downloads release tarball and SHA256SUMS, verifies checksums, installs, and can prepare the kernel; update supports coordinated resident-worker checkpoints.
Evidence
Caveats
- Repository install.sh contains release placeholders; users should use the published URL or set the base URL.
ci
As a maintainer, I want formatting/type/build checks plus package, process, and kernel tests.
CI builds/checks on Node 22 and runs agent, AI, TUI, sharded coding-agent, daemon process, and kernel jobs; nightly process stress is separate.
Evidence
release
As a maintainer, I want all packages versioned together with stable and rolling beta artifacts.
Release scripts version packages in lockstep; workflow builds/checks/packs, uploads immutable tarballs/checksums to R2, advances manifests, and creates GitHub releases.
Evidence
benchmarks
As a maintainer, I want performance regressions measurable.
Scripts/tests benchmark daemon fanout/attach, startup, TUI rendering, tool statistics, and high-worker process stress.
Evidence
Caveats
- Benchmarks are not a product correctness/evaluation suite.