749 KiB
749 KiB
CLI Commands
!!! adr "Architecture Decision" The CLI command structure, output rendering, and interaction patterns are defined in ADR-021: CLI and Output Rendering.
Command Synopsis
agents|cleveragents [--data-dir <DATA_PATH>] [--config-path <CONFIG_PATH>] [--format (rich|color|table|plain|json|yaml)] [--help|-h] [--version] [--install-completion [<INST_SHELL>]] [--show-completion [<SHOW_SHELL>]] [-v...] <COMMAND> [<ARGS>...]agents version agents info agents diagnostics agents init [--yes|-y]
agents session create [--actor <ACTOR>] agents session list agents session show <SESSION_ID> agents session delete [--yes|-y] <SESSION_ID> agents session export [(--output|-o) <FILE>] <SESSION_ID> agents session import (--input|-i) <FILE> agents session tell --session <SESSION_ID> [--actor <ACTOR>] [--stream] <PROMPT>
agents project create [(--description|-d) <DESC>] [--resource <RESOURCE>]... [--invariant <INVARIANT>]... [--invariant-actor <ACTOR>] <NAME> agents project link-resource [--read-only] <PROJECT> <RESOURCE> agents project unlink-resource [--yes|-y] <PROJECT> <RESOURCE_NAME> agents project list [(--namespace|-n) NS] [<REGEX>] agents project show <PROJECT> agents project delete [--force|-f] [--yes|-y] <NAME> agents project context set[--view (strategize|execute|apply|default)] [--include-resource <INCLUDE_RESOURCE>]... [--exclude-resource <EXCLUDE_RESOURCE>]... [--include-path <INCLUDE_GLOB>]... [--exclude-path <EXCLUDE_GLOB>]... [--hot-max-tokens <N>] [--warm-max-decisions <N_WARM_MAX>] [--cold-max-decisions <N_COLD_MAX>] [--query-limit <N>] [--max-file-size <MAX_FILE_BYTES>] [--max-total-size <MAX_TOTAL_BYTES>] [--summarize|--no-summarize] [--summary-max-tokens <N>] [--strategy <STRATEGY>]... [--default-breadth <N>] [--default-depth <INT_OR_NAME>] [--depth-gradient <HOP:INT_OR_NAME>]... [--skeleton-ratio <FLOAT>] [--temporal-scope (current|recent|all)] [--auto-refresh|--no-auto-refresh] [--execution-environment <RESOURCE_NAME>] [--execution-env-priority (fallback|override)] [--clear] <PROJECT> agents project context show [--view (strategize|execute|apply|default)] <PROJECT> agents project context inspect [--view (strategize|execute|apply|default)] [--strategy <STRATEGY>] [--focus <UKO_URI>]... [--breadth <N>] [--depth <INT_OR_NAME>] <PROJECT> agents project context simulate [--view (strategize|execute|apply|default)] [--budget <TOKENS>] [--focus <UKO_URI>]... [--strategy <STRATEGY>]... <PROJECT>
agents validation add --config|-c <FILE> [--update] agents validation attach [--project <PROJECT>|--plan <PLAN_ID>] <RESOURCE> <VALIDATION> [<ARGS>...] agents validation detach [--yes|-y] <ATTACHMENT_ID>
agents actor run [(--output|-o) <OUTPUT_FILE>] [-v...] [--unsafe|-u] [--context <CONTEXT_NAME>] [--context-dir <CONTEXT_PATH>] [--load-context <LOAD_CONTEXT_NAME>] [(--temperature|-t) <TEMP>] [--allow-rxpy-in-run-mode] [--skill <SKILL>]... <NAME> <PROMPT> agents actor add --config|-c <FILE> [--update] agents actor remove <NAME> agents actor list agents actor show <NAME> agents actor context remove [--yes|-y] (--all|-a|<NAME>) agents actor context list [<REGEX>] agents actor context show <NAME> agents actor context export (--output|-o) <FILE> <NAME> agents actor context import [--update] (--input|-i) <FILE> [<NAME>] agents actor context clear [--yes|-y] (--all|-a|<NAME>)
agents skill add --config|-c <FILE> [--update] agents skill remove [--yes|-y] <NAME> agents skill list [(--namespace|-n) <NS>] [--source <SOURCE>] agents skill show <NAME> agents skill tools <NAME>
agents tool add --config|-c <FILE> [--update] agents tool remove [--yes|-y] <NAME> agents tool list [(--namespace|-n) <NS>] [--source <SOURCE>] [--type (tool|validation)] [<REGEX>] agents tool show <NAME>
agents lsp add --config|-c <FILE> [--update] agents lsp remove [--yes|-y] <NAME> agents lsp list [(--namespace|-n) <NS>] [--language <LANG>] agents lsp show <NAME> agents lsp serve [--log-level <LEVEL>]
agents resource type add --config|-c <FILE> [--update] agents resource type remove [--yes|-y] <NAME> agents resource type list [<REGEX>] agents resource type show <NAME>
agents resource add [(--description|-d) <DESC>] [--update] <TYPE> <NAME> [type-specific-flags...] agents resource remove [--yes|-y] <NAME> agents resource list [--all] [(--type|-t) <TYPE>] agents resource show <RESOURCE> agents resource inspect [--tree] [--file <PATH>] <RESOURCE> agents resource tree [(--depth|-d) <N>] [(--type|-t) <TYPE>] <RESOURCE> agents resource link-child <PARENT> <CHILD> agents resource unlink-child [--yes|-y] <PARENT> <CHILD> agents resource stop <NAME> agents resource rebuild <NAME>
agents plan list [--phase <PHASE>] [--state <STATE>] [--project <PROJECT>] [--action <ACTION>] [<REGEX>] agents plan use [--automation-profile <PROFILE>] [--invariant <INVARIANT>]... [--strategy-actor <STRATEGY_ACTOR>] [--execution-actor <EXEC_ACTOR>] [--estimation-actor <EST_ACTOR>] [--invariant-actor <INV_ACTOR>] [--execution-environment <RESOURCE_NAME>] [--execution-env-priority (fallback|override)] [--arg/-a name=value]... <ACTION> <PROJECT>... agents plan execute <PLAN_ID> agents plan apply [--yes|-y] <PLAN_ID> agents plan status <PLAN_ID> agents plan cancel [(--reason|-r) <REASON>] <PLAN_ID> agents plan tree [--show-superseded] <PLAN_ID> agents plan explain [--show-context] [--show-reasoning] <DECISION_ID> agents plan correct --mode (revert|append) (--guidance|-g) <GUIDANCE> [--dry-run] [--yes|-y] <DECISION_ID> agents plan diff (--correction <CORRECTION_ATTEMPT_ID>|<PLAN_ID>) agents plan artifacts <PLAN_ID> agents plan prompt <PLAN_ID> <GUIDANCE> agents plan rollback [--yes|-y] <PLAN_ID> <CHECKPOINT_ID>
agents action create --config|-c <CFG_FILE> agents action list [(--namespace|-n) <NS>] [(--state|-s) <STATE>] [<REGEX>] agents action show <ACTION_NAME> agents action archive <ACTION_NAME>
agents automation-profile add --config|-c <FILE> [--update] agents automation-profile remove [--yes|-y] <NAME> agents automation-profile list [<REGEX>] agents automation-profile show <NAME>
agents config set <key> <value> agents config get <key> agents config list [--filter-values <REGEX>] [<REGEX>]
agents invariant add [--global] [(--project|-p) PROJECT] [--plan PLAN_ID]... [--action ACTION]... <INVARIANT_TEXT> agents invariant list [--global] [(--project|-p) PROJECT] [--plan PLAN_ID] [--action ACTION] [--effective] [<REGEX>] agents invariant remove [--yes|-y] <INVARIANT_ID>
Command Reference
!!! info "Output Format Tabs"
Each command example below is shown in multiple output formats using content tabs. Select a tab to see how the same command renders in that format. The table format is visually identical to rich in static documentation (the difference is live animation). The color format has the same layout as plain but with ANSI color codes applied to headers, keys, and values. See Output Rendering Framework for full format specifications.
Global Options
!!! note "Purpose"
Configure global state locations and shell integration for every command.
Arguments
-
--data-dir PATH: Overrides the global data directory (database, caches, sessions, logs). When omitted, the default data location is used. -
--config-path PATH: Overrides the global configuration file path. When omitted, the default config path is used. -
--format rich|color|table|plain|json|yaml: Set the output rendering format for all subcommands. When omitted, the value is read from the global config keycore.format. If not set in config either, defaults torich. See Output Rendering Framework for full details on each format.??? tip "Available Output Formats"
| Format | Description | Best For | | :----- | :---------- | :------- | | `rich` | Modern rich CLI elements with dynamic effects, animated spinners, progress bars, and generous color | Interactive terminal use **(default)** | | `color` | Plain scrolling text with ANSI color codes | Terminals that support color but not advanced rendering | | `table` | ASCII box-drawing characters to create structured tables and panels with color | Structured visual output similar to examples in this document | | `plain` | Plain text with no color codes or non-ASCII characters | Piping into files, logs, or non-terminal consumers | | `json` | Structured JSON output for programmatic consumption | Scripts, CI/CD pipelines, programmatic consumption | | `yaml` | Structured YAML output for programmatic consumption | Configuration, programmatic consumption | -
--help,-h: Print help for the current command. -
--version: Print the version and exit. -
--install-completion [SHELL]: Install shell completion for the given shell. -
--show-completion [SHELL]: Show the completion script for the given shell. -
-v: Increase log verbosity for a single invocation (repeatable). By default (no-v), only normal command output is shown on stdout; logging output is suppressed except on fatal errors where the application exits entirely and displays the error. Each additional-vraises the verbosity one level:-v= ERROR (non-fatal, recoverable errors),-vv= WARN (warnings that may indicate a degraded system but are not necessarily errors),-vvv= INFO (routine informative messages useful to common users),-vvvv= DEBUG (coarse debugging output),-vvvvv= TRACE (the most granular logging level available). Increased verbosity writes to both the log file and stderr by default, keeping log output separate from normal program output on stdout. The destination for log output raised by-vis configurable: it can be sent to the terminal (stderr by default, or redirected to another stream such as stdin or a device), to the log file only, or to both. Seecore.log.terminal,core.log.terminal-stream, andcore.log.file-enabledconfiguration keys for details. This flag does not persist — it only affects the current invocation.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> <span style="color: cyan;">--data-dir</span> /srv/cleveragents <span style="color: cyan;">--config-path</span> /srv/cleveragents/config.toml info
╭─ System Snapshot ─────────────────╮
│ <span style="color: cyan; font-weight: 600;">CleverAgents</span> 1.0.0 │
│ <span style="color: #5599ff; font-weight: 600;">Mode:</span> local │
│ <span style="color: magenta; font-weight: 600;">Automation:</span> review │
│ <span style="color: #66cc66; font-weight: 600;">Status:</span> ready │
╰───────────────────────────────────╯
╭─ Paths ───────────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Data Dir:</span> /srv/cleveragents │
│ <span style="color: #5599ff; font-weight: 600;">Config:</span> /srv/cleveragents/config.toml │
│ <span style="color: #5599ff; font-weight: 600;">Logs:</span> /srv/cleveragents/logs │
│ <span style="color: #5599ff; font-weight: 600;">Cache:</span> /srv/cleveragents/cache │
│ <span style="color: #5599ff; font-weight: 600;">Database:</span> /srv/cleveragents/agents.db │
╰───────────────────────────────────────╯
╭─ Runtime ──────────╮
│ <span style="color: yellow; font-weight: 600;">PID:</span> 4127 │
│ <span style="color: #66cc66; font-weight: 600;">Uptime:</span> 00:14:32 │
│ <span style="color: #5599ff; font-weight: 600;">Python:</span> 3.13.1 │
│ <span style="color: #5599ff; font-weight: 600;">Host:</span> devbox.local │
│ <span style="color: #5599ff; font-weight: 600;">Platform:</span> linux │
╰────────────────────╯
╭─ Projects & Sessions ─╮
│ <span style="color: #5599ff; font-weight: 600;">Projects:</span> 2 │
│ <span style="color: #5599ff; font-weight: 600;">Sessions:</span> 1 active │
│ <span style="color: #5599ff; font-weight: 600;">Active Plans:</span> 0 │
│ <span style="color: #5599ff; font-weight: 600;">Actors:</span> 3 │
╰───────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Environment loaded
</code></pre></div>
=== "Plain"
```
$ agents --data-dir /srv/cleveragents --config-path /srv/cleveragents/config.toml info
System Snapshot
CleverAgents 1.0.0
Mode: local
Automation: review
Status: ready
Paths
Data Dir: /srv/cleveragents
Config: /srv/cleveragents/config.toml
Logs: /srv/cleveragents/logs
Cache: /srv/cleveragents/cache
Database: /srv/cleveragents/agents.db
Runtime
PID: 4127
Uptime: 00:14:32
Python: 3.13.1
Host: devbox.local
Platform: linux
Projects & Sessions
Projects: 2
Sessions: 1 active
Active Plans: 0
Actors: 3
[OK] Environment loaded
```
=== "JSON"
```json
{
"command": "info",
"status": "ok",
"exit_code": 0,
"data": {
"system_snapshot": {
"name": "CleverAgents",
"version": "1.0.0",
"mode": "local",
"automation": "review",
"status": "ready"
},
"paths": {
"data_dir": "/srv/cleveragents",
"config": "/srv/cleveragents/config.toml",
"logs": "/srv/cleveragents/logs",
"cache": "/srv/cleveragents/cache",
"database": "/srv/cleveragents/agents.db"
},
"runtime": {
"pid": 4127,
"uptime": "00:14:32",
"python": "3.13.1",
"host": "devbox.local",
"platform": "linux"
},
"projects_and_sessions": {
"projects": 2,
"sessions": "1 active",
"active_plans": 0,
"actors": 3
}
},
"timing": {
"duration_ms": 12
},
"messages": [
{ "level": "ok", "text": "Environment loaded" }
]
}
```
=== "YAML"
```yaml
command: info
status: ok
exit_code: 0
data:
system_snapshot:
name: CleverAgents
version: "1.0.0"
mode: local
automation: review
status: ready
paths:
data_dir: /srv/cleveragents
config: /srv/cleveragents/config.toml
logs: /srv/cleveragents/logs
cache: /srv/cleveragents/cache
database: /srv/cleveragents/agents.db
runtime:
pid: 4127
uptime: "00:14:32"
python: "3.13.1"
host: devbox.local
platform: linux
projects_and_sessions:
projects: 2
sessions: 1 active
active_plans: 0
actors: 3
timing:
duration_ms: 12
messages:
- level: ok
text: Environment loaded
```
agents version
agents versionPurpose Print the current CLI version.
Arguments
None.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> version
╭─ CLI Version ────╮
│ <span style="color: cyan; font-weight: 600;">CleverAgents CLI</span> │
│ <span style="color: #5599ff; font-weight: 600;">Version:</span> 1.0.0 │
│ <span style="color: #5599ff; font-weight: 600;">Channel:</span> stable │
│ <span style="color: #5599ff; font-weight: 600;">Python:</span> 3.13 │
╰──────────────────╯
╭─ Build ────────────────╮
│ <span style="color: #66cc66; font-weight: 600;">Build Date:</span> 2026-02-08 │
│ <span style="color: magenta; font-weight: 600;">Commit:</span> a17c3f9 │
│ <span style="color: #5599ff; font-weight: 600;">Schema:</span> v3 │
│ <span style="color: #5599ff; font-weight: 600;">Platform:</span> linux-x86_64 │
╰────────────────────────╯
╭─ Dependencies ─────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">LangGraph:</span> 0.2.60 │
│ <span style="color: #5599ff; font-weight: 600;">LangChain:</span> 0.3.18 │
│ <span style="color: #5599ff; font-weight: 600;">MCP SDK:</span> 1.4.0 │
│ <span style="color: #5599ff; font-weight: 600;">Pydantic:</span> 2.10.4 │
╰────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Version reported
</code></pre></div>
=== "Plain"
```
$ agents version
CLI Version
CleverAgents CLI
Version: 1.0.0
Channel: stable
Python: 3.13
Build
Build Date: 2026-02-08
Commit: a17c3f9
Schema: v3
Platform: linux-x86_64
Dependencies
LangGraph: 0.2.60
LangChain: 0.3.18
MCP SDK: 1.4.0
Pydantic: 2.10.4
[OK] Version reported
```
=== "JSON"
```json
{
"command": "version",
"status": "ok",
"exit_code": 0,
"data": {
"cli": {
"name": "CleverAgents CLI",
"version": "1.0.0",
"channel": "stable",
"python": "3.13"
},
"build": {
"build_date": "2026-02-08",
"commit": "a17c3f9",
"schema": "v3",
"platform": "linux-x86_64"
},
"dependencies": {
"langgraph": "0.2.60",
"langchain": "0.3.18",
"mcp_sdk": "1.4.0",
"pydantic": "2.10.4"
}
},
"timing": {
"duration_ms": 8
},
"messages": [
{ "level": "ok", "text": "Version reported" }
]
}
```
=== "YAML"
```yaml
command: version
status: ok
exit_code: 0
data:
cli:
name: CleverAgents CLI
version: "1.0.0"
channel: stable
python: "3.13"
build:
build_date: "2026-02-08"
commit: a17c3f9
schema: v3
platform: linux-x86_64
dependencies:
langgraph: "0.2.60"
langchain: "0.3.18"
mcp_sdk: "1.4.0"
pydantic: "2.10.4"
timing:
duration_ms: 8
messages:
- level: ok
text: Version reported
```
agents info
agents infoPurpose Show configuration and runtime information useful for debugging or support.
Arguments
None.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> info
╭─ Environment ───────────────────────────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Data Dir:</span> /home/alex/.cleveragents │
│ <span style="color: #5599ff; font-weight: 600;">Config:</span> /home/alex/.cleveragents/config.toml │
│ <span style="color: #66cc66; font-weight: 600;">Database:</span> sqlite:///home/alex/.cleveragents/cleveragents.db │
│ <span style="color: yellow; font-weight: 600;">Server Mode:</span> disabled │
│ <span style="color: #5599ff; font-weight: 600;">Platform:</span> Linux 6.8.0 (x86_64) │
╰─────────────────────────────────────────────────────────────╯
╭─ Runtime ─────────────────────────╮
│ <span style="color: magenta; font-weight: 600;">Automation:</span> review │
│ <span style="color: #5599ff; font-weight: 600;">Providers:</span> 3 configured │
│ <span style="color: yellow; font-weight: 600;">Sessions:</span> 2 active │
│ <span style="color: #5599ff; font-weight: 600;">Active Plans:</span> 1 │
╰───────────────────────────────────╯
╭─ Storage ─────╮
│ <span style="color: #5599ff; font-weight: 600;">Cache:</span> 118 MB │
│ <span style="color: #5599ff; font-weight: 600;">Logs:</span> 42 MB │
│ <span style="color: yellow; font-weight: 600;">Backups:</span> 3 │
│ <span style="color: #5599ff; font-weight: 600;">DB Size:</span> 8 MB │
╰───────────────╯
╭─ Indexing ─────────────╮
│ <span style="color: #66cc66; font-weight: 600;">Text Index:</span> ready │
│ <span style="color: #66cc66; font-weight: 600;">Vector Index:</span> ready │
│ <span style="color: yellow; font-weight: 600;">Graph Store:</span> disabled │
│ <span style="color: #5599ff; font-weight: 600;">Indexed Files:</span> 1,247 │
╰────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Environment details ready
</code></pre></div>
=== "Plain"
```
$ agents info
Environment
Data Dir: /home/alex/.cleveragents
Config: /home/alex/.cleveragents/config.toml
Database: sqlite:///home/alex/.cleveragents/cleveragents.db
Server Mode: disabled
Platform: Linux 6.8.0 (x86_64)
Runtime
Automation: review
Providers: 3 configured
Sessions: 2 active
Active Plans: 1
Storage
Cache: 118 MB
Logs: 42 MB
Backups: 3
DB Size: 8 MB
Indexing
Text Index: ready
Vector Index: ready
Graph Store: disabled
Indexed Files: 1,247
[OK] Environment details ready
```
=== "JSON"
```json
{
"command": "info",
"status": "ok",
"exit_code": 0,
"data": {
"environment": {
"data_dir": "/home/alex/.cleveragents",
"config": "/home/alex/.cleveragents/config.toml",
"database": "sqlite:///home/alex/.cleveragents/cleveragents.db",
"server_mode": "disabled",
"platform": "Linux 6.8.0 (x86_64)"
},
"runtime": {
"automation": "review",
"providers": 3,
"sessions": "2 active",
"active_plans": 1
},
"storage": {
"cache_mb": 118,
"logs_mb": 42,
"backups": 3,
"db_size_mb": 8
},
"indexing": {
"text_index": "ready",
"vector_index": "ready",
"graph_store": "disabled",
"indexed_files": 1247
}
},
"timing": {
"duration_ms": 18
},
"messages": [
{ "level": "ok", "text": "Environment details ready" }
]
}
```
=== "YAML"
```yaml
command: info
status: ok
exit_code: 0
data:
environment:
data_dir: /home/alex/.cleveragents
config: /home/alex/.cleveragents/config.toml
database: sqlite:///home/alex/.cleveragents/cleveragents.db
server_mode: disabled
platform: Linux 6.8.0 (x86_64)
runtime:
automation: review
providers: 3
sessions: 2 active
active_plans: 1
storage:
cache_mb: 118
logs_mb: 42
backups: 3
db_size_mb: 8
indexing:
text_index: ready
vector_index: ready
graph_store: disabled
indexed_files: 1247
timing:
duration_ms: 18
messages:
- level: ok
text: Environment details ready
```
agents diagnostics
agents diagnosticsPurpose Run health checks for configuration, providers, and filesystem permissions.
Arguments
None.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> diagnostics
╭─ Checks ────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Check</span> <span style="color: cyan; font-weight: 600;">Status</span> <span style="color: cyan; font-weight: 600;">Details</span> │
│ <span style="opacity: 0.7;">─────────────── ────── ──────────────</span> │
│ Config file <span style="color: #66cc66; font-weight: 600;">OK</span> readable │
│ Database <span style="color: #66cc66; font-weight: 600;">OK</span> writable │
│ OPENAI_API_KEY <span style="color: yellow; font-weight: 600;">WARN</span> missing │
│ Anthropic key <span style="color: #66cc66; font-weight: 600;">OK</span> configured │
│ Disk space <span style="color: #66cc66; font-weight: 600;">OK</span> 2.1 GB free │
│ Text index <span style="color: #66cc66; font-weight: 600;">OK</span> tantivy 0.22 │
│ Vector index <span style="color: #66cc66; font-weight: 600;">OK</span> faiss (CPU) │
│ Graph store <span style="color: yellow; font-weight: 600;">WARN</span> not configured │
│ File permissions <span style="color: #66cc66; font-weight: 600;">OK</span> data dir r/w │
│ Git <span style="color: #66cc66; font-weight: 600;">OK</span> git 2.43.0 │
╰─────────────────────────────────────────╯
╭─ Summary ─────────╮
│ <span style="color: #5599ff; font-weight: 600;">Checks:</span> 10 total │
│ <span style="color: yellow; font-weight: 600;">Warnings:</span> 2 │
│ <span style="color: #ff6666; font-weight: 600;">Errors:</span> 0 │
│ <span style="color: #66cc66; font-weight: 600;">Duration:</span> 0.6s │
╰───────────────────╯
╭─ Recommendations ─────────────────────────────────────────────╮
│ - Set OPENAI_API_KEY to enable OpenAI models │
│ - Configure a graph store backend for structural code queries │
│ - Verify provider credentials via config │
╰───────────────────────────────────────────────────────────────╯
<span style="color: yellow; font-weight: 600;">⚠ WARN</span> 2 warnings require attention
</code></pre></div>
=== "Plain"
```
$ agents diagnostics
Checks
Check Status Details
--------------- ------ --------------
Config file OK readable
Database OK writable
OPENAI_API_KEY WARN missing
Anthropic key OK configured
Disk space OK 2.1 GB free
Text index OK tantivy 0.22
Vector index OK faiss (CPU)
Graph store WARN not configured
File permissions OK data dir r/w
Git OK git 2.43.0
Summary
Checks: 10 total
Warnings: 2
Errors: 0
Duration: 0.6s
Recommendations
- Set OPENAI_API_KEY to enable OpenAI models
- Configure a graph store backend for structural code queries
- Verify provider credentials via config
[WARN] 2 warnings require attention
```
=== "JSON"
```json
{
"command": "diagnostics",
"status": "ok",
"exit_code": 0,
"data": {
"checks": [
{ "check": "Config file", "status": "ok", "details": "readable" },
{ "check": "Database", "status": "ok", "details": "writable" },
{ "check": "OPENAI_API_KEY", "status": "warn", "details": "missing" },
{ "check": "Anthropic key", "status": "ok", "details": "configured" },
{ "check": "Disk space", "status": "ok", "details": "2.1 GB free" },
{ "check": "Text index", "status": "ok", "details": "tantivy 0.22" },
{ "check": "Vector index", "status": "ok", "details": "faiss (CPU)" },
{ "check": "Graph store", "status": "warn", "details": "not configured" },
{ "check": "File permissions", "status": "ok", "details": "data dir r/w" },
{ "check": "Git", "status": "ok", "details": "git 2.43.0" }
],
"summary": {
"total": 10,
"warnings": 2,
"errors": 0,
"duration_s": 0.6
},
"recommendations": [
"Set OPENAI_API_KEY to enable OpenAI models",
"Configure a graph store backend for structural code queries",
"Verify provider credentials via config"
]
},
"timing": {
"duration_ms": 600
},
"messages": [
{ "level": "warn", "text": "2 warnings require attention" }
]
}
```
=== "YAML"
```yaml
command: diagnostics
status: ok
exit_code: 0
data:
checks:
- check: Config file
status: ok
details: readable
- check: Database
status: ok
details: writable
- check: OPENAI_API_KEY
status: warn
details: missing
- check: Anthropic key
status: ok
details: configured
- check: Disk space
status: ok
details: 2.1 GB free
- check: Text index
status: ok
details: tantivy 0.22
- check: Vector index
status: ok
details: faiss (CPU)
- check: Graph store
status: warn
details: not configured
- check: File permissions
status: ok
details: data dir r/w
- check: Git
status: ok
details: git 2.43.0
summary:
total: 10
warnings: 2
errors: 0
duration_s: 0.6
recommendations:
- Set OPENAI_API_KEY to enable OpenAI models
- Configure a graph store backend for structural code queries
- Verify provider credentials via config
timing:
duration_ms: 600
messages:
- level: warn
text: 2 warnings require attention
```
When critical checks fail, diagnostics reports errors:
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> diagnostics
╭─ Checks ────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Check</span> <span style="color: cyan; font-weight: 600;">Status</span> <span style="color: cyan; font-weight: 600;">Details</span> │
│ <span style="opacity: 0.7;">─────────────── ─────── ────────────────────</span> │
│ Config file <span style="color: #66cc66; font-weight: 600;">OK</span> readable │
│ Database <span style="color: #ff6666; font-weight: 600;">ERROR</span> locked by another process │
│ OPENAI_API_KEY <span style="color: #66cc66; font-weight: 600;">OK</span> configured │
│ Anthropic key <span style="color: #ff6666; font-weight: 600;">ERROR</span> invalid key format │
│ Disk space <span style="color: yellow; font-weight: 600;">WARN</span> 312 MB free (low) │
│ Text index <span style="color: #66cc66; font-weight: 600;">OK</span> tantivy 0.22 │
│ Vector index <span style="color: #ff6666; font-weight: 600;">ERROR</span> FAISS library not found │
│ Graph store <span style="color: #66cc66; font-weight: 600;">OK</span> neo4j 5.15 │
│ File permissions <span style="color: #66cc66; font-weight: 600;">OK</span> data dir r/w │
│ Git <span style="color: #66cc66; font-weight: 600;">OK</span> git 2.43.0 │
╰─────────────────────────────────────────────────────╯
╭─ Summary ─────────╮
│ <span style="color: #5599ff; font-weight: 600;">Checks:</span> 10 total │
│ <span style="color: yellow; font-weight: 600;">Warnings:</span> 1 │
│ <span style="color: #ff6666; font-weight: 600;">Errors:</span> 3 │
│ <span style="color: #66cc66; font-weight: 600;">Duration:</span> 1.2s │
╰───────────────────╯
╭─ Errors (must fix) ─────────────────────────────────────────────────╮
│ <span style="color: #ff6666; font-weight: 600;">1.</span> Database is locked by PID 12847 — stop the other process or │
│ delete the lock file at ~/.cleveragents/agents.db-lock │
│ <span style="color: #ff6666; font-weight: 600;">2.</span> Anthropic key starts with <span style="color: #66cc66;">"pk-"</span> — expected <span style="color: #66cc66;">"sk-ant-"</span> prefix │
│ Run: agents config set provider.anthropic.api-key <correct-key> │
│ <span style="color: #ff6666; font-weight: 600;">3.</span> FAISS library not installed — vector search will not work │
│ Run: pip install faiss-cpu │
╰─────────────────────────────────────────────────────────────────────╯
<span style="color: #ff6666; font-weight: 600;">✗ ERROR</span> 3 errors must be resolved before CleverAgents can operate
</code></pre></div>
=== "Plain"
```
$ agents diagnostics
Checks
Check Status Details
--------------- ------- ------------------------
Config file OK readable
Database ERROR locked by another process
OPENAI_API_KEY OK configured
Anthropic key ERROR invalid key format
Disk space WARN 312 MB free (low)
Text index OK tantivy 0.22
Vector index ERROR FAISS library not found
Graph store OK neo4j 5.15
File permissions OK data dir r/w
Git OK git 2.43.0
Summary
Checks: 10 total
Warnings: 1
Errors: 3
Duration: 1.2s
Errors (must fix)
1. Database is locked by PID 12847 -- stop the other process or
delete the lock file at ~/.cleveragents/agents.db-lock
2. Anthropic key starts with "pk-" -- expected "sk-ant-" prefix
Run: agents config set provider.anthropic.api-key <correct-key>
3. FAISS library not installed -- vector search will not work
Run: pip install faiss-cpu
[ERROR] 3 errors must be resolved before CleverAgents can operate
```
=== "JSON"
```json
{
"command": "diagnostics",
"status": "error",
"exit_code": 1,
"data": {
"checks": [
{ "check": "Config file", "status": "ok", "details": "readable" },
{ "check": "Database", "status": "error", "details": "locked by another process" },
{ "check": "OPENAI_API_KEY", "status": "ok", "details": "configured" },
{ "check": "Anthropic key", "status": "error", "details": "invalid key format" },
{ "check": "Disk space", "status": "warn", "details": "312 MB free (low)" },
{ "check": "Text index", "status": "ok", "details": "tantivy 0.22" },
{ "check": "Vector index", "status": "error", "details": "FAISS library not found" },
{ "check": "Graph store", "status": "ok", "details": "neo4j 5.15" },
{ "check": "File permissions", "status": "ok", "details": "data dir r/w" },
{ "check": "Git", "status": "ok", "details": "git 2.43.0" }
],
"summary": {
"total": 10,
"warnings": 1,
"errors": 3,
"duration_s": 1.2
},
"errors": [
{
"index": 1,
"message": "Database is locked by PID 12847 -- stop the other process or delete the lock file at ~/.cleveragents/agents.db-lock"
},
{
"index": 2,
"message": "Anthropic key starts with \"pk-\" -- expected \"sk-ant-\" prefix",
"fix": "agents config set provider.anthropic.api-key <correct-key>"
},
{
"index": 3,
"message": "FAISS library not installed -- vector search will not work",
"fix": "pip install faiss-cpu"
}
]
},
"timing": {
"duration_ms": 1200
},
"messages": [
{ "level": "error", "text": "3 errors must be resolved before CleverAgents can operate" }
]
}
```
=== "YAML"
```yaml
command: diagnostics
status: error
exit_code: 1
data:
checks:
- check: Config file
status: ok
details: readable
- check: Database
status: error
details: locked by another process
- check: OPENAI_API_KEY
status: ok
details: configured
- check: Anthropic key
status: error
details: invalid key format
- check: Disk space
status: warn
details: 312 MB free (low)
- check: Text index
status: ok
details: tantivy 0.22
- check: Vector index
status: error
details: FAISS library not found
- check: Graph store
status: ok
details: neo4j 5.15
- check: File permissions
status: ok
details: data dir r/w
- check: Git
status: ok
details: git 2.43.0
summary:
total: 10
warnings: 1
errors: 3
duration_s: 1.2
errors:
- index: 1
message: >-
Database is locked by PID 12847 -- stop the other process or
delete the lock file at ~/.cleveragents/agents.db-lock
- index: 2
message: Anthropic key starts with "pk-" -- expected "sk-ant-" prefix
fix: agents config set provider.anthropic.api-key <correct-key>
- index: 3
message: FAISS library not installed -- vector search will not work
fix: pip install faiss-cpu
timing:
duration_ms: 1200
messages:
- level: error
text: 3 errors must be resolved before CleverAgents can operate
```
agents init
agents init [--yes|-y]!!! danger "Destructive Operation"
This command ==wipes all existing data== and re-creates the global config and database. A backup is created automatically, but all sessions, plans, and registry entries will be removed.
Purpose Initialize or reset the global CleverAgents environment. This wipes any existing data and re-creates the global config and database.
Arguments
--yes: Skip the confirmation prompt and proceed with the wipe.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> init
<span style="color: yellow; font-weight: 600;">Warning</span>: This will remove all data in /home/alex/.cleveragents
Continue? [y/N]: y
╭─ Environment Reset ────────────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Config:</span> /home/alex/.cleveragents/config.toml │
│ <span style="color: #66cc66; font-weight: 600;">Database:</span> /home/alex/.cleveragents/cleveragents.db │
│ <span style="color: yellow; font-weight: 600;">Backup:</span> /home/alex/.cleveragents.backup-2026-02-08 │
│ <span style="color: #66cc66; font-weight: 600;">Status:</span> ready │
╰────────────────────────────────────────────────────╯
╭─ Defaults ──────────────────────────────────╮
│ <span style="color: magenta; font-weight: 600;">Automation Profile:</span> supervised │
│ <span style="color: #5599ff; font-weight: 600;">Built-in Profiles:</span> 8 loaded │
╰─────────────────────────────────────────────╯
╭─ Created ─────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Config:</span> config.toml │
│ <span style="color: #66cc66; font-weight: 600;">Database:</span> cleveragents.db │
│ <span style="color: #5599ff; font-weight: 600;">Logs:</span> logs/ │
│ <span style="color: #5599ff; font-weight: 600;">Cache:</span> cache/ │
│ <span style="color: #5599ff; font-weight: 600;">Backups:</span> backups/ │
╰───────────────────────────╯
╭─ Schema ───────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Version:</span> v3 │
│ <span style="color: #66cc66; font-weight: 600;">Tables:</span> 12 created │
│ <span style="color: #5599ff; font-weight: 600;">Migrations:</span> up to date │
╰────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Environment initialized
</code></pre></div>
=== "Plain"
```
$ agents init
Warning: This will remove all data in /home/alex/.cleveragents
Continue? [y/N]: y
Environment Reset
Config: /home/alex/.cleveragents/config.toml
Database: /home/alex/.cleveragents/cleveragents.db
Backup: /home/alex/.cleveragents.backup-2026-02-08
Status: ready
Defaults
Automation Profile: supervised
Built-in Profiles: 8 loaded
Created
Config: config.toml
Database: cleveragents.db
Logs: logs/
Cache: cache/
Backups: backups/
Schema
Version: v3
Tables: 12 created
Migrations: up to date
[OK] Environment initialized
```
=== "JSON"
```json
{
"command": "init",
"status": "ok",
"exit_code": 0,
"data": {
"environment_reset": {
"config": "/home/alex/.cleveragents/config.toml",
"database": "/home/alex/.cleveragents/cleveragents.db",
"backup": "/home/alex/.cleveragents.backup-2026-02-08",
"status": "ready"
},
"defaults": {
"automation_profile": "supervised",
"builtin_profiles": 8
},
"created": {
"config": "config.toml",
"database": "cleveragents.db",
"logs": "logs/",
"cache": "cache/",
"backups": "backups/"
},
"schema": {
"version": "v3",
"tables": 12,
"migrations": "up to date"
}
},
"timing": {
"duration_ms": 340
},
"messages": [
{ "level": "ok", "text": "Environment initialized" }
]
}
```
=== "YAML"
```yaml
command: init
status: ok
exit_code: 0
data:
environment_reset:
config: /home/alex/.cleveragents/config.toml
database: /home/alex/.cleveragents/cleveragents.db
backup: /home/alex/.cleveragents.backup-2026-02-08
status: ready
defaults:
automation_profile: supervised
builtin_profiles: 8
created:
config: config.toml
database: cleveragents.db
logs: logs/
cache: cache/
backups: backups/
schema:
version: v3
tables: 12
migrations: up to date
timing:
duration_ms: 340
messages:
- level: ok
text: Environment initialized
```
Non-interactive initialization using --yes (useful in scripts and CI):
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> init <span style="color: cyan;">--yes</span>
╭─ Initialized ──────────────────────────────────────────╮
│ <span style="color: #66cc66; font-weight: 600;">Data Dir:</span> /home/alex/.cleveragents (created) │
│ <span style="color: #66cc66; font-weight: 600;">Config:</span> /home/alex/.cleveragents/config.toml │
│ <span style="color: #66cc66; font-weight: 600;">Database:</span> initialized (schema v3) │
│ <span style="color: #66cc66; font-weight: 600;">Directories:</span> logs, cache, sessions, contexts │
╰────────────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Initialized (non-interactive)
</code></pre></div>
=== "Plain"
```
$ agents init --yes
Initialized
Data Dir: /home/alex/.cleveragents (created)
Config: /home/alex/.cleveragents/config.toml
Database: initialized (schema v3)
Directories: logs, cache, sessions, contexts
[OK] Initialized (non-interactive)
```
=== "JSON"
```json
{
"command": "init --yes",
"status": "ok",
"exit_code": 0,
"data": {
"initialized": {
"data_dir": "/home/alex/.cleveragents",
"config": "/home/alex/.cleveragents/config.toml",
"database": "initialized (schema v3)",
"directories": ["logs", "cache", "sessions", "contexts"]
}
},
"timing": {
"duration_ms": 280
},
"messages": [
{ "level": "ok", "text": "Initialized (non-interactive)" }
]
}
```
=== "YAML"
```yaml
command: init --yes
status: ok
exit_code: 0
data:
initialized:
data_dir: /home/alex/.cleveragents
config: /home/alex/.cleveragents/config.toml
database: initialized (schema v3)
directories:
- logs
- cache
- sessions
- contexts
timing:
duration_ms: 280
messages:
- level: ok
text: Initialized (non-interactive)
```
agents session
Purpose Manage interactive sessions that hold a conversation history and orchestrator state.
agents session create
agents session create [--actor <ACTOR>]Purpose Create a new session for interactive work.
Arguments
--actor ACTOR: Orchestrator actor to use forsession tell.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> session create <span style="color: cyan;">--actor</span> local/orchestrator
╭─ Session ───────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">ID:</span> 01HXM2A6K1P2E9Q9D4GQ7J4S7Z │
│ <span style="color: magenta; font-weight: 600;">Actor:</span> local/orchestrator │
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-08 12:44 │
│ <span style="color: #5599ff; font-weight: 600;">Namespace:</span> local │
╰─────────────────────────────────╯
╭─ Settings ─────────────╮
│ <span style="color: magenta; font-weight: 600;">Automation:</span> review │
│ <span style="color: #5599ff; font-weight: 600;">Streaming:</span> off │
│ <span style="color: #5599ff; font-weight: 600;">Context:</span> default │
│ <span style="color: #5599ff; font-weight: 600;">Memory:</span> enabled │
│ <span style="color: yellow; font-weight: 600;">Max History:</span> 50 turns │
╰────────────────────────╯
╭─ Actor Details ───────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Provider:</span> anthropic │
│ <span style="color: magenta; font-weight: 600;">Model:</span> claude-3.5 │
│ <span style="color: #5599ff; font-weight: 600;">Temperature:</span> 0.7 │
│ <span style="color: #5599ff; font-weight: 600;">Context Window:</span> 200K tokens │
╰───────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Session created
</code></pre></div>
=== "Plain"
```
$ agents session create --actor local/orchestrator
Session
ID: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
Actor: local/orchestrator
Created: 2026-02-08 12:44
Namespace: local
Settings
Automation: review
Streaming: off
Context: default
Memory: enabled
Max History: 50 turns
Actor Details
Provider: anthropic
Model: claude-3.5
Temperature: 0.7
Context Window: 200K tokens
[OK] Session created
```
=== "JSON"
```json
{
"command": "agents session create --actor local/orchestrator",
"status": "ok",
"exit_code": 0,
"data": {
"session": {
"id": "01HXM2A6K1P2E9Q9D4GQ7J4S7Z",
"actor": "local/orchestrator",
"created": "2026-02-08T12:44:00Z",
"namespace": "local"
},
"settings": {
"automation": "review",
"streaming": "off",
"context": "default",
"memory": "enabled",
"max_history": 50
},
"actor_details": {
"provider": "anthropic",
"model": "claude-3.5",
"temperature": 0.7,
"context_window": "200K tokens"
}
},
"timing": { "duration_ms": 120 },
"messages": [{ "level": "ok", "text": "Session created" }]
}
```
=== "YAML"
```yaml
command: agents session create --actor local/orchestrator
status: ok
exit_code: 0
data:
session:
id: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
actor: local/orchestrator
created: "2026-02-08T12:44:00Z"
namespace: local
settings:
automation: review
streaming: "off"
context: default
memory: enabled
max_history: 50
actor_details:
provider: anthropic
model: claude-3.5
temperature: 0.7
context_window: 200K tokens
timing:
duration_ms: 120
messages:
- level: ok
text: Session created
```
agents session list
agents session listPurpose List sessions available on the local machine.
Arguments
None.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> <span style="color: cyan;">--format</span> table session list
╭─ Sessions ───────────────────────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">ID</span> <span style="color: cyan; font-weight: 600;">Name</span> <span style="color: cyan; font-weight: 600;">Actor</span> <span style="color: cyan; font-weight: 600;">Messages</span> <span style="color: cyan; font-weight: 600;">Updated</span> │
│ <span style="opacity: 0.7;">──────── ─────────────── ────────────────── ──────── ────────────────</span> │
│ 01HXM2A6 weekly-planning local/orchestrator 6 2026-02-08 12:44 │
│ 01HXM1F2 refactor-sprint local/orchestrator 14 2026-02-07 18:11 │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Summary ────────────────────╮
│ <span style="color: yellow; font-weight: 600;">Total:</span> 2 │
│ <span style="color: #66cc66; font-weight: 600;">Most Recent:</span> weekly-planning │
│ <span style="color: #5599ff; font-weight: 600;">Oldest:</span> refactor-sprint │
│ <span style="color: #5599ff; font-weight: 600;">Total Messages:</span> 20 │
│ <span style="color: #5599ff; font-weight: 600;">Storage:</span> 42 KB │
╰──────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 2 sessions listed
</code></pre></div>
=== "Plain"
```
$ agents --format table session list
Sessions
ID Name Actor Messages Updated
-------- --------------- ------------------ -------- ----------------
01HXM2A6 weekly-planning local/orchestrator 6 2026-02-08 12:44
01HXM1F2 refactor-sprint local/orchestrator 14 2026-02-07 18:11
Summary
Total: 2
Most Recent: weekly-planning
Oldest: refactor-sprint
Total Messages: 20
Storage: 42 KB
[OK] 2 sessions listed
```
=== "JSON"
```json
{
"command": "agents --format table session list",
"status": "ok",
"exit_code": 0,
"data": {
"sessions": [
{
"id": "01HXM2A6",
"name": "weekly-planning",
"actor": "local/orchestrator",
"messages": 6,
"updated": "2026-02-08T12:44:00Z"
},
{
"id": "01HXM1F2",
"name": "refactor-sprint",
"actor": "local/orchestrator",
"messages": 14,
"updated": "2026-02-07T18:11:00Z"
}
],
"summary": {
"total": 2,
"most_recent": "weekly-planning",
"oldest": "refactor-sprint",
"total_messages": 20,
"storage": "42 KB"
}
},
"timing": { "duration_ms": 85 },
"messages": [{ "level": "ok", "text": "2 sessions listed" }]
}
```
=== "YAML"
```yaml
command: agents --format table session list
status: ok
exit_code: 0
data:
sessions:
- id: 01HXM2A6
name: weekly-planning
actor: local/orchestrator
messages: 6
updated: "2026-02-08T12:44:00Z"
- id: 01HXM1F2
name: refactor-sprint
actor: local/orchestrator
messages: 14
updated: "2026-02-07T18:11:00Z"
summary:
total: 2
most_recent: weekly-planning
oldest: refactor-sprint
total_messages: 20
storage: 42 KB
timing:
duration_ms: 85
messages:
- level: ok
text: 2 sessions listed
```
agents session show
agents session show <SESSION_ID>Purpose Show details and recent messages for a session.
Arguments
<SESSION_ID>: The session identifier.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> session show 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
╭─ Session Summary ───────────────╮
│ <span style="color: #5599ff; font-weight: 600;">ID:</span> 01HXM2A6K1P2E9Q9D4GQ7J4S7Z │
│ <span style="color: magenta; font-weight: 600;">Actor:</span> local/orchestrator │
│ <span style="color: yellow; font-weight: 600;">Messages:</span> 6 │
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-08 12:30 │
│ <span style="color: #66cc66; font-weight: 600;">Updated:</span> 2026-02-08 12:44 │
│ <span style="color: #5599ff; font-weight: 600;">Automation:</span> review │
╰─────────────────────────────────╯
╭─ Recent Messages ──────────────────────────────────╮
│ <span style="opacity: 0.7;">user</span> Create an action to refresh dependency locks │
│ <span style="opacity: 0.7;">assistant</span> Plan created, running commands... │
│ <span style="opacity: 0.7;">assistant</span> Completed 2 commands │
╰────────────────────────────────────────────────────╯
╭─ Linked Plans ────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Plan ID</span> <span style="color: cyan; font-weight: 600;">Phase</span> <span style="color: cyan; font-weight: 600;">State</span> │
│ <span style="opacity: 0.7;">────────────────────────── ────── ────────</span> │
│ 01HXM8C2ZK4Q7C2B3F2R4VYV6J execute complete │
╰───────────────────────────────────────────────╯
╭─ Token Usage ──────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Input Tokens:</span> 3,420 │
│ <span style="color: #5599ff; font-weight: 600;">Output Tokens:</span> 1,185 │
│ <span style="color: yellow; font-weight: 600;">Estimated Cost:</span> $0.0184 │
╰────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Session details loaded
</code></pre></div>
=== "Plain"
```
$ agents session show 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
Session Summary
ID: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
Actor: local/orchestrator
Messages: 6
Created: 2026-02-08 12:30
Updated: 2026-02-08 12:44
Automation: review
Recent Messages
user Create an action to refresh dependency locks
assistant Plan created, running commands...
assistant Completed 2 commands
Linked Plans
Plan ID Phase State
-------------------------- ------- --------
01HXM8C2ZK4Q7C2B3F2R4VYV6J execute complete
Token Usage
Input Tokens: 3,420
Output Tokens: 1,185
Estimated Cost: $0.0184
[OK] Session details loaded
```
=== "JSON"
```json
{
"command": "agents session show 01HXM2A6K1P2E9Q9D4GQ7J4S7Z",
"status": "ok",
"exit_code": 0,
"data": {
"session_summary": {
"id": "01HXM2A6K1P2E9Q9D4GQ7J4S7Z",
"actor": "local/orchestrator",
"messages": 6,
"created": "2026-02-08T12:30:00Z",
"updated": "2026-02-08T12:44:00Z",
"automation": "review"
},
"recent_messages": [
{ "role": "user", "text": "Create an action to refresh dependency locks" },
{ "role": "assistant", "text": "Plan created, running commands..." },
{ "role": "assistant", "text": "Completed 2 commands" }
],
"linked_plans": [
{
"plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
"phase": "execute",
"state": "complete"
}
],
"token_usage": {
"input_tokens": 3420,
"output_tokens": 1185,
"estimated_cost": "$0.0184"
}
},
"timing": { "duration_ms": 95 },
"messages": [{ "level": "ok", "text": "Session details loaded" }]
}
```
=== "YAML"
```yaml
command: agents session show 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
status: ok
exit_code: 0
data:
session_summary:
id: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
actor: local/orchestrator
messages: 6
created: "2026-02-08T12:30:00Z"
updated: "2026-02-08T12:44:00Z"
automation: review
recent_messages:
- role: user
text: Create an action to refresh dependency locks
- role: assistant
text: Plan created, running commands...
- role: assistant
text: Completed 2 commands
linked_plans:
- plan_id: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
phase: execute
state: complete
token_usage:
input_tokens: 3420
output_tokens: 1185
estimated_cost: "$0.0184"
timing:
duration_ms: 95
messages:
- level: ok
text: Session details loaded
```
agents session delete
agents session delete [--yes|-y] <SESSION_ID>!!! danger "Irreversible Deletion"
This command ==permanently deletes== a session and its stored conversation history. Messages and context cannot be recovered after deletion. Use --yes to skip the confirmation prompt.
Arguments
<SESSION_ID>: The session identifier.--yes, -y: Skip the confirmation prompt.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> session delete 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
Delete session 01HXM2A6K1P2E9Q9D4GQ7J4S7Z? [y/N]: y
╭─ Deletion Summary ──────────────────╮
│ <span style="color: cyan; font-weight: 600;">Session:</span> 01HXM2A6K1P2E9Q9D4GQ7J4S7Z │
│ <span style="color: #5599ff; font-weight: 600;">ID:</span> 01HXM2A6K1P2E9Q9D4GQ7J4S7Z │
│ <span style="color: yellow; font-weight: 600;">Messages:</span> 6 removed │
│ <span style="color: #5599ff; font-weight: 600;">Storage:</span> 18 KB freed │
│ <span style="color: #5599ff; font-weight: 600;">Plans Orphaned:</span> 0 │
╰─────────────────────────────────────╯
╭─ Cleanup ───────────╮
│ <span style="color: #66cc66; font-weight: 600;">Backups:</span> none │
│ <span style="color: #5599ff; font-weight: 600;">Logs:</span> preserved │
│ <span style="color: #5599ff; font-weight: 600;">Context:</span> cleared │
│ <span style="color: #5599ff; font-weight: 600;">Checkpoints:</span> none │
╰─────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Session deleted
</code></pre></div>
=== "Plain"
```
$ agents session delete 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
Delete session 01HXM2A6K1P2E9Q9D4GQ7J4S7Z? [y/N]: y
Deletion Summary
Session: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
ID: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
Messages: 6 removed
Storage: 18 KB freed
Plans Orphaned: 0
Cleanup
Backups: none
Logs: preserved
Context: cleared
Checkpoints: none
[OK] Session deleted
```
=== "JSON"
```json
{
"command": "agents session delete 01HXM2A6K1P2E9Q9D4GQ7J4S7Z",
"status": "ok",
"exit_code": 0,
"data": {
"deletion_summary": {
"session": "01HXM2A6K1P2E9Q9D4GQ7J4S7Z",
"id": "01HXM2A6K1P2E9Q9D4GQ7J4S7Z",
"messages_removed": 6,
"storage_freed": "18 KB",
"plans_orphaned": 0
},
"cleanup": {
"backups": "none",
"logs": "preserved",
"context": "cleared",
"checkpoints": "none"
}
},
"timing": { "duration_ms": 62 },
"messages": [{ "level": "ok", "text": "Session deleted" }]
}
```
=== "YAML"
```yaml
command: agents session delete 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
status: ok
exit_code: 0
data:
deletion_summary:
session: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
id: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
messages_removed: 6
storage_freed: 18 KB
plans_orphaned: 0
cleanup:
backups: none
logs: preserved
context: cleared
checkpoints: none
timing:
duration_ms: 62
messages:
- level: ok
text: Session deleted
```
agents session export
agents session export [(--output|-o) <FILE>] <SESSION_ID>Purpose Export a session as a portable JSON file.
Arguments
<SESSION_ID>: The session identifier.--output/-o FILE: Output file path (optional).
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> session export <span style="color: cyan;">--output</span> /tmp/weekly-planning.json 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
╭─ Session Export ────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Session:</span> 01HXM2A6K1P2E9Q9D4GQ7J4S7Z │
│ <span style="color: #5599ff; font-weight: 600;">Output:</span> /tmp/weekly-planning.json │
│ <span style="color: yellow; font-weight: 600;">Messages:</span> 6 │
│ <span style="color: #66cc66; font-weight: 600;">Size:</span> 24 KB │
│ <span style="color: #5599ff; font-weight: 600;">Format:</span> JSON │
╰─────────────────────────────────────╯
╭─ Contents ─────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Messages:</span> 6 │
│ <span style="color: #5599ff; font-weight: 600;">Plan References:</span> 1 │
│ <span style="color: #5599ff; font-weight: 600;">Metadata Keys:</span> 2 │
│ <span style="color: yellow; font-weight: 600;">Actor Config:</span> included │
│ <span style="color: #5599ff; font-weight: 600;">Schema Version:</span> v3 │
╰────────────────────────────╯
╭─ Integrity ──────────────────╮
│ <span style="color: magenta; font-weight: 600;">Checksum:</span> sha256:7a9b...42c1 │
│ <span style="color: yellow; font-weight: 600;">Encrypted:</span> no │
╰──────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Export completed
</code></pre></div>
=== "Plain"
```
$ agents session export --output /tmp/weekly-planning.json 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
Session Export
Session: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
Output: /tmp/weekly-planning.json
Messages: 6
Size: 24 KB
Format: JSON
Contents
Messages: 6
Plan References: 1
Metadata Keys: 2
Actor Config: included
Schema Version: v3
Integrity
Checksum: sha256:7a9b...42c1
Encrypted: no
[OK] Export completed
```
=== "JSON"
```json
{
"command": "agents session export --output /tmp/weekly-planning.json 01HXM2A6K1P2E9Q9D4GQ7J4S7Z",
"status": "ok",
"exit_code": 0,
"data": {
"session_export": {
"session": "01HXM2A6K1P2E9Q9D4GQ7J4S7Z",
"output": "/tmp/weekly-planning.json",
"messages": 6,
"size": "24 KB",
"format": "JSON"
},
"contents": {
"messages": 6,
"plan_references": 1,
"metadata_keys": 2,
"actor_config": "included",
"schema_version": "v3"
},
"integrity": {
"checksum": "sha256:7a9b...42c1",
"encrypted": false
}
},
"timing": { "duration_ms": 140 },
"messages": [{ "level": "ok", "text": "Export completed" }]
}
```
=== "YAML"
```yaml
command: agents session export --output /tmp/weekly-planning.json 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
status: ok
exit_code: 0
data:
session_export:
session: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
output: /tmp/weekly-planning.json
messages: 6
size: 24 KB
format: JSON
contents:
messages: 6
plan_references: 1
metadata_keys: 2
actor_config: included
schema_version: v3
integrity:
checksum: "sha256:7a9b...42c1"
encrypted: false
timing:
duration_ms: 140
messages:
- level: ok
text: Export completed
```
agents session import
agents session import (--input|-i) <FILE>Purpose Import a session JSON file.
Arguments
--input/-i FILE: Input JSON file.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> session import <span style="color: cyan;">--input</span> /tmp/weekly-planning.json
╭─ Session Import ────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Input:</span> /tmp/weekly-planning.json │
│ <span style="color: #5599ff; font-weight: 600;">Session ID:</span> 01HXM3D3B2W4CQYQ3P4ZB8A5T1 │
│ <span style="color: yellow; font-weight: 600;">Messages:</span> 6 │
│ <span style="color: #5599ff; font-weight: 600;">Schema:</span> v3 │
╰─────────────────────────────────────────╯
╭─ Validation ────────────╮
│ <span style="color: #66cc66; font-weight: 600;">Checksum:</span> verified │
│ <span style="color: #66cc66; font-weight: 600;">Schema:</span> compatible │
│ <span style="color: #66cc66; font-weight: 600;">Actor Ref:</span> resolved │
╰─────────────────────────╯
╭─ Merge ──────────────╮
│ <span style="color: #66cc66; font-weight: 600;">Existing:</span> none │
│ <span style="color: #5599ff; font-weight: 600;">Strategy:</span> create new │
╰──────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Import completed
</code></pre></div>
=== "Plain"
```
$ agents session import --input /tmp/weekly-planning.json
Session Import
Input: /tmp/weekly-planning.json
Session ID: 01HXM3D3B2W4CQYQ3P4ZB8A5T1
Messages: 6
Schema: v3
Validation
Checksum: verified
Schema: compatible
Actor Ref: resolved
Merge
Existing: none
Strategy: create new
[OK] Import completed
```
=== "JSON"
```json
{
"command": "agents session import --input /tmp/weekly-planning.json",
"status": "ok",
"exit_code": 0,
"data": {
"session_import": {
"input": "/tmp/weekly-planning.json",
"session_id": "01HXM3D3B2W4CQYQ3P4ZB8A5T1",
"messages": 6,
"schema": "v3"
},
"validation": {
"checksum": "verified",
"schema": "compatible",
"actor_ref": "resolved"
},
"merge": {
"existing": "none",
"strategy": "create new"
}
},
"timing": { "duration_ms": 210 },
"messages": [{ "level": "ok", "text": "Import completed" }]
}
```
=== "YAML"
```yaml
command: agents session import --input /tmp/weekly-planning.json
status: ok
exit_code: 0
data:
session_import:
input: /tmp/weekly-planning.json
session_id: 01HXM3D3B2W4CQYQ3P4ZB8A5T1
messages: 6
schema: v3
validation:
checksum: verified
schema: compatible
actor_ref: resolved
merge:
existing: none
strategy: create new
timing:
duration_ms: 210
messages:
- level: ok
text: Import completed
```
agents session tell
agents session tell --session <SESSION_ID> [--actor <ACTOR>] [--stream] <PROMPT>!!! tip "Primary User Interface"
This is the main natural-language interface for interacting with CleverAgents. The orchestrator interprets your request and issues the necessary CleverAgents commands under the hood — creating actions, plans, or project changes as needed. Use `--stream` to see responses in real time.
Purpose Send a natural-language request to the orchestrator. The orchestrator can create actions, plans, or project changes by issuing the necessary CleverAgents commands under the hood.
Arguments
<PROMPT>: Instruction text (positional argument).--session SESSION_ID: Session to use (required).--actor ACTOR: Override the session actor for this request.--stream: Stream progress as the orchestrator works.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> session tell <span style="color: #66cc66;">"Create an action to refresh dependency locks and add it to the platform project"</span> \
<span style="color: cyan;">--session</span> 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
╭─ Plan Request ──────────────────────────────────────────╮
│ <span style="color: magenta; font-weight: 600;">Actor:</span> local/orchestrator │
│ <span style="color: cyan; font-weight: 600;">Session:</span> 01HXM2A6K1P2E9Q9D4GQ7J4S7Z │
│ <span style="color: magenta; font-weight: 600;">Automation:</span> review │
│ <span style="color: #5599ff; font-weight: 600;">Prompt:</span> Create an action to refresh dependency locks... │
╰─────────────────────────────────────────────────────────╯
╭─ Commands Executed ─────────────────────────────────────────────────────────────────────────────────────────╮
│ - agents action create <span style="color: cyan;">--config</span> ./actions/refresh-locks.yaml │
│ - agents resource add git-checkout local/platform-repo <span style="color: cyan;">--path</span> /repos/platform │
│ - agents project link-resource local/platform local/platform-repo │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Result ──────────────────────────╮
│ <span style="color: #66cc66; font-weight: 600;">Action:</span> local/refresh-locks │
│ <span style="color: #5599ff; font-weight: 600;">Project:</span> local/platform │
│ <span style="color: magenta; font-weight: 600;">Resource:</span> local/platform-repo │
╰───────────────────────────────────╯
╭─ Usage ─────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Input Tokens:</span> 1,842 │
│ <span style="color: #5599ff; font-weight: 600;">Output Tokens:</span> 624 │
│ <span style="color: yellow; font-weight: 600;">Cost:</span> $0.0094 │
│ <span style="color: #66cc66; font-weight: 600;">Duration:</span> 3.2s │
│ <span style="color: #5599ff; font-weight: 600;">Tool Calls:</span> 3 │
╰─────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Orchestrator completed 3 commands
</code></pre></div>
=== "Plain"
```
$ agents session tell "Create an action to refresh dependency locks and add it to the platform project" \
--session 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
Plan Request
Actor: local/orchestrator
Session: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
Automation: review
Prompt: Create an action to refresh dependency locks...
Commands Executed
- agents action create --config ./actions/refresh-locks.yaml
- agents resource add git-checkout local/platform-repo --path /repos/platform
- agents project link-resource local/platform local/platform-repo
Result
Action: local/refresh-locks
Project: local/platform
Resource: local/platform-repo
Usage
Input Tokens: 1,842
Output Tokens: 624
Cost: $0.0094
Duration: 3.2s
Tool Calls: 3
[OK] Orchestrator completed 3 commands
```
=== "JSON"
```json
{
"command": "agents session tell \"Create an action to refresh dependency locks and add it to the platform project\" --session 01HXM2A6K1P2E9Q9D4GQ7J4S7Z",
"status": "ok",
"exit_code": 0,
"data": {
"plan_request": {
"actor": "local/orchestrator",
"session": "01HXM2A6K1P2E9Q9D4GQ7J4S7Z",
"automation": "review",
"prompt": "Create an action to refresh dependency locks..."
},
"commands_executed": [
"agents action create --config ./actions/refresh-locks.yaml",
"agents resource add git-checkout local/platform-repo --path /repos/platform",
"agents project link-resource local/platform local/platform-repo"
],
"result": {
"action": "local/refresh-locks",
"project": "local/platform",
"resource": "local/platform-repo"
},
"usage": {
"input_tokens": 1842,
"output_tokens": 624,
"cost": "$0.0094",
"duration_s": 3.2,
"tool_calls": 3
}
},
"timing": { "duration_ms": 3200 },
"messages": [{ "level": "ok", "text": "Orchestrator completed 3 commands" }]
}
```
=== "YAML"
```yaml
command: agents session tell "Create an action to refresh dependency locks and add it to the platform project" --session 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
status: ok
exit_code: 0
data:
plan_request:
actor: local/orchestrator
session: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
automation: review
prompt: Create an action to refresh dependency locks...
commands_executed:
- agents action create --config ./actions/refresh-locks.yaml
- agents resource add git-checkout local/platform-repo --path /repos/platform
- agents project link-resource local/platform local/platform-repo
result:
action: local/refresh-locks
project: local/platform
resource: local/platform-repo
usage:
input_tokens: 1842
output_tokens: 624
cost: "$0.0094"
duration_s: 3.2
tool_calls: 3
timing:
duration_ms: 3200
messages:
- level: ok
text: Orchestrator completed 3 commands
```
Using --stream to see the response as it is generated (token by token):
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> session tell <span style="color: cyan;">--session</span> 01HXM2A6K1 <span style="color: cyan;">--stream</span> <span style="color: #66cc66;">"What files were changed in the last plan?"</span>
╭─ Session ──────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">ID:</span> 01HXM2A6K1P2E9Q9D4GQ7J4S7Z │
│ <span style="color: #5599ff; font-weight: 600;">Actor:</span> local/orchestrator │
│ <span style="color: #5599ff; font-weight: 600;">Mode:</span> streaming │
╰────────────────────────────────────╯
<span style="color: #66cc66;">▍</span> The last plan (01HXM8C2ZK) modified 6 files in the auth module:
1. `src/auth/session.py` — refactored session validation
2. `src/auth/tokens.py` — updated token expiry to 7200s
3. `src/auth/__init__.py` — updated exports
4. `tests/test_auth.py` — added 12 new test cases
5. `tests/test_session.py` — updated session fixtures
6. `docs/auth.md` — updated API documentation
All changes passed validation (24/24 tests, lint clean).
╭─ Usage ──────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Tokens:</span> 1,240 (stream) │
│ <span style="color: #5599ff; font-weight: 600;">Duration:</span> 3.1s │
│ <span style="color: #5599ff; font-weight: 600;">Tool Calls:</span> 2 │
╰──────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Stream complete
</code></pre></div>
=== "Plain"
```
$ agents session tell --session 01HXM2A6K1 --stream "What files were changed in the last plan?"
Session
ID: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
Actor: local/orchestrator
Mode: streaming
The last plan (01HXM8C2ZK) modified 6 files in the auth module:
1. src/auth/session.py -- refactored session validation
2. src/auth/tokens.py -- updated token expiry to 7200s
3. src/auth/__init__.py -- updated exports
4. tests/test_auth.py -- added 12 new test cases
5. tests/test_session.py -- updated session fixtures
6. docs/auth.md -- updated API documentation
All changes passed validation (24/24 tests, lint clean).
Usage
Tokens: 1,240 (stream)
Duration: 3.1s
Tool Calls: 2
[OK] Stream complete
```
=== "JSON"
```json
{
"command": "agents session tell --session 01HXM2A6K1 --stream \"What files were changed in the last plan?\"",
"status": "ok",
"exit_code": 0,
"data": {
"session": {
"id": "01HXM2A6K1P2E9Q9D4GQ7J4S7Z",
"actor": "local/orchestrator",
"mode": "streaming"
},
"response": "The last plan (01HXM8C2ZK) modified 6 files in the auth module:\n\n1. src/auth/session.py \u2014 refactored session validation\n2. src/auth/tokens.py \u2014 updated token expiry to 7200s\n3. src/auth/__init__.py \u2014 updated exports\n4. tests/test_auth.py \u2014 added 12 new test cases\n5. tests/test_session.py \u2014 updated session fixtures\n6. docs/auth.md \u2014 updated API documentation\n\nAll changes passed validation (24/24 tests, lint clean).",
"files_changed": [
"src/auth/session.py",
"src/auth/tokens.py",
"src/auth/__init__.py",
"tests/test_auth.py",
"tests/test_session.py",
"docs/auth.md"
],
"usage": {
"tokens": 1240,
"duration_s": 3.1,
"tool_calls": 2
}
},
"timing": { "duration_ms": 3100 },
"messages": [{ "level": "ok", "text": "Stream complete" }]
}
```
=== "YAML"
```yaml
command: agents session tell --session 01HXM2A6K1 --stream "What files were changed in the last plan?"
status: ok
exit_code: 0
data:
session:
id: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
actor: local/orchestrator
mode: streaming
response: >
The last plan (01HXM8C2ZK) modified 6 files in the auth module:
1. src/auth/session.py -- refactored session validation
2. src/auth/tokens.py -- updated token expiry to 7200s
3. src/auth/__init__.py -- updated exports
4. tests/test_auth.py -- added 12 new test cases
5. tests/test_session.py -- updated session fixtures
6. docs/auth.md -- updated API documentation
All changes passed validation (24/24 tests, lint clean).
files_changed:
- src/auth/session.py
- src/auth/tokens.py
- src/auth/__init__.py
- tests/test_auth.py
- tests/test_session.py
- docs/auth.md
usage:
tokens: 1240
duration_s: 3.1
tool_calls: 2
timing:
duration_ms: 3100
messages:
- level: ok
text: Stream complete
```
agents project
Purpose Manage projects and their resources.
agents project create
agents project create [(--description|-d) <DESC>] [--resource <RESOURCE>]...
[--invariant <INVARIANT>]... [--invariant-actor <ACTOR>] <NAME>Purpose Create a new project record.
Arguments
<NAME>: Namespaced project name (positional argument).--description/-d TEXT: Optional description.--resource RESOURCE: Resource name or ULID to link to the project at creation time (repeatable).--invariant TEXT: Invariant to attach to this project (repeatable). These invariants apply to all plans targeting this project.--invariant-actor ACTOR: Invariant Reconciliation Actor for this project. Used to reconcile project-level invariants against global invariants for all plans targeting this project (unless the plan overrides it).
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> project create <span style="color: cyan;">--description</span> <span style="color: #66cc66;">"Backend API"</span> local/api-service
╭─ Project ──────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/api-service │
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> Backend API │
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> local │
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-08 12:46 │
╰────────────────────────────────╯
╭─ Paths ────────────────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Root:</span> /repos/api-service │
│ <span style="color: #5599ff; font-weight: 600;">Data Dir:</span> /repos/api-service/.cleveragents │
╰────────────────────────────────────────────╯
╭─ Defaults ──────────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Sandbox:</span> git_worktree │
│ <span style="color: #66cc66; font-weight: 600;">Validations:</span> 0 │
│ <span style="color: yellow; font-weight: 600;">Context Filters:</span> none │
│ <span style="color: magenta; font-weight: 600;">Automation Profile:</span> (inherits global) │
╰─────────────────────────────────────────╯
╭─ Resources ──────╮
│ <span style="color: yellow; font-weight: 600;">Total:</span> 0 │
│ <span style="color: #5599ff; font-weight: 600;">Indexed:</span> 0 │
│ <span style="color: #5599ff; font-weight: 600;">Sandboxable:</span> 0 │
╰──────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Project created
</code></pre></div>
=== "Plain"
```
$ agents project create --description "Backend API" local/api-service
Project
Name: local/api-service
Description: Backend API
Type: local
Created: 2026-02-08 12:46
Paths
Root: /repos/api-service
Data Dir: /repos/api-service/.cleveragents
Defaults
Sandbox: git_worktree
Validations: 0
Context Filters: none
Automation Profile: (inherits global)
Resources
Total: 0
Indexed: 0
Sandboxable: 0
[OK] Project created
```
=== "JSON"
```json
{
"command": "agents project create --description \"Backend API\" local/api-service",
"status": "ok",
"exit_code": 0,
"data": {
"project": {
"name": "local/api-service",
"description": "Backend API",
"type": "local",
"created": "2026-02-08T12:46:00Z"
},
"paths": {
"root": "/repos/api-service",
"data_dir": "/repos/api-service/.cleveragents"
},
"defaults": {
"sandbox": "git_worktree",
"validations": 0,
"context_filters": null,
"automation_profile": null
},
"resources": {
"total": 0,
"indexed": 0,
"sandboxable": 0
}
},
"timing": { "duration_ms": 85 },
"messages": [{ "level": "ok", "text": "Project created" }]
}
```
=== "YAML"
```yaml
command: agents project create --description "Backend API" local/api-service
status: ok
exit_code: 0
data:
project:
name: local/api-service
description: Backend API
type: local
created: "2026-02-08T12:46:00Z"
paths:
root: /repos/api-service
data_dir: /repos/api-service/.cleveragents
defaults:
sandbox: git_worktree
validations: 0
context_filters: null
automation_profile: null
resources:
total: 0
indexed: 0
sandboxable: 0
timing:
duration_ms: 85
messages:
- level: ok
text: Project created
```
Creating a project with resources and invariants in one command:
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> project create <span style="color: cyan;">-d</span> <span style="color: #66cc66;">"Frontend web application"</span> \
<span style="color: cyan;">--resource</span> local/web-repo <span style="color: cyan;">--resource</span> local/web-db \
<span style="color: cyan;">--invariant</span> <span style="color: #66cc66;">"All components must have unit tests"</span> \
<span style="color: cyan;">--invariant</span> <span style="color: #66cc66;">"CSS must pass stylelint checks"</span> \
<span style="color: cyan;">--invariant-actor</span> local/invariant-resolver \
local/web-app
╭─ Project Created ─────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/web-app │
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> Frontend web app │
│ <span style="color: #5599ff; font-weight: 600;">Remote:</span> no │
╰───────────────────────────────────────╯
╭─ Linked Resources ───────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name</span> <span style="color: cyan; font-weight: 600;">Type</span> <span style="color: cyan; font-weight: 600;">Read-Only</span> │
│ <span style="opacity: 0.7;">───────────────── ────────────── ─────────</span> │
│ local/web-repo git-checkout no │
│ local/web-db local/database no │
╰──────────────────────────────────────────────────────────╯
╭─ Invariants ────────────────────────────────────╮
│ <span style="color: magenta; font-weight: 600;">1.</span> All components must have unit tests │
│ <span style="color: magenta; font-weight: 600;">2.</span> CSS must pass stylelint checks │
│ <span style="color: #5599ff; font-weight: 600;">Reconciliation Actor:</span> local/invariant-resolver │
╰─────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Project created
</code></pre></div>
=== "Plain"
```
$ agents project create -d "Frontend web application" \
--resource local/web-repo --resource local/web-db \
--invariant "All components must have unit tests" \
--invariant "CSS must pass stylelint checks" \
--invariant-actor local/invariant-resolver \
local/web-app
Project Created
Name: local/web-app
Description: Frontend web app
Remote: no
Linked Resources
Name Type Read-Only
----------------- -------------- ---------
local/web-repo git-checkout no
local/web-db local/database no
Invariants
1. All components must have unit tests
2. CSS must pass stylelint checks
Reconciliation Actor: local/invariant-resolver
[OK] Project created
```
=== "JSON"
```json
{
"command": "agents project create -d \"Frontend web application\" --resource local/web-repo --resource local/web-db --invariant \"All components must have unit tests\" --invariant \"CSS must pass stylelint checks\" --invariant-actor local/invariant-resolver local/web-app",
"status": "ok",
"exit_code": 0,
"data": {
"project": {
"name": "local/web-app",
"description": "Frontend web app",
"remote": false
},
"linked_resources": [
{ "name": "local/web-repo", "type": "git-checkout", "read_only": false },
{ "name": "local/web-db", "type": "local/database", "read_only": false }
],
"invariants": {
"items": [
"All components must have unit tests",
"CSS must pass stylelint checks"
],
"reconciliation_actor": "local/invariant-resolver"
}
},
"timing": { "duration_ms": 120 },
"messages": [{ "level": "ok", "text": "Project created" }]
}
```
=== "YAML"
```yaml
command: agents project create -d "Frontend web application" --resource local/web-repo --resource local/web-db --invariant "All components must have unit tests" --invariant "CSS must pass stylelint checks" --invariant-actor local/invariant-resolver local/web-app
status: ok
exit_code: 0
data:
project:
name: local/web-app
description: Frontend web app
remote: false
linked_resources:
- name: local/web-repo
type: git-checkout
read_only: false
- name: local/web-db
type: local/database
read_only: false
invariants:
items:
- All components must have unit tests
- CSS must pass stylelint checks
reconciliation_actor: local/invariant-resolver
timing:
duration_ms: 120
messages:
- level: ok
text: Project created
```
agents project link-resource
agents project link-resource [--read-only] <PROJECT> <RESOURCE>Purpose
Link a registered resource to a project. The resource must already be registered via agents resource add. A resource can be linked to multiple projects. Optionally, the resource can be marked as read-only within this project context, and given an alias for convenience.
Arguments
<PROJECT>: Project name (positional argument).<RESOURCE>: Resource name or ULID (positional argument).--read-only: Mark the resource as read-only within this project (even if the resource itself is writable).
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource add git-checkout local/api-repo <span style="color: cyan;">--path</span> /repos/api <span style="color: cyan;">--branch</span> main
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> project link-resource local/api-service local/api-repo
╭─ Resource Linked ───────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Project:</span> local/api-service │
│ <span style="color: #5599ff; font-weight: 600;">Resource:</span> local/api-repo │
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> git-checkout │
│ <span style="color: #5599ff; font-weight: 600;">Read-Only:</span> no │
╰─────────────────────────────────────────╯
╭─ Access ─────────────────╮
│ <span style="color: #66cc66; font-weight: 600;">Read:</span> allowed │
│ <span style="color: yellow; font-weight: 600;">Write:</span> allowed │
│ <span style="color: #5599ff; font-weight: 600;">Apply:</span> requires approval │
╰──────────────────────────╯
╭─ Indexing ─────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Status:</span> indexing... │
│ <span style="color: #5599ff; font-weight: 600;">Files Found:</span> 347 │
│ <span style="color: #5599ff; font-weight: 600;">Language:</span> Python (primary) │
│ <span style="color: #5599ff; font-weight: 600;">Estimated Time:</span> ~20 seconds │
╰────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Resource linked to project
</code></pre></div>
=== "Plain"
```
$ agents resource add git-checkout local/api-repo --path /repos/api --branch main
$ agents project link-resource local/api-service local/api-repo
Resource Linked
Project: local/api-service
Resource: local/api-repo
Type: git-checkout
Read-Only: no
Access
Read: allowed
Write: allowed
Apply: requires approval
Indexing
Status: indexing...
Files Found: 347
Language: Python (primary)
Estimated Time: ~20 seconds
[OK] Resource linked to project
```
=== "JSON"
```json
{
"command": "agents project link-resource local/api-service local/api-repo",
"status": "ok",
"exit_code": 0,
"data": {
"resource_linked": {
"project": "local/api-service",
"resource": "local/api-repo",
"type": "git-checkout",
"read_only": false
},
"access": {
"read": "allowed",
"write": "allowed",
"apply": "requires approval"
},
"indexing": {
"status": "indexing",
"files_found": 347,
"language": "Python (primary)",
"estimated_time_seconds": 20
}
},
"timing": { "duration_ms": 92 },
"messages": [{ "level": "ok", "text": "Resource linked to project" }]
}
```
=== "YAML"
```yaml
command: agents project link-resource local/api-service local/api-repo
status: ok
exit_code: 0
data:
resource_linked:
project: local/api-service
resource: local/api-repo
type: git-checkout
read_only: false
access:
read: allowed
write: allowed
apply: requires approval
indexing:
status: indexing
files_found: 347
language: Python (primary)
estimated_time_seconds: 20
timing:
duration_ms: 92
messages:
- level: ok
text: Resource linked to project
```
agents project unlink-resource
agents project unlink-resource [--yes|-y] <PROJECT> <RESOURCE_NAME>Purpose Unlink a resource from a project. The resource itself remains registered in the Resource Registry and can still be linked to other projects. Active plans using this resource in this project context will be warned.
Arguments
<PROJECT>: Project name (positional argument).<RESOURCE_NAME>: Resource name (positional argument). Only user-added (named) resources can be unlinked.--yes, -y: Skip confirmation prompt.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> project unlink-resource local/api-service local/api-repo
Unlink local/api-repo from local/api-service? [y/N]: y
╭─ Resource Unlinked ─────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Project:</span> local/api-service │
│ <span style="color: #5599ff; font-weight: 600;">Resource:</span> local/api-repo │
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> git-checkout │
╰─────────────────────────────────────────────────────╯
╭─ Index Cleanup ──────────╮
│ <span style="color: yellow; font-weight: 600;">Text Index:</span> 347 removed │
│ <span style="color: yellow; font-weight: 600;">Vectors:</span> 892 removed │
│ <span style="color: yellow; font-weight: 600;">Graph Triples:</span> cleared │
│ <span style="color: #66cc66; font-weight: 600;">Duration:</span> 0.3s │
╰──────────────────────────╯
╭─ Project Summary ──────────────╮
│ <span style="color: yellow; font-weight: 600;">Linked Resources:</span> 1 remaining │
│ <span style="color: #66cc66; font-weight: 600;">Last Updated:</span> 2026-02-09 10:30 │
│ <span style="color: #5599ff; font-weight: 600;">Active Plans:</span> 0 │
╰────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Resource unlinked from project
</code></pre></div>
=== "Plain"
```
$ agents project unlink-resource local/api-service local/api-repo
Unlink local/api-repo from local/api-service? [y/N]: y
Resource Unlinked
Project: local/api-service
Resource: local/api-repo
Type: git-checkout
Index Cleanup
Text Index: 347 removed
Vectors: 892 removed
Graph Triples: cleared
Duration: 0.3s
Project Summary
Linked Resources: 1 remaining
Last Updated: 2026-02-09 10:30
Active Plans: 0
[OK] Resource unlinked from project
```
=== "JSON"
```json
{
"command": "agents project unlink-resource local/api-service local/api-repo",
"status": "ok",
"exit_code": 0,
"data": {
"resource_unlinked": {
"project": "local/api-service",
"resource": "local/api-repo",
"type": "git-checkout"
},
"index_cleanup": {
"text_index": "347 removed",
"vectors": "892 removed",
"graph_triples": "cleared",
"duration_seconds": 0.3
},
"project_summary": {
"linked_resources": 1,
"last_updated": "2026-02-09T10:30:00Z",
"active_plans": 0
}
},
"timing": { "duration_ms": 340 },
"messages": [{ "level": "ok", "text": "Resource unlinked from project" }]
}
```
=== "YAML"
```yaml
command: agents project unlink-resource local/api-service local/api-repo
status: ok
exit_code: 0
data:
resource_unlinked:
project: local/api-service
resource: local/api-repo
type: git-checkout
index_cleanup:
text_index: 347 removed
vectors: 892 removed
graph_triples: cleared
duration_seconds: 0.3
project_summary:
linked_resources: 1
last_updated: "2026-02-09T10:30:00Z"
active_plans: 0
timing:
duration_ms: 340
messages:
- level: ok
text: Resource unlinked from project
```
agents project list
agents project list [(--namespace|-n) NS] [<REGEX>]Purpose List projects with optional filters.
Arguments
--namespace/-n NS: Filter by namespace.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> <span style="color: cyan;">--format</span> table project list
╭─ Projects ────────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name</span> <span style="color: cyan; font-weight: 600;">Resources</span> <span style="color: cyan; font-weight: 600;">Remote</span> <span style="color: cyan; font-weight: 600;">Active Plans</span> │
│ <span style="opacity: 0.7;">───────────────── ───────── ────── ────────────</span> │
│ local/api-service 2 No 1 │
│ local/docs 1 No 0 │
╰───────────────────────────────────────────────────────────────╯
╭─ Summary ──────────────────╮
│ <span style="color: yellow; font-weight: 600;">Total:</span> 2 │
│ <span style="color: #66cc66; font-weight: 600;">With Resources:</span> 2 │
│ <span style="color: #5599ff; font-weight: 600;">Remote:</span> 0 │
│ <span style="color: #5599ff; font-weight: 600;">Total Resources:</span> 3 │
│ <span style="color: #5599ff; font-weight: 600;">Indexed Files:</span> 1,247 │
│ <span style="color: yellow; font-weight: 600;">Active Plans:</span> 1 │
╰────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 2 projects listed
</code></pre></div>
=== "Plain"
```
$ agents --format table project list
Projects
Name Resources Remote Active Plans
----------------- --------- ------ ------------
local/api-service 2 No 1
local/docs 1 No 0
Summary
Total: 2
With Resources: 2
Remote: 0
Total Resources: 3
Indexed Files: 1,247
Active Plans: 1
[OK] 2 projects listed
```
=== "JSON"
```json
{
"command": "agents --format table project list",
"status": "ok",
"exit_code": 0,
"data": {
"projects": [
{ "name": "local/api-service", "resources": 2, "remote": false, "active_plans": 1 },
{ "name": "local/docs", "resources": 1, "remote": false, "active_plans": 0 }
],
"summary": {
"total": 2,
"with_resources": 2,
"remote": 0,
"total_resources": 3,
"indexed_files": 1247,
"active_plans": 1
}
},
"timing": { "duration_ms": 45 },
"messages": [{ "level": "ok", "text": "2 projects listed" }]
}
```
=== "YAML"
```yaml
command: agents --format table project list
status: ok
exit_code: 0
data:
projects:
- name: local/api-service
resources: 2
remote: false
active_plans: 1
- name: local/docs
resources: 1
remote: false
active_plans: 0
summary:
total: 2
with_resources: 2
remote: 0
total_resources: 3
indexed_files: 1247
active_plans: 1
timing:
duration_ms: 45
messages:
- level: ok
text: 2 projects listed
```
agents project show
agents project show <PROJECT>Purpose Show full project details.
Arguments
<NAME>: Project name.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> project show local/api-service
╭─ Project Details ──────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/api-service │
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> Backend API │
│ <span style="color: yellow; font-weight: 600;">Resources:</span> 2 │
│ <span style="color: #66cc66; font-weight: 600;">Remote:</span> no │
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-08 12:46 │
╰────────────────────────────────╯
╭─ Linked Resources ──────────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Resource</span> <span style="color: cyan; font-weight: 600;">Type</span> <span style="color: cyan; font-weight: 600;">Sandbox</span> <span style="color: cyan; font-weight: 600;">Read-Only</span> │
│ <span style="opacity: 0.7;">──────────────── ────────────── ──────────────────── ─────────</span> │
│ local/api-repo git-checkout git_worktree no │
│ local/staging-db local/database transaction_rollback yes │
╰─────────────────────────────────────────────────────────────────────────╯
╭─ Validations (3) ──────────────────────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">local/run-tests</span> Run unit tests with coverage <span style="color: #66cc66; font-weight: 600;">required</span> │
│ <span style="opacity: 0.7;">resource: local/api-repo scope: project (attachment: 01HXM5A1B2C3D4E5F6G7…)</span> │
│ <span style="color: cyan; font-weight: 600;">local/lint-check</span> Lint check <span style="color: #66cc66; font-weight: 600;">required</span> │
│ <span style="opacity: 0.7;">resource: local/api-repo scope: direct (always active) (attachment: 01HXM5…)</span> │
│ <span style="color: cyan; font-weight: 600;">local/check-bundle-size</span> Check bundle size (advisory) <span style="color: yellow; font-weight: 600;">informational</span> │
│ <span style="opacity: 0.7;">resource: local/api-repo scope: project (attachment: 01HXM5D4E5F6G7H8J9…)</span> │
╰────────────────────────────────────────────────────────────────────────────────────╯
╭─ Context ───────────────────╮
│ <span style="color: #66cc66; font-weight: 600;">Include:</span> repo │
│ <span style="color: yellow; font-weight: 600;">Exclude:</span> **/node_modules/** │
│ <span style="color: #5599ff; font-weight: 600;">Max File Size:</span> 1 MB │
╰─────────────────────────────╯
╭─ Indexing Status ──────────╮
│ <span style="color: #66cc66; font-weight: 600;">Text Index:</span> ready │
│ <span style="color: #66cc66; font-weight: 600;">Vector Index:</span> ready │
│ <span style="color: yellow; font-weight: 600;">Graph Store:</span> disabled │
│ <span style="color: #5599ff; font-weight: 600;">Indexed Files:</span> 347 │
│ <span style="color: #5599ff; font-weight: 600;">Last Indexed:</span> 12:48 │
╰────────────────────────────╯
╭─ Active Plans ──────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Plan ID</span> <span style="color: cyan; font-weight: 600;">Action</span> <span style="color: cyan; font-weight: 600;">Phase</span> │
│ <span style="opacity: 0.7;">──────── ─────────────────── ───────</span> │
│ 01HXM7A9 local/code-coverage execute │
╰─────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Project loaded
</code></pre></div>
=== "Plain"
```
$ agents project show local/api-service
Project Details
Name: local/api-service
Description: Backend API
Resources: 2
Remote: no
Created: 2026-02-08 12:46
Linked Resources
Resource Type Sandbox Read-Only
---------------- -------------- -------------------- ---------
local/api-repo git-checkout git_worktree no
local/staging-db local/database transaction_rollback yes
Validations (3)
local/run-tests Run unit tests with coverage required
resource: local/api-repo scope: project (attachment: 01HXM5A1B2C3D4E5F6G7...)
local/lint-check Lint check required
resource: local/api-repo scope: direct (always active) (attachment: 01HXM5...)
local/check-bundle-size Check bundle size (advisory) informational
resource: local/api-repo scope: project (attachment: 01HXM5D4E5F6G7H8J9...)
Context
Include: repo
Exclude: **/node_modules/**
Max File Size: 1 MB
Indexing Status
Text Index: ready
Vector Index: ready
Graph Store: disabled
Indexed Files: 347
Last Indexed: 12:48
Active Plans
Plan ID Action Phase
-------- ------------------- -------
01HXM7A9 local/code-coverage execute
[OK] Project loaded
```
=== "JSON"
```json
{
"command": "agents project show local/api-service",
"status": "ok",
"exit_code": 0,
"data": {
"project": {
"name": "local/api-service",
"description": "Backend API",
"resources": 2,
"remote": false,
"created": "2026-02-08T12:46:00Z"
},
"linked_resources": [
{ "name": "local/api-repo", "type": "git-checkout", "sandbox": "git_worktree", "read_only": false },
{ "name": "local/staging-db", "type": "local/database", "sandbox": "transaction_rollback", "read_only": true }
],
"validations": [
{
"name": "local/run-tests",
"description": "Run unit tests with coverage",
"mode": "required",
"resource": "local/api-repo",
"scope": "project",
"attachment_id": "01HXM5A1B2C3D4E5F6G7"
},
{
"name": "local/lint-check",
"description": "Lint check",
"mode": "required",
"resource": "local/api-repo",
"scope": "direct",
"attachment_id": "01HXM5"
},
{
"name": "local/check-bundle-size",
"description": "Check bundle size (advisory)",
"mode": "informational",
"resource": "local/api-repo",
"scope": "project",
"attachment_id": "01HXM5D4E5F6G7H8J9"
}
],
"context": {
"include": ["repo"],
"exclude": ["**/node_modules/**"],
"max_file_size_bytes": 1048576
},
"indexing_status": {
"text_index": "ready",
"vector_index": "ready",
"graph_store": "disabled",
"indexed_files": 347,
"last_indexed": "12:48"
},
"active_plans": [
{ "plan_id": "01HXM7A9", "action": "local/code-coverage", "phase": "execute" }
]
},
"timing": { "duration_ms": 62 },
"messages": [{ "level": "ok", "text": "Project loaded" }]
}
```
=== "YAML"
```yaml
command: agents project show local/api-service
status: ok
exit_code: 0
data:
project:
name: local/api-service
description: Backend API
resources: 2
remote: false
created: "2026-02-08T12:46:00Z"
linked_resources:
- name: local/api-repo
type: git-checkout
sandbox: git_worktree
read_only: false
- name: local/staging-db
type: local/database
sandbox: transaction_rollback
read_only: true
validations:
- name: local/run-tests
description: Run unit tests with coverage
mode: required
resource: local/api-repo
scope: project
attachment_id: 01HXM5A1B2C3D4E5F6G7
- name: local/lint-check
description: Lint check
mode: required
resource: local/api-repo
scope: direct
attachment_id: 01HXM5
- name: local/check-bundle-size
description: Check bundle size (advisory)
mode: informational
resource: local/api-repo
scope: project
attachment_id: 01HXM5D4E5F6G7H8J9
context:
include:
- repo
exclude:
- "**/node_modules/**"
max_file_size_bytes: 1048576
indexing_status:
text_index: ready
vector_index: ready
graph_store: disabled
indexed_files: 347
last_indexed: "12:48"
active_plans:
- plan_id: 01HXM7A9
action: local/code-coverage
phase: execute
timing:
duration_ms: 62
messages:
- level: ok
text: Project loaded
```
agents project validations
Note: Validations are managed as a top-level entity via agents validation commands (see the agents validation section below). A validation is always attached to a resource, but can optionally be scoped to a project via agents validation attach --project <PROJECT> <RESOURCE> <VALIDATION>. When scoped to a project, the validation only runs when that resource is accessed through the specified project. The agents project show command displays all validations relevant to the project — both directly-attached validations on linked resources and project-scoped validations.
See: agents validation for full details on creating, managing, and attaching validations.
agents project delete
agents project delete [--force|-f] [--yes|-y] <NAME>!!! warning "Irreversible Action"
Deleting a project ==cannot be undone==. All resource links, validation attachments, and context policies will be removed. The resources themselves remain in the Resource Registry. Use `--force` to also cancel active plans targeting this project.
Purpose Delete a project and unlink all associated resources. The resources themselves remain in the Resource Registry.
Arguments
<NAME>: Project name.--force/-f: Delete even if active plans exist.--yes: Skip confirmation prompt.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> project delete local/docs
Delete project local/docs? This cannot be undone. [y/N]: y
╭─ Deletion Summary ──────────────────╮
│ <span style="color: cyan; font-weight: 600;">Project:</span> local/docs │
│ <span style="color: yellow; font-weight: 600;">Resources:</span> 1 unlinked │
│ <span style="color: #5599ff; font-weight: 600;">Data Dir:</span> /repos/docs/.cleveragents │
╰─────────────────────────────────────╯
╭─ Index Cleanup ────────╮
│ <span style="color: yellow; font-weight: 600;">Text Index:</span> cleared │
│ <span style="color: yellow; font-weight: 600;">Vectors:</span> 240 removed │
│ <span style="color: yellow; font-weight: 600;">Graph Triples:</span> none │
│ <span style="color: #5599ff; font-weight: 600;">Storage Freed:</span> 12 MB │
╰────────────────────────╯
╭─ Backups ────────────────────────────────────╮
│ <span style="color: #66cc66; font-weight: 600;">Snapshot:</span> /backups/local-docs-2026-02-08.tgz │
│ <span style="color: yellow; font-weight: 600;">Retention:</span> 7 days │
╰──────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Project deleted
</code></pre></div>
=== "Plain"
```
$ agents project delete local/docs
Delete project local/docs? This cannot be undone. [y/N]: y
Deletion Summary
Project: local/docs
Resources: 1 unlinked
Data Dir: /repos/docs/.cleveragents
Index Cleanup
Text Index: cleared
Vectors: 240 removed
Graph Triples: none
Storage Freed: 12 MB
Backups
Snapshot: /backups/local-docs-2026-02-08.tgz
Retention: 7 days
[OK] Project deleted
```
=== "JSON"
```json
{
"command": "agents project delete local/docs",
"status": "ok",
"exit_code": 0,
"data": {
"deletion_summary": {
"project": "local/docs",
"resources_unlinked": 1,
"data_dir": "/repos/docs/.cleveragents"
},
"index_cleanup": {
"text_index": "cleared",
"vectors": "240 removed",
"graph_triples": "none",
"storage_freed_mb": 12
},
"backups": {
"snapshot": "/backups/local-docs-2026-02-08.tgz",
"retention_days": 7
}
},
"timing": { "duration_ms": 530 },
"messages": [{ "level": "ok", "text": "Project deleted" }]
}
```
=== "YAML"
```yaml
command: agents project delete local/docs
status: ok
exit_code: 0
data:
deletion_summary:
project: local/docs
resources_unlinked: 1
data_dir: /repos/docs/.cleveragents
index_cleanup:
text_index: cleared
vectors: 240 removed
graph_triples: none
storage_freed_mb: 12
backups:
snapshot: /backups/local-docs-2026-02-08.tgz
retention_days: 7
timing:
duration_ms: 530
messages:
- level: ok
text: Project deleted
```
Attempting to delete a project that has active plans (without --force):
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> project delete local/api-service
Delete project local/api-service? [y/N]: y
╭─ Delete Blocked ──────────────────────────────────────────╮
│ <span style="color: #ff6666; font-weight: 600;">Cannot delete:</span> project has active plans │
│ <span style="color: #5599ff; font-weight: 600;">Active Plans:</span> 2 │
│ <span style="opacity: 0.7;">01HXM7A9 — execute/processing (local/code-coverage)</span> │
│ <span style="opacity: 0.7;">01HXM4J1 — strategize/processing (local/refactor-api)</span> │
╰───────────────────────────────────────────────────────────╯
╭─ Resolution ──────────────────────────────────────────────────────╮
│ - Cancel or complete active plans first, or │
│ - Use <span style="color: cyan;">--force</span> to cancel all active plans and delete the project │
╰───────────────────────────────────────────────────────────────────╯
<span style="color: #ff6666; font-weight: 600;">✗ ERROR</span> Delete blocked — 2 active plans
</code></pre></div>
=== "Plain"
```
$ agents project delete local/api-service
Delete project local/api-service? [y/N]: y
Delete Blocked
Cannot delete: project has active plans
Active Plans: 2
01HXM7A9 -- execute/processing (local/code-coverage)
01HXM4J1 -- strategize/processing (local/refactor-api)
Resolution
- Cancel or complete active plans first, or
- Use --force to cancel all active plans and delete the project
[ERROR] Delete blocked -- 2 active plans
```
=== "JSON"
```json
{
"command": "agents project delete local/api-service",
"status": "error",
"exit_code": 1,
"data": {
"delete_blocked": {
"reason": "project has active plans",
"active_plans": [
{ "plan_id": "01HXM7A9", "phase": "execute/processing", "action": "local/code-coverage" },
{ "plan_id": "01HXM4J1", "phase": "strategize/processing", "action": "local/refactor-api" }
]
},
"resolution": [
"Cancel or complete active plans first",
"Use --force to cancel all active plans and delete the project"
]
},
"timing": { "duration_ms": 38 },
"messages": [{ "level": "error", "text": "Delete blocked — 2 active plans" }]
}
```
=== "YAML"
```yaml
command: agents project delete local/api-service
status: error
exit_code: 1
data:
delete_blocked:
reason: project has active plans
active_plans:
- plan_id: 01HXM7A9
phase: execute/processing
action: local/code-coverage
- plan_id: 01HXM4J1
phase: strategize/processing
action: local/refactor-api
resolution:
- Cancel or complete active plans first
- Use --force to cancel all active plans and delete the project
timing:
duration_ms: 38
messages:
- level: error
text: "Delete blocked \u2014 2 active plans"
```
Force-deleting a project with active plans:
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> project delete <span style="color: cyan;">--force</span> <span style="color: cyan;">--yes</span> local/api-service
╭─ Force Delete ─────────────────────────────────────────╮
│ <span style="color: yellow; font-weight: 600;">Cancelling:</span> 2 active plans │
│ <span style="opacity: 0.7;">01HXM7A9 — cancelled (was execute/processing)</span> │
│ <span style="opacity: 0.7;">01HXM4J1 — cancelled (was strategize/processing)</span> │
╰────────────────────────────────────────────────────────╯
╭─ Deleted ────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Project:</span> local/api-service │
│ <span style="color: #5599ff; font-weight: 600;">Resources Unlinked:</span> 2 │
│ <span style="color: #5599ff; font-weight: 600;">Validations Detached:</span> 3 │
│ <span style="color: #5599ff; font-weight: 600;">Plans Cancelled:</span> 2 │
│ <span style="color: #5599ff; font-weight: 600;">Context Policies:</span> cleared │
╰──────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Project force-deleted
</code></pre></div>
=== "Plain"
```
$ agents project delete --force --yes local/api-service
Force Delete
Cancelling: 2 active plans
01HXM7A9 -- cancelled (was execute/processing)
01HXM4J1 -- cancelled (was strategize/processing)
Deleted
Project: local/api-service
Resources Unlinked: 2
Validations Detached: 3
Plans Cancelled: 2
Context Policies: cleared
[OK] Project force-deleted
```
=== "JSON"
```json
{
"command": "agents project delete --force --yes local/api-service",
"status": "ok",
"exit_code": 0,
"data": {
"force_delete": {
"cancelled_plans": [
{ "plan_id": "01HXM7A9", "previous_state": "execute/processing" },
{ "plan_id": "01HXM4J1", "previous_state": "strategize/processing" }
]
},
"deleted": {
"project": "local/api-service",
"resources_unlinked": 2,
"validations_detached": 3,
"plans_cancelled": 2,
"context_policies": "cleared"
}
},
"timing": { "duration_ms": 245 },
"messages": [{ "level": "ok", "text": "Project force-deleted" }]
}
```
=== "YAML"
```yaml
command: agents project delete --force --yes local/api-service
status: ok
exit_code: 0
data:
force_delete:
cancelled_plans:
- plan_id: 01HXM7A9
previous_state: execute/processing
- plan_id: 01HXM4J1
previous_state: strategize/processing
deleted:
project: local/api-service
resources_unlinked: 2
validations_detached: 3
plans_cancelled: 2
context_policies: cleared
timing:
duration_ms: 245
messages:
- level: ok
text: Project force-deleted
```
agents project context
Purpose Manage ACMS context policies for the hot/warm/cold tiers, per-view context selection, strategy configuration, UKO depth/breadth parameters, and context budget tuning.
agents project context set
agents project context set[--view (strategize|execute|apply|default)]
[--include-resource <INCLUDE_RESOURCE>]...
[--exclude-resource <EXCLUDE_RESOURCE>]...
[--include-path <INCLUDE_GLOB>]...
[--exclude-path <EXCLUDE_GLOB>]...
[--hot-max-tokens <N>]
[--warm-max-decisions <N_WARM_MAX>]
[--cold-max-decisions <N_COLD_MAX>]
[--query-limit <N>]
[--max-file-size <MAX_FILE_BYTES>]
[--max-total-size <MAX_TOTAL_BYTES>]
[--summarize|--no-summarize]
[--summary-max-tokens <N>]
[--strategy <STRATEGY>]...
[--default-breadth <N>]
[--default-depth <INT_OR_NAME>]
[--depth-gradient <HOP:INT_OR_NAME>]...
[--skeleton-ratio <FLOAT>]
[--temporal-scope (current|recent|all)]
[--auto-refresh|--no-auto-refresh]
[--execution-environment <RESOURCE_NAME>]
[--execution-env-priority (fallback|override)]
[--clear] <PROJECT>Purpose Set the context policy for a project and (optionally) a specific view.
Arguments
<PROJECT>: Project name (positional argument, at end of command).--view strategize|execute|apply|default: Which view this policy applies to.--include-resource NAME: Resource allowlist (repeatable).--exclude-resource NAME: Resource denylist (repeatable).--include-path GLOB: Path allowlist (repeatable).--exclude-path GLOB: Path denylist (repeatable).--hot-max-tokens N: Maximum token budget for hot context. This is a soft cap and may be null. The actor/LLM hard limit can be lower; the effective hot context is the lesser of the two.--warm-max-decisions N: Maximum number of decisions kept in warm context.--cold-max-decisions N: Maximum number of decisions kept in cold context.--query-limit N: Max number of retrieval results per query.--max-file-size BYTES: Max file size included in context.--max-total-size BYTES: Max total size across included files.--summarize/--no-summarize: Enable or disable summarization for large context segments.--summary-max-tokens N: Token limit for generated summaries.--strategy STRATEGY: ACMS context strategy to enable for this view (repeatable). Overrides the globalcontext.strategies.enabledlist. Built-in:simple-keyword,semantic-embedding,breadth-depth-navigator,arce,temporal-archaeology,plan-decision-context.--default-breadth N: Default number of hops from focus nodes in the UKO graph.0= focus nodes only. Default:2.--default-depth INT_OR_NAME: Default detail depth for context fragments. Accepts a raw integer (e.g.,4) or a named level from the active domain's DetailLevelMap (e.g.,SIGNATURES,MEMBER_SUMMARY). Named levels are resolved to integers via the DetailLevelMap inheritance chain. Default:3(typicallyMEMBER_SUMMARY/FULL_TOC/TYPED_COLUMNSdepending on domain).--depth-gradient HOP:INT_OR_NAME: Per-hop detail depth override (repeatable). Format:0:9,1:4,2:0or0:FULL_SOURCE,1:SIGNATURES,2:MODULE_LISTING. Hops not specified use--default-depth.--skeleton-ratio FLOAT: Fraction of context budget reserved for inherited plan skeleton. Range: 0.0–1.0. Default:0.15.--temporal-scope current|recent|all: Temporal scope for UKO node resolution. Default:current.--auto-refresh/--no-auto-refresh: Enable or disable automatic context re-assembly on budget changes.--execution-environment RESOURCE_NAME: Name of acontainer-instanceordevcontainer-instanceresource to use as the default execution environment for this project. When set, tool invocations during plan execution are routed to this container unless overridden at the plan level. See ADR-043 §3.3.--execution-env-priority fallback|override: Priority semantics for the project-level execution environment.fallback(default): defers to auto-detected devcontainers when present; used only when no closer-scoped environment exists.override: always uses the specified environment, bypassing devcontainer auto-detection. See §Execution Environment Routing.--clear: Clear the policy for the selected view.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> project context set <span style="color: cyan;">--view</span> strategize \
<span style="color: cyan;">--include-resource</span> repo <span style="color: cyan;">--exclude-path</span> <span style="color: #66cc66;">"**/node_modules/**"</span> \
<span style="color: cyan;">--hot-max-tokens</span> 12000 <span style="color: cyan;">--warm-max-decisions</span> 50 <span style="color: cyan;">--cold-max-decisions</span> 200 \
<span style="color: cyan;">--summarize</span> <span style="color: cyan;">--summary-max-tokens</span> 800 local/api-service
╭─ Context Policy ────────────╮
│ <span style="color: cyan; font-weight: 600;">Project:</span> local/api-service │
│ <span style="color: #5599ff; font-weight: 600;">View:</span> strategize │
│ <span style="color: #66cc66; font-weight: 600;">Include:</span> repo │
│ <span style="color: yellow; font-weight: 600;">Exclude:</span> **/node_modules/** │
╰─────────────────────────────╯
╭─ Limits ─────────────────────╮
│ <span style="color: magenta; font-weight: 600;">Hot Tokens:</span> 12000 (soft cap) │
│ <span style="color: magenta; font-weight: 600;">Warm Decisions:</span> 50 │
│ <span style="color: magenta; font-weight: 600;">Cold Decisions:</span> 200 │
│ <span style="color: #5599ff; font-weight: 600;">Query Limit:</span> 20 │
│ <span style="color: #5599ff; font-weight: 600;">Max File Size:</span> 1 MB │
│ <span style="color: #5599ff; font-weight: 600;">Max Total Size:</span> 50 MB │
╰──────────────────────────────╯
╭─ Summarization ─╮
│ <span style="color: #66cc66; font-weight: 600;">Enabled:</span> yes │
│ <span style="color: #5599ff; font-weight: 600;">Max Tokens:</span> 800 │
╰─────────────────╯
╭─ Other Views ────────╮
│ <span style="color: #5599ff; font-weight: 600;">execute:</span> (default) │
│ <span style="color: #5599ff; font-weight: 600;">apply:</span> (default) │
│ <span style="color: #5599ff; font-weight: 600;">default:</span> (unset) │
╰──────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Context policy updated
</code></pre></div>
=== "Plain"
```
$ agents project context set --view strategize \
--include-resource repo --exclude-path "**/node_modules/**" \
--hot-max-tokens 12000 --warm-max-decisions 50 --cold-max-decisions 200 \
--summarize --summary-max-tokens 800 local/api-service
Context Policy
Project: local/api-service
View: strategize
Include: repo
Exclude: **/node_modules/**
Limits
Hot Tokens: 12000 (soft cap)
Warm Decisions: 50
Cold Decisions: 200
Query Limit: 20
Max File Size: 1 MB
Max Total Size: 50 MB
Summarization
Enabled: yes
Max Tokens: 800
Other Views
execute: (default)
apply: (default)
default: (unset)
[OK] Context policy updated
```
=== "JSON"
```json
{
"command": "project context set",
"status": "ok",
"exit_code": 0,
"data": {
"context_policy": {
"project": "local/api-service",
"view": "strategize",
"include_resources": ["repo"],
"exclude_paths": ["**/node_modules/**"]
},
"limits": {
"hot_max_tokens": 12000,
"warm_max_decisions": 50,
"cold_max_decisions": 200,
"query_limit": 20,
"max_file_size": "1 MB",
"max_total_size": "50 MB"
},
"summarization": {
"enabled": true,
"max_tokens": 800
},
"other_views": {
"execute": "(default)",
"apply": "(default)",
"default": "(unset)"
}
},
"timing": {
"duration_ms": 42
},
"messages": ["Context policy updated"]
}
```
=== "YAML"
```yaml
command: project context set
status: ok
exit_code: 0
data:
context_policy:
project: local/api-service
view: strategize
include_resources:
- repo
exclude_paths:
- "**/node_modules/**"
limits:
hot_max_tokens: 12000
warm_max_decisions: 50
cold_max_decisions: 200
query_limit: 20
max_file_size: 1 MB
max_total_size: 50 MB
summarization:
enabled: true
max_tokens: 800
other_views:
execute: (default)
apply: (default)
default: (unset)
timing:
duration_ms: 42
messages:
- Context policy updated
```
agents project context show
agents project context show [--view (strategize|execute|apply|default)]
<PROJECT>Purpose Show the active context policy for a project.
Arguments
<PROJECT>: Project name (positional argument, at end of command).--view strategize|execute|apply|default: View to display.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> project context show <span style="color: cyan;">--view</span> strategize local/api-service
╭─ Context Policy ────────────╮
│ <span style="color: cyan; font-weight: 600;">Project:</span> local/api-service │
│ <span style="color: #5599ff; font-weight: 600;">View:</span> strategize │
│ <span style="color: #66cc66; font-weight: 600;">Include:</span> repo │
│ <span style="color: yellow; font-weight: 600;">Exclude:</span> **/node_modules/** │
╰─────────────────────────────╯
╭─ Limits ─────────────────────╮
│ <span style="color: magenta; font-weight: 600;">Hot Tokens:</span> 12000 (soft cap) │
│ <span style="color: magenta; font-weight: 600;">Warm Decisions:</span> 50 │
│ <span style="color: magenta; font-weight: 600;">Cold Decisions:</span> 200 │
│ <span style="color: #5599ff; font-weight: 600;">Query Limit:</span> 20 │
│ <span style="color: #5599ff; font-weight: 600;">Max File Size:</span> 1 MB │
│ <span style="color: #5599ff; font-weight: 600;">Max Total Size:</span> 50 MB │
╰──────────────────────────────╯
╭─ Summarization ─╮
│ <span style="color: #66cc66; font-weight: 600;">Enabled:</span> yes │
│ <span style="color: #5599ff; font-weight: 600;">Max Tokens:</span> 800 │
╰─────────────────╯
╭─ Current Usage ──────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Hot Context:</span> 8,420 / 12,000 │
│ <span style="color: #5599ff; font-weight: 600;">Warm Entries:</span> 12 / 50 │
│ <span style="color: #5599ff; font-weight: 600;">Cold Entries:</span> 47 / 200 │
│ <span style="color: #66cc66; font-weight: 600;">Indexed Resources:</span> 1 │
╰──────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Context policy loaded
</code></pre></div>
=== "Plain"
```
$ agents project context show --view strategize local/api-service
Context Policy
Project: local/api-service
View: strategize
Include: repo
Exclude: **/node_modules/**
Limits
Hot Tokens: 12000 (soft cap)
Warm Decisions: 50
Cold Decisions: 200
Query Limit: 20
Max File Size: 1 MB
Max Total Size: 50 MB
Summarization
Enabled: yes
Max Tokens: 800
Current Usage
Hot Context: 8,420 / 12,000
Warm Entries: 12 / 50
Cold Entries: 47 / 200
Indexed Resources: 1
[OK] Context policy loaded
```
=== "JSON"
```json
{
"command": "project context show",
"status": "ok",
"exit_code": 0,
"data": {
"context_policy": {
"project": "local/api-service",
"view": "strategize",
"include_resources": ["repo"],
"exclude_paths": ["**/node_modules/**"]
},
"limits": {
"hot_max_tokens": 12000,
"warm_max_decisions": 50,
"cold_max_decisions": 200,
"query_limit": 20,
"max_file_size": "1 MB",
"max_total_size": "50 MB"
},
"summarization": {
"enabled": true,
"max_tokens": 800
},
"current_usage": {
"hot_context_tokens": 8420,
"hot_context_limit": 12000,
"warm_entries": 12,
"warm_limit": 50,
"cold_entries": 47,
"cold_limit": 200,
"indexed_resources": 1
}
},
"timing": {
"duration_ms": 38
},
"messages": ["Context policy loaded"]
}
```
=== "YAML"
```yaml
command: project context show
status: ok
exit_code: 0
data:
context_policy:
project: local/api-service
view: strategize
include_resources:
- repo
exclude_paths:
- "**/node_modules/**"
limits:
hot_max_tokens: 12000
warm_max_decisions: 50
cold_max_decisions: 200
query_limit: 20
max_file_size: 1 MB
max_total_size: 50 MB
summarization:
enabled: true
max_tokens: 800
current_usage:
hot_context_tokens: 8420
hot_context_limit: 12000
warm_entries: 12
warm_limit: 50
cold_entries: 47
cold_limit: 200
indexed_resources: 1
timing:
duration_ms: 38
messages:
- Context policy loaded
```
agents project context inspect
agents project context inspect [--view (strategize|execute|apply|default)]
[--strategy <STRATEGY>]
[--focus <UKO_URI>]...
[--breadth <N>] [--depth <INT_OR_NAME>]
<PROJECT>Purpose Inspect the current state of the ACMS context assembly for a project. Shows the UKO graph structure, active strategies, indexed resources, context budget usage, and the most recent fusion result. Useful for debugging context quality issues.
Arguments
<PROJECT>: Project name (positional argument, at end of command).--view strategize|execute|apply|default: View to inspect. Default:default.--strategy STRATEGY: Filter to show results from a specific strategy only.--focus UKO_URI: Show the UKO subgraph rooted at these focus nodes (repeatable). When omitted, shows a summary of the full indexed graph.--breadth N: Override the breadth (hop count) for the focus node expansion. Default: uses the view'sdefault_breadth.--depth INT_OR_NAME: Override the detail depth for the display. Accepts a raw integer or a named level from the active DetailLevelMap. Default: uses the view'sdefault_depth.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> project context inspect <span style="color: cyan;">--view</span> execute <span style="color: cyan;">--focus</span> uko-py:module/src.auth <span style="color: cyan;">--breadth</span> 2 local/api-service
╭─ ACMS Context Inspection ────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Project:</span> local/api-service │
│ <span style="color: #5599ff; font-weight: 600;">View:</span> execute │
│ <span style="color: #66cc66; font-weight: 600;">Focus:</span> uko-py:module/src.auth │
│ <span style="color: magenta; font-weight: 600;">Breadth:</span> 2 hops │ <span style="color: magenta; font-weight: 600;">Depth:</span> 3 (MEMBER_SUMMARY) │
╰──────────────────────────────────────────────────────────────────╯
╭─ UKO Graph (2-hop neighborhood) ─────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">uko-py:module/src.auth</span> (depth 9/FULL_SOURCE, 1,240 tokens) │
│ ├─ contains → <span style="color: #5599ff;">uko-py:class/AuthHandler</span> (depth 3, 320 tokens) │
│ ├─ contains → <span style="color: #5599ff;">uko-py:class/TokenValidator</span> (depth 3, 280 tok) │
│ ├─ imports → <span style="color: #5599ff;">uko-py:module/src.db</span> (depth 0, 90 tokens) │
│ └─ imports → <span style="color: #5599ff;">uko-py:module/src.config</span> (depth 0, 60 tok) │
╰──────────────────────────────────────────────────────────────────╯
╭─ Active Strategies ──────────────────────────────────────────────╮
│ <span style="color: #66cc66; font-weight: 600;">breadth-depth-navigator</span> quality=0.85 budget=45% 4 fragments │
│ <span style="color: #66cc66; font-weight: 600;">semantic-embedding</span> quality=0.60 budget=35% 6 fragments │
│ <span style="color: #66cc66; font-weight: 600;">simple-keyword</span> quality=0.30 budget=20% 3 fragments │
╰──────────────────────────────────────────────────────────────────╯
╭─ Budget ─────────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Model Window:</span> 128,000 tokens │
│ <span style="color: #5599ff; font-weight: 600;">Response Reserve:</span> 4,096 tokens │
│ <span style="color: #5599ff; font-weight: 600;">Tool Definitions:</span> 2,400 tokens │
│ <span style="color: #5599ff; font-weight: 600;">System Prompt:</span> 1,200 tokens │
│ <span style="color: #5599ff; font-weight: 600;">Skeleton Reserve:</span> 18,046 (15%) │
│ <span style="color: magenta; font-weight: 600;">Available Budget:</span> 102,258 tokens │
│ <span style="color: #66cc66; font-weight: 600;">Used:</span> 1,990 / 102,258 (1.9%) │
╰──────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Context inspection complete
</code></pre></div>
=== "Plain"
```
$ agents project context inspect --view execute --focus uko-py:module/src.auth --breadth 2 local/api-service
ACMS Context Inspection
Project: local/api-service
View: execute
Focus: uko-py:module/src.auth
Breadth: 2 hops Depth: 3 (MEMBER_SUMMARY)
UKO Graph (2-hop neighborhood)
uko-py:module/src.auth (depth 9/FULL_SOURCE, 1,240 tokens)
contains -> uko-py:class/AuthHandler (depth 3, 320 tokens)
contains -> uko-py:class/TokenValidator (depth 3, 280 tok)
imports -> uko-py:module/src.db (depth 0, 90 tokens)
imports -> uko-py:module/src.config (depth 0, 60 tok)
Active Strategies
Strategy Quality Budget Fragments
------------------------- ------- ------ ---------
breadth-depth-navigator 0.85 45% 4
semantic-embedding 0.60 35% 6
simple-keyword 0.30 20% 3
Budget
Model Window: 128,000 tokens
Response Reserve: 4,096 tokens
Tool Definitions: 2,400 tokens
System Prompt: 1,200 tokens
Skeleton Reserve: 18,046 (15%)
Available Budget: 102,258 tokens
Used: 1,990 / 102,258 (1.9%)
[OK] Context inspection complete
```
=== "JSON"
```json
{
"command": "project context inspect",
"status": "ok",
"exit_code": 0,
"data": {
"inspection": {
"project": "local/api-service",
"view": "execute",
"focus": ["uko-py:module/src.auth"],
"breadth": 2,
"depth": 3,
"depth_name": "MEMBER_SUMMARY"
},
"uko_graph": {
"root": "uko-py:module/src.auth",
"root_depth": 9,
"root_depth_name": "FULL_SOURCE",
"root_tokens": 1240,
"edges": [
{ "relation": "contains", "target": "uko-py:class/AuthHandler", "depth": 3, "tokens": 320 },
{ "relation": "contains", "target": "uko-py:class/TokenValidator", "depth": 3, "tokens": 280 },
{ "relation": "imports", "target": "uko-py:module/src.db", "depth": 0, "tokens": 90 },
{ "relation": "imports", "target": "uko-py:module/src.config", "depth": 0, "tokens": 60 }
]
},
"active_strategies": [
{ "name": "breadth-depth-navigator", "quality": 0.85, "budget_pct": 0.45, "fragments": 4 },
{ "name": "semantic-embedding", "quality": 0.60, "budget_pct": 0.35, "fragments": 6 },
{ "name": "simple-keyword", "quality": 0.30, "budget_pct": 0.20, "fragments": 3 }
],
"budget": {
"model_window": 128000,
"response_reserve": 4096,
"tool_definitions": 2400,
"system_prompt": 1200,
"skeleton_reserve": 18046,
"skeleton_ratio": 0.15,
"available_budget": 102258,
"used": 1990,
"utilization": 0.019
}
},
"timing": {
"duration_ms": 185
},
"messages": ["Context inspection complete"]
}
```
=== "YAML"
```yaml
command: project context inspect
status: ok
exit_code: 0
data:
inspection:
project: local/api-service
view: execute
focus:
- uko-py:module/src.auth
breadth: 2
depth: 3
depth_name: MEMBER_SUMMARY
uko_graph:
root: uko-py:module/src.auth
root_depth: 9
root_depth_name: FULL_SOURCE
root_tokens: 1240
edges:
- relation: contains
target: uko-py:class/AuthHandler
depth: 3
tokens: 320
- relation: contains
target: uko-py:class/TokenValidator
depth: 3
tokens: 280
- relation: imports
target: uko-py:module/src.db
depth: 0
tokens: 90
- relation: imports
target: uko-py:module/src.config
depth: 0
tokens: 60
active_strategies:
- name: breadth-depth-navigator
quality: 0.85
budget_pct: 0.45
fragments: 4
- name: semantic-embedding
quality: 0.60
budget_pct: 0.35
fragments: 6
- name: simple-keyword
quality: 0.30
budget_pct: 0.20
fragments: 3
budget:
model_window: 128000
response_reserve: 4096
tool_definitions: 2400
system_prompt: 1200
skeleton_reserve: 18046
skeleton_ratio: 0.15
available_budget: 102258
used: 1990
utilization: 0.019
timing:
duration_ms: 185
messages:
- Context inspection complete
```
agents project context simulate
agents project context simulate [--view (strategize|execute|apply|default)]
[--budget <TOKENS>]
[--focus <UKO_URI>]...
[--strategy <STRATEGY>]...
<PROJECT>Purpose Simulate a context assembly run without invoking an actor. Produces a dry-run report showing what the Context Assembly Pipeline would include in the context payload, which strategies contributed, how the budget was allocated, and what was excluded. Useful for tuning context view configurations before running plans.
Arguments
<PROJECT>: Project name (positional argument, at end of command).--view strategize|execute|apply|default: View to simulate. Default:default.--budget TOKENS: Override the context budget in tokens. When omitted, uses the dynamic budget calculation.--focus UKO_URI: Focus nodes for the simulation (repeatable). When omitted, uses a default focus derived from recent plan activity.--strategy STRATEGY: Override which strategies to run (repeatable). When omitted, uses the view's configured strategies.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> project context simulate <span style="color: cyan;">--view</span> strategize <span style="color: cyan;">--budget</span> 16000 \
<span style="color: cyan;">--focus</span> uko-py:module/src.auth <span style="color: cyan;">--focus</span> uko-py:module/src.db \
local/api-service
╭─ ACMS Simulation ────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Project:</span> local/api-service │
│ <span style="color: #5599ff; font-weight: 600;">View:</span> strategize │
│ <span style="color: magenta; font-weight: 600;">Budget:</span> 16,000 tokens (override) │
│ <span style="color: #66cc66; font-weight: 600;">Focus:</span> uko-py:module/src.auth, uko-py:module/src.db │
╰──────────────────────────────────────────────────────────────────╯
╭─ Strategy Results ───────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">breadth-depth-navigator</span> │
│ Confidence: 0.85 │ Budget: 7,200 tokens │ 12 fragments │
│ Top: src/auth/__init__.py (depth 9, 1,240t, score=0.95) │
│ src/db/models.py (depth 3, 480t, score=0.88) │
│ │
│ <span style="color: cyan; font-weight: 600;">semantic-embedding</span> │
│ Confidence: 0.60 │ Budget: 5,600 tokens │ 8 fragments │
│ Top: src/auth/jwt.py (depth 3, 380t, score=0.82) │
│ src/middleware/auth_check.py (depth 3, 290t, score=0.79) │
│ │
│ <span style="color: cyan; font-weight: 600;">simple-keyword</span> │
│ Confidence: 0.30 │ Budget: 3,200 tokens │ 5 fragments │
│ Top: src/auth/utils.py (depth 6, 210t, score=0.71) │
╰──────────────────────────────────────────────────────────────────╯
╭─ Fusion Result ──────────────────────────────────────────────────╮
│ <span style="color: #66cc66; font-weight: 600;">Included:</span> 18 fragments (14,820 tokens, 92.6% of budget) │
│ <span style="color: yellow; font-weight: 600;">Excluded:</span> 7 fragments (3,200 tokens, below budget cutoff) │
│ <span style="color: #5599ff; font-weight: 600;">Deduplicated:</span> 4 fragments merged │
│ <span style="color: #5599ff; font-weight: 600;">Skeleton:</span> 2,400 tokens (15% reserve) │
│ <span style="color: magenta; font-weight: 600;">Preamble:</span> 180 tokens │
╰──────────────────────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Simulation complete (dry run — no context was assembled)
</code></pre></div>
=== "Plain"
```
$ agents project context simulate --view strategize --budget 16000 \
--focus uko-py:module/src.auth --focus uko-py:module/src.db \
local/api-service
ACMS Simulation
Project: local/api-service
View: strategize
Budget: 16,000 tokens (override)
Focus: uko-py:module/src.auth, uko-py:module/src.db
Strategy Results
breadth-depth-navigator
Confidence: 0.85 Budget: 7,200 tokens 12 fragments
Top: src/auth/__init__.py (depth 9, 1,240t, score=0.95)
src/db/models.py (depth 3, 480t, score=0.88)
semantic-embedding
Confidence: 0.60 Budget: 5,600 tokens 8 fragments
Top: src/auth/jwt.py (depth 3, 380t, score=0.82)
src/middleware/auth_check.py (depth 3, 290t, score=0.79)
simple-keyword
Confidence: 0.30 Budget: 3,200 tokens 5 fragments
Top: src/auth/utils.py (depth 6, 210t, score=0.71)
Fusion Result
Included: 18 fragments (14,820 tokens, 92.6% of budget)
Excluded: 7 fragments (3,200 tokens, below budget cutoff)
Deduplicated: 4 fragments merged
Skeleton: 2,400 tokens (15% reserve)
Preamble: 180 tokens
[OK] Simulation complete (dry run -- no context was assembled)
```
=== "JSON"
```json
{
"command": "project context simulate",
"status": "ok",
"exit_code": 0,
"data": {
"simulation": {
"project": "local/api-service",
"view": "strategize",
"budget": 16000,
"budget_source": "override",
"focus": ["uko-py:module/src.auth", "uko-py:module/src.db"]
},
"strategy_results": [
{
"name": "breadth-depth-navigator",
"confidence": 0.85,
"budget_tokens": 7200,
"fragments": 12,
"top": [
{ "path": "src/auth/__init__.py", "depth": 9, "tokens": 1240, "score": 0.95 },
{ "path": "src/db/models.py", "depth": 3, "tokens": 480, "score": 0.88 }
]
},
{
"name": "semantic-embedding",
"confidence": 0.60,
"budget_tokens": 5600,
"fragments": 8,
"top": [
{ "path": "src/auth/jwt.py", "depth": 3, "tokens": 380, "score": 0.82 },
{ "path": "src/middleware/auth_check.py", "depth": 3, "tokens": 290, "score": 0.79 }
]
},
{
"name": "simple-keyword",
"confidence": 0.30,
"budget_tokens": 3200,
"fragments": 5,
"top": [
{ "path": "src/auth/utils.py", "depth": 6, "tokens": 210, "score": 0.71 }
]
}
],
"fusion_result": {
"included_fragments": 18,
"included_tokens": 14820,
"budget_utilization": 0.926,
"excluded_fragments": 7,
"excluded_tokens": 3200,
"deduplicated_fragments": 4,
"skeleton_tokens": 2400,
"skeleton_ratio": 0.15,
"preamble_tokens": 180
}
},
"timing": {
"duration_ms": 310
},
"messages": ["Simulation complete (dry run -- no context was assembled)"]
}
```
=== "YAML"
```yaml
command: project context simulate
status: ok
exit_code: 0
data:
simulation:
project: local/api-service
view: strategize
budget: 16000
budget_source: override
focus:
- uko-py:module/src.auth
- uko-py:module/src.db
strategy_results:
- name: breadth-depth-navigator
confidence: 0.85
budget_tokens: 7200
fragments: 12
top:
- path: src/auth/__init__.py
depth: 9
tokens: 1240
score: 0.95
- path: src/db/models.py
depth: 3
tokens: 480
score: 0.88
- name: semantic-embedding
confidence: 0.60
budget_tokens: 5600
fragments: 8
top:
- path: src/auth/jwt.py
depth: 3
tokens: 380
score: 0.82
- path: src/middleware/auth_check.py
depth: 3
tokens: 290
score: 0.79
- name: simple-keyword
confidence: 0.30
budget_tokens: 3200
fragments: 5
top:
- path: src/auth/utils.py
depth: 6
tokens: 210
score: 0.71
fusion_result:
included_fragments: 18
included_tokens: 14820
budget_utilization: 0.926
excluded_fragments: 7
excluded_tokens: 3200
deduplicated_fragments: 4
skeleton_tokens: 2400
skeleton_ratio: 0.15
preamble_tokens: 180
timing:
duration_ms: 310
messages:
- "Simulation complete (dry run -- no context was assembled)"
```
agents actor
Purpose Manage actors and run actor configurations directly.
agents actor run
agents actor run [(--output|-o) <OUTPUT_FILE>]
[-v...] [--unsafe|-u] [--context <CONTEXT_NAME>]
[--context-dir <CONTEXT_PATH>] [--load-context <LOAD_CONTEXT_NAME>]
[(--temperature|-t) <TEMP>] [--allow-rxpy-in-run-mode]
[--skill <SKILL>]... <NAME> <PROMPT>Purpose Run a named actor in isolation with simple, manual context.
Arguments
<NAME>: The name of the actor to run (required).<PROMPT>: Prompt text (positional argument).--output/-o FILE: Output file path.--verbose/-v: Increase log verbosity (repeatable). Same semantics as the global-vflag: no-v= normal output only,-v= ERROR,-vv= WARN,-vvv= INFO,-vvvv= DEBUG,-vvvvv= TRACE.--unsafe/-u: Allow unsafe configs.--context NAME: Named actor context to attach.--context-dir PATH: Context storage location.--load-context FILE: Load context from JSON.--temperature/-t FLOAT: Override temperature.--skill NAME: Skill to attach (repeatable).--allow-rxpy-in-run-mode: Allow RxPy routes in run mode.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> actor run <span style="color: cyan;">--context</span> docs local/code_reader <span style="color: #66cc66;">"Summarize the README"</span>
╭─ Run Summary ─────────────────╮
│ <span style="color: cyan; font-weight: 600;">Actor:</span> local/code_reader │
│ <span style="color: #5599ff; font-weight: 600;">Context:</span> docs │
│ <span style="color: yellow; font-weight: 600;">Temperature:</span> 0.2 │
│ <span style="color: #5599ff; font-weight: 600;">Provider:</span> anthropic │
│ <span style="color: #5599ff; font-weight: 600;">Model:</span> claude-3.5 │
╰───────────────────────────────╯
╭─ Inputs ─────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Prompt:</span> Summarize the README │
│ <span style="color: #66cc66; font-weight: 600;">Context Files:</span> 3 │
│ <span style="color: #5599ff; font-weight: 600;">Context Size:</span> 12.4 KB │
╰──────────────────────────────╯
╭─ Result Metrics ───────╮
│ <span style="color: #66cc66; font-weight: 600;">Output:</span> stdout │
│ <span style="color: #5599ff; font-weight: 600;">Input Tokens:</span> 1,524 │
│ <span style="color: #5599ff; font-weight: 600;">Output Tokens:</span> 842 │
│ <span style="color: #5599ff; font-weight: 600;">Duration:</span> 1.8s │
│ <span style="color: yellow; font-weight: 600;">Cost:</span> $0.0021 │
│ <span style="color: #5599ff; font-weight: 600;">Tool Calls:</span> 0 │
╰────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Summary generated
</code></pre></div>
=== "Plain"
```
$ agents actor run --context docs local/code_reader "Summarize the README"
Run Summary
Actor: local/code_reader
Context: docs
Temperature: 0.2
Provider: anthropic
Model: claude-3.5
Inputs
Prompt: Summarize the README
Context Files: 3
Context Size: 12.4 KB
Result Metrics
Output: stdout
Input Tokens: 1,524
Output Tokens: 842
Duration: 1.8s
Cost: $0.0021
Tool Calls: 0
[OK] Summary generated
```
=== "JSON"
```json
{
"command": "agents actor run --context docs local/code_reader \"Summarize the README\"",
"status": "ok",
"exit_code": 0,
"data": {
"run_summary": {
"actor": "local/code_reader",
"context": "docs",
"temperature": 0.2,
"provider": "anthropic",
"model": "claude-3.5"
},
"inputs": {
"prompt": "Summarize the README",
"context_files": 3,
"context_size": "12.4 KB"
},
"result_metrics": {
"output": "stdout",
"input_tokens": 1524,
"output_tokens": 842,
"duration_s": 1.8,
"cost": "$0.0021",
"tool_calls": 0
}
},
"timing": {
"duration_ms": 1800
},
"messages": [
{ "level": "ok", "text": "Summary generated" }
]
}
```
=== "YAML"
```yaml
command: agents actor run --context docs local/code_reader "Summarize the README"
status: ok
exit_code: 0
data:
run_summary:
actor: local/code_reader
context: docs
temperature: 0.2
provider: anthropic
model: claude-3.5
inputs:
prompt: Summarize the README
context_files: 3
context_size: 12.4 KB
result_metrics:
output: stdout
input_tokens: 1524
output_tokens: 842
duration_s: 1.8
cost: "$0.0021"
tool_calls: 0
timing:
duration_ms: 1800
messages:
- level: ok
text: Summary generated
```
Running an actor with a custom temperature and skill attachment:
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> actor run <span style="color: cyan;">--temperature</span> 0.2 <span style="color: cyan;">--skill</span> local/code-analysis \
local/reviewer <span style="color: #66cc66;">"Review the auth module for security issues"</span>
╭─ Actor Run ─────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Actor:</span> local/reviewer │
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> agent │
│ <span style="color: #5599ff; font-weight: 600;">Temperature:</span> 0.2 │
│ <span style="color: #5599ff; font-weight: 600;">Skill:</span> local/code-analysis │
╰─────────────────────────────────────╯
╭─ Response ────────────────────────────────────────────────────────╮
│ I identified 3 potential security concerns in the auth module: │
│ │
│ 1. <span style="color: yellow; font-weight: 600;">Token expiry not validated</span> in `validate_session()` at │
│ src/auth/session.py:42. The JWT expiry claim is decoded but │
│ not checked against current time. │
│ │
│ 2. <span style="color: yellow; font-weight: 600;">Missing rate limiting</span> on the `/auth/refresh` endpoint. │
│ An attacker could brute-force refresh tokens. │
│ │
│ 3. <span style="color: #66cc66; font-weight: 600;">Low severity:</span> Password hashing uses bcrypt with cost=10. │
│ Consider cost=12 for production deployments. │
╰───────────────────────────────────────────────────────────────────╯
╭─ Usage ──────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Tokens:</span> 2,840 │
│ <span style="color: #5599ff; font-weight: 600;">Duration:</span> 4.2s │
│ <span style="color: #5599ff; font-weight: 600;">Cost:</span> $0.009 │
│ <span style="color: #5599ff; font-weight: 600;">Tool Calls:</span> 6 │
╰──────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Actor run completed
</code></pre></div>
=== "Plain"
```
$ agents actor run --temperature 0.2 --skill local/code-analysis \
local/reviewer "Review the auth module for security issues"
Actor Run
Actor: local/reviewer
Type: agent
Temperature: 0.2
Skill: local/code-analysis
Response
I identified 3 potential security concerns in the auth module:
1. Token expiry not validated in validate_session() at
src/auth/session.py:42. The JWT expiry claim is decoded but
not checked against current time.
2. Missing rate limiting on the /auth/refresh endpoint.
An attacker could brute-force refresh tokens.
3. Low severity: Password hashing uses bcrypt with cost=10.
Consider cost=12 for production deployments.
Usage
Tokens: 2,840
Duration: 4.2s
Cost: $0.009
Tool Calls: 6
[OK] Actor run completed
```
=== "JSON"
```json
{
"command": "agents actor run --temperature 0.2 --skill local/code-analysis local/reviewer \"Review the auth module for security issues\"",
"status": "ok",
"exit_code": 0,
"data": {
"actor_run": {
"actor": "local/reviewer",
"type": "agent",
"temperature": 0.2,
"skill": "local/code-analysis"
},
"response": {
"text": "I identified 3 potential security concerns in the auth module:\n\n1. Token expiry not validated in validate_session() at src/auth/session.py:42. The JWT expiry claim is decoded but not checked against current time.\n\n2. Missing rate limiting on the /auth/refresh endpoint. An attacker could brute-force refresh tokens.\n\n3. Low severity: Password hashing uses bcrypt with cost=10. Consider cost=12 for production deployments.",
"issues_found": 3
},
"usage": {
"tokens": 2840,
"duration_s": 4.2,
"cost": "$0.009",
"tool_calls": 6
}
},
"timing": {
"duration_ms": 4200
},
"messages": [
{ "level": "ok", "text": "Actor run completed" }
]
}
```
=== "YAML"
```yaml
command: >-
agents actor run --temperature 0.2 --skill local/code-analysis
local/reviewer "Review the auth module for security issues"
status: ok
exit_code: 0
data:
actor_run:
actor: local/reviewer
type: agent
temperature: 0.2
skill: local/code-analysis
response:
text: >-
I identified 3 potential security concerns in the auth module:
1. Token expiry not validated in validate_session() at
src/auth/session.py:42. The JWT expiry claim is decoded but
not checked against current time.
2. Missing rate limiting on the /auth/refresh endpoint.
An attacker could brute-force refresh tokens.
3. Low severity: Password hashing uses bcrypt with cost=10.
Consider cost=12 for production deployments.
issues_found: 3
usage:
tokens: 2840
duration_s: 4.2
cost: "$0.009"
tool_calls: 6
timing:
duration_ms: 4200
messages:
- level: ok
text: Actor run completed
```
Saving actor output to a file:
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> actor run <span style="color: cyan;">--output</span> review.md local/reviewer <span style="color: #66cc66;">"Write a code review report"</span>
╭─ Actor Run ───────────────╮
│ <span style="color: cyan; font-weight: 600;">Actor:</span> local/reviewer │
│ <span style="color: #5599ff; font-weight: 600;">Output:</span> review.md │
│ <span style="color: #5599ff; font-weight: 600;">Tokens:</span> 4,120 │
│ <span style="color: #5599ff; font-weight: 600;">Duration:</span> 6.8s │
╰───────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Output written to review.md (2.4 KB)
</code></pre></div>
=== "Plain"
```
$ agents actor run --output review.md local/reviewer "Write a code review report"
Actor Run
Actor: local/reviewer
Output: review.md
Tokens: 4,120
Duration: 6.8s
[OK] Output written to review.md (2.4 KB)
```
=== "JSON"
```json
{
"command": "agents actor run --output review.md local/reviewer \"Write a code review report\"",
"status": "ok",
"exit_code": 0,
"data": {
"actor_run": {
"actor": "local/reviewer",
"output": "review.md",
"tokens": 4120,
"duration_s": 6.8
}
},
"timing": {
"duration_ms": 6800
},
"messages": [
{ "level": "ok", "text": "Output written to review.md (2.4 KB)" }
]
}
```
=== "YAML"
```yaml
command: agents actor run --output review.md local/reviewer "Write a code review report"
status: ok
exit_code: 0
data:
actor_run:
actor: local/reviewer
output: review.md
tokens: 4120
duration_s: 6.8
timing:
duration_ms: 6800
messages:
- level: ok
text: Output written to review.md (2.4 KB)
```
agents actor add
agents actor add --config|-c <FILE> [--update]Purpose
Add a new actor configuration, or replace an existing one with --update. The actor is fully defined by the YAML configuration file specified with --config. If a local actor with the same name already exists, the command fails unless the --update flag is provided, which replaces the existing actor.
Arguments
--config/-c FILE: Actor config file (required). The file must fully define the actor, including thenamefield which determines the actor's registered name.--update: Replace an existing local actor with the same name. Without this flag, attempting to add an actor whose name is already registered will fail.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> actor add <span style="color: cyan;">--config</span> ./actors/reviewer.yaml
╭─ Actor Added ────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/reviewer │
│ <span style="color: #5599ff; font-weight: 600;">Provider:</span> openai │
│ <span style="color: magenta; font-weight: 600;">Model:</span> gpt-4 │
│ <span style="color: yellow; font-weight: 600;">Default:</span> yes │
│ <span style="color: #ff6666; font-weight: 600;">Unsafe:</span> no │
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> graph │
╰──────────────────────╯
╭─ Config ─────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Path:</span> ./actors/reviewer.yaml │
│ <span style="color: magenta; font-weight: 600;">Hash:</span> 8b3f3d2 │
│ <span style="color: #66cc66; font-weight: 600;">Options:</span> 4 │
│ <span style="color: #5599ff; font-weight: 600;">Nodes:</span> 3 │
│ <span style="color: #5599ff; font-weight: 600;">Edges:</span> 4 │
╰──────────────────────────────╯
╭─ Capabilities ───────╮
│ - code review │
│ - diff summarization │
│ - lint guidance │
╰──────────────────────╯
╭─ Tools ────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Tool</span> <span style="color: cyan; font-weight: 600;">Read-Only</span> <span style="color: cyan; font-weight: 600;">Safe</span> │
│ <span style="opacity: 0.7;">──────────── ───────── ────</span> │
│ read_file yes yes │
│ search_files yes yes │
│ git_diff yes yes │
╰────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Actor added
</code></pre></div>
=== "Plain"
```
$ agents actor add --config ./actors/reviewer.yaml
Actor Added
Name: local/reviewer
Provider: openai
Model: gpt-4
Default: yes
Unsafe: no
Type: graph
Config
Path: ./actors/reviewer.yaml
Hash: 8b3f3d2
Options: 4
Nodes: 3
Edges: 4
Capabilities
- code review
- diff summarization
- lint guidance
Tools
Tool Read-Only Safe
------------ --------- ----
read_file yes yes
search_files yes yes
git_diff yes yes
[OK] Actor added
```
=== "JSON"
```json
{
"command": "agents actor add --config ./actors/reviewer.yaml",
"status": "ok",
"exit_code": 0,
"data": {
"actor_added": {
"name": "local/reviewer",
"provider": "openai",
"model": "gpt-4",
"default": true,
"unsafe": false,
"type": "graph"
},
"config": {
"path": "./actors/reviewer.yaml",
"hash": "8b3f3d2",
"options": 4,
"nodes": 3,
"edges": 4
},
"capabilities": [
"code review",
"diff summarization",
"lint guidance"
],
"tools": [
{ "tool": "read_file", "read_only": true, "safe": true },
{ "tool": "search_files", "read_only": true, "safe": true },
{ "tool": "git_diff", "read_only": true, "safe": true }
]
},
"timing": {
"duration_ms": 95
},
"messages": [
{ "level": "ok", "text": "Actor added" }
]
}
```
=== "YAML"
```yaml
command: agents actor add --config ./actors/reviewer.yaml
status: ok
exit_code: 0
data:
actor_added:
name: local/reviewer
provider: openai
model: gpt-4
default: true
unsafe: false
type: graph
config:
path: ./actors/reviewer.yaml
hash: 8b3f3d2
options: 4
nodes: 3
edges: 4
capabilities:
- code review
- diff summarization
- lint guidance
tools:
- tool: read_file
read_only: true
safe: true
- tool: search_files
read_only: true
safe: true
- tool: git_diff
read_only: true
safe: true
timing:
duration_ms: 95
messages:
- level: ok
text: Actor added
```
Attempting to register an actor that already exists (without --update):
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> actor add <span style="color: cyan;">--config</span> ./actors/reviewer.yaml
╭─ Error ─────────────────────────────────────────────────╮
│ <span style="color: #ff6666; font-weight: 600;">Actor already exists:</span> local/reviewer │
│ <span style="color: #5599ff; font-weight: 600;">Registered:</span> 2026-02-07 14:22 │
│ <span style="opacity: 0.7;">Use <span style="color: cyan;">--update</span> to replace the existing actor definition.</span> │
╰─────────────────────────────────────────────────────────╯
<span style="color: #ff6666; font-weight: 600;">✗ ERROR</span> Actor already registered — use --update to replace
</code></pre></div>
=== "Plain"
```
$ agents actor add --config ./actors/reviewer.yaml
Error
Actor already exists: local/reviewer
Registered: 2026-02-07 14:22
Use --update to replace the existing actor definition.
[ERROR] Actor already registered -- use --update to replace
```
=== "JSON"
```json
{
"command": "agents actor add --config ./actors/reviewer.yaml",
"status": "error",
"exit_code": 1,
"data": {
"error": {
"message": "Actor already exists: local/reviewer",
"registered": "2026-02-07T14:22:00Z",
"hint": "Use --update to replace the existing actor definition."
}
},
"timing": {
"duration_ms": 42
},
"messages": [
{ "level": "error", "text": "Actor already registered -- use --update to replace" }
]
}
```
=== "YAML"
```yaml
command: agents actor add --config ./actors/reviewer.yaml
status: error
exit_code: 1
data:
error:
message: "Actor already exists: local/reviewer"
registered: "2026-02-07T14:22:00Z"
hint: Use --update to replace the existing actor definition.
timing:
duration_ms: 42
messages:
- level: error
text: Actor already registered -- use --update to replace
```
Updating an existing actor with --update:
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> actor add <span style="color: cyan;">--config</span> ./actors/reviewer.yaml <span style="color: cyan;">--update</span>
╭─ Actor Updated ─────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/reviewer │
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> agent │
│ <span style="color: yellow; font-weight: 600;">Status:</span> updated │
╰─────────────────────────────────────╯
╭─ Changes ────────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Skills:</span> +1 (local/code-analysis) │
│ <span style="color: #5599ff; font-weight: 600;">Model:</span> unchanged │
│ <span style="color: #5599ff; font-weight: 600;">Graph:</span> updated │
╰──────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Actor updated
</code></pre></div>
=== "Plain"
```
$ agents actor add --config ./actors/reviewer.yaml --update
Actor Updated
Name: local/reviewer
Type: agent
Status: updated
Changes
Skills: +1 (local/code-analysis)
Model: unchanged
Graph: updated
[OK] Actor updated
```
=== "JSON"
```json
{
"command": "agents actor add --config ./actors/reviewer.yaml --update",
"status": "ok",
"exit_code": 0,
"data": {
"actor_updated": {
"name": "local/reviewer",
"type": "agent",
"status": "updated"
},
"changes": {
"skills": "+1 (local/code-analysis)",
"model": "unchanged",
"graph": "updated"
}
},
"timing": {
"duration_ms": 88
},
"messages": [
{ "level": "ok", "text": "Actor updated" }
]
}
```
=== "YAML"
```yaml
command: agents actor add --config ./actors/reviewer.yaml --update
status: ok
exit_code: 0
data:
actor_updated:
name: local/reviewer
type: agent
status: updated
changes:
skills: "+1 (local/code-analysis)"
model: unchanged
graph: updated
timing:
duration_ms: 88
messages:
- level: ok
text: Actor updated
```
agents actor remove
agents actor remove <NAME>!!! warning "Destructive Operation" Removes a custom actor registration. Active plans and actions referencing this actor will lose their actor binding. Check the Impact section in the output to verify no active plans or sessions are affected.
Arguments
<NAME>: Actor name.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> actor remove local/reviewer
╭─ Actor Removed ──────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/reviewer │
│ <span style="color: #5599ff; font-weight: 600;">Provider:</span> openai │
│ <span style="color: magenta; font-weight: 600;">Model:</span> gpt-4 │
╰──────────────────────╯
╭─ Impact ───────────────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Sessions:</span> 0 affected │
│ <span style="color: #5599ff; font-weight: 600;">Active Plans:</span> 0 affected │
│ <span style="color: #5599ff; font-weight: 600;">Actions Referencing:</span> 0 │
╰────────────────────────────────────────────╯
╭─ Cleanup ──────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Config:</span> kept on disk │
│ <span style="color: yellow; font-weight: 600;">Contexts:</span> 1 orphaned │
╰────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Actor removed
</code></pre></div>
=== "Plain"
```
$ agents actor remove local/reviewer
Actor Removed
Name: local/reviewer
Provider: openai
Model: gpt-4
Impact
Sessions: 0 affected
Active Plans: 0 affected
Actions Referencing: 0
Cleanup
Config: kept on disk
Contexts: 1 orphaned
[OK] Actor removed
```
=== "JSON"
```json
{
"command": "agents actor remove local/reviewer",
"status": "ok",
"exit_code": 0,
"data": {
"actor_removed": {
"name": "local/reviewer",
"provider": "openai",
"model": "gpt-4"
},
"impact": {
"sessions": 0,
"active_plans": 0,
"actions_referencing": 0
},
"cleanup": {
"config": "kept on disk",
"contexts": "1 orphaned"
}
},
"timing": {
"duration_ms": 65
},
"messages": [
{ "level": "ok", "text": "Actor removed" }
]
}
```
=== "YAML"
```yaml
command: agents actor remove local/reviewer
status: ok
exit_code: 0
data:
actor_removed:
name: local/reviewer
provider: openai
model: gpt-4
impact:
sessions: 0
active_plans: 0
actions_referencing: 0
cleanup:
config: kept on disk
contexts: 1 orphaned
timing:
duration_ms: 65
messages:
- level: ok
text: Actor removed
```
agents actor list
agents actor listPurpose List all actors.
Arguments
None.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> actor list
╭─ Actors ──────────────────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name</span> <span style="color: cyan; font-weight: 600;">Provider</span> <span style="color: cyan; font-weight: 600;">Model</span> <span style="color: cyan; font-weight: 600;">Default</span> <span style="color: cyan; font-weight: 600;">Built-in</span> <span style="color: cyan; font-weight: 600;">Unsafe</span> │
│ <span style="opacity: 0.7;">────────────── ───────── ────────── ─────── ──────── ──────</span> │
│ local/reviewer openai gpt-4 ✓ no │
│ openai/gpt-4 openai gpt-4 ✓ no │
│ anthropic/3.5 anthropic claude-3.5 ✓ no │
╰───────────────────────────────────────────────────────────────────────╯
╭─ Summary ──────────────╮
│ <span style="color: yellow; font-weight: 600;">Total:</span> 3 │
│ <span style="color: #66cc66; font-weight: 600;">Built-in:</span> 2 │
│ <span style="color: #5599ff; font-weight: 600;">Custom:</span> 1 │
│ <span style="color: #ff6666; font-weight: 600;">Unsafe:</span> 0 │
│ <span style="color: #5599ff; font-weight: 600;">Providers Used:</span> 2 │
╰────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 3 actors listed
</code></pre></div>
=== "Plain"
```
$ agents actor list
Actors
Name Provider Model Default Built-in Unsafe
-------------- --------- ---------- ------- -------- ------
local/reviewer openai gpt-4 yes no
openai/gpt-4 openai gpt-4 yes no
anthropic/3.5 anthropic claude-3.5 yes no
Summary
Total: 3
Built-in: 2
Custom: 1
Unsafe: 0
Providers Used: 2
[OK] 3 actors listed
```
=== "JSON"
```json
{
"command": "agents actor list",
"status": "ok",
"exit_code": 0,
"data": {
"actors": [
{
"name": "local/reviewer",
"provider": "openai",
"model": "gpt-4",
"default": true,
"builtin": false,
"unsafe": false
},
{
"name": "openai/gpt-4",
"provider": "openai",
"model": "gpt-4",
"default": false,
"builtin": true,
"unsafe": false
},
{
"name": "anthropic/3.5",
"provider": "anthropic",
"model": "claude-3.5",
"default": false,
"builtin": true,
"unsafe": false
}
],
"summary": {
"total": 3,
"builtin": 2,
"custom": 1,
"unsafe": 0,
"providers_used": 2
}
},
"timing": {
"duration_ms": 55
},
"messages": [
{ "level": "ok", "text": "3 actors listed" }
]
}
```
=== "YAML"
```yaml
command: agents actor list
status: ok
exit_code: 0
data:
actors:
- name: local/reviewer
provider: openai
model: gpt-4
default: true
builtin: false
unsafe: false
- name: openai/gpt-4
provider: openai
model: gpt-4
default: false
builtin: true
unsafe: false
- name: anthropic/3.5
provider: anthropic
model: claude-3.5
default: false
builtin: true
unsafe: false
summary:
total: 3
builtin: 2
custom: 1
unsafe: 0
providers_used: 2
timing:
duration_ms: 55
messages:
- level: ok
text: 3 actors listed
```
agents actor show
agents actor show <NAME>Purpose Show details for a single actor.
Arguments
<NAME>: Actor name.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> actor show local/reviewer
╭─ Actor Details ────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/reviewer │
│ <span style="color: #5599ff; font-weight: 600;">Provider:</span> openai │
│ <span style="color: magenta; font-weight: 600;">Model:</span> gpt-4 │
│ <span style="color: yellow; font-weight: 600;">Default:</span> yes │
│ <span style="color: #66cc66; font-weight: 600;">Built-in:</span> no │
│ <span style="color: #ff6666; font-weight: 600;">Unsafe:</span> no │
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> graph │
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-08 12:35 │
│ <span style="color: #66cc66; font-weight: 600;">Updated:</span> 2026-02-08 12:40 │
│ <span style="color: #5599ff; font-weight: 600;">Config:</span> ./actors/reviewer.yaml │
│ <span style="color: magenta; font-weight: 600;">Config Hash:</span> 9c4e2a1 │
╰────────────────────────────────────╯
╭─ Options ──────────╮
│ - temperature: 0.2 │
│ - max_tokens: 2048 │
│ - top_p: 1.0 │
╰────────────────────╯
╭─ Graph Structure ─╮
│ <span style="color: #5599ff; font-weight: 600;">Nodes:</span> 3 │
│ <span style="color: #5599ff; font-weight: 600;">Edges:</span> 4 │
│ <span style="color: #5599ff; font-weight: 600;">Entry:</span> analyze │
│ <span style="color: #5599ff; font-weight: 600;">Exit:</span> report │
╰───────────────────╯
╭─ Tools ────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Tool</span> <span style="color: cyan; font-weight: 600;">Read-Only</span> <span style="color: cyan; font-weight: 600;">Safe</span> │
│ <span style="opacity: 0.7;">──────────── ───────── ────</span> │
│ read_file yes yes │
│ search_files yes yes │
│ git_diff yes yes │
╰────────────────────────────────╯
╭─ Access ────────────╮
│ <span style="color: #ff6666; font-weight: 600;">Unsafe:</span> no │
│ <span style="color: #66cc66; font-weight: 600;">Filesystem:</span> allowed │
│ <span style="color: yellow; font-weight: 600;">Network:</span> restricted │
╰─────────────────────╯
╭─ Usage ─────────────────────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Referenced by Actions:</span> 1 (local/code-coverage) │
│ <span style="color: #5599ff; font-weight: 600;">Active in Sessions:</span> 0 │
│ <span style="color: #5599ff; font-weight: 600;">Total Runs:</span> 14 │
│ <span style="color: #5599ff; font-weight: 600;">Avg Cost/Run:</span> $0.0032 │
╰─────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Actor loaded
</code></pre></div>
=== "Plain"
```
$ agents actor show local/reviewer
Actor Details
Name: local/reviewer
Provider: openai
Model: gpt-4
Default: yes
Built-in: no
Unsafe: no
Type: graph
Created: 2026-02-08 12:35
Updated: 2026-02-08 12:40
Config: ./actors/reviewer.yaml
Config Hash: 9c4e2a1
Options
- temperature: 0.2
- max_tokens: 2048
- top_p: 1.0
Graph Structure
Nodes: 3
Edges: 4
Entry: analyze
Exit: report
Tools
Tool Read-Only Safe
------------ --------- ----
read_file yes yes
search_files yes yes
git_diff yes yes
Access
Unsafe: no
Filesystem: allowed
Network: restricted
Usage
Referenced by Actions: 1 (local/code-coverage)
Active in Sessions: 0
Total Runs: 14
Avg Cost/Run: $0.0032
[OK] Actor loaded
```
=== "JSON"
```json
{
"command": "agents actor show local/reviewer",
"status": "ok",
"exit_code": 0,
"data": {
"actor_details": {
"name": "local/reviewer",
"provider": "openai",
"model": "gpt-4",
"default": true,
"builtin": false,
"unsafe": false,
"type": "graph",
"created": "2026-02-08T12:35:00Z",
"updated": "2026-02-08T12:40:00Z",
"config": "./actors/reviewer.yaml",
"config_hash": "9c4e2a1"
},
"options": {
"temperature": 0.2,
"max_tokens": 2048,
"top_p": 1.0
},
"graph_structure": {
"nodes": 3,
"edges": 4,
"entry": "analyze",
"exit": "report"
},
"tools": [
{ "tool": "read_file", "read_only": true, "safe": true },
{ "tool": "search_files", "read_only": true, "safe": true },
{ "tool": "git_diff", "read_only": true, "safe": true }
],
"access": {
"unsafe": false,
"filesystem": "allowed",
"network": "restricted"
},
"usage": {
"referenced_by_actions": "1 (local/code-coverage)",
"active_in_sessions": 0,
"total_runs": 14,
"avg_cost_per_run": "$0.0032"
}
},
"timing": {
"duration_ms": 78
},
"messages": [
{ "level": "ok", "text": "Actor loaded" }
]
}
```
=== "YAML"
```yaml
command: agents actor show local/reviewer
status: ok
exit_code: 0
data:
actor_details:
name: local/reviewer
provider: openai
model: gpt-4
default: true
builtin: false
unsafe: false
type: graph
created: "2026-02-08T12:35:00Z"
updated: "2026-02-08T12:40:00Z"
config: ./actors/reviewer.yaml
config_hash: 9c4e2a1
options:
temperature: 0.2
max_tokens: 2048
top_p: 1.0
graph_structure:
nodes: 3
edges: 4
entry: analyze
exit: report
tools:
- tool: read_file
read_only: true
safe: true
- tool: search_files
read_only: true
safe: true
- tool: git_diff
read_only: true
safe: true
access:
unsafe: false
filesystem: allowed
network: restricted
usage:
referenced_by_actions: 1 (local/code-coverage)
active_in_sessions: 0
total_runs: 14
avg_cost_per_run: "$0.0032"
timing:
duration_ms: 78
messages:
- level: ok
text: Actor loaded
```
agents actor context
Purpose Manage manual context for actor runs. These commands mirror the legacy context behavior but are scoped to an actor context name.
agents actor context remove
agents actor context remove [--yes|-y] (--all|-a|<NAME>)!!! warning "Context Data Loss"
Remove files or directories from an actor context. Use --all to clear all contexts at once. Context data is not recoverable after removal.
Arguments
<NAME>: Context name (positional argument). Use --all/-a to target all contexts.--all, -a: Target all contexts instead of a named one.--yes, -y: Skip confirmation prompt.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> actor context remove docs
╭─ Context Removed ───────────╮
│ <span style="color: cyan; font-weight: 600;">Context:</span> docs │
│ <span style="color: #66cc66; font-weight: 600;">Status:</span> removed │
╰─────────────────────────────╯
╭─ Stats ───────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Remaining Size:</span> 48 KB │
│ <span style="color: #66cc66; font-weight: 600;">Updated:</span> 2026-02-08 13:06 │
╰───────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Context updated
</code></pre></div>
=== "Plain"
```
$ agents actor context remove docs
Context Removed
Context: docs
Status: removed
Stats
Remaining Size: 48 KB
Updated: 2026-02-08 13:06
[OK] Context updated
```
=== "JSON"
```json
{
"command": "agents actor context remove docs",
"status": "ok",
"exit_code": 0,
"data": {
"context_removed": {
"context": "docs",
"status": "removed"
},
"stats": {
"remaining_size_kb": 48,
"updated": "2026-02-08T13:06:00Z"
}
},
"timing": { "duration_ms": 65 },
"messages": [{ "level": "ok", "text": "Context updated" }]
}
```
=== "YAML"
```yaml
command: agents actor context remove docs
status: ok
exit_code: 0
data:
context_removed:
context: docs
status: removed
stats:
remaining_size_kb: 48
updated: "2026-02-08T13:06:00Z"
timing:
duration_ms: 65
messages:
- level: ok
text: Context updated
```
agents actor context list
agents actor context list [<REGEX>]Purpose List files stored in an actor context.
Arguments
[REGEX]: Optional regex filter for context names.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> actor context list docs
╭─ Context Files ──────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name</span> <span style="color: cyan; font-weight: 600;">Type</span> <span style="color: cyan; font-weight: 600;">Size</span> <span style="color: cyan; font-weight: 600;">Added</span> │
│ <span style="opacity: 0.7;">──────────────── ──── ─────── ──────────</span> │
│ README.md file 4.2 KB 02-08 12:10 │
│ docs/overview.md file 12.8 KB 02-08 12:10 │
│ docs/cli.md file 9.5 KB 02-08 12:10 │
╰──────────────────────────────────────────────╯
╭─ Stats ───────────────────────╮
│ <span style="color: yellow; font-weight: 600;">Total Files:</span> 3 │
│ <span style="color: #66cc66; font-weight: 600;">Total Size:</span> 26.5 KB │
│ <span style="color: #5599ff; font-weight: 600;">Estimated Tokens:</span> ~6,600 │
│ <span style="color: #5599ff; font-weight: 600;">Languages:</span> Markdown │
╰───────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 3 files listed
</code></pre></div>
=== "Plain"
```
$ agents actor context list docs
Context Files
Name Type Size Added
---------------- ---- ------- ----------
README.md file 4.2 KB 02-08 12:10
docs/overview.md file 12.8 KB 02-08 12:10
docs/cli.md file 9.5 KB 02-08 12:10
Stats
Total Files: 3
Total Size: 26.5 KB
Estimated Tokens: ~6,600
Languages: Markdown
[OK] 3 files listed
```
=== "JSON"
```json
{
"command": "agents actor context list docs",
"status": "ok",
"exit_code": 0,
"data": {
"context_files": [
{ "name": "README.md", "type": "file", "size_kb": 4.2, "added": "2026-02-08T12:10:00Z" },
{ "name": "docs/overview.md", "type": "file", "size_kb": 12.8, "added": "2026-02-08T12:10:00Z" },
{ "name": "docs/cli.md", "type": "file", "size_kb": 9.5, "added": "2026-02-08T12:10:00Z" }
],
"stats": {
"total_files": 3,
"total_size_kb": 26.5,
"estimated_tokens": 6600,
"languages": ["Markdown"]
}
},
"timing": { "duration_ms": 35 },
"messages": [{ "level": "ok", "text": "3 files listed" }]
}
```
=== "YAML"
```yaml
command: agents actor context list docs
status: ok
exit_code: 0
data:
context_files:
- name: README.md
type: file
size_kb: 4.2
added: "2026-02-08T12:10:00Z"
- name: docs/overview.md
type: file
size_kb: 12.8
added: "2026-02-08T12:10:00Z"
- name: docs/cli.md
type: file
size_kb: 9.5
added: "2026-02-08T12:10:00Z"
stats:
total_files: 3
total_size_kb: 26.5
estimated_tokens: 6600
languages:
- Markdown
timing:
duration_ms: 35
messages:
- level: ok
text: 3 files listed
```
agents actor context show
agents actor context show <NAME>Purpose Show content of a file in an actor context.
Arguments
<NAME>: Context name (positional argument).
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> actor context show docs
╭─ Context Summary ───────────╮
│ <span style="color: cyan; font-weight: 600;">Context:</span> docs │
│ <span style="color: #66cc66; font-weight: 600;">Files:</span> 3 │
│ <span style="color: yellow; font-weight: 600;">Total Size:</span> 26.5 KB │
│ <span style="color: #5599ff; font-weight: 600;">Estimated Tokens:</span> ~6,600 │
│ <span style="color: #5599ff; font-weight: 600;">Created:</span> 2026-02-08 12:10 │
╰─────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Context displayed
</code></pre></div>
=== "Plain"
```
$ agents actor context show docs
Context Summary
Context: docs
Files: 3
Total Size: 26.5 KB
Estimated Tokens: ~6,600
Created: 2026-02-08 12:10
[OK] Context displayed
```
=== "JSON"
```json
{
"command": "agents actor context show docs",
"status": "ok",
"exit_code": 0,
"data": {
"context_summary": {
"context": "docs",
"files": 3,
"total_size_kb": 26.5,
"estimated_tokens": 6600,
"created": "2026-02-08T12:10:00Z"
}
},
"timing": { "duration_ms": 45 },
"messages": [{ "level": "ok", "text": "Context displayed" }]
}
```
=== "YAML"
```yaml
command: agents actor context show docs
status: ok
exit_code: 0
data:
context_summary:
context: docs
files: 3
total_size_kb: 26.5
estimated_tokens: 6600
created: "2026-02-08T12:10:00Z"
timing:
duration_ms: 45
messages:
- level: ok
text: Context displayed
```
agents actor context export
agents actor context export (--output|-o) <FILE> <NAME>Purpose Export a context as JSON.
Arguments
<NAME>: Context name (positional argument).--output/-o FILE: Output file path (required).
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> actor context export <span style="color: cyan;">--output</span> /tmp/docs-context.json docs
╭─ Context Export ───────────────╮
│ <span style="color: cyan; font-weight: 600;">Context:</span> docs │
│ <span style="color: #5599ff; font-weight: 600;">Output:</span> /tmp/docs-context.json │
│ <span style="color: yellow; font-weight: 600;">Items:</span> 12 │
│ <span style="color: #66cc66; font-weight: 600;">Size:</span> 48 KB │
╰────────────────────────────────╯
╭─ Integrity ──────────────────╮
│ <span style="color: magenta; font-weight: 600;">Checksum:</span> sha256:19b2...a7d0 │
│ <span style="color: #5599ff; font-weight: 600;">Compressed:</span> no │
╰──────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Export completed
</code></pre></div>
=== "Plain"
```
$ agents actor context export --output /tmp/docs-context.json docs
Context Export
Context: docs
Output: /tmp/docs-context.json
Items: 12
Size: 48 KB
Integrity
Checksum: sha256:19b2...a7d0
Compressed: no
[OK] Export completed
```
=== "JSON"
```json
{
"command": "agents actor context export --output /tmp/docs-context.json docs",
"status": "ok",
"exit_code": 0,
"data": {
"context_export": {
"context": "docs",
"output": "/tmp/docs-context.json",
"items": 12,
"size_kb": 48
},
"integrity": {
"checksum": "sha256:19b2...a7d0",
"compressed": false
}
},
"timing": { "duration_ms": 180 },
"messages": [{ "level": "ok", "text": "Export completed" }]
}
```
=== "YAML"
```yaml
command: agents actor context export --output /tmp/docs-context.json docs
status: ok
exit_code: 0
data:
context_export:
context: docs
output: /tmp/docs-context.json
items: 12
size_kb: 48
integrity:
checksum: "sha256:19b2...a7d0"
compressed: false
timing:
duration_ms: 180
messages:
- level: ok
text: Export completed
```
agents actor context import
agents actor context import [--update] (--input|-i) <FILE> [<NAME>]Purpose Import a context from JSON.
Arguments
[NAME]: Context name (optional, inferred from file if omitted).--input/-i FILE: Input JSON file (required).--update: Replace an existing context with the same name.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> actor context import <span style="color: cyan;">--input</span> /tmp/docs-context.json docs
╭─ Context Import ──────────────╮
│ <span style="color: cyan; font-weight: 600;">Context:</span> docs │
│ <span style="color: #5599ff; font-weight: 600;">Input:</span> /tmp/docs-context.json │
│ <span style="color: yellow; font-weight: 600;">Items:</span> 12 │
╰───────────────────────────────╯
╭─ Merge ───────────╮
│ <span style="color: #5599ff; font-weight: 600;">Strategy:</span> replace │
│ <span style="color: yellow; font-weight: 600;">Conflicts:</span> 0 │
╰───────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Import completed
</code></pre></div>
=== "Plain"
```
$ agents actor context import --input /tmp/docs-context.json docs
Context Import
Context: docs
Input: /tmp/docs-context.json
Items: 12
Merge
Strategy: replace
Conflicts: 0
[OK] Import completed
```
=== "JSON"
```json
{
"command": "agents actor context import --input /tmp/docs-context.json docs",
"status": "ok",
"exit_code": 0,
"data": {
"context_import": {
"context": "docs",
"input": "/tmp/docs-context.json",
"items": 12
},
"merge": {
"strategy": "replace",
"conflicts": 0
}
},
"timing": { "duration_ms": 210 },
"messages": [{ "level": "ok", "text": "Import completed" }]
}
```
=== "YAML"
```yaml
command: agents actor context import --input /tmp/docs-context.json docs
status: ok
exit_code: 0
data:
context_import:
context: docs
input: /tmp/docs-context.json
items: 12
merge:
strategy: replace
conflicts: 0
timing:
duration_ms: 210
messages:
- level: ok
text: Import completed
```
agents actor context clear
agents actor context clear [--yes|-y] (--all|-a|<NAME>)Purpose Clear all files from a context but keep the context itself.
Arguments
<NAME>: Context name (positional argument). Use --all/-a to target all contexts.--all, -a: Target all contexts instead of a named one.--yes, -y: Skip confirmation.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> actor context clear docs
Clear context docs? [y/N]: y
╭─ Context Cleared ────╮
│ <span style="color: cyan; font-weight: 600;">Context:</span> docs │
│ <span style="color: yellow; font-weight: 600;">Items:</span> 12 removed │
│ <span style="color: #5599ff; font-weight: 600;">Storage:</span> 48 KB freed │
╰──────────────────────╯
╭─ Retention ────────╮
│ <span style="color: #66cc66; font-weight: 600;">Context:</span> preserved │
│ <span style="color: yellow; font-weight: 600;">Files:</span> removed │
╰────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Context cleared
</code></pre></div>
=== "Plain"
```
$ agents actor context clear docs
Clear context docs? [y/N]: y
Context Cleared
Context: docs
Items: 12 removed
Storage: 48 KB freed
Retention
Context: preserved
Files: removed
[OK] Context cleared
```
=== "JSON"
```json
{
"command": "agents actor context clear docs",
"status": "ok",
"exit_code": 0,
"data": {
"context_cleared": {
"context": "docs",
"items": "12 removed",
"storage": "48 KB freed"
},
"retention": {
"context": "preserved",
"files": "removed"
}
},
"timing": { "duration_ms": 85 },
"messages": [{ "level": "ok", "text": "Context cleared" }]
}
```
=== "YAML"
```yaml
command: agents actor context clear docs
status: ok
exit_code: 0
data:
context_cleared:
context: docs
items: 12 removed
storage: 48 KB freed
retention:
context: preserved
files: removed
timing:
duration_ms: 85
messages:
- level: ok
text: Context cleared
```
agents skill
!!! info "Purpose"
Manage skills — reusable, namespaced collections of tools. Skills are defined in their own YAML configuration files and registered in the system through these commands. Once registered, skills can be referenced by actors.
agents skill add
agents skill add --config|-c <FILE> [--update]Purpose
Register a new skill. The skill is fully defined by the YAML configuration file specified with --config. If a skill with the same name already exists, the command fails unless the --update flag is provided, which allows overwriting the existing registration with the new configuration.
Arguments
--config/-c FILE: Path to the skill YAML configuration file (required). The file must fully define the skill, including thenamefield which determines the skill's registered name.--update: Allow overwriting an existing skill registration. Without this flag, attempting to add a skill whose name is already registered will fail.
Examples
Registering a new skill:
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> skill add <span style="color: cyan;">--config</span> ./skills/devops-toolkit.yaml
╭─ Skill Registered ────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/devops-toolkit │
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> Full-stack development tools │
│ <span style="color: #66cc66; font-weight: 600;">Config:</span> ./skills/devops-toolkit.yaml │
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-08 13:10 │
╰───────────────────────────────────────────╯
╭─ Includes ────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">local/file-ops</span> (registered) │
│ <span style="color: #5599ff; font-weight: 600;">local/git-ops</span> (registered) │
│ <span style="color: #5599ff; font-weight: 600;">local/github</span> (registered) │
╰───────────────────────────────╯
╭─ Tool Sources ────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Source</span> <span style="color: cyan; font-weight: 600;">Count</span> <span style="color: cyan; font-weight: 600;">Details</span> │
│ <span style="opacity: 0.7;">───────────── ───── ───────────────────</span> │
│ builtin 14 file, dir, git, shell │
│ mcp 6 github (4), linear (2) │
│ agent_skill 2 deploy, code-review │
│ custom 1 run_migrations │
│ <span style="opacity: 0.7;">───────────── ───── ───────────────────</span> │
│ <span style="color: yellow; font-weight: 600;">Total:</span> 23 │
╰───────────────────────────────────────────────╯
╭─ MCP Servers ────────────────────╮
│ <span style="color: #66cc66; font-weight: 600;">linear:</span> validated (2 tools) │
╰──────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Skill registered with 23 tools
</code></pre></div>
=== "Plain"
```
$ agents skill add --config ./skills/devops-toolkit.yaml
Skill Registered
Name: local/devops-toolkit
Description: Full-stack development tools
Config: ./skills/devops-toolkit.yaml
Created: 2026-02-08 13:10
Includes
local/file-ops (registered)
local/git-ops (registered)
local/github (registered)
Tool Sources
Source Count Details
------------- ----- -------------------
builtin 14 file, dir, git, shell
mcp 6 github (4), linear (2)
agent_skill 2 deploy, code-review
custom 1 run_migrations
------------- ----- -------------------
Total: 23
MCP Servers
linear: validated (2 tools)
[OK] Skill registered with 23 tools
```
=== "JSON"
```json
{
"command": "skill add --config ./skills/devops-toolkit.yaml",
"status": "ok",
"exit_code": 0,
"data": {
"skill": {
"name": "local/devops-toolkit",
"description": "Full-stack development tools",
"config": "./skills/devops-toolkit.yaml",
"created": "2026-02-08T13:10:00Z"
},
"includes": [
{ "name": "local/file-ops", "status": "registered" },
{ "name": "local/git-ops", "status": "registered" },
{ "name": "local/github", "status": "registered" }
],
"tool_sources": [
{ "source": "builtin", "count": 14, "details": "file, dir, git, shell" },
{ "source": "mcp", "count": 6, "details": "github (4), linear (2)" },
{ "source": "agent_skill", "count": 2, "details": "deploy, code-review" },
{ "source": "custom", "count": 1, "details": "run_migrations" }
],
"total_tools": 23,
"mcp_servers": [
{ "name": "linear", "status": "validated", "tools": 2 }
]
},
"timing": {
"duration_ms": 150
},
"messages": [
{ "level": "ok", "text": "Skill registered with 23 tools" }
]
}
```
=== "YAML"
```yaml
command: skill add --config ./skills/devops-toolkit.yaml
status: ok
exit_code: 0
data:
skill:
name: local/devops-toolkit
description: Full-stack development tools
config: ./skills/devops-toolkit.yaml
created: "2026-02-08T13:10:00Z"
includes:
- name: local/file-ops
status: registered
- name: local/git-ops
status: registered
- name: local/github
status: registered
tool_sources:
- source: builtin
count: 14
details: file, dir, git, shell
- source: mcp
count: 6
details: github (4), linear (2)
- source: agent_skill
count: 2
details: deploy, code-review
- source: custom
count: 1
details: run_migrations
total_tools: 23
mcp_servers:
- name: linear
status: validated
tools: 2
timing:
duration_ms: 150
messages:
- level: ok
text: Skill registered with 23 tools
```
Attempting to add a skill that already exists (without --update):
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> skill add <span style="color: cyan;">--config</span> ./skills/devops-toolkit-v2.yaml
<span style="color: #ff6666; font-weight: 600;">✗ Error:</span> Skill 'local/devops-toolkit' is already registered.
To overwrite the existing configuration, re-run with <span style="color: cyan;">--update</span>:
agents skill add <span style="color: cyan;">--config</span> ./skills/devops-toolkit-v2.yaml <span style="color: cyan;">--update</span>
</code></pre></div>
=== "Plain"
```
$ agents skill add --config ./skills/devops-toolkit-v2.yaml
Error: Skill 'local/devops-toolkit' is already registered.
To overwrite the existing configuration, re-run with --update:
agents skill add --config ./skills/devops-toolkit-v2.yaml --update
```
=== "JSON"
```json
{
"command": "skill add --config ./skills/devops-toolkit-v2.yaml",
"status": "error",
"exit_code": 1,
"data": {
"skill_name": "local/devops-toolkit",
"reason": "already registered"
},
"timing": {
"duration_ms": 30
},
"messages": [
{ "level": "error", "text": "Skill 'local/devops-toolkit' is already registered." },
{ "level": "info", "text": "To overwrite the existing configuration, re-run with --update" }
]
}
```
=== "YAML"
```yaml
command: skill add --config ./skills/devops-toolkit-v2.yaml
status: error
exit_code: 1
data:
skill_name: local/devops-toolkit
reason: already registered
timing:
duration_ms: 30
messages:
- level: error
text: "Skill 'local/devops-toolkit' is already registered."
- level: info
text: To overwrite the existing configuration, re-run with --update
```
Updating an existing skill with --update:
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> skill add <span style="color: cyan;">--config</span> ./skills/devops-toolkit-v2.yaml <span style="color: cyan;">--update</span>
╭─ Skill Updated ───────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/devops-toolkit │
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> Full-stack development tools │
│ <span style="color: #66cc66; font-weight: 600;">Updated:</span> 2026-02-08 14:22 │
╰───────────────────────────────────────────╯
╭─ Changes ─────────────────────╮
│ <span style="color: #66cc66; font-weight: 600;">Tools Added:</span> 2 │
│ <span style="color: yellow; font-weight: 600;">Tools Removed:</span> 0 │
│ <span style="color: #5599ff; font-weight: 600;">Tools Modified:</span> 1 │
│ <span style="color: #5599ff; font-weight: 600;">Includes Changed:</span> no │
│ <span style="color: #5599ff; font-weight: 600;">MCP Servers Changed:</span> no │
╰───────────────────────────────╯
╭─ Affected Actors ─────────────────────────────╮
│ <span style="color: yellow; font-weight: 600;">Warning:</span> 2 actors reference this skill: │
│ - local/code-assistant │
│ - local/full-stack-assistant │
│ These actors will pick up changes on next use │
╰───────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Skill updated (23 → 25 tools)
</code></pre></div>
=== "Plain"
```
$ agents skill add --config ./skills/devops-toolkit-v2.yaml --update
Skill Updated
Name: local/devops-toolkit
Description: Full-stack development tools
Updated: 2026-02-08 14:22
Changes
Tools Added: 2
Tools Removed: 0
Tools Modified: 1
Includes Changed: no
MCP Servers Changed: no
Affected Actors
Warning: 2 actors reference this skill:
- local/code-assistant
- local/full-stack-assistant
These actors will pick up changes on next use
[OK] Skill updated (23 -> 25 tools)
```
=== "JSON"
```json
{
"command": "skill add --config ./skills/devops-toolkit-v2.yaml --update",
"status": "ok",
"exit_code": 0,
"data": {
"skill": {
"name": "local/devops-toolkit",
"description": "Full-stack development tools",
"updated": "2026-02-08T14:22:00Z"
},
"changes": {
"tools_added": 2,
"tools_removed": 0,
"tools_modified": 1,
"includes_changed": false,
"mcp_servers_changed": false
},
"affected_actors": [
"local/code-assistant",
"local/full-stack-assistant"
],
"tool_count": {
"before": 23,
"after": 25
}
},
"timing": {
"duration_ms": 180
},
"messages": [
{ "level": "ok", "text": "Skill updated (23 -> 25 tools)" },
{ "level": "warn", "text": "2 actors reference this skill and will pick up changes on next use" }
]
}
```
=== "YAML"
```yaml
command: skill add --config ./skills/devops-toolkit-v2.yaml --update
status: ok
exit_code: 0
data:
skill:
name: local/devops-toolkit
description: Full-stack development tools
updated: "2026-02-08T14:22:00Z"
changes:
tools_added: 2
tools_removed: 0
tools_modified: 1
includes_changed: false
mcp_servers_changed: false
affected_actors:
- local/code-assistant
- local/full-stack-assistant
tool_count:
before: 23
after: 25
timing:
duration_ms: 180
messages:
- level: ok
text: "Skill updated (23 -> 25 tools)"
- level: warn
text: 2 actors reference this skill and will pick up changes on next use
```
agents skill remove
agents skill remove [--yes|-y] <NAME>!!! warning "Cascading Impact" Removing a skill ==unregisters all tools== provided by that skill and closes any associated MCP server connections. Other skills that include this skill, and actors that reference it, will lose access to those tools.
Arguments
<NAME>: Skill name to remove.--yes: Skip confirmation prompt.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> skill remove local/devops-toolkit
Remove skill local/devops-toolkit? [y/N]: y
╭─ Skill Removed ──────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/devops-toolkit │
│ <span style="color: yellow; font-weight: 600;">Tools:</span> 23 removed from registry │
│ <span style="color: #5599ff; font-weight: 600;">MCP Servers:</span> 1 connection closed │
╰──────────────────────────────────────╯
╭─ Dependency Check ─────────────────────────────────╮
│ <span style="color: yellow; font-weight: 600;">Warning:</span> 1 skill includes this skill: │
│ - local/full-stack-dev (will lose devops tools) │
│ <span style="color: yellow; font-weight: 600;">Warning:</span> 2 actors reference this skill: │
│ - local/code-assistant │
│ - local/full-stack-assistant │
╰────────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Skill removed
</code></pre></div>
=== "Plain"
```
$ agents skill remove local/devops-toolkit
Remove skill local/devops-toolkit? [y/N]: y
Skill Removed
Name: local/devops-toolkit
Tools: 23 removed from registry
MCP Servers: 1 connection closed
Dependency Check
Warning: 1 skill includes this skill:
- local/full-stack-dev (will lose devops tools)
Warning: 2 actors reference this skill:
- local/code-assistant
- local/full-stack-assistant
[OK] Skill removed
```
=== "JSON"
```json
{
"command": "skill remove local/devops-toolkit",
"status": "ok",
"exit_code": 0,
"data": {
"skill": {
"name": "local/devops-toolkit",
"tools_removed": 23,
"mcp_servers_closed": 1
},
"dependency_check": {
"including_skills": [
{ "name": "local/full-stack-dev", "impact": "will lose devops tools" }
],
"referencing_actors": [
"local/code-assistant",
"local/full-stack-assistant"
]
}
},
"timing": {
"duration_ms": 95
},
"messages": [
{ "level": "ok", "text": "Skill removed" },
{ "level": "warn", "text": "1 skill includes this skill" },
{ "level": "warn", "text": "2 actors reference this skill" }
]
}
```
=== "YAML"
```yaml
command: skill remove local/devops-toolkit
status: ok
exit_code: 0
data:
skill:
name: local/devops-toolkit
tools_removed: 23
mcp_servers_closed: 1
dependency_check:
including_skills:
- name: local/full-stack-dev
impact: will lose devops tools
referencing_actors:
- local/code-assistant
- local/full-stack-assistant
timing:
duration_ms: 95
messages:
- level: ok
text: Skill removed
- level: warn
text: 1 skill includes this skill
- level: warn
text: 2 actors reference this skill
```
agents skill list
agents skill list [(--namespace|-n) <NS>] [--source <SOURCE>]Purpose List registered skills with optional filters.
Arguments
--namespace/-n NS: Filter by namespace.--source SOURCE: Filter by tool source type (mcp, agent_skill, builtin, custom).
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> skill list
╭─ Skills ────────────────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name</span> <span style="color: cyan; font-weight: 600;">Tools</span> <span style="color: cyan; font-weight: 600;">Includes</span> <span style="color: cyan; font-weight: 600;">Sources</span> │
│ <span style="opacity: 0.7;">────────────────────── ───── ──────── ──────────────────────</span> │
│ local/file-ops 9 0 builtin │
│ local/git-ops 4 0 builtin │
│ local/github 4 0 mcp │
│ local/devops-toolkit 23 3 builtin, mcp, custom │
│ local/full-stack-dev 25 4 builtin, mcp, custom │
╰─────────────────────────────────────────────────────────────────────╯
╭─ Summary ─────────╮
│ <span style="color: yellow; font-weight: 600;">Total:</span> 5 │
│ <span style="color: #5599ff; font-weight: 600;">Local:</span> 5 │
│ <span style="color: #5599ff; font-weight: 600;">Server:</span> 0 │
│ <span style="color: #5599ff; font-weight: 600;">Total Tools:</span> 28 │
╰───────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 5 skills listed
</code></pre></div>
=== "Plain"
```
$ agents skill list
Skills
Name Tools Includes Sources
---------------------- ----- -------- ----------------------
local/file-ops 9 0 builtin
local/git-ops 4 0 builtin
local/github 4 0 mcp
local/devops-toolkit 23 3 builtin, mcp, custom
local/full-stack-dev 25 4 builtin, mcp, custom
Summary
Total: 5
Local: 5
Server: 0
Total Tools: 28
[OK] 5 skills listed
```
=== "JSON"
```json
{
"command": "skill list",
"status": "ok",
"exit_code": 0,
"data": {
"skills": [
{ "name": "local/file-ops", "tools": 9, "includes": 0, "sources": ["builtin"] },
{ "name": "local/git-ops", "tools": 4, "includes": 0, "sources": ["builtin"] },
{ "name": "local/github", "tools": 4, "includes": 0, "sources": ["mcp"] },
{ "name": "local/devops-toolkit", "tools": 23, "includes": 3, "sources": ["builtin", "mcp", "custom"] },
{ "name": "local/full-stack-dev", "tools": 25, "includes": 4, "sources": ["builtin", "mcp", "custom"] }
],
"summary": {
"total": 5,
"local": 5,
"server": 0,
"total_tools": 28
}
},
"timing": {
"duration_ms": 45
},
"messages": [
{ "level": "ok", "text": "5 skills listed" }
]
}
```
=== "YAML"
```yaml
command: skill list
status: ok
exit_code: 0
data:
skills:
- name: local/file-ops
tools: 9
includes: 0
sources:
- builtin
- name: local/git-ops
tools: 4
includes: 0
sources:
- builtin
- name: local/github
tools: 4
includes: 0
sources:
- mcp
- name: local/devops-toolkit
tools: 23
includes: 3
sources:
- builtin
- mcp
- custom
- name: local/full-stack-dev
tools: 25
includes: 4
sources:
- builtin
- mcp
- custom
summary:
total: 5
local: 5
server: 0
total_tools: 28
timing:
duration_ms: 45
messages:
- level: ok
text: 5 skills listed
```
agents skill show
agents skill show <NAME>Purpose Show full details for a registered skill, including its includes, tool sources, and capability summary.
Arguments
<NAME>: Skill name.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> skill show local/devops-toolkit
╭─ Skill Details ──────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/devops-toolkit │
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> Full-stack development tools │
│ <span style="color: #66cc66; font-weight: 600;">Config:</span> ./skills/devops-toolkit.yaml │
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-08 13:10 │
│ <span style="color: #66cc66; font-weight: 600;">Updated:</span> 2026-02-08 14:22 │
╰──────────────────────────────────────────────╯
╭─ Includes (3) ────────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">local/file-ops</span> → 9 tools (builtin) │
│ <span style="color: #5599ff; font-weight: 600;">local/git-ops</span> → 4 tools (builtin) │
│ <span style="color: #5599ff; font-weight: 600;">local/github</span> → 4 tools (mcp) │
╰───────────────────────────────────────────╯
╭─ Direct Tools (6) ────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name</span> <span style="color: cyan; font-weight: 600;">Source</span> <span style="color: cyan; font-weight: 600;">Writes</span> <span style="color: cyan; font-weight: 600;">Checkpoint</span> │
│ <span style="opacity: 0.7;">──────────────── ─────────── ────── ──────────</span> │
│ create_issue mcp:linear yes no │
│ list_issues mcp:linear no — │
│ deploy-to-staging agent_skill yes composite │
│ code-review agent_skill no — │
│ run_migrations custom yes transaction │
│ shell_execute builtin yes snapshot │
╰───────────────────────────────────────────────────────────╯
╭─ MCP Servers (1) ───────────────────╮
│ <span style="color: #66cc66; font-weight: 600;">linear:</span> stdio, 2 tools, connected │
╰─────────────────────────────────────╯
╭─ Capability Summary ──────────╮
│ <span style="color: #5599ff; font-weight: 600;">Total Tools:</span> 23 │
│ <span style="color: #66cc66; font-weight: 600;">Read-Only:</span> 10 │
│ <span style="color: yellow; font-weight: 600;">Writes:</span> 13 │
│ <span style="color: #66cc66; font-weight: 600;">Checkpointable:</span> 10 │
│ <span style="color: yellow; font-weight: 600;">Has Side Effects:</span> 3 │
│ <span style="color: #5599ff; font-weight: 600;">Requires Approval:</span> 1 │
╰───────────────────────────────╯
╭─ Referenced By ───────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Actors:</span> local/code-assistant │
│ <span style="color: #5599ff; font-weight: 600;">Skills:</span> local/full-stack-dev │
╰───────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Skill loaded
</code></pre></div>
=== "Plain"
```
$ agents skill show local/devops-toolkit
Skill Details
Name: local/devops-toolkit
Description: Full-stack development tools
Config: ./skills/devops-toolkit.yaml
Created: 2026-02-08 13:10
Updated: 2026-02-08 14:22
Includes (3)
local/file-ops -> 9 tools (builtin)
local/git-ops -> 4 tools (builtin)
local/github -> 4 tools (mcp)
Direct Tools (6)
Name Source Writes Checkpoint
---------------- ----------- ------ ----------
create_issue mcp:linear yes no
list_issues mcp:linear no -
deploy-to-staging agent_skill yes composite
code-review agent_skill no -
run_migrations custom yes transaction
shell_execute builtin yes snapshot
MCP Servers (1)
linear: stdio, 2 tools, connected
Capability Summary
Total Tools: 23
Read-Only: 10
Writes: 13
Checkpointable: 10
Has Side Effects: 3
Requires Approval: 1
Referenced By
Actors: local/code-assistant
Skills: local/full-stack-dev
[OK] Skill loaded
```
=== "JSON"
```json
{
"command": "skill show local/devops-toolkit",
"status": "ok",
"exit_code": 0,
"data": {
"skill": {
"name": "local/devops-toolkit",
"description": "Full-stack development tools",
"config": "./skills/devops-toolkit.yaml",
"created": "2026-02-08T13:10:00Z",
"updated": "2026-02-08T14:22:00Z"
},
"includes": [
{ "name": "local/file-ops", "tools": 9, "source": "builtin" },
{ "name": "local/git-ops", "tools": 4, "source": "builtin" },
{ "name": "local/github", "tools": 4, "source": "mcp" }
],
"direct_tools": [
{ "name": "create_issue", "source": "mcp:linear", "writes": true, "checkpoint": "no" },
{ "name": "list_issues", "source": "mcp:linear", "writes": false, "checkpoint": null },
{ "name": "deploy-to-staging", "source": "agent_skill", "writes": true, "checkpoint": "composite" },
{ "name": "code-review", "source": "agent_skill", "writes": false, "checkpoint": null },
{ "name": "run_migrations", "source": "custom", "writes": true, "checkpoint": "transaction" },
{ "name": "shell_execute", "source": "builtin", "writes": true, "checkpoint": "snapshot" }
],
"mcp_servers": [
{ "name": "linear", "transport": "stdio", "tools": 2, "status": "connected" }
],
"capability_summary": {
"total_tools": 23,
"read_only": 10,
"writes": 13,
"checkpointable": 10,
"has_side_effects": 3,
"requires_approval": 1
},
"referenced_by": {
"actors": ["local/code-assistant"],
"skills": ["local/full-stack-dev"]
}
},
"timing": {
"duration_ms": 110
},
"messages": [
{ "level": "ok", "text": "Skill loaded" }
]
}
```
=== "YAML"
```yaml
command: skill show local/devops-toolkit
status: ok
exit_code: 0
data:
skill:
name: local/devops-toolkit
description: Full-stack development tools
config: ./skills/devops-toolkit.yaml
created: "2026-02-08T13:10:00Z"
updated: "2026-02-08T14:22:00Z"
includes:
- name: local/file-ops
tools: 9
source: builtin
- name: local/git-ops
tools: 4
source: builtin
- name: local/github
tools: 4
source: mcp
direct_tools:
- name: create_issue
source: "mcp:linear"
writes: true
checkpoint: "no"
- name: list_issues
source: "mcp:linear"
writes: false
checkpoint: null
- name: deploy-to-staging
source: agent_skill
writes: true
checkpoint: composite
- name: code-review
source: agent_skill
writes: false
checkpoint: null
- name: run_migrations
source: custom
writes: true
checkpoint: transaction
- name: shell_execute
source: builtin
writes: true
checkpoint: snapshot
mcp_servers:
- name: linear
transport: stdio
tools: 2
status: connected
capability_summary:
total_tools: 23
read_only: 10
writes: 13
checkpointable: 10
has_side_effects: 3
requires_approval: 1
referenced_by:
actors:
- local/code-assistant
skills:
- local/full-stack-dev
timing:
duration_ms: 110
messages:
- level: ok
text: Skill loaded
```
agents skill tools
agents skill tools <NAME>Purpose List all tools provided by a skill, including those inherited from included skills (the flattened tool set).
Arguments
<NAME>: Skill name.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> skill tools local/devops-toolkit
╭─ Tools for local/devops-toolkit ─────────────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Tool</span> <span style="color: cyan; font-weight: 600;">Source</span> <span style="color: cyan; font-weight: 600;">From Skill</span> <span style="color: cyan; font-weight: 600;">Read-Only</span> <span style="color: cyan; font-weight: 600;">Writes</span> <span style="color: cyan; font-weight: 600;">Checkpoint</span> │
│ <span style="opacity: 0.7;">───────────────── ─────────── ────────────── ───────── ────── ──────────</span> │
│ read_file builtin local/file-ops ✓ — — │
│ write_file builtin local/file-ops — ✓ file │
│ edit_file builtin local/file-ops — ✓ file │
│ delete_file builtin local/file-ops — ✓ file │
│ move_file builtin local/file-ops — ✓ file │
│ copy_file builtin local/file-ops — ✓ file │
│ create_directory builtin local/file-ops — ✓ file │
│ list_directory builtin local/file-ops ✓ — — │
│ delete_directory builtin local/file-ops — ✓ file │
│ git_status builtin local/git-ops ✓ — — │
│ git_diff builtin local/git-ops ✓ — — │
│ git_log builtin local/git-ops ✓ — — │
│ git_blame builtin local/git-ops ✓ — — │
│ create_issue mcp:github local/github — ✓ no │
│ create_pr mcp:github local/github — ✓ no │
│ list_repos mcp:github local/github ✓ — — │
│ get_file_contents mcp:github local/github ✓ — — │
│ create_issue mcp:linear (direct) — ✓ no │
│ list_issues mcp:linear (direct) ✓ — — │
│ run_migrations custom (direct) — ✓ transaction │
│ deploy-to-staging agent_skill (direct) — ✓ composite │
│ code-review agent_skill (direct) ✓ — — │
│ shell_execute builtin (direct) — ✓ snapshot │
╰──────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Summary ──────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Total:</span> 23 │
│ <span style="color: #66cc66; font-weight: 600;">From Includes:</span> 17 │
│ <span style="color: #5599ff; font-weight: 600;">Direct:</span> 6 │
│ <span style="color: #66cc66; font-weight: 600;">Read-Only:</span> 10 │
│ <span style="color: yellow; font-weight: 600;">Writes:</span> 13 │
│ <span style="color: #66cc66; font-weight: 600;">Checkpointable:</span> 10 │
╰────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 23 tools listed
</code></pre></div>
=== "Plain"
```
$ agents skill tools local/devops-toolkit
Tools for local/devops-toolkit
Tool Source From Skill Read-Only Writes Checkpoint
----------------- ----------- -------------- --------- ------ ----------
read_file builtin local/file-ops yes - -
write_file builtin local/file-ops - yes file
edit_file builtin local/file-ops - yes file
delete_file builtin local/file-ops - yes file
move_file builtin local/file-ops - yes file
copy_file builtin local/file-ops - yes file
create_directory builtin local/file-ops - yes file
list_directory builtin local/file-ops yes - -
delete_directory builtin local/file-ops - yes file
git_status builtin local/git-ops yes - -
git_diff builtin local/git-ops yes - -
git_log builtin local/git-ops yes - -
git_blame builtin local/git-ops yes - -
create_issue mcp:github local/github - yes no
create_pr mcp:github local/github - yes no
list_repos mcp:github local/github yes - -
get_file_contents mcp:github local/github yes - -
create_issue mcp:linear (direct) - yes no
list_issues mcp:linear (direct) yes - -
run_migrations custom (direct) - yes transaction
deploy-to-staging agent_skill (direct) - yes composite
code-review agent_skill (direct) yes - -
shell_execute builtin (direct) - yes snapshot
Summary
Total: 23
From Includes: 17
Direct: 6
Read-Only: 10
Writes: 13
Checkpointable: 10
[OK] 23 tools listed
```
=== "JSON"
```json
{
"command": "skill tools local/devops-toolkit",
"status": "ok",
"exit_code": 0,
"data": {
"tools": [
{ "name": "read_file", "source": "builtin", "from_skill": "local/file-ops", "read_only": true, "writes": false, "checkpoint": null },
{ "name": "write_file", "source": "builtin", "from_skill": "local/file-ops", "read_only": false, "writes": true, "checkpoint": "file" },
{ "name": "edit_file", "source": "builtin", "from_skill": "local/file-ops", "read_only": false, "writes": true, "checkpoint": "file" },
{ "name": "delete_file", "source": "builtin", "from_skill": "local/file-ops", "read_only": false, "writes": true, "checkpoint": "file" },
{ "name": "move_file", "source": "builtin", "from_skill": "local/file-ops", "read_only": false, "writes": true, "checkpoint": "file" },
{ "name": "copy_file", "source": "builtin", "from_skill": "local/file-ops", "read_only": false, "writes": true, "checkpoint": "file" },
{ "name": "create_directory", "source": "builtin", "from_skill": "local/file-ops", "read_only": false, "writes": true, "checkpoint": "file" },
{ "name": "list_directory", "source": "builtin", "from_skill": "local/file-ops", "read_only": true, "writes": false, "checkpoint": null },
{ "name": "delete_directory", "source": "builtin", "from_skill": "local/file-ops", "read_only": false, "writes": true, "checkpoint": "file" },
{ "name": "git_status", "source": "builtin", "from_skill": "local/git-ops", "read_only": true, "writes": false, "checkpoint": null },
{ "name": "git_diff", "source": "builtin", "from_skill": "local/git-ops", "read_only": true, "writes": false, "checkpoint": null },
{ "name": "git_log", "source": "builtin", "from_skill": "local/git-ops", "read_only": true, "writes": false, "checkpoint": null },
{ "name": "git_blame", "source": "builtin", "from_skill": "local/git-ops", "read_only": true, "writes": false, "checkpoint": null },
{ "name": "create_issue", "source": "mcp:github", "from_skill": "local/github", "read_only": false, "writes": true, "checkpoint": "no" },
{ "name": "create_pr", "source": "mcp:github", "from_skill": "local/github", "read_only": false, "writes": true, "checkpoint": "no" },
{ "name": "list_repos", "source": "mcp:github", "from_skill": "local/github", "read_only": true, "writes": false, "checkpoint": null },
{ "name": "get_file_contents", "source": "mcp:github", "from_skill": "local/github", "read_only": true, "writes": false, "checkpoint": null },
{ "name": "create_issue", "source": "mcp:linear", "from_skill": null, "read_only": false, "writes": true, "checkpoint": "no" },
{ "name": "list_issues", "source": "mcp:linear", "from_skill": null, "read_only": true, "writes": false, "checkpoint": null },
{ "name": "run_migrations", "source": "custom", "from_skill": null, "read_only": false, "writes": true, "checkpoint": "transaction" },
{ "name": "deploy-to-staging", "source": "agent_skill", "from_skill": null, "read_only": false, "writes": true, "checkpoint": "composite" },
{ "name": "code-review", "source": "agent_skill", "from_skill": null, "read_only": true, "writes": false, "checkpoint": null },
{ "name": "shell_execute", "source": "builtin", "from_skill": null, "read_only": false, "writes": true, "checkpoint": "snapshot" }
],
"summary": {
"total": 23,
"from_includes": 17,
"direct": 6,
"read_only": 10,
"writes": 13,
"checkpointable": 10
}
},
"timing": {
"duration_ms": 85
},
"messages": [
{ "level": "ok", "text": "23 tools listed" }
]
}
```
=== "YAML"
```yaml
command: skill tools local/devops-toolkit
status: ok
exit_code: 0
data:
tools:
- name: read_file
source: builtin
from_skill: local/file-ops
read_only: true
writes: false
checkpoint: null
- name: write_file
source: builtin
from_skill: local/file-ops
read_only: false
writes: true
checkpoint: file
- name: edit_file
source: builtin
from_skill: local/file-ops
read_only: false
writes: true
checkpoint: file
- name: delete_file
source: builtin
from_skill: local/file-ops
read_only: false
writes: true
checkpoint: file
- name: move_file
source: builtin
from_skill: local/file-ops
read_only: false
writes: true
checkpoint: file
- name: copy_file
source: builtin
from_skill: local/file-ops
read_only: false
writes: true
checkpoint: file
- name: create_directory
source: builtin
from_skill: local/file-ops
read_only: false
writes: true
checkpoint: file
- name: list_directory
source: builtin
from_skill: local/file-ops
read_only: true
writes: false
checkpoint: null
- name: delete_directory
source: builtin
from_skill: local/file-ops
read_only: false
writes: true
checkpoint: file
- name: git_status
source: builtin
from_skill: local/git-ops
read_only: true
writes: false
checkpoint: null
- name: git_diff
source: builtin
from_skill: local/git-ops
read_only: true
writes: false
checkpoint: null
- name: git_log
source: builtin
from_skill: local/git-ops
read_only: true
writes: false
checkpoint: null
- name: git_blame
source: builtin
from_skill: local/git-ops
read_only: true
writes: false
checkpoint: null
- name: create_issue
source: "mcp:github"
from_skill: local/github
read_only: false
writes: true
checkpoint: "no"
- name: create_pr
source: "mcp:github"
from_skill: local/github
read_only: false
writes: true
checkpoint: "no"
- name: list_repos
source: "mcp:github"
from_skill: local/github
read_only: true
writes: false
checkpoint: null
- name: get_file_contents
source: "mcp:github"
from_skill: local/github
read_only: true
writes: false
checkpoint: null
- name: create_issue
source: "mcp:linear"
from_skill: null
read_only: false
writes: true
checkpoint: "no"
- name: list_issues
source: "mcp:linear"
from_skill: null
read_only: true
writes: false
checkpoint: null
- name: run_migrations
source: custom
from_skill: null
read_only: false
writes: true
checkpoint: transaction
- name: deploy-to-staging
source: agent_skill
from_skill: null
read_only: false
writes: true
checkpoint: composite
- name: code-review
source: agent_skill
from_skill: null
read_only: true
writes: false
checkpoint: null
- name: shell_execute
source: builtin
from_skill: null
read_only: false
writes: true
checkpoint: snapshot
summary:
total: 23
from_includes: 17
direct: 6
read_only: 10
writes: 13
checkpointable: 10
timing:
duration_ms: 85
messages:
- level: ok
text: 23 tools listed
```
agents tool
!!! info "Purpose" Manage ==tools== — namespaced, independently registered, callable operations. Tools are defined in their own YAML configuration files and registered in the system through these commands. Once registered, tools can be referenced by name in skills (as part of a tool collection) and in actor graphs (as tool nodes).
??? tip "Tool Lifecycle Overview"
| Stage | Command | Description |
| :---- | :------ | :---------- |
| Register | agents tool add | Register from YAML config |
| Inspect | agents tool show | View tool details and capabilities |
| List | agents tool list | Browse registered tools |
| Update | agents tool add --update | Re-register with updated config |
| Remove | agents tool remove | Unregister a tool |
agents tool add
agents tool add --config|-c <FILE> [--update]Purpose
Register a new tool. The tool is fully defined by the YAML configuration file specified with --config. If a tool with the same name already exists, the command fails unless the --update flag is provided, which allows overwriting the existing registration with the new configuration.
Arguments
--config/-c FILE: Path to the tool YAML configuration file (required). The file must fully define the tool, including thenamefield which determines the tool's registered name.--update: Allow overwriting an existing tool registration. Without this flag, attempting to add a tool whose name is already registered will fail.
Examples
Registering a new tool:
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> tool add <span style="color: cyan;">--config</span> ./tools/run-migrations.yaml
╭─ Tool Registered ────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/run-migrations │
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> Run database migrations │
│ <span style="color: #5599ff; font-weight: 600;">Source:</span> custom │
│ <span style="color: #66cc66; font-weight: 600;">Config:</span> ./tools/run-migrations.yaml │
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-09 10:15 │
╰──────────────────────────────────────────────╯
╭─ Capability ─────────────────────╮
│ <span style="color: yellow; font-weight: 600;">Writes:</span> true │
│ <span style="color: #5599ff; font-weight: 600;">Write Scope:</span> database:migrations │
│ <span style="color: #66cc66; font-weight: 600;">Checkpointable:</span> true │
│ <span style="color: #5599ff; font-weight: 600;">Checkpoint Scope:</span> transaction │
│ <span style="color: yellow; font-weight: 600;">Side Effects:</span> schema_mutation │
╰──────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Tool registered
</code></pre></div>
=== "Plain"
```
$ agents tool add --config ./tools/run-migrations.yaml
Tool Registered
Name: local/run-migrations
Description: Run database migrations
Source: custom
Config: ./tools/run-migrations.yaml
Created: 2026-02-09 10:15
Capability
Writes: true
Write Scope: database:migrations
Checkpointable: true
Checkpoint Scope: transaction
Side Effects: schema_mutation
[OK] Tool registered
```
=== "JSON"
```json
{
"command": "tool add",
"status": "ok",
"exit_code": 0,
"data": {
"tool_registered": {
"name": "local/run-migrations",
"description": "Run database migrations",
"source": "custom",
"config": "./tools/run-migrations.yaml",
"created": "2026-02-09T10:15:00Z"
},
"capability": {
"writes": true,
"write_scope": "database:migrations",
"checkpointable": true,
"checkpoint_scope": "transaction",
"side_effects": ["schema_mutation"]
}
},
"timing": { "duration_ms": 58 },
"messages": ["Tool registered"]
}
```
=== "YAML"
```yaml
command: tool add
status: ok
exit_code: 0
data:
tool_registered:
name: local/run-migrations
description: Run database migrations
source: custom
config: ./tools/run-migrations.yaml
created: "2026-02-09T10:15:00Z"
capability:
writes: true
write_scope: "database:migrations"
checkpointable: true
checkpoint_scope: transaction
side_effects:
- schema_mutation
timing:
duration_ms: 58
messages:
- Tool registered
```
Attempting to add a tool that already exists (without --update):
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> tool add <span style="color: cyan;">--config</span> ./tools/run-migrations-v2.yaml
<span style="color: #ff6666; font-weight: 600;">✗ Error:</span> Tool 'local/run-migrations' is already registered.
To overwrite the existing configuration, re-run with <span style="color: cyan;">--update</span>:
agents tool add <span style="color: cyan;">--config</span> ./tools/run-migrations-v2.yaml <span style="color: cyan;">--update</span>
</code></pre></div>
=== "Plain"
```
$ agents tool add --config ./tools/run-migrations-v2.yaml
[ERROR] Tool 'local/run-migrations' is already registered.
To overwrite the existing configuration, re-run with --update:
agents tool add --config ./tools/run-migrations-v2.yaml --update
```
=== "JSON"
```json
{
"command": "tool add",
"status": "error",
"exit_code": 1,
"data": {
"error": "Tool 'local/run-migrations' is already registered.",
"hint": "To overwrite the existing configuration, re-run with --update",
"suggested_command": "agents tool add --config ./tools/run-migrations-v2.yaml --update"
},
"timing": { "duration_ms": 12 },
"messages": ["Tool 'local/run-migrations' is already registered."]
}
```
=== "YAML"
```yaml
command: tool add
status: error
exit_code: 1
data:
error: "Tool 'local/run-migrations' is already registered."
hint: "To overwrite the existing configuration, re-run with --update"
suggested_command: "agents tool add --config ./tools/run-migrations-v2.yaml --update"
timing:
duration_ms: 12
messages:
- "Tool 'local/run-migrations' is already registered."
```
Updating an existing tool with --update:
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> tool add <span style="color: cyan;">--config</span> ./tools/db-migrate.yaml <span style="color: cyan;">--update</span>
╭─ Tool Updated ─────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/db-migrate │
│ <span style="color: #5599ff; font-weight: 600;">Source:</span> custom (Python) │
│ <span style="color: yellow; font-weight: 600;">Status:</span> updated (was version 1 → now 2) │
╰────────────────────────────────────────────╯
╭─ Changes ─────────────────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Input Schema:</span> modified (added batch_size) │
│ <span style="color: #5599ff; font-weight: 600;">Capabilities:</span> unchanged (writes, checkpoint) │
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> updated │
╰───────────────────────────────────────────────╯
╭─ References ──────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Skills:</span> 1 (local/db-tools) │
│ <span style="color: #5599ff; font-weight: 600;">Actors:</span> 0 │
│ <span style="opacity: 0.7;">Referencing skills will use</span> │
│ <span style="opacity: 0.7;">the updated definition.</span> │
╰───────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Tool updated
</code></pre></div>
=== "Plain"
```
$ agents tool add --config ./tools/db-migrate.yaml --update
Tool Updated
Name: local/db-migrate
Source: custom (Python)
Status: updated (was version 1 -> now 2)
Changes
Input Schema: modified (added batch_size)
Capabilities: unchanged (writes, checkpoint)
Description: updated
References
Skills: 1 (local/db-tools)
Actors: 0
Referencing skills will use the updated definition.
[OK] Tool updated
```
=== "JSON"
```json
{
"command": "tool add",
"status": "ok",
"exit_code": 0,
"data": {
"tool_updated": {
"name": "local/db-migrate",
"source": "custom",
"source_language": "Python",
"status": "updated",
"previous_version": 1,
"current_version": 2
},
"changes": {
"input_schema": "modified (added batch_size)",
"capabilities": "unchanged (writes, checkpoint)",
"description": "updated"
},
"references": {
"skills": ["local/db-tools"],
"actors": []
}
},
"timing": { "duration_ms": 45 },
"messages": ["Tool updated"]
}
```
=== "YAML"
```yaml
command: tool add
status: ok
exit_code: 0
data:
tool_updated:
name: local/db-migrate
source: custom
source_language: Python
status: updated
previous_version: 1
current_version: 2
changes:
input_schema: "modified (added batch_size)"
capabilities: "unchanged (writes, checkpoint)"
description: updated
references:
skills:
- local/db-tools
actors: []
timing:
duration_ms: 45
messages:
- Tool updated
```
agents tool remove
agents tool remove [--yes|-y] <NAME>!!! danger "Destructive Operation" Remove a registered tool. Because Validations are a subtype of Tool and share the same registry, this command ==also removes validations==. When removing a Validation, all attachments are automatically detached before the entry is removed from the registry.
References from skills and actor graphs will **break** until resolved.
Arguments
<NAME>: Tool or validation name to remove.--yes: Skip confirmation prompt.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> tool remove local/run-migrations
Remove tool local/run-migrations? [y/N]: y
╭─ Tool Removed ────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/run-migrations │
│ <span style="color: #5599ff; font-weight: 600;">Source:</span> custom │
╰───────────────────────────────────╯
╭─ References ──────────────────────────────────────╮
│ <span style="color: yellow; font-weight: 600;">Warning:</span> This tool is referenced by: │
│ - Skill: local/devops-toolkit │
│ - Actor graph node: code_executor.run_db_migrate │
│ These references will break until resolved. │
╰───────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Tool removed
</code></pre></div>
=== "Plain"
```
$ agents tool remove local/run-migrations
Remove tool local/run-migrations? [y/N]: y
Tool Removed
Name: local/run-migrations
Source: custom
References
Warning: This tool is referenced by:
- Skill: local/devops-toolkit
- Actor graph node: code_executor.run_db_migrate
These references will break until resolved.
[OK] Tool removed
```
=== "JSON"
```json
{
"command": "tool remove",
"status": "ok",
"exit_code": 0,
"data": {
"tool_removed": {
"name": "local/run-migrations",
"source": "custom"
},
"broken_references": [
{ "type": "skill", "name": "local/devops-toolkit" },
{ "type": "actor_graph_node", "name": "code_executor.run_db_migrate" }
]
},
"timing": { "duration_ms": 34 },
"messages": [
"Tool removed",
"Warning: This tool is referenced by 1 skill and 1 actor graph node. These references will break until resolved."
]
}
```
=== "YAML"
```yaml
command: tool remove
status: ok
exit_code: 0
data:
tool_removed:
name: local/run-migrations
source: custom
broken_references:
- type: skill
name: local/devops-toolkit
- type: actor_graph_node
name: code_executor.run_db_migrate
timing:
duration_ms: 34
messages:
- Tool removed
- "Warning: This tool is referenced by 1 skill and 1 actor graph node. These references will break until resolved."
```
When removing a validation, attachments are cleaned up automatically:
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> tool remove local/check-bundle-size
Remove validation local/check-bundle-size? [y/N]: y
╭─ Validation Removed ─────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/check-bundle-size │
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> Check bundle size (advisory) │
╰──────────────────────────────────────────────────╯
╭─ Detached From ────────────────────────────────────────────╮
│ <span style="color: yellow; font-weight: 600;">Warning:</span> This validation had 2 attachments: │
│ - local/api-repo (scope: project local/api-service) │
│ - local/api-repo (direct) │
│ These attachments have been removed. │
╰────────────────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Validation removed─
</code></pre></div>
=== "Plain"
```
$ agents tool remove local/check-bundle-size
Remove validation local/check-bundle-size? [y/N]: y
Validation Removed
Name: local/check-bundle-size
Description: Check bundle size (advisory)
Detached From
Warning: This validation had 2 attachments:
- local/api-repo (scope: project local/api-service)
- local/api-repo (direct)
These attachments have been removed.
[OK] Validation removed
```
=== "JSON"
```json
{
"command": "tool remove",
"status": "ok",
"exit_code": 0,
"data": {
"validation_removed": {
"name": "local/check-bundle-size",
"description": "Check bundle size (advisory)"
},
"detached_attachments": [
{ "resource": "local/api-repo", "scope": "project", "project": "local/api-service" },
{ "resource": "local/api-repo", "scope": "direct" }
]
},
"timing": { "duration_ms": 41 },
"messages": [
"Validation removed",
"Warning: This validation had 2 attachments which have been removed."
]
}
```
=== "YAML"
```yaml
command: tool remove
status: ok
exit_code: 0
data:
validation_removed:
name: local/check-bundle-size
description: "Check bundle size (advisory)"
detached_attachments:
- resource: local/api-repo
scope: project
project: local/api-service
- resource: local/api-repo
scope: direct
timing:
duration_ms: 41
messages:
- Validation removed
- "Warning: This validation had 2 attachments which have been removed."
```
agents tool list
agents tool list [(--namespace|-n) <NS>] [--source <SOURCE>] [--type (tool|validation)] [<REGEX>]Purpose
List registered tools with optional filters. Because Validations are a subtype of Tool and share the same registry, this command lists both plain tools and validations. Use --type validation to show only validations, or --type tool to show only plain tools. When --type is omitted, both are listed with a Type column distinguishing them.
Arguments
--namespace/-n NS: Filter by namespace.--source SOURCE: Filter by tool source type (mcp, agent_skill, builtin, custom).--type TYPE: Filter by entry type:tool(plain tools only) orvalidation(validations only). When omitted, both are listed.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> tool list <span style="color: cyan;">--namespace</span> local
╭─ Tools ─────────────────────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name</span> <span style="color: cyan; font-weight: 600;">Type</span> <span style="color: cyan; font-weight: 600;">Source</span> <span style="color: cyan; font-weight: 600;">Read-Only</span> <span style="color: cyan; font-weight: 600;">Writes</span> │
│ <span style="opacity: 0.7;">───────────────────────── ────────── ─────── ───────── ──────</span> │
│ local/run-migrations tool custom — ✓ │
│ local/validate-api-compat tool custom — ✓ │
│ local/create-subplan tool custom — ✓ │
│ local/deploy-staging tool agent — ✓ │
│ local/run-tests validation custom ✓ — │
│ local/lint-check validation custom ✓ — │
│ local/check-bundle-size validation custom ✓ — │
│ local/type-check validation custom ✓ — │
╰─────────────────────────────────────────────────────────────────────────╯
╭─ Summary ────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Total:</span> 8 │
│ <span style="color: #5599ff; font-weight: 600;">Tools:</span> 4 │
│ <span style="color: #5599ff; font-weight: 600;">Validations:</span> 4 │
│ <span style="color: #66cc66; font-weight: 600;">Read-Only:</span> 4 │
│ <span style="color: yellow; font-weight: 600;">Writes:</span> 4 │
╰──────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 8 tools listed
</code></pre></div>
=== "Plain"
```
$ agents tool list --namespace local
Tools
Name Type Source Read-Only Writes
------------------------- ---------- ------- --------- ------
local/run-migrations tool custom - yes
local/validate-api-compat tool custom - yes
local/create-subplan tool custom - yes
local/deploy-staging tool agent - yes
local/run-tests validation custom yes -
local/lint-check validation custom yes -
local/check-bundle-size validation custom yes -
local/type-check validation custom yes -
Summary
Total: 8
Tools: 4
Validations: 4
Read-Only: 4
Writes: 4
[OK] 8 tools listed
```
=== "JSON"
```json
{
"command": "tool list",
"status": "ok",
"exit_code": 0,
"data": {
"tools": [
{ "name": "local/run-migrations", "type": "tool", "source": "custom", "read_only": false, "writes": true },
{ "name": "local/validate-api-compat", "type": "tool", "source": "custom", "read_only": false, "writes": true },
{ "name": "local/create-subplan", "type": "tool", "source": "custom", "read_only": false, "writes": true },
{ "name": "local/deploy-staging", "type": "tool", "source": "agent", "read_only": false, "writes": true },
{ "name": "local/run-tests", "type": "validation", "source": "custom", "read_only": true, "writes": false },
{ "name": "local/lint-check", "type": "validation", "source": "custom", "read_only": true, "writes": false },
{ "name": "local/check-bundle-size", "type": "validation", "source": "custom", "read_only": true, "writes": false },
{ "name": "local/type-check", "type": "validation", "source": "custom", "read_only": true, "writes": false }
],
"summary": {
"total": 8,
"tools": 4,
"validations": 4,
"read_only": 4,
"writes": 4
}
},
"timing": { "duration_ms": 22 },
"messages": ["8 tools listed"]
}
```
=== "YAML"
```yaml
command: tool list
status: ok
exit_code: 0
data:
tools:
- name: local/run-migrations
type: tool
source: custom
read_only: false
writes: true
- name: local/validate-api-compat
type: tool
source: custom
read_only: false
writes: true
- name: local/create-subplan
type: tool
source: custom
read_only: false
writes: true
- name: local/deploy-staging
type: tool
source: agent
read_only: false
writes: true
- name: local/run-tests
type: validation
source: custom
read_only: true
writes: false
- name: local/lint-check
type: validation
source: custom
read_only: true
writes: false
- name: local/check-bundle-size
type: validation
source: custom
read_only: true
writes: false
- name: local/type-check
type: validation
source: custom
read_only: true
writes: false
summary:
total: 8
tools: 4
validations: 4
read_only: 4
writes: 4
timing:
duration_ms: 22
messages:
- 8 tools listed
```
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> tool list <span style="color: cyan;">--type</span> validation <span style="color: cyan;">--namespace</span> local
╭─ Validations ─────────────────────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name</span> <span style="color: cyan; font-weight: 600;">Source</span> <span style="color: cyan; font-weight: 600;">Mode</span> <span style="color: cyan; font-weight: 600;">Attachments</span> │
│ <span style="opacity: 0.7;">───────────────────────── ─────── ──────────── ────────────────────────</span> │
│ local/run-tests custom required 2 (1 direct, 1 project) │
│ local/lint-check custom required 1 (1 direct) │
│ local/check-bundle-size custom informational 1 (1 project) │
│ local/type-check custom required 2 (2 project) │
╰───────────────────────────────────────────────────────────────────────────────╯
╭─ Summary ──────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Total:</span> 4 │
│ <span style="color: #66cc66; font-weight: 600;">Required:</span> 3 │
│ <span style="color: yellow; font-weight: 600;">Informational:</span> 1 │
╰────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 4 validations listed
</code></pre></div>
=== "Plain"
```
$ agents tool list --type validation --namespace local
Validations
Name Source Mode Attachments
------------------------- ------- ------------ ------------------------
local/run-tests custom required 2 (1 direct, 1 project)
local/lint-check custom required 1 (1 direct)
local/check-bundle-size custom informational 1 (1 project)
local/type-check custom required 2 (2 project)
Summary
Total: 4
Required: 3
Informational: 1
[OK] 4 validations listed
```
=== "JSON"
```json
{
"command": "tool list",
"status": "ok",
"exit_code": 0,
"data": {
"validations": [
{ "name": "local/run-tests", "source": "custom", "mode": "required", "attachments": { "total": 2, "direct": 1, "project": 1 } },
{ "name": "local/lint-check", "source": "custom", "mode": "required", "attachments": { "total": 1, "direct": 1 } },
{ "name": "local/check-bundle-size", "source": "custom", "mode": "informational", "attachments": { "total": 1, "project": 1 } },
{ "name": "local/type-check", "source": "custom", "mode": "required", "attachments": { "total": 2, "project": 2 } }
],
"summary": {
"total": 4,
"required": 3,
"informational": 1
}
},
"timing": { "duration_ms": 18 },
"messages": ["4 validations listed"]
}
```
=== "YAML"
```yaml
command: tool list
status: ok
exit_code: 0
data:
validations:
- name: local/run-tests
source: custom
mode: required
attachments:
total: 2
direct: 1
project: 1
- name: local/lint-check
source: custom
mode: required
attachments:
total: 1
direct: 1
- name: local/check-bundle-size
source: custom
mode: informational
attachments:
total: 1
project: 1
- name: local/type-check
source: custom
mode: required
attachments:
total: 2
project: 2
summary:
total: 4
required: 3
informational: 1
timing:
duration_ms: 18
messages:
- 4 validations listed
```
agents tool show
agents tool show <NAME>Purpose
Show full details for a registered tool, including its schema, capability metadata, and where it is referenced. Because Validations are a subtype of Tool and share the same registry, this command also shows validation details. When showing a Validation, additional validation-specific fields are displayed: Mode (required/informational) and Attached To (listing each resource attachment with its scope — direct, project-scoped, or plan-scoped).
Arguments
<NAME>: Tool or validation name.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> tool show local/run-migrations
╭─ Tool Details ───────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/run-migrations │
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> Run database migrations │
│ <span style="color: #5599ff; font-weight: 600;">Source:</span> custom │
│ <span style="color: #66cc66; font-weight: 600;">Config:</span> ./tools/run-migrations.yaml │
│ <span style="color: #66cc66; font-weight: 600;">Registered:</span> 2026-02-09 10:15 │
╰──────────────────────────────────────────────╯
╭─ Input Schema ─────────────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">direction</span>: string (required) enum: [up, down] │
│ <span style="color: #5599ff; font-weight: 600;">count</span>: integer (default: 1) │
╰────────────────────────────────────────────────╯
╭─ Capability ──────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Read-Only:</span> false │
│ <span style="color: yellow; font-weight: 600;">Writes:</span> true │
│ <span style="color: #5599ff; font-weight: 600;">Write Scope:</span> database:migrations │
│ <span style="color: #66cc66; font-weight: 600;">Checkpointable:</span> true │
│ <span style="color: #5599ff; font-weight: 600;">Checkpoint Scope:</span> transaction │
│ <span style="color: yellow; font-weight: 600;">Side Effects:</span> schema_mutation │
│ <span style="color: #5599ff; font-weight: 600;">Idempotent:</span> false │
╰───────────────────────────────────╯
╭─ Referenced By ───────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Skills:</span> │
│ - local/devops-toolkit │
│ <span style="color: #5599ff; font-weight: 600;">Actor Graph Nodes:</span> │
│ - code_executor.run_db_migrate │
╰───────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Tool details loaded
</code></pre></div>
=== "Plain"
```
$ agents tool show local/run-migrations
Tool Details
Name: local/run-migrations
Description: Run database migrations
Source: custom
Config: ./tools/run-migrations.yaml
Registered: 2026-02-09 10:15
Input Schema
direction: string (required) enum: [up, down]
count: integer (default: 1)
Capability
Read-Only: false
Writes: true
Write Scope: database:migrations
Checkpointable: true
Checkpoint Scope: transaction
Side Effects: schema_mutation
Idempotent: false
Referenced By
Skills:
- local/devops-toolkit
Actor Graph Nodes:
- code_executor.run_db_migrate
[OK] Tool details loaded
```
=== "JSON"
```json
{
"command": "tool show",
"status": "ok",
"exit_code": 0,
"data": {
"tool_details": {
"name": "local/run-migrations",
"description": "Run database migrations",
"source": "custom",
"config": "./tools/run-migrations.yaml",
"registered": "2026-02-09T10:15:00Z"
},
"input_schema": {
"direction": { "type": "string", "required": true, "enum": ["up", "down"] },
"count": { "type": "integer", "default": 1 }
},
"capability": {
"read_only": false,
"writes": true,
"write_scope": "database:migrations",
"checkpointable": true,
"checkpoint_scope": "transaction",
"side_effects": ["schema_mutation"],
"idempotent": false
},
"referenced_by": {
"skills": ["local/devops-toolkit"],
"actor_graph_nodes": ["code_executor.run_db_migrate"]
}
},
"timing": { "duration_ms": 15 },
"messages": ["Tool details loaded"]
}
```
=== "YAML"
```yaml
command: tool show
status: ok
exit_code: 0
data:
tool_details:
name: local/run-migrations
description: Run database migrations
source: custom
config: ./tools/run-migrations.yaml
registered: "2026-02-09T10:15:00Z"
input_schema:
direction:
type: string
required: true
enum:
- up
- down
count:
type: integer
default: 1
capability:
read_only: false
writes: true
write_scope: "database:migrations"
checkpointable: true
checkpoint_scope: transaction
side_effects:
- schema_mutation
idempotent: false
referenced_by:
skills:
- local/devops-toolkit
actor_graph_nodes:
- code_executor.run_db_migrate
timing:
duration_ms: 15
messages:
- Tool details loaded
```
When showing a Validation, the output includes validation-specific sections:
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> tool show local/run-tests
╭─ Validation Details ──────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/run-tests │
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> validation │
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> Run unit tests with coverage │
│ <span style="color: #5599ff; font-weight: 600;">Source:</span> custom │
│ <span style="color: #66cc66; font-weight: 600;">Mode:</span> required │
│ <span style="color: #66cc66; font-weight: 600;">Config:</span> ./validations/run-tests.yaml │
│ <span style="color: #66cc66; font-weight: 600;">Registered:</span> 2026-02-09 10:15 │
╰───────────────────────────────────────────────────╯
╭─ Input Schema ─────────────────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">coverage_threshold</span>: integer (default: 80) │
╰────────────────────────────────────────────────────╯
╭─ Output Schema (Validation Return Format) ─────────╮
│ <span style="color: #66cc66; font-weight: 600;">passed</span>: boolean (required) │
│ <span style="color: #5599ff; font-weight: 600;">message</span>: string (optional) │
│ <span style="color: #5599ff; font-weight: 600;">data</span>: object (optional, arbitrary structure) │
╰────────────────────────────────────────────────────╯
╭─ Capability ──────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Read-Only:</span> true (enforced) │
│ <span style="color: #66cc66; font-weight: 600;">Checkpointable:</span> false (enforced) │
│ <span style="color: yellow; font-weight: 600;">Timeout:</span> 600s │
╰───────────────────────────────────╯
╭─ Attached To ─────────────────────────────────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">local/api-repo</span> (direct, always active) │
│ <span style="opacity: 0.7;">(attachment: 01HXM5B2C3D4E5F6G7H8J9K0L1)</span> │
│ <span style="color: #5599ff; font-weight: 600;">local/api-repo</span> (scope: project local/api-service) │
│ <span style="opacity: 0.7;">(attachment: 01HXM5A1B2C3D4E5F6G7H8J9K0)</span> │
╰───────────────────────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Validation details loaded
</code></pre></div>
=== "Plain"
```
$ agents tool show local/run-tests
Validation Details
Name: local/run-tests
Type: validation
Description: Run unit tests with coverage
Source: custom
Mode: required
Config: ./validations/run-tests.yaml
Registered: 2026-02-09 10:15
Input Schema
coverage_threshold: integer (default: 80)
Output Schema (Validation Return Format)
passed: boolean (required)
message: string (optional)
data: object (optional, arbitrary structure)
Capability
Read-Only: true (enforced)
Checkpointable: false (enforced)
Timeout: 600s
Attached To
local/api-repo (direct, always active)
(attachment: 01HXM5B2C3D4E5F6G7H8J9K0L1)
local/api-repo (scope: project local/api-service)
(attachment: 01HXM5A1B2C3D4E5F6G7H8J9K0)
[OK] Validation details loaded
```
=== "JSON"
```json
{
"command": "tool show",
"status": "ok",
"exit_code": 0,
"data": {
"validation_details": {
"name": "local/run-tests",
"type": "validation",
"description": "Run unit tests with coverage",
"source": "custom",
"mode": "required",
"config": "./validations/run-tests.yaml",
"registered": "2026-02-09T10:15:00Z"
},
"input_schema": {
"coverage_threshold": { "type": "integer", "default": 80 }
},
"output_schema": {
"passed": { "type": "boolean", "required": true },
"message": { "type": "string", "required": false },
"data": { "type": "object", "required": false, "description": "arbitrary structure" }
},
"capability": {
"read_only": true,
"read_only_enforced": true,
"checkpointable": false,
"checkpointable_enforced": true,
"timeout_seconds": 600
},
"attached_to": [
{ "resource": "local/api-repo", "scope": "direct", "attachment_id": "01HXM5B2C3D4E5F6G7H8J9K0L1" },
{ "resource": "local/api-repo", "scope": "project", "project": "local/api-service", "attachment_id": "01HXM5A1B2C3D4E5F6G7H8J9K0" }
]
},
"timing": { "duration_ms": 19 },
"messages": ["Validation details loaded"]
}
```
=== "YAML"
```yaml
command: tool show
status: ok
exit_code: 0
data:
validation_details:
name: local/run-tests
type: validation
description: Run unit tests with coverage
source: custom
mode: required
config: ./validations/run-tests.yaml
registered: "2026-02-09T10:15:00Z"
input_schema:
coverage_threshold:
type: integer
default: 80
output_schema:
passed:
type: boolean
required: true
message:
type: string
required: false
data:
type: object
required: false
description: arbitrary structure
capability:
read_only: true
read_only_enforced: true
checkpointable: false
checkpointable_enforced: true
timeout_seconds: 600
attached_to:
- resource: local/api-repo
scope: direct
attachment_id: 01HXM5B2C3D4E5F6G7H8J9K0L1
- resource: local/api-repo
scope: project
project: local/api-service
attachment_id: 01HXM5A1B2C3D4E5F6G7H8J9K0
timing:
duration_ms: 19
messages:
- Validation details loaded
```
agents lsp
!!! info "Purpose"
Manage the LSP Registry — the global registry of Language Server Protocol servers that provide language intelligence (diagnostics, type information, completions, references, definitions, symbols, formatting, code actions, renaming) to actors. LSP servers are Infrastructure-layer components attached to actors via the lsp: configuration field; they have nothing to do with IDE integration. Each registered LSP server has a namespaced name ([[server:]namespace/]name), a launch command, supported languages, initialization options, and capability declarations. The agents lsp commands mirror the structure of agents tool commands.
agents lsp add
agents lsp add [--update|-u] (--config|-c) <FILE>Purpose
Register an LSP server from a YAML configuration file. The config file defines the server's namespaced name, launch command, supported languages, initialization options, and capability declarations. If the server already exists and --update is not provided, the command fails with an error and a hint to use --update.
Arguments
--config/-c FILE: Path to LSP server YAML configuration file (required).--update/-u: Overwrite if the server already exists in the registry.
Examples
Registering a new LSP server:
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> lsp add <span style="color: cyan;">--config</span> lsp/pyright.yaml
╭─ LSP Server Registered ──────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/pyright │
│ <span style="color: #5599ff; font-weight: 600;">Languages:</span> python │
│ <span style="color: #5599ff; font-weight: 600;">Command:</span> pyright-langserver --stdio │
│ <span style="color: #5599ff; font-weight: 600;">Capabilities:</span> diagnostics, hover, completions, │
│ references, definitions, symbols, │
│ rename, code_actions │
╰──────────────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> LSP server registered
</code></pre></div>
=== "Plain"
```
$ agents lsp add --config lsp/pyright.yaml
LSP Server Registered
Name: local/pyright
Languages: python
Command: pyright-langserver --stdio
Capabilities: diagnostics, hover, completions, references, definitions, symbols, rename, code_actions
[OK] LSP server registered
```
=== "JSON"
```json
{
"command": "lsp add",
"status": "ok",
"exit_code": 0,
"data": {
"lsp_server": {
"name": "local/pyright",
"languages": ["python"],
"command": "pyright-langserver --stdio",
"capabilities": [
"diagnostics", "hover", "completions", "references",
"definitions", "symbols", "rename", "code_actions"
]
}
},
"timing": { "duration_ms": 12 },
"messages": ["LSP server registered"]
}
```
=== "YAML"
```yaml
command: lsp add
status: ok
exit_code: 0
data:
lsp_server:
name: local/pyright
languages:
- python
command: pyright-langserver --stdio
capabilities:
- diagnostics
- hover
- completions
- references
- definitions
- symbols
- rename
- code_actions
timing:
duration_ms: 12
messages:
- LSP server registered
```
Attempting to add a server that already exists (without --update):
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> lsp add <span style="color: cyan;">--config</span> lsp/pyright.yaml
<span style="color: red; font-weight: 600;">✗ ERROR</span> LSP server 'local/pyright' already exists
<span style="color: yellow;">Hint:</span> Use <span style="color: cyan;">--update</span> to overwrite: agents lsp add --update --config lsp/pyright.yaml
</code></pre></div>
=== "Plain"
```
$ agents lsp add --config lsp/pyright.yaml
[ERROR] LSP server 'local/pyright' already exists
Hint: Use --update to overwrite: agents lsp add --update --config lsp/pyright.yaml
```
=== "JSON"
```json
{
"command": "lsp add",
"status": "error",
"exit_code": 1,
"data": {
"error": "LSP server 'local/pyright' already exists"
},
"hint": "Use --update to overwrite",
"suggested_command": "agents lsp add --update --config lsp/pyright.yaml",
"timing": { "duration_ms": 5 },
"messages": ["LSP server 'local/pyright' already exists"]
}
```
=== "YAML"
```yaml
command: lsp add
status: error
exit_code: 1
data:
error: "LSP server 'local/pyright' already exists"
hint: Use --update to overwrite
suggested_command: agents lsp add --update --config lsp/pyright.yaml
timing:
duration_ms: 5
messages:
- "LSP server 'local/pyright' already exists"
```
agents lsp remove
agents lsp remove [--yes|-y] <NAME>!!! danger "Destructive Operation" Remove a registered LSP server from the LSP Registry. Running LSP server processes bound to the removed entry are terminated. Actor configurations referencing this server by name will fail at activation until resolved.
Arguments
<NAME>: Namespaced LSP server name to remove.--yes/-y: Skip confirmation prompt.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> lsp remove local/pyright
Remove LSP server local/pyright? [y/N]: y
╭─ LSP Server Removed ─────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/pyright │
│ <span style="color: #5599ff; font-weight: 600;">Languages:</span> python │
╰──────────────────────────────────────────╯
╭─ References ──────────────────────────────────────────────────╮
│ <span style="color: yellow; font-weight: 600;">Warning:</span> This LSP server is referenced by: │
│ - Actor: local/code-reviewer (lsp: [local/pyright]) │
│ - Actor: local/refactor-agent (lsp: [local/pyright]) │
│ These actor LSP bindings will fail until resolved. │
╰───────────────────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> LSP server removed
</code></pre></div>
=== "Plain"
```
$ agents lsp remove local/pyright
Remove LSP server local/pyright? [y/N]: y
LSP Server Removed
Name: local/pyright
Languages: python
References
Warning: This LSP server is referenced by:
- Actor: local/code-reviewer (lsp: [local/pyright])
- Actor: local/refactor-agent (lsp: [local/pyright])
These actor LSP bindings will fail until resolved.
[OK] LSP server removed
```
=== "JSON"
```json
{
"command": "lsp remove",
"status": "ok",
"exit_code": 0,
"data": {
"lsp_server_removed": {
"name": "local/pyright",
"languages": ["python"]
},
"broken_references": [
{ "type": "actor", "name": "local/code-reviewer" },
{ "type": "actor", "name": "local/refactor-agent" }
]
},
"timing": { "duration_ms": 28 },
"messages": [
"LSP server removed",
"Warning: This LSP server is referenced by 2 actors. These actor LSP bindings will fail until resolved."
]
}
```
=== "YAML"
```yaml
command: lsp remove
status: ok
exit_code: 0
data:
lsp_server_removed:
name: local/pyright
languages:
- python
broken_references:
- type: actor
name: local/code-reviewer
- type: actor
name: local/refactor-agent
timing:
duration_ms: 28
messages:
- LSP server removed
- "Warning: This LSP server is referenced by 2 actors. These actor LSP bindings will fail until resolved."
```
agents lsp list
agents lsp list [(--namespace|-n) <NS>] [--language <LANG>] [<REGEX>]Purpose List registered LSP servers with optional filters. Shows each server's name, supported languages, command, and the number of actors currently bound to it.
Arguments
--namespace/-n NS: Filter by namespace.--language LANG: Filter by supported language (e.g.,python,typescript).<REGEX>: Optional name filter pattern.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> lsp list
╭─ LSP Registry (3 servers) ───────────────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name</span> │ <span style="color: cyan; font-weight: 600;">Languages</span> │ <span style="color: cyan; font-weight: 600;">Command</span> │ <span style="color: cyan; font-weight: 600;">Bound</span> │
│─────────────────────────│──────────────────────│─────────────────────────────│───────│
│ local/pyright │ python │ pyright-langserver --stdio │ 3 │
│ local/ts-server │ typescript, jsx, tsx │ typescript-language-server │ 2 │
│ local/gopls │ go │ gopls serve │ 1 │
╰──────────────────────────────────────────────────────────────────────────────────────╯
</code></pre></div>
=== "Plain"
```
$ agents lsp list
LSP Registry (3 servers)
Name Languages Command Bound
local/pyright python pyright-langserver --stdio 3
local/ts-server typescript, jsx, tsx typescript-language-server 2
local/gopls go gopls serve 1
```
=== "JSON"
```json
{
"command": "lsp list",
"status": "ok",
"exit_code": 0,
"data": {
"lsp_servers": [
{
"name": "local/pyright",
"languages": ["python"],
"command": "pyright-langserver --stdio",
"bound_actors": 3
},
{
"name": "local/ts-server",
"languages": ["typescript", "jsx", "tsx"],
"command": "typescript-language-server",
"bound_actors": 2
},
{
"name": "local/gopls",
"languages": ["go"],
"command": "gopls serve",
"bound_actors": 1
}
],
"total": 3
},
"timing": { "duration_ms": 8 },
"messages": ["3 LSP servers listed"]
}
```
=== "YAML"
```yaml
command: lsp list
status: ok
exit_code: 0
data:
lsp_servers:
- name: local/pyright
languages:
- python
command: pyright-langserver --stdio
bound_actors: 3
- name: local/ts-server
languages:
- typescript
- jsx
- tsx
command: typescript-language-server
bound_actors: 2
- name: local/gopls
languages:
- go
command: gopls serve
bound_actors: 1
total: 3
timing:
duration_ms: 8
messages:
- 3 LSP servers listed
```
Filtering by language:
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> lsp list <span style="color: cyan;">--language</span> python
╭─ LSP Registry (1 server, filtered: language=python) ─────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name</span> │ <span style="color: cyan; font-weight: 600;">Languages</span> │ <span style="color: cyan; font-weight: 600;">Command</span> │ <span style="color: cyan; font-weight: 600;">Bound</span> │
│─────────────────────────│────────────│───────────────────────────────────│───────│
│ local/pyright │ python │ pyright-langserver --stdio │ 3 │
╰──────────────────────────────────────────────────────────────────────────────────╯
</code></pre></div>
=== "Plain"
```
$ agents lsp list --language python
LSP Registry (1 server, filtered: language=python)
Name Languages Command Bound
local/pyright python pyright-langserver --stdio 3
```
=== "JSON"
```json
{
"command": "lsp list",
"status": "ok",
"exit_code": 0,
"data": {
"lsp_servers": [
{
"name": "local/pyright",
"languages": ["python"],
"command": "pyright-langserver --stdio",
"bound_actors": 3
}
],
"total": 1,
"filter": { "language": "python" }
},
"timing": { "duration_ms": 6 },
"messages": ["1 LSP server listed (filtered: language=python)"]
}
```
=== "YAML"
```yaml
command: lsp list
status: ok
exit_code: 0
data:
lsp_servers:
- name: local/pyright
languages:
- python
command: pyright-langserver --stdio
bound_actors: 3
total: 1
filter:
language: python
timing:
duration_ms: 6
messages:
- "1 LSP server listed (filtered: language=python)"
```
agents lsp show
agents lsp show <NAME>Purpose Show full details for a registered LSP server, including its configuration, supported languages, capabilities, initialization options, and which actors are bound to it.
Arguments
<NAME>: Namespaced LSP server name.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> lsp show local/pyright
╭─ LSP Server Details ──────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/pyright │
│ <span style="color: #5599ff; font-weight: 600;">Languages:</span> python │
│ <span style="color: #5599ff; font-weight: 600;">Command:</span> pyright-langserver --stdio │
│ <span style="color: #5599ff; font-weight: 600;">Root path:</span> {{ project.root }} │
│ <span style="color: #5599ff; font-weight: 600;">Init options:</span> │
│ python.analysis.typeCheckingMode: standard │
│ python.analysis.autoSearchPaths: true │
╰───────────────────────────────────────────────────────────────╯
╭─ Capabilities ────────────────────────────────────────────────╮
│ diagnostics, hover, completions, references, definitions, │
│ symbols, rename, code_actions │
╰───────────────────────────────────────────────────────────────╯
╭─ Bound Actors ────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">local/code-reviewer</span> (explicit binding) │
│ <span style="color: cyan; font-weight: 600;">local/refactor-agent</span> (language-based: python) │
│ <span style="color: cyan; font-weight: 600;">local/polyglot-planner</span> (auto-discovery) │
╰───────────────────────────────────────────────────────────────╯
</code></pre></div>
=== "Plain"
```
$ agents lsp show local/pyright
LSP Server Details
Name: local/pyright
Languages: python
Command: pyright-langserver --stdio
Root path: {{ project.root }}
Init options:
python.analysis.typeCheckingMode: standard
python.analysis.autoSearchPaths: true
Capabilities
diagnostics, hover, completions, references, definitions, symbols, rename, code_actions
Bound Actors
local/code-reviewer (explicit binding)
local/refactor-agent (language-based: python)
local/polyglot-planner (auto-discovery)
```
=== "JSON"
```json
{
"command": "lsp show",
"status": "ok",
"exit_code": 0,
"data": {
"lsp_server": {
"name": "local/pyright",
"languages": ["python"],
"command": "pyright-langserver --stdio",
"root_path": "{{ project.root }}",
"init_options": {
"python.analysis.typeCheckingMode": "standard",
"python.analysis.autoSearchPaths": true
},
"capabilities": [
"diagnostics", "hover", "completions", "references",
"definitions", "symbols", "rename", "code_actions"
],
"bound_actors": [
{ "name": "local/code-reviewer", "binding_mode": "explicit" },
{ "name": "local/refactor-agent", "binding_mode": "language_based", "language": "python" },
{ "name": "local/polyglot-planner", "binding_mode": "auto_discovery" }
]
}
},
"timing": { "duration_ms": 14 },
"messages": ["LSP server details loaded"]
}
```
=== "YAML"
```yaml
command: lsp show
status: ok
exit_code: 0
data:
lsp_server:
name: local/pyright
languages:
- python
command: pyright-langserver --stdio
root_path: "{{ project.root }}"
init_options:
python.analysis.typeCheckingMode: standard
python.analysis.autoSearchPaths: true
capabilities:
- diagnostics
- hover
- completions
- references
- definitions
- symbols
- rename
- code_actions
bound_actors:
- name: local/code-reviewer
binding_mode: explicit
- name: local/refactor-agent
binding_mode: language_based
language: python
- name: local/polyglot-planner
binding_mode: auto_discovery
timing:
duration_ms: 14
messages:
- LSP server details loaded
```
agents lsp serve
agents lsp serve [--log-level <LEVEL>]Purpose
Launch the stub LSP server over stdin/stdout using the JSON-RPC base protocol with Content-Length header framing. The server supports the initialize, shutdown, and exit lifecycle methods. Requests received before initialize are rejected with ServerNotInitialized (-32002) per the LSP specification. After initialization, unsupported LSP methods return a MethodNotFound (-32601) error. After shutdown is received, only exit is accepted; other requests are rejected with InvalidRequest (-32600). Sending initialize a second time is also rejected with InvalidRequest.
This command is intended for development and testing of LSP transport integration. In a future milestone the stub handlers will be replaced by real LSP server proxying through the A2A facade.
Arguments
--log-level LEVEL: Logging level for the server process. Valid values:debug,info(default),warning,error. Invalid values cause immediate exit with a descriptive error message.
Transport Limits
| Limit | Value | Description |
|---|---|---|
| Max Content-Length | 10 MB | Messages exceeding this are rejected with a warning log (DoS guard) |
| Max header lines | 32 | Headers with more lines are rejected with a warning log (DoS guard) |
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> lsp serve
<span style="color: cyan; font-weight: 600;">CleverAgents LSP Server</span> (stub) starting — PID 7412
Log level: info
Transport: stdin/stdout (JSON-RPC, Content-Length framing)
Supported methods: initialize, shutdown, exit
All other methods → MethodNotFound (-32601)
</code></pre></div>
=== "Plain"
```
$ agents lsp serve
CleverAgents LSP Server (stub) starting — PID 7412
Log level: info
Transport: stdin/stdout (JSON-RPC, Content-Length framing)
Supported methods: initialize, shutdown, exit
All other methods → MethodNotFound (-32601)
```
agents validation
!!! info "Purpose"
Register and attach ==validations== — a specialized subtype of Tool that extends the Tool class with pass/fail semantics and attachment scoping. A Validation inherits all base Tool properties (name, source, input_schema, capability, resource bindings, lifecycle hooks, etc.) and adds: a mode field (required or informational), and a structured JSON return format with a mandatory passed boolean, an optional message string, and an optional data object for arbitrary informational output. Since Validation extends Tool, it shares the same backing sources (custom, MCP, agent_skill, builtin) plus the additional wrapped source type for Validations that wrap an existing Tool via the wraps field. It uses the same YAML configuration format (with an additional validation block and optional wraps/transform fields), and the same registries and resolution mechanisms. Validations are always read-only (writes is always false, checkpointable is always false).
Because Validations are a subtype of Tool and share the same Tool Registry and naming namespace, only validation-specific operations have dedicated subcommands here: add (registration with validation-specific fields like mode), attach, and detach. General tool operations — listing, inspection, and removal — are handled through the agents tool commands:
- List validations:
agents tool list --type validation - Show validation details:
agents tool show <NAME>(displays validation-specific fields when the entry is a Validation) - Remove a validation:
agents tool remove <NAME>(automatically removes all attachments)
A validation is always attached to a resource. The optional --project or --plan flag controls the scope of the attachment:
- Direct attachment (no scope flag): The validation is always active for that resource, regardless of which plan or project accesses it. Use
agents validation attach <RESOURCE> <VALIDATION> [args...]. - Project-scoped attachment (
--project): The validation only runs for that resource when it is being interacted with through the specified project. Useagents validation attach --project <PROJECT> <RESOURCE> <VALIDATION> [args...]. - Plan-scoped attachment (
--plan): The validation only runs for that resource when it is being interacted with through the specified plan. Useagents validation attach --plan <PLAN_ID> <RESOURCE> <VALIDATION> [args...].
The same validation can be attached to the same resource multiple times — directly, through different projects, and through different plans — and since validations accept arguments, attaching the same validation to the same resource multiple times with different arguments is a common and useful configuration pattern (e.g., running the same test suite with different coverage thresholds for different projects).
Each attach invocation returns a system-assigned attachment ULID uniquely identifying that attachment. Use this ULID with agents validation detach <ATTACHMENT_ID> to remove a specific attachment.
When multiple attachment scopes apply, the union of all applicable validations is used. A resource with a directly-attached validation will always have that validation run, plus any additional validations attached through the active project or plan.
agents validation add
agents validation add --config|-c <FILE> [--required | --informational] [--update]Purpose
Register a new validation. The validation is fully defined by the YAML configuration file specified with --config. The validation is registered in the shared Tool Registry under the name specified in the config file; the name must not conflict with any existing tool or validation. If a validation with the same name already exists, the command fails unless --update is provided. The validation YAML may use wraps to reference an existing Tool, reusing its implementation and interpreting its output through a transform function (see Tool Wrapping under Core Concepts > Validation). When wraps is used, the wrapped Tool must already be registered.
Arguments
--config/-c FILE: Path to the validation YAML configuration file (required). The file must fully define the validation, including thenamefield which determines the validation's registered name, thevalidation.modefield (requiredorinformational), and either inline implementation (source+code) or wrapping (wraps+transform).--required: Override the mode in the YAML config torequired. Mutually exclusive with--informational.--informational: Override the mode in the YAML config toinformational. Mutually exclusive with--required.--update: Allow overwriting an existing validation registration.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> validation add <span style="color: cyan;">--config</span> ./validations/run-tests.yaml
╭─ Validation Registered ────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/run-tests │
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> Run unit tests with coverage │
│ <span style="color: #5599ff; font-weight: 600;">Source:</span> custom │
│ <span style="color: #66cc66; font-weight: 600;">Mode:</span> required │
│ <span style="color: #66cc66; font-weight: 600;">Config:</span> ./validations/run-tests.yaml │
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-09 10:15 │
╰────────────────────────────────────────────────────────╯
╭─ Capability ────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Read-Only:</span> true (enforced) │
│ <span style="color: #66cc66; font-weight: 600;">Checkpointable:</span> false (enforced) │
│ <span style="color: yellow; font-weight: 600;">Timeout:</span> 600s │
╰─────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Validation registered
</code></pre></div>
=== "Plain"
```
$ agents validation add --config ./validations/run-tests.yaml
Validation Registered
Name: local/run-tests
Description: Run unit tests with coverage
Source: custom
Mode: required
Config: ./validations/run-tests.yaml
Created: 2026-02-09 10:15
Capability
Read-Only: true (enforced)
Checkpointable: false (enforced)
Timeout: 600s
[OK] Validation registered
```
=== "JSON"
```json
{
"command": "validation add",
"status": "ok",
"exit_code": 0,
"data": {
"validation_registered": {
"name": "local/run-tests",
"description": "Run unit tests with coverage",
"source": "custom",
"mode": "required",
"config": "./validations/run-tests.yaml",
"created": "2026-02-09 10:15"
},
"capability": {
"read_only": "true (enforced)",
"checkpointable": "false (enforced)",
"timeout": "600s"
}
},
"timing": { "started": "2026-02-09T10:15:00Z", "duration_ms": 120 },
"messages": ["Validation registered"]
}
```
=== "YAML"
```yaml
command: validation add
status: ok
exit_code: 0
data:
validation_registered:
name: local/run-tests
description: Run unit tests with coverage
source: custom
mode: required
config: ./validations/run-tests.yaml
created: "2026-02-09 10:15"
capability:
read_only: "true (enforced)"
checkpointable: "false (enforced)"
timeout: 600s
timing:
started: "2026-02-09T10:15:00Z"
duration_ms: 120
messages:
- "Validation registered"
```
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> validation add <span style="color: cyan;">--config</span> ./validations/lint-check.yaml
╭─ Validation Registered ──────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/lint-check │
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> Lint check │
│ <span style="color: #5599ff; font-weight: 600;">Source:</span> custom │
│ <span style="color: #66cc66; font-weight: 600;">Mode:</span> required │
│ <span style="color: yellow; font-weight: 600;">Timeout:</span> 300s │
╰──────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Validation registered
</code></pre></div>
=== "Plain"
```
$ agents validation add --config ./validations/lint-check.yaml
Validation Registered
Name: local/lint-check
Description: Lint check
Source: custom
Mode: required
Timeout: 300s
[OK] Validation registered
```
=== "JSON"
```json
{
"command": "validation add",
"status": "ok",
"exit_code": 0,
"data": {
"validation_registered": {
"name": "local/lint-check",
"description": "Lint check",
"source": "custom",
"mode": "required",
"timeout": "300s"
}
},
"timing": { "started": "2026-02-09T10:15:00Z", "duration_ms": 95 },
"messages": ["Validation registered"]
}
```
=== "YAML"
```yaml
command: validation add
status: ok
exit_code: 0
data:
validation_registered:
name: local/lint-check
description: Lint check
source: custom
mode: required
timeout: 300s
timing:
started: "2026-02-09T10:15:00Z"
duration_ms: 95
messages:
- "Validation registered"
```
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> validation add <span style="color: cyan;">--config</span> ./validations/check-bundle-size.yaml
╭─ Validation Registered ───────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/check-bundle-size │
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> Check bundle size (advisory) │
│ <span style="color: #5599ff; font-weight: 600;">Source:</span> custom │
│ <span style="color: yellow; font-weight: 600;">Mode:</span> informational │
│ <span style="color: yellow; font-weight: 600;">Timeout:</span> 300s │
╰───────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Validation registered
</code></pre></div>
=== "Plain"
```
$ agents validation add --config ./validations/check-bundle-size.yaml
Validation Registered
Name: local/check-bundle-size
Description: Check bundle size (advisory)
Source: custom
Mode: informational
Timeout: 300s
[OK] Validation registered
```
=== "JSON"
```json
{
"command": "validation add",
"status": "ok",
"exit_code": 0,
"data": {
"validation_registered": {
"name": "local/check-bundle-size",
"description": "Check bundle size (advisory)",
"source": "custom",
"mode": "informational",
"timeout": "300s"
}
},
"timing": { "started": "2026-02-09T10:16:00Z", "duration_ms": 88 },
"messages": ["Validation registered"]
}
```
=== "YAML"
```yaml
command: validation add
status: ok
exit_code: 0
data:
validation_registered:
name: local/check-bundle-size
description: "Check bundle size (advisory)"
source: custom
mode: informational
timeout: 300s
timing:
started: "2026-02-09T10:16:00Z"
duration_ms: 88
messages:
- "Validation registered"
```
agents validation attach
agents validation attach [--project <PROJECT>|--plan <PLAN_ID>]
<RESOURCE> <VALIDATION> [<ARGS>...]Purpose
Attach a registered validation to a resource, with an optional project or plan scope. A resource is always required — validations are fundamentally resource-centric. The optional --project or --plan flag narrows when the validation is active: without either flag, the validation runs whenever any plan or project accesses the resource; with --project, it only runs when the resource is accessed through that project; with --plan, it only runs when the resource is accessed through that plan. At most one scope flag may be provided per invocation.
The command returns a system-assigned attachment ULID that uniquely identifies this specific attachment association. This ULID is used to detach the validation later via agents validation detach <ATTACHMENT_ID>. The same validation can be attached to the same resource multiple times — directly, through different projects, through different plans, and even to the same resource and scope multiple times with different arguments.
Arguments
<RESOURCE>: Resource name or ULID to attach the validation to (positional argument, required).<VALIDATION>: Validation name (positional argument, required).--project PROJECT: Scope the attachment to a specific project. The validation only runs for this resource when it is accessed through the specified project.--plan PLAN_ID: Scope the attachment to a specific plan. The validation only runs for this resource when it is accessed through the specified plan.<ARGS>...: Optional validation-specific arguments (passed through to the validation tool'sinput_schemaat execution time).
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> validation attach <span style="color: cyan;">--project</span> local/api-service local/api-repo local/run-tests
╭─ Validation Attached ──────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Attachment ID:</span> 01HXM5A1B2C3D4E5F6G7H8J9K0 │
│ <span style="color: cyan; font-weight: 600;">Validation:</span> local/run-tests │
│ <span style="color: #5599ff; font-weight: 600;">Mode:</span> required │
│ <span style="color: #66cc66; font-weight: 600;">Resource:</span> local/api-repo │
│ <span style="color: #66cc66; font-weight: 600;">Scope:</span> project local/api-service │
╰────────────────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Validation attached
</code></pre></div>
=== "Plain"
```
$ agents validation attach --project local/api-service local/api-repo local/run-tests
Validation Attached
Attachment ID: 01HXM5A1B2C3D4E5F6G7H8J9K0
Validation: local/run-tests
Mode: required
Resource: local/api-repo
Scope: project local/api-service
[OK] Validation attached
```
=== "JSON"
```json
{
"command": "validation attach",
"status": "ok",
"exit_code": 0,
"data": {
"validation_attached": {
"attachment_id": "01HXM5A1B2C3D4E5F6G7H8J9K0",
"validation": "local/run-tests",
"mode": "required",
"resource": "local/api-repo",
"scope": "project local/api-service"
}
},
"timing": { "started": "2026-02-09T10:20:00Z", "duration_ms": 45 },
"messages": ["Validation attached"]
}
```
=== "YAML"
```yaml
command: validation attach
status: ok
exit_code: 0
data:
validation_attached:
attachment_id: 01HXM5A1B2C3D4E5F6G7H8J9K0
validation: local/run-tests
mode: required
resource: local/api-repo
scope: project local/api-service
timing:
started: "2026-02-09T10:20:00Z"
duration_ms: 45
messages:
- "Validation attached"
```
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> validation attach local/api-repo local/lint-check
╭─ Validation Attached ──────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Attachment ID:</span> 01HXM5B2C3D4E5F6G7H8J9K0L1 │
│ <span style="color: cyan; font-weight: 600;">Validation:</span> local/lint-check │
│ <span style="color: #5599ff; font-weight: 600;">Mode:</span> required │
│ <span style="color: #66cc66; font-weight: 600;">Resource:</span> local/api-repo │
│ <span style="color: #66cc66; font-weight: 600;">Scope:</span> direct (always active) │
│ <span style="opacity: 0.7;">This validation will run for ALL plans/projects</span> │
│ <span style="opacity: 0.7;">that access this resource.</span> │
╰────────────────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Validation attached
</code></pre></div>
=== "Plain"
```
$ agents validation attach local/api-repo local/lint-check
Validation Attached
Attachment ID: 01HXM5B2C3D4E5F6G7H8J9K0L1
Validation: local/lint-check
Mode: required
Resource: local/api-repo
Scope: direct (always active)
This validation will run for ALL plans/projects
that access this resource.
[OK] Validation attached
```
=== "JSON"
```json
{
"command": "validation attach",
"status": "ok",
"exit_code": 0,
"data": {
"validation_attached": {
"attachment_id": "01HXM5B2C3D4E5F6G7H8J9K0L1",
"validation": "local/lint-check",
"mode": "required",
"resource": "local/api-repo",
"scope": "direct (always active)",
"note": "This validation will run for ALL plans/projects that access this resource."
}
},
"timing": { "started": "2026-02-09T10:21:00Z", "duration_ms": 42 },
"messages": ["Validation attached"]
}
```
=== "YAML"
```yaml
command: validation attach
status: ok
exit_code: 0
data:
validation_attached:
attachment_id: 01HXM5B2C3D4E5F6G7H8J9K0L1
validation: local/lint-check
mode: required
resource: local/api-repo
scope: "direct (always active)"
note: "This validation will run for ALL plans/projects that access this resource."
timing:
started: "2026-02-09T10:21:00Z"
duration_ms: 42
messages:
- "Validation attached"
```
Attaching with validation-specific arguments:
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> validation attach <span style="color: cyan;">--project</span> local/api-service local/api-repo local/run-tests <span style="color: cyan;">--coverage-threshold</span> 90
╭─ Validation Attached ──────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Attachment ID:</span> 01HXM5C3D4E5F6G7H8J9K0L1M2 │
│ <span style="color: cyan; font-weight: 600;">Validation:</span> local/run-tests │
│ <span style="color: #5599ff; font-weight: 600;">Mode:</span> required │
│ <span style="color: #66cc66; font-weight: 600;">Resource:</span> local/api-repo │
│ <span style="color: #66cc66; font-weight: 600;">Scope:</span> project local/api-service │
│ <span style="color: #5599ff; font-weight: 600;">Args:</span> coverage_threshold=90 │
╰────────────────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Validation attached
</code></pre></div>
=== "Plain"
```
$ agents validation attach --project local/api-service local/api-repo local/run-tests --coverage-threshold 90
Validation Attached
Attachment ID: 01HXM5C3D4E5F6G7H8J9K0L1M2
Validation: local/run-tests
Mode: required
Resource: local/api-repo
Scope: project local/api-service
Args: coverage_threshold=90
[OK] Validation attached
```
=== "JSON"
```json
{
"command": "validation attach",
"status": "ok",
"exit_code": 0,
"data": {
"validation_attached": {
"attachment_id": "01HXM5C3D4E5F6G7H8J9K0L1M2",
"validation": "local/run-tests",
"mode": "required",
"resource": "local/api-repo",
"scope": "project local/api-service",
"args": {
"coverage_threshold": 90
}
}
},
"timing": { "started": "2026-02-09T10:22:00Z", "duration_ms": 48 },
"messages": ["Validation attached"]
}
```
=== "YAML"
```yaml
command: validation attach
status: ok
exit_code: 0
data:
validation_attached:
attachment_id: 01HXM5C3D4E5F6G7H8J9K0L1M2
validation: local/run-tests
mode: required
resource: local/api-repo
scope: project local/api-service
args:
coverage_threshold: 90
timing:
started: "2026-02-09T10:22:00Z"
duration_ms: 48
messages:
- "Validation attached"
```
agents validation detach
agents validation detach [--yes|-y] <ATTACHMENT_ID>Purpose
Detach a validation by its attachment ULID. The attachment ULID is returned by agents validation attach when the attachment is created and is also displayed by agents tool show <VALIDATION> in the "Attached To" section. Because a validation may be attached to the same resource multiple times — directly, through different projects, through different plans, or even to the same resource and scope with different arguments — the ULID uniquely identifies the specific attachment to remove. The validation itself remains registered in the Tool Registry; only the attachment association is removed.
Arguments
<ATTACHMENT_ID>: The ULID of the attachment to remove (returned byagents validation attach).--yes, -y: Skip confirmation prompt.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> validation detach 01HXM5A1B2C3D4E5F6G7H8J9K0
Detach validation local/run-tests from resource local/api-repo (scope: project local/api-service)? [y/N]: y
╭─ Validation Detached ───────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Attachment ID:</span> 01HXM5A1B2C3D4E5F6G7H8J9K0 │
│ <span style="color: cyan; font-weight: 600;">Validation:</span> local/run-tests │
│ <span style="color: #5599ff; font-weight: 600;">Resource:</span> local/api-repo │
│ <span style="color: #5599ff; font-weight: 600;">Scope:</span> project local/api-service │
╰─────────────────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Validation detached
</code></pre></div>
=== "Plain"
```
$ agents validation detach 01HXM5A1B2C3D4E5F6G7H8J9K0
Detach validation local/run-tests from resource local/api-repo (scope: project local/api-service)? [y/N]: y
Validation Detached
Attachment ID: 01HXM5A1B2C3D4E5F6G7H8J9K0
Validation: local/run-tests
Resource: local/api-repo
Scope: project local/api-service
[OK] Validation detached
```
=== "JSON"
```json
{
"command": "validation detach",
"status": "ok",
"exit_code": 0,
"data": {
"validation_detached": {
"attachment_id": "01HXM5A1B2C3D4E5F6G7H8J9K0",
"validation": "local/run-tests",
"resource": "local/api-repo",
"scope": "project local/api-service"
},
"confirmation": "Detach validation local/run-tests from resource local/api-repo (scope: project local/api-service)? [y/N]: y"
},
"timing": { "started": "2026-02-09T10:25:00Z", "duration_ms": 1200 },
"messages": ["Validation detached"]
}
```
=== "YAML"
```yaml
command: validation detach
status: ok
exit_code: 0
data:
validation_detached:
attachment_id: 01HXM5A1B2C3D4E5F6G7H8J9K0
validation: local/run-tests
resource: local/api-repo
scope: project local/api-service
confirmation: "Detach validation local/run-tests from resource local/api-repo (scope: project local/api-service)? [y/N]: y"
timing:
started: "2026-02-09T10:25:00Z"
duration_ms: 1200
messages:
- "Validation detached"
```
agents resource type
Purpose
Manage resource type definitions. Resource types are schema-level definitions that constrain categories of resources — they define what CLI arguments agents resource add <type> accepts, whether instances are physical or virtual, allowed parent/child types, auto-discovery behavior, sandbox strategy, and handler implementation. Built-in types (git-checkout, git, fs-mount, fs-directory, and their child types) are hardcoded. Custom types are defined in YAML configuration files and extend the system with new agents resource add subcommands.
agents resource type add
agents resource type add --config|-c <FILE> [--update]Purpose
Register a new custom resource type. The resource type is fully defined by the YAML configuration file specified with --config.
Arguments
--config/-c FILE: Path to the resource type YAML configuration file (required). The file must fully define the resource type, including thenamefield which determines the type's registered name.--update: If the type name already exists, overwrite it. Without this flag, adding a duplicate name fails with an error.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource type add <span style="color: cyan;">--config</span> ./resource-types/svn.yaml
╭─ Resource Type ────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/svn │
│ <span style="color: #5599ff; font-weight: 600;">Physical/Virtual:</span> physical │
│ <span style="color: #5599ff; font-weight: 600;">User Addable:</span> yes │
│ <span style="color: #66cc66; font-weight: 600;">Registered:</span> 2026-02-09 10:15 │
╰────────────────────────────────────╯
╭─ CLI Arguments ────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Argument</span> <span style="color: cyan; font-weight: 600;">Required</span> <span style="color: cyan; font-weight: 600;">Description</span> │
│ <span style="opacity: 0.7;">──────────── ──────── ─────────────</span> │
│ <span style="color: cyan;">--url</span> yes Repository URL │
│ <span style="color: cyan;">--checkout</span> no Local checkout │
╰────────────────────────────────────────╯
╭─ Child Types ──────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Auto-discover:</span> svn-revision, svn-file │
│ <span style="color: #5599ff; font-weight: 600;">Manual link:</span> fs-mount │
╰────────────────────────────────────────╯
╭─ Sandbox ──────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Strategy:</span> copy_on_write │
│ <span style="color: #5599ff; font-weight: 600;">Handler:</span> SVNHandler (custom) │
╰────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Resource type registered
<span style="color: cyan; font-weight: 600;">ℹ</span> New subcommand available: agents resource add local/svn
</code></pre></div>
=== "Plain"
```
$ agents resource type add --config ./resource-types/svn.yaml
Resource Type
Name: local/svn
Physical/Virtual: physical
User Addable: yes
Registered: 2026-02-09 10:15
CLI Arguments
Argument Required Description
------------ -------- -------------
--url yes Repository URL
--checkout no Local checkout
Child Types
Auto-discover: svn-revision, svn-file
Manual link: fs-mount
Sandbox
Strategy: copy_on_write
Handler: SVNHandler (custom)
[OK] Resource type registered
Info: New subcommand available: agents resource add local/svn
```
=== "JSON"
```json
{
"command": "resource type add",
"status": "ok",
"exit_code": 0,
"data": {
"name": "local/svn",
"physical_virtual": "physical",
"user_addable": true,
"registered": "2026-02-09T10:15:00Z",
"cli_arguments": [
{ "argument": "--url", "required": true, "description": "Repository URL" },
{ "argument": "--checkout", "required": false, "description": "Local checkout" }
],
"child_types": {
"auto_discover": ["svn-revision", "svn-file"],
"manual_link": ["fs-mount"]
},
"sandbox": {
"strategy": "copy_on_write",
"handler": "SVNHandler (custom)"
}
},
"timing": { "started": "2026-02-09T10:15:00Z", "duration_ms": 85 },
"messages": ["Resource type registered", "New subcommand available: agents resource add local/svn"]
}
```
=== "YAML"
```yaml
command: resource type add
status: ok
exit_code: 0
data:
name: local/svn
physical_virtual: physical
user_addable: true
registered: "2026-02-09T10:15:00Z"
cli_arguments:
- argument: "--url"
required: true
description: Repository URL
- argument: "--checkout"
required: false
description: Local checkout
child_types:
auto_discover:
- svn-revision
- svn-file
manual_link:
- fs-mount
sandbox:
strategy: copy_on_write
handler: "SVNHandler (custom)"
timing:
started: "2026-02-09T10:15:00Z"
duration_ms: 85
messages:
- "Resource type registered"
- "New subcommand available: agents resource add local/svn"
```
agents resource type remove
agents resource type remove [--yes|-y] <NAME>!!! warning "Destructive Operation" Remove a custom resource type. ==Built-in types cannot be removed.== Fails if any registered resources currently use this type — remove those resources first.
Arguments
<NAME>: Resource type name.--yes: Skip confirmation prompt.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource type remove local/svn
Remove resource type local/svn? [y/N]: y
╭─ Resource Type Removed ───────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/svn │
│ <span style="color: yellow; font-weight: 600;">Resources Using:</span> 0 │
│ <span style="color: #5599ff; font-weight: 600;">Subcommand Removed:</span> yes │
╰───────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Resource type removed
</code></pre></div>
=== "Plain"
```
$ agents resource type remove local/svn
Remove resource type local/svn? [y/N]: y
Resource Type Removed
Name: local/svn
Resources Using: 0
Subcommand Removed: yes
[OK] Resource type removed
```
=== "JSON"
```json
{
"command": "resource type remove",
"status": "ok",
"exit_code": 0,
"data": {
"name": "local/svn",
"resources_using": 0,
"subcommand_removed": true
},
"timing": { "started": "2026-02-09T10:16:00Z", "duration_ms": 60 },
"messages": ["Resource type removed"]
}
```
=== "YAML"
```yaml
command: resource type remove
status: ok
exit_code: 0
data:
name: local/svn
resources_using: 0
subcommand_removed: true
timing:
started: "2026-02-09T10:16:00Z"
duration_ms: 60
messages:
- "Resource type removed"
```
agents resource type list
agents resource type list [<REGEX>]Purpose List all registered resource types (built-in and custom).
Arguments
None (use the global --format option to control output format).
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource type list
╭─ Resource Types ──────────────────────────────────────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name</span> <span style="color: cyan; font-weight: 600;">Source</span> <span style="color: cyan; font-weight: 600;">Phys/Virt</span> <span style="color: cyan; font-weight: 600;">Addable</span> <span style="color: cyan; font-weight: 600;">Auto-children</span> │
│ <span style="opacity: 0.7;">─────────────────── ──────── ───────── ─────── ──────────────────────────────────────</span> │
│ git-checkout built-in physical yes git, fs-directory │
│ git built-in physical yes git-remote, git-branch, git-tag, │
│ git-commit, git-stash, git-submodule │
│ git-remote built-in physical no (none) │
│ git-branch built-in physical no git-commit │
│ git-tag built-in physical no (none) │
│ git-commit built-in physical no git-tree │
│ git-tree built-in physical no git-tree-entry │
│ git-tree-entry built-in physical no (none) │
│ git-stash built-in physical no (none) │
│ git-submodule built-in physical no (none) │
│ fs-mount built-in physical yes fs-directory │
│ fs-directory built-in physical yes fs-file, fs-directory, │
│ fs-symlink, fs-hardlink │
│ fs-file built-in physical no (none) │
│ fs-symlink built-in physical no (none) │
│ fs-hardlink built-in physical no (none) │
│ file built-in virtual no (none) │
│ directory built-in virtual no (none) │
│ symlink built-in virtual no (none) │
│ commit built-in virtual no (none) │
│ branch built-in virtual no (none) │
│ tag built-in virtual no (none) │
│ remote built-in virtual no (none) │
│ submodule built-in virtual no (none) │
│ tree built-in virtual no (none) │
│ local/svn custom physical yes svn-revision, svn-file │
╰───────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Summary ─────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Built-in:</span> 24 │
│ <span style="color: #5599ff; font-weight: 600;">Custom:</span> 1 │
│ <span style="color: #66cc66; font-weight: 600;">User Addable:</span> 4 │
╰───────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 25 resource types listed
</code></pre></div>
=== "Plain"
```
$ agents resource type list
Resource Types
-------------------
Name Source Phys/Virt Addable Auto-children
------------------- -------- --------- ------- --------------------------------------
git-checkout built-in physical yes git, fs-directory
git built-in physical yes git-remote, git-branch, git-tag, git-commit, git-stash, git-submodule
git-remote built-in physical no (none)
git-branch built-in physical no git-commit
git-tag built-in physical no (none)
git-commit built-in physical no git-tree
git-tree built-in physical no git-tree-entry
git-tree-entry built-in physical no (none)
git-stash built-in physical no (none)
git-submodule built-in physical no (none)
fs-mount built-in physical yes fs-directory
fs-directory built-in physical yes fs-file, fs-directory, fs-symlink, fs-hardlink
fs-file built-in physical no (none)
fs-symlink built-in physical no (none)
fs-hardlink built-in physical no (none)
file built-in virtual no (none)
directory built-in virtual no (none)
symlink built-in virtual no (none)
commit built-in virtual no (none)
branch built-in virtual no (none)
tag built-in virtual no (none)
remote built-in virtual no (none)
submodule built-in virtual no (none)
tree built-in virtual no (none)
local/svn custom physical yes svn-revision, svn-file
Summary
Built-in: 24
Custom: 1
User Addable: 4
[OK] 25 resource types listed
```
=== "JSON"
```json
{
"command": "resource type list",
"status": "ok",
"exit_code": 0,
"data": {
"resource_types": [
{ "name": "git-checkout", "source": "built-in", "physical_virtual": "physical", "addable": true, "auto_children": ["git", "fs-directory"] },
{ "name": "git", "source": "built-in", "physical_virtual": "physical", "addable": true, "auto_children": ["git-remote", "git-branch", "git-tag", "git-commit", "git-stash", "git-submodule"] },
{ "name": "git-remote", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": [] },
{ "name": "git-branch", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": ["git-commit"] },
{ "name": "git-tag", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": [] },
{ "name": "git-commit", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": ["git-tree"] },
{ "name": "git-tree", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": ["git-tree-entry"] },
{ "name": "git-tree-entry", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": [] },
{ "name": "git-stash", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": [] },
{ "name": "git-submodule", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": [] },
{ "name": "fs-mount", "source": "built-in", "physical_virtual": "physical", "addable": true, "auto_children": ["fs-directory"] },
{ "name": "fs-directory", "source": "built-in", "physical_virtual": "physical", "addable": true, "auto_children": ["fs-file", "fs-directory", "fs-symlink", "fs-hardlink"] },
{ "name": "fs-file", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": [] },
{ "name": "fs-symlink", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": [] },
{ "name": "fs-hardlink", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": [] },
{ "name": "file", "source": "built-in", "physical_virtual": "virtual", "addable": false, "auto_children": [] },
{ "name": "directory", "source": "built-in", "physical_virtual": "virtual", "addable": false, "auto_children": [] },
{ "name": "symlink", "source": "built-in", "physical_virtual": "virtual", "addable": false, "auto_children": [] },
{ "name": "commit", "source": "built-in", "physical_virtual": "virtual", "addable": false, "auto_children": [] },
{ "name": "branch", "source": "built-in", "physical_virtual": "virtual", "addable": false, "auto_children": [] },
{ "name": "tag", "source": "built-in", "physical_virtual": "virtual", "addable": false, "auto_children": [] },
{ "name": "remote", "source": "built-in", "physical_virtual": "virtual", "addable": false, "auto_children": [] },
{ "name": "submodule", "source": "built-in", "physical_virtual": "virtual", "addable": false, "auto_children": [] },
{ "name": "tree", "source": "built-in", "physical_virtual": "virtual", "addable": false, "auto_children": [] },
{ "name": "local/svn", "source": "custom", "physical_virtual": "physical", "addable": true, "auto_children": ["svn-revision", "svn-file"] }
],
"summary": {
"built_in": 24,
"custom": 1,
"user_addable": 4
}
},
"timing": { "started": "2026-02-09T10:16:00Z", "duration_ms": 45 },
"messages": ["25 resource types listed"]
}
```
=== "YAML"
```yaml
command: resource type list
status: ok
exit_code: 0
data:
resource_types:
- name: git-checkout
source: built-in
physical_virtual: physical
addable: true
auto_children: [git, fs-directory]
- name: git
source: built-in
physical_virtual: physical
addable: true
auto_children: [git-remote, git-branch, git-tag, git-commit, git-stash, git-submodule]
- name: git-remote
source: built-in
physical_virtual: physical
addable: false
auto_children: []
- name: git-branch
source: built-in
physical_virtual: physical
addable: false
auto_children: [git-commit]
- name: git-tag
source: built-in
physical_virtual: physical
addable: false
auto_children: []
- name: git-commit
source: built-in
physical_virtual: physical
addable: false
auto_children: [git-tree]
- name: git-tree
source: built-in
physical_virtual: physical
addable: false
auto_children: [git-tree-entry]
- name: git-tree-entry
source: built-in
physical_virtual: physical
addable: false
auto_children: []
- name: git-stash
source: built-in
physical_virtual: physical
addable: false
auto_children: []
- name: git-submodule
source: built-in
physical_virtual: physical
addable: false
auto_children: []
- name: fs-mount
source: built-in
physical_virtual: physical
addable: true
auto_children: [fs-directory]
- name: fs-directory
source: built-in
physical_virtual: physical
addable: true
auto_children: [fs-file, fs-directory, fs-symlink, fs-hardlink]
- name: fs-file
source: built-in
physical_virtual: physical
addable: false
auto_children: []
- name: fs-symlink
source: built-in
physical_virtual: physical
addable: false
auto_children: []
- name: fs-hardlink
source: built-in
physical_virtual: physical
addable: false
auto_children: []
- name: file
source: built-in
physical_virtual: virtual
addable: false
auto_children: []
- name: directory
source: built-in
physical_virtual: virtual
addable: false
auto_children: []
- name: symlink
source: built-in
physical_virtual: virtual
addable: false
auto_children: []
- name: commit
source: built-in
physical_virtual: virtual
addable: false
auto_children: []
- name: branch
source: built-in
physical_virtual: virtual
addable: false
auto_children: []
- name: tag
source: built-in
physical_virtual: virtual
addable: false
auto_children: []
- name: remote
source: built-in
physical_virtual: virtual
addable: false
auto_children: []
- name: submodule
source: built-in
physical_virtual: virtual
addable: false
auto_children: []
- name: tree
source: built-in
physical_virtual: virtual
addable: false
auto_children: []
- name: local/svn
source: custom
physical_virtual: physical
addable: true
auto_children: [svn-revision, svn-file]
summary:
built_in: 24
custom: 1
user_addable: 4
timing:
started: "2026-02-09T10:16:00Z"
duration_ms: 45
messages:
- "25 resource types listed"
```
agents resource type show
agents resource type show <NAME>Purpose Show detailed information about a resource type, including its full schema.
Arguments
<NAME>: Resource type name.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource type show git-checkout
╭─ Resource Type ──────────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> git-checkout │
│ <span style="color: #5599ff; font-weight: 600;">Source:</span> built-in │
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> A locally checked-out git repository with worktree │
│ <span style="color: #5599ff; font-weight: 600;">Physical/Virtual:</span> physical │
│ <span style="color: #66cc66; font-weight: 600;">User Addable:</span> yes │
╰──────────────────────────────────────────────────────────────────────╯
╭─ CLI Arguments (agents resource add git-checkout) ─────────────────╮
│ <span style="color: cyan; font-weight: 600;">Argument</span> <span style="color: cyan; font-weight: 600;">Required</span> <span style="color: cyan; font-weight: 600;">Type</span> <span style="color: cyan; font-weight: 600;">Description</span> │
│ <span style="opacity: 0.7;">────────── ──────── ────── ──────────────────────────────</span> │
│ <span style="color: cyan;">--path</span> yes path Local checkout directory │
│ <span style="color: cyan;">--branch</span> no string Default branch (default: main) │
╰────────────────────────────────────────────────────────────────────╯
╭─ Parent Types ───────────────╮
│ Allowed: (any, top-level OK) │
╰──────────────────────────────╯
╭─ Child Types ────────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Type</span> <span style="color: cyan; font-weight: 600;">Auto</span> <span style="color: cyan; font-weight: 600;">Manual Link</span> <span style="color: cyan; font-weight: 600;">Description</span> │
│ <span style="opacity: 0.7;">───────────── ──── ─────────── ──────────────────────────</span> │
│ git yes no Repo object DB and history │
│ fs-directory yes no Worktree root directory │
╰──────────────────────────────────────────────────────────────────╯
╭─ Sandbox ──────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Strategy:</span> git_worktree │
│ <span style="color: #5599ff; font-weight: 600;">Checkpointable:</span> yes │
│ <span style="color: #5599ff; font-weight: 600;">Handler:</span> GitCheckoutHandler │
╰────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Resource type details loaded
</code></pre></div>
=== "Plain"
```
$ agents resource type show git-checkout
Resource Type
Name: git-checkout
Source: built-in
Description: A locally checked-out git repository with worktree
Physical/Virtual: physical
User Addable: yes
CLI Arguments (agents resource add git-checkout)
Argument Required Type Description
---------- -------- ------ ------------------------------
--path yes path Local checkout directory
--branch no string Default branch (default: main)
Parent Types
Allowed: (any, top-level OK)
Child Types
Type Auto Manual Link Description
------------- ---- ----------- --------------------------
git yes no Repo object DB and history
fs-directory yes no Worktree root directory
Sandbox
Strategy: git_worktree
Checkpointable: yes
Handler: GitCheckoutHandler
[OK] Resource type details loaded
```
=== "JSON"
```json
{
"command": "resource type show",
"status": "ok",
"exit_code": 0,
"data": {
"name": "git-checkout",
"source": "built-in",
"description": "A locally checked-out git repository with worktree",
"physical_virtual": "physical",
"user_addable": true,
"cli_arguments": [
{ "argument": "--path", "required": true, "type": "path", "description": "Local checkout directory" },
{ "argument": "--branch", "required": false, "type": "string", "description": "Default branch (default: main)" }
],
"parent_types": {
"allowed": "any",
"top_level": true
},
"child_types": [
{ "type": "git", "auto": true, "manual_link": false, "description": "Repo object DB and history" },
{ "type": "fs-directory", "auto": true, "manual_link": false, "description": "Worktree root directory" }
],
"sandbox": {
"strategy": "git_worktree",
"checkpointable": true,
"handler": "GitCheckoutHandler"
}
},
"timing": { "started": "2026-02-09T10:15:00Z", "duration_ms": 42 },
"messages": ["Resource type details loaded"]
}
```
=== "YAML"
```yaml
command: resource type show
status: ok
exit_code: 0
data:
name: git-checkout
source: built-in
description: "A locally checked-out git repository with worktree"
physical_virtual: physical
user_addable: true
cli_arguments:
- argument: "--path"
required: true
type: path
description: "Local checkout directory"
- argument: "--branch"
required: false
type: string
description: "Default branch (default: main)"
parent_types:
allowed: any
top_level: true
child_types:
- type: git
auto: true
manual_link: false
description: "Repo object DB and history"
- type: fs-directory
auto: true
manual_link: false
description: "Worktree root directory"
sandbox:
strategy: git_worktree
checkpointable: true
handler: GitCheckoutHandler
timing:
started: "2026-02-09T10:15:00Z"
duration_ms: 42
messages:
- "Resource type details loaded"
```
agents resource
!!! info "Purpose"
Manage independently registered ==resources==. Resources represent anything that can be read, written, or queried — git repositories, filesystems, databases, APIs, and more. Resources are registered independently of projects and linked to one or more projects via agents project link-resource. Resources form a ==directed acyclic graph (DAG)== with parent/child relationships, and child resources are often auto-discovered when a parent resource is registered.
??? example "Supported Resource Types"
| Type | Physical | Description |
| :--- | :------: | :---------- |
| git-checkout | Yes | Local git working directory |
| git | Yes | Bare git repository |
| fs-mount | Yes | Filesystem mount point |
| fs-directory | Virtual | Directory within a mount |
| fs-file | Virtual | Individual file reference |
| container-instance | Yes | Container instance (ADR-039) |
| devcontainer-instance | Yes | Devcontainer instance (ADR-043) |
| Custom types | Varies | Registered via agents resource type add |
agents resource add
agents resource add [(--description|-d) <DESC>] [--update] <TYPE> <NAME> [type-specific-flags...]Purpose
Register a new resource. Every resource receives a system-assigned ULID. User-added resources also require a namespaced name ([[server:]namespace/]name) specified at creation time. The add command uses type-specific subcommands — each registered resource type (built-in or custom) provides its own subcommand with type-appropriate arguments. On success, the command returns both the name and the ULID assigned to the newly created resource.
Arguments
<TYPE>: Resource type name (e.g.,git-checkout,git,fs-mount,fs-directory,local/svn). Determines type-specific flags.<NAME>: Namespaced resource name (positional, required). Must be globally unique following the standard[[server:]namespace/]nameformat.--description/-d TEXT: Optional resource description.
Type-specific flags depend on the resource type. See agents resource type show <TYPE> for available arguments.
Container-specific flags (for container-instance and devcontainer-instance types):
--image IMAGE_REF: Container image reference (e.g.,ubuntu:latest,python:3.12-slim). Required forcontainer-instancewhen--container-idis not provided. Not required fordevcontainer-instance(image is derived fromdevcontainer.json).--mount RESOURCE_OR_PATH:CONTAINER_PATH: Mount a resource or host path into the container (repeatable). Accepts either a resource reference (local/api-repo:/workspace) or a raw host path (/home/user/projects/api:/workspace). See ADR-043 §3.2.--clone-into REPO_URL:CONTAINER_PATH: Clone a remote repository into the container at the specified path. The clone happens lazily on first container start.
The command returns the name and ULID of the newly created resource. Auto-discovered child resources are created automatically with ULIDs only (no names).
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource add git-checkout local/api-repo <span style="color: cyan;">--path</span> /home/user/projects/api-service <span style="color: cyan;">--branch</span> main
╭─ Resource ──────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/api-repo │
│ <span style="color: cyan; font-weight: 600;">ID:</span> 01HXR1A1B2C3D4E5F6G7H8J9K0 │
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> git-checkout │
│ <span style="color: #5599ff; font-weight: 600;">Physical/Virtual:</span> physical │
│ <span style="color: #66cc66; font-weight: 600;">Path:</span> /home/user/projects/api-service │
│ <span style="color: #5599ff; font-weight: 600;">Branch:</span> main │
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-09 10:20 │
╰─────────────────────────────────────────────────╯
╭─ Auto-discovered Children ─────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">ID</span> <span style="color: cyan; font-weight: 600;">Type</span> <span style="color: cyan; font-weight: 600;">Status</span> │
│ <span style="opacity: 0.7;">─────────────── ────────────── ─────────────────</span> │
│ 01HXR1A1B2C3… git <span style="color: #66cc66; font-weight: 600;">created</span> │
│ 01HXR1A1B2C4… git-remote <span style="color: #66cc66; font-weight: 600;">created</span> │
│ 01HXR1A1B2C5… git-branch <span style="color: #66cc66; font-weight: 600;">created</span> │
│ 01HXR1A1B2C6… git-branch <span style="color: #66cc66; font-weight: 600;">created</span> │
│ 01HXR1A1B2C7… fs-directory <span style="color: #66cc66; font-weight: 600;">created</span> │
│ + 47 git-commit resources │
│ + 312 git-tree-entry resources │
│ + 3 fs-directory + 28 fs-file │
╰────────────────────────────────────────────────────────────────────╯
╭─ Capabilities ─────────────────╮
│ <span style="color: #66cc66; font-weight: 600;">Readable:</span> yes │
│ <span style="color: yellow; font-weight: 600;">Writable:</span> yes │
│ <span style="color: #66cc66; font-weight: 600;">Sandboxable:</span> yes │
│ <span style="color: #66cc66; font-weight: 600;">Checkpointable:</span> yes │
│ <span style="color: #5599ff; font-weight: 600;">Sandbox Strategy:</span> git_worktree │
╰────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Resource registered (395 child resources discovered)
</code></pre></div>
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource add fs-mount local/docs <span style="color: cyan;">--mount-path</span> /docs/api-reference
╭─ Resource ──────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/docs │
│ <span style="color: cyan; font-weight: 600;">ID:</span> 01HXR2B3C4D5E6F7G8H9J0K1L2 │
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> fs-mount │
│ <span style="color: #5599ff; font-weight: 600;">Physical/Virtual:</span> physical │
│ <span style="color: #66cc66; font-weight: 600;">Mount Path:</span> /docs/api-reference │
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-09 10:22 │
╰─────────────────────────────────────────────────╯
╭─ Auto-discovered Children ────────────────────╮
│ + 1 fs-directory (root) │
│ + 3 fs-directory resources │
│ + 28 fs-file resources │
╰───────────────────────────────────────────────╯
╭─ Capabilities ──────────────────────╮
│ <span style="color: #66cc66; font-weight: 600;">Readable:</span> yes │
│ <span style="color: yellow; font-weight: 600;">Writable:</span> yes │
│ <span style="color: #66cc66; font-weight: 600;">Sandboxable:</span> yes │
│ <span style="color: #66cc66; font-weight: 600;">Checkpointable:</span> yes │
│ <span style="color: #5599ff; font-weight: 600;">Sandbox Strategy:</span> copy_on_write │
╰─────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Resource registered (31 child resources discovered)
</code></pre></div>
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource add container-instance local/api-dev <span style="color: cyan;">--mount</span> local/api-repo:/workspace <span style="color: cyan;">--mount</span> /home/user/.config/nvim:/home/dev/.config/nvim
╭─ Resource ──────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/api-dev │
│ <span style="color: cyan; font-weight: 600;">ID:</span> 01HXR3C4D5E6F7G8H9J0K1L2M3 │
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> container-instance │
│ <span style="color: #5599ff; font-weight: 600;">Physical/Virtual:</span> physical │
│ <span style="color: #66cc66; font-weight: 600;">State:</span> created (not started) │
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-09 10:25 │
╰─────────────────────────────────────────────────╯
╭─ Mounts ──────────────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Source</span> <span style="color: cyan; font-weight: 600;">Container Path</span> <span style="color: cyan; font-weight: 600;">Kind</span> │
│ <span style="opacity: 0.7;">──────────────────────────────── ─────────────── ───────────</span> │
│ local/api-repo /workspace resource-ref │
│ /home/user/.config/nvim /home/dev/… host-path │
╰───────────────────────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Container resource registered (container will start on first access)
</code></pre></div>
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource add container-instance cloud/ci-runner <span style="color: cyan;">--clone-into</span> https://github.com/acme/api.git:/workspace
╭─ Resource ──────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> cloud/ci-runner │
│ <span style="color: cyan; font-weight: 600;">ID:</span> 01HXR4D5E6F7G8H9J0K1L2M3N4 │
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> container-instance │
│ <span style="color: #5599ff; font-weight: 600;">Physical/Virtual:</span> physical │
│ <span style="color: #66cc66; font-weight: 600;">State:</span> created (not started) │
│ <span style="color: #66cc66; font-weight: 600;">Clone:</span> https://github.com/acme/api.git │
│ <span style="color: #66cc66; font-weight: 600;">Clone Target:</span> /workspace │
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-09 10:27 │
╰─────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Container resource registered (repo will be cloned on first start)
</code></pre></div>
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource add git-checkout local/webapp <span style="color: cyan;">--path</span> /home/user/projects/webapp
╭─ Resource ──────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/webapp │
│ <span style="color: cyan; font-weight: 600;">ID:</span> 01HXR5E6F7G8H9J0K1L2M3N4O5 │
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> git-checkout │
│ <span style="color: #5599ff; font-weight: 600;">Physical/Virtual:</span> physical │
│ <span style="color: #66cc66; font-weight: 600;">Path:</span> /home/user/projects/webapp │
│ <span style="color: #66cc66; font-weight: 600;">Branch:</span> main │
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-09 10:30 │
╰─────────────────────────────────────────────────────╯
╭─ Auto-discovered Children ─────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">ID</span> <span style="color: cyan; font-weight: 600;">Type</span> <span style="color: cyan; font-weight: 600;">Status</span> │
│ <span style="opacity: 0.7;">─────────────── ────────────────────── ───────────────────</span> │
│ 01HXR5E6F7G9… git <span style="color: #66cc66; font-weight: 600;">created</span> │
│ 01HXR5E6F7GA… <span style="color: yellow; font-weight: 600;">devcontainer-instance</span> <span style="color: yellow; font-weight: 600;">detected (not built)</span> │
│ 01HXR5E6F7GB… fs-directory <span style="color: #66cc66; font-weight: 600;">created</span> │
│ + 52 git-commit resources │
│ + 189 git-tree-entry resources │
╰────────────────────────────────────────────────────────────────────╯
<span style="color: yellow; font-weight: 600;">⚠ Devcontainer detected</span> at .devcontainer/devcontainer.json
Container will be built lazily on first access.
Use <span style="color: cyan;">agents resource show</span> 01HXR5E6F7GA… to inspect.
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Resource registered (245 child resources discovered)
</code></pre></div>
=== "Plain"
```
$ agents resource add git-checkout local/api-repo --path /home/user/projects/api-service --branch main
Resource
Name: local/api-repo
ID: 01HXR1A1B2C3D4E5F6G7H8J9K0
Type: git-checkout
Physical/Virtual: physical
Path: /home/user/projects/api-service
Branch: main
Created: 2026-02-09 10:20
Auto-discovered Children
ID Type Status
--------------- -------------- -----------------
01HXR1A1B2C3.. git created
01HXR1A1B2C4.. git-remote created
01HXR1A1B2C5.. git-branch created
01HXR1A1B2C6.. git-branch created
01HXR1A1B2C7.. fs-directory created
+ 47 git-commit resources
+ 312 git-tree-entry resources
+ 3 fs-directory + 28 fs-file
Capabilities
Readable: yes
Writable: yes
Sandboxable: yes
Checkpointable: yes
Sandbox Strategy: git_worktree
[OK] Resource registered (395 child resources discovered)
$ agents resource add fs-mount local/docs --mount-path /docs/api-reference
Resource
Name: local/docs
ID: 01HXR2B3C4D5E6F7G8H9J0K1L2
Type: fs-mount
Physical/Virtual: physical
Mount Path: /docs/api-reference
Created: 2026-02-09 10:22
Auto-discovered Children
+ 1 fs-directory (root)
+ 3 fs-directory resources
+ 28 fs-file resources
Capabilities
Readable: yes
Writable: yes
Sandboxable: yes
Checkpointable: yes
Sandbox Strategy: copy_on_write
[OK] Resource registered (31 child resources discovered)
$ agents resource add container-instance local/api-dev --mount local/api-repo:/workspace --mount /home/user/.config/nvim:/home/dev/.config/nvim
Resource
Name: local/api-dev
ID: 01HXR3C4D5E6F7G8H9J0K1L2M3
Type: container-instance
Physical/Virtual: physical
State: created (not started)
Created: 2026-02-09 10:25
Mounts
Source Container Path Kind
-------------------------------- --------------- ---------
local/api-repo /workspace resource-ref
/home/user/.config/nvim /home/dev/... host-path
[OK] Container resource registered (container will start on first access)
$ agents resource add container-instance cloud/ci-runner --clone-into https://github.com/acme/api.git:/workspace
Resource
Name: cloud/ci-runner
ID: 01HXR4D5E6F7G8H9J0K1L2M3N4
Type: container-instance
Physical/Virtual: physical
State: created (not started)
Clone: https://github.com/acme/api.git
Clone Target: /workspace
Created: 2026-02-09 10:27
[OK] Container resource registered (repo will be cloned on first start)
$ agents resource add git-checkout local/webapp --path /home/user/projects/webapp
Resource
Name: local/webapp
ID: 01HXR5E6F7G8H9J0K1L2M3N4O5
Type: git-checkout
Physical/Virtual: physical
Path: /home/user/projects/webapp
Branch: main
Created: 2026-02-09 10:30
Auto-discovered Children
ID Type Status
--------------- ---------------------- -----------------
01HXR5E6F7G9.. git created
01HXR5E6F7GA.. devcontainer-instance detected (not built)
01HXR5E6F7GB.. fs-directory created
+ 52 git-commit resources
+ 189 git-tree-entry resources
[WARN] Devcontainer detected at .devcontainer/devcontainer.json
Container will be built lazily on first access.
Use agents resource show 01HXR5E6F7GA… to inspect.
[OK] Resource registered (245 child resources discovered)
```
=== "JSON"
```json
{
"command": "resource add",
"status": "ok",
"exit_code": 0,
"data": {
"name": "local/api-repo",
"id": "01HXR1A1B2C3D4E5F6G7H8J9K0",
"type": "git-checkout",
"physical_virtual": "physical",
"path": "/home/user/projects/api-service",
"branch": "main",
"created": "2026-02-09T10:20:00Z",
"auto_discovered_children": [
{ "id": "01HXR1A1B2C3…", "type": "git", "status": "created" },
{ "id": "01HXR1A1B2C4…", "type": "git-remote", "status": "created" },
{ "id": "01HXR1A1B2C5…", "type": "git-branch", "status": "created" },
{ "id": "01HXR1A1B2C6…", "type": "git-branch", "status": "created" },
{ "id": "01HXR1A1B2C7…", "type": "fs-directory", "status": "created" }
],
"children_summary": {
"git_commit": 47,
"git_tree_entry": 312,
"fs_directory": 3,
"fs_file": 28
},
"total_children": 395,
"capabilities": {
"readable": true,
"writable": true,
"sandboxable": true,
"checkpointable": true,
"sandbox_strategy": "git_worktree"
}
},
"timing": { "started": "2026-02-09T10:20:00Z", "duration_ms": 250 },
"messages": ["Resource registered (395 child resources discovered)"]
}
```
=== "YAML"
```yaml
command: resource add
status: ok
exit_code: 0
data:
name: local/api-repo
id: 01HXR1A1B2C3D4E5F6G7H8J9K0
type: git-checkout
physical_virtual: physical
path: /home/user/projects/api-service
branch: main
created: "2026-02-09T10:20:00Z"
auto_discovered_children:
- id: "01HXR1A1B2C3\u2026"
type: git
status: created
- id: "01HXR1A1B2C4\u2026"
type: git-remote
status: created
- id: "01HXR1A1B2C5\u2026"
type: git-branch
status: created
- id: "01HXR1A1B2C6\u2026"
type: git-branch
status: created
- id: "01HXR1A1B2C7\u2026"
type: fs-directory
status: created
children_summary:
git_commit: 47
git_tree_entry: 312
fs_directory: 3
fs_file: 28
total_children: 395
capabilities:
readable: true
writable: true
sandboxable: true
checkpointable: true
sandbox_strategy: git_worktree
timing:
started: "2026-02-09T10:20:00Z"
duration_ms: 250
messages:
- "Resource registered (395 child resources discovered)"
```
agents resource remove
agents resource remove [--yes|-y] <NAME>!!! danger "Cascading Deletion"
Removes a registered resource ==and all its auto-discovered child resources==. A git-checkout resource can have hundreds of child resources (files, directories). This operation fails if the resource is linked to any project — use agents project unlink-resource first.
Arguments
<NAME>: Resource name (only user-added resources can be removed).--yes: Skip confirmation prompt.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource remove local/api-repo
Remove resource local/api-repo and 395 child resources? [y/N]: y
╭─ Resource Removed ──────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/api-repo │
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> git-checkout │
│ <span style="color: yellow; font-weight: 600;">Children Removed:</span> 395 │
│ <span style="color: #5599ff; font-weight: 600;">Projects Unlinked:</span> 0 │
╰─────────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Resource removed
</code></pre></div>
=== "Plain"
```
$ agents resource remove local/api-repo
Remove resource local/api-repo and 395 child resources? [y/N]: y
Resource Removed
Name: local/api-repo
Type: git-checkout
Children Removed: 395
Projects Unlinked: 0
[OK] Resource removed
```
=== "JSON"
```json
{
"command": "resource remove",
"status": "ok",
"exit_code": 0,
"data": {
"name": "local/api-repo",
"type": "git-checkout",
"children_removed": 395,
"projects_unlinked": 0
},
"timing": { "started": "2026-02-09T10:24:00Z", "duration_ms": 120 },
"messages": ["Resource removed"]
}
```
=== "YAML"
```yaml
command: resource remove
status: ok
exit_code: 0
data:
name: local/api-repo
type: git-checkout
children_removed: 395
projects_unlinked: 0
timing:
started: "2026-02-09T10:24:00Z"
duration_ms: 120
messages:
- "Resource removed"
```
agents resource list
agents resource list [--all] [(--type|-t) <TYPE>] Purpose
List registered resources with optional filters. By default, lists only user-added (named) resources. Use --all to include auto-discovered child resources.
Arguments
--type/-t TYPE: Filter by resource type (accepts a regex).--all: Include auto-discovered child resources (by default only user-added resources are shown).
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource list
╭─ Resources ──────────────────────────────────────────────────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name</span> <span style="color: cyan; font-weight: 600;">ID</span> <span style="color: cyan; font-weight: 600;">Type</span> <span style="color: cyan; font-weight: 600;">Phys/Virt</span> <span style="color: cyan; font-weight: 600;">Children</span> <span style="color: cyan; font-weight: 600;">Projects</span> │
│ <span style="opacity: 0.7;">───────────────── ──────────────────────────── ─────────── ───────── ──────── ────────────────</span> │
│ local/api-repo 01HXR1A1B2C3D4E5F6G7H8J9K0 git-checkout physical 395 local/api-service │
│ local/docs 01HXR2B2C3D4E5F6G7H8J9K0L1 fs-mount physical 32 local/api-service │
│ local/staging-db 01HXR3C3D4E5F6G7H8J9K0L1M2 database physical 12 local/api-service, │
│ local/staging │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Summary ───────────╮
│ <span style="color: #5599ff; font-weight: 600;">Total:</span> 3 │
│ <span style="color: #5599ff; font-weight: 600;">Physical:</span> 3 │
│ <span style="color: #5599ff; font-weight: 600;">Virtual:</span> 0 │
│ <span style="color: #5599ff; font-weight: 600;">Total Children:</span> 405 │
╰─────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 3 resources listed
</code></pre></div>
=== "Plain"
```
$ agents resource list
Resources
---------
Name ID Type Phys/Virt Children Projects
----------------- ---------------------------- ----------- --------- -------- ----------------
local/api-repo 01HXR1A1B2C3D4E5F6G7H8J9K0 git-checkout physical 395 local/api-service
local/docs 01HXR2B2C3D4E5F6G7H8J9K0L1 fs-mount physical 32 local/api-service
local/staging-db 01HXR3C3D4E5F6G7H8J9K0L1M2 database physical 12 local/api-service, local/staging
Summary
Total: 3
Physical: 3
Virtual: 0
Total Children: 405
[OK] 3 resources listed
```
=== "JSON"
```json
{
"command": "resource list",
"status": "ok",
"exit_code": 0,
"data": {
"resources": [
{
"name": "local/api-repo",
"id": "01HXR1A1B2C3D4E5F6G7H8J9K0",
"type": "git-checkout",
"physical_virtual": "physical",
"children": 395,
"projects": ["local/api-service"]
},
{
"name": "local/docs",
"id": "01HXR2B2C3D4E5F6G7H8J9K0L1",
"type": "fs-mount",
"physical_virtual": "physical",
"children": 32,
"projects": ["local/api-service"]
},
{
"name": "local/staging-db",
"id": "01HXR3C3D4E5F6G7H8J9K0L1M2",
"type": "database",
"physical_virtual": "physical",
"children": 12,
"projects": ["local/api-service", "local/staging"]
}
],
"summary": {
"total": 3,
"physical": 3,
"virtual": 0,
"total_children": 405
}
},
"timing": { "started": "2026-02-09T10:25:00Z", "duration_ms": 90 },
"messages": ["3 resources listed"]
}
```
=== "YAML"
```yaml
command: resource list
status: ok
exit_code: 0
data:
resources:
- name: local/api-repo
id: 01HXR1A1B2C3D4E5F6G7H8J9K0
type: git-checkout
physical_virtual: physical
children: 395
projects:
- local/api-service
- name: local/docs
id: 01HXR2B2C3D4E5F6G7H8J9K0L1
type: fs-mount
physical_virtual: physical
children: 32
projects:
- local/api-service
- name: local/staging-db
id: 01HXR3C3D4E5F6G7H8J9K0L1M2
type: database
physical_virtual: physical
children: 12
projects:
- local/api-service
- local/staging
summary:
total: 3
physical: 3
virtual: 0
total_children: 405
timing:
started: "2026-02-09T10:25:00Z"
duration_ms: 90
messages:
- "3 resources listed"
```
agents resource show
agents resource show <RESOURCE>Purpose Show detailed information about a registered resource including its type, capabilities, parent/child relationships, and linked projects.
Arguments
<RESOURCE>: Resource name or ULID.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource show local/api-repo
╭─ Resource ─────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/api-repo │
│ <span style="color: cyan; font-weight: 600;">ID:</span> 01HXR1A1B2C3D4E5F6G7H8J9K0 │
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> git-checkout │
│ <span style="color: #5599ff; font-weight: 600;">Physical/Virtual:</span> physical │
│ <span style="color: #66cc66; font-weight: 600;">Path:</span> /home/user/projects/api-service │
│ <span style="color: #5599ff; font-weight: 600;">Branch:</span> main │
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-09 10:20 │
╰────────────────────────────────────────────────────╯
╭─ Capabilities ────────────────────╮
│ <span style="color: #66cc66; font-weight: 600;">Readable:</span> yes │
│ <span style="color: yellow; font-weight: 600;">Writable:</span> yes │
│ <span style="color: #66cc66; font-weight: 600;">Sandboxable:</span> yes │
│ <span style="color: #66cc66; font-weight: 600;">Checkpointable:</span> yes │
│ <span style="color: #5599ff; font-weight: 600;">Sandbox Strategy:</span> git_worktree │
╰───────────────────────────────────╯
╭─ Parents ────╮
│ (top-level) │
╰──────────────╯
╭─ Direct Children ──────────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">ID</span> <span style="color: cyan; font-weight: 600;">Type</span> <span style="color: cyan; font-weight: 600;">Auto</span> <span style="color: cyan; font-weight: 600;">Children</span> │
│ <span style="opacity: 0.7;">──────────────────────────── ──────────── ──── ────────</span> │
│ 01HXR4D4E5F6G7H8J9K0L1M2N3 git yes 363 │
│ 01HXR5E5F6G7H8J9K0L1M2N3P4 fs-directory yes 32 │
╰────────────────────────────────────────────────────────────────────────╯
╭─ Linked Projects ─────────────╮
│ - local/api-service (r/w) │
╰───────────────────────────────╯
╭─ Tool Bindings ────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Tool</span> <span style="color: cyan; font-weight: 600;">Slot</span> <span style="color: cyan; font-weight: 600;">Access</span> │
│ <span style="opacity: 0.7;">──────────────────────── ───── ───────────</span> │
│ (builtin) git_status repo read_only │
│ (builtin) git_diff repo read_only │
│ (builtin) git_log repo read_only │
│ local/run-migrations db (not bound) │
╰────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Resource details loaded
</code></pre></div>
=== "Plain"
```
$ agents resource show local/api-repo
Resource
Name: local/api-repo
ID: 01HXR1A1B2C3D4E5F6G7H8J9K0
Type: git-checkout
Physical/Virtual: physical
Path: /home/user/projects/api-service
Branch: main
Created: 2026-02-09 10:20
Capabilities
Readable: yes
Writable: yes
Sandboxable: yes
Checkpointable: yes
Sandbox Strategy: git_worktree
Parents
(top-level)
Direct Children
ID Type Auto Children
---------------------------- ------------ ---- --------
01HXR4D4E5F6G7H8J9K0L1M2N3 git yes 363
01HXR5E5F6G7H8J9K0L1M2N3P4 fs-directory yes 32
Linked Projects
- local/api-service (r/w)
Tool Bindings
Tool Slot Access
------------------------ ----- -----------
(builtin) git_status repo read_only
(builtin) git_diff repo read_only
(builtin) git_log repo read_only
local/run-migrations db (not bound)
[OK] Resource details loaded
```
=== "JSON"
```json
{
"command": "resource show",
"status": "ok",
"exit_code": 0,
"data": {
"name": "local/api-repo",
"id": "01HXR1A1B2C3D4E5F6G7H8J9K0",
"type": "git-checkout",
"physical_virtual": "physical",
"path": "/home/user/projects/api-service",
"branch": "main",
"created": "2026-02-09T10:20:00Z",
"capabilities": {
"readable": true,
"writable": true,
"sandboxable": true,
"checkpointable": true,
"sandbox_strategy": "git_worktree"
},
"parents": ["(top-level)"],
"direct_children": [
{ "id": "01HXR4D4E5F6G7H8J9K0L1M2N3", "type": "git", "auto": true, "children": 363 },
{ "id": "01HXR5E5F6G7H8J9K0L1M2N3P4", "type": "fs-directory", "auto": true, "children": 32 }
],
"linked_projects": [
{ "name": "local/api-service", "access": "r/w" }
],
"tool_bindings": [
{ "tool": "(builtin) git_status", "slot": "repo", "access": "read_only" },
{ "tool": "(builtin) git_diff", "slot": "repo", "access": "read_only" },
{ "tool": "(builtin) git_log", "slot": "repo", "access": "read_only" },
{ "tool": "local/run-migrations", "slot": "db", "access": "(not bound)" }
]
},
"timing": { "started": "2026-02-09T10:15:00Z", "duration_ms": 65 },
"messages": ["Resource details loaded"]
}
```
=== "YAML"
```yaml
command: resource show
status: ok
exit_code: 0
data:
name: local/api-repo
id: 01HXR1A1B2C3D4E5F6G7H8J9K0
type: git-checkout
physical_virtual: physical
path: /home/user/projects/api-service
branch: main
created: "2026-02-09T10:20:00Z"
capabilities:
readable: true
writable: true
sandboxable: true
checkpointable: true
sandbox_strategy: git_worktree
parents:
- (top-level)
direct_children:
- id: 01HXR4D4E5F6G7H8J9K0L1M2N3
type: git
auto: true
children: 363
- id: 01HXR5E5F6G7H8J9K0L1M2N3P4
type: fs-directory
auto: true
children: 32
linked_projects:
- name: local/api-service
access: r/w
tool_bindings:
- tool: (builtin) git_status
slot: repo
access: read_only
- tool: (builtin) git_diff
slot: repo
access: read_only
- tool: (builtin) git_log
slot: repo
access: read_only
- tool: local/run-migrations
slot: db
access: (not bound)
timing:
started: "2026-02-09T10:15:00Z"
duration_ms: 65
messages:
- Resource details loaded
```
agents resource inspect
agents resource inspect [--tree] [--file <PATH>] <RESOURCE>Purpose Inspect a resource's contents. For file-based resources (git checkouts, filesystem mounts, directories), displays the file tree or the contents of a specific file. Works with any resource — user-added or auto-discovered — via name or ULID.
Arguments
<RESOURCE>: Resource name or ULID.--tree: Show the resource's file/content tree.--file PATH: Show contents of a specific file within the resource.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource inspect local/api-repo <span style="color: cyan;">--tree</span>
╭─ Resource Tree: local/api-repo ──────────────────────────────────────╮
│ │
│ <span style="color: cyan; font-weight: 600;">/home/user/projects/api-service</span> │
│ ├── <span style="color: #5599ff; font-weight: 600;">src/</span> │
│ │ ├── <span style="color: #5599ff; font-weight: 600;">api/</span> │
│ │ │ ├── __init__.py │
│ │ │ ├── <span style="color: #5599ff; font-weight: 600;">auth/</span> │
│ │ │ │ ├── auth_middleware.py │
│ │ │ │ ├── token_service.py │
│ │ │ │ └── rbac.py │
│ │ │ ├── <span style="color: #5599ff; font-weight: 600;">routes/</span> │
│ │ │ └── <span style="color: #5599ff; font-weight: 600;">models/</span> │
│ │ └── <span style="color: #5599ff; font-weight: 600;">utils/</span> │
│ ├── <span style="color: #5599ff; font-weight: 600;">tests/</span> │
│ ├── README.md │
│ └── pyproject.toml │
│ │
╰──────────────────────────────────────────────────────────────────────╯
╭─ Summary ──────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Directories:</span> 8 │
│ <span style="color: #5599ff; font-weight: 600;">Files:</span> 41 │
│ <span style="color: #5599ff; font-weight: 600;">Total Size:</span> 284 KB │
╰────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Resource tree displayed
</code></pre></div>
=== "Plain"
```
$ agents resource inspect local/api-repo --tree
Resource Tree: local/api-repo
/home/user/projects/api-service
+-- src/
| +-- api/
| | +-- __init__.py
| | +-- auth/
| | | +-- auth_middleware.py
| | | +-- token_service.py
| | | +-- rbac.py
| | +-- routes/
| | +-- models/
| +-- utils/
+-- tests/
+-- README.md
+-- pyproject.toml
Summary
Directories: 8
Files: 41
Total Size: 284 KB
[OK] Resource tree displayed
```
=== "JSON"
```json
{
"command": "resource inspect",
"status": "ok",
"exit_code": 0,
"data": {
"resource": "local/api-repo",
"mode": "tree",
"root": "/home/user/projects/api-service",
"tree": [
{
"name": "src/",
"type": "directory",
"children": [
{
"name": "api/",
"type": "directory",
"children": [
{ "name": "__init__.py", "type": "file" },
{
"name": "auth/",
"type": "directory",
"children": [
{ "name": "auth_middleware.py", "type": "file" },
{ "name": "token_service.py", "type": "file" },
{ "name": "rbac.py", "type": "file" }
]
},
{ "name": "routes/", "type": "directory" },
{ "name": "models/", "type": "directory" }
]
},
{ "name": "utils/", "type": "directory" }
]
},
{ "name": "tests/", "type": "directory" },
{ "name": "README.md", "type": "file" },
{ "name": "pyproject.toml", "type": "file" }
],
"summary": {
"directories": 8,
"files": 41,
"total_size": "284 KB"
}
},
"timing": { "started": "2026-02-09T10:15:00Z", "duration_ms": 150 },
"messages": ["Resource tree displayed"]
}
```
=== "YAML"
```yaml
command: resource inspect
status: ok
exit_code: 0
data:
resource: local/api-repo
mode: tree
root: /home/user/projects/api-service
tree:
- name: src/
type: directory
children:
- name: api/
type: directory
children:
- name: __init__.py
type: file
- name: auth/
type: directory
children:
- name: auth_middleware.py
type: file
- name: token_service.py
type: file
- name: rbac.py
type: file
- name: routes/
type: directory
- name: models/
type: directory
- name: utils/
type: directory
- name: tests/
type: directory
- name: README.md
type: file
- name: pyproject.toml
type: file
summary:
directories: 8
files: 41
total_size: 284 KB
timing:
started: "2026-02-09T10:15:00Z"
duration_ms: 150
messages:
- Resource tree displayed
```
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource inspect local/api-repo <span style="color: cyan;">--file</span> src/api/auth/auth_middleware.py
╭─ File: src/api/auth/auth_middleware.py ──────────────────╮
│ <span style="color: cyan; font-weight: 600;">Resource:</span> local/api-repo │
│ <span style="color: #5599ff; font-weight: 600;">Size:</span> 2.4 KB │
│ <span style="color: #5599ff; font-weight: 600;">Language:</span> Python │
│ <span style="color: #5599ff; font-weight: 600;">Last Modified:</span> 2026-02-10 14:32 │
╰──────────────────────────────────────────────────────────╯
<span style="opacity: 0.7;"> 1</span> │ <span style="color: cyan;">from</span> fastapi <span style="color: cyan;">import</span> Request, HTTPException
<span style="opacity: 0.7;"> 2</span> │ <span style="color: cyan;">from</span> .token_service <span style="color: cyan;">import</span> validate_token
<span style="opacity: 0.7;"> 3</span> │
<span style="opacity: 0.7;"> 4</span> │ <span style="color: cyan;">async def</span> <span style="color: #66cc66;">auth_middleware</span>(request: Request):
<span style="opacity: 0.7;"> 5</span> │ token = request.headers.get(<span style="color: #66cc66;">"Authorization"</span>)
<span style="opacity: 0.7;"> 6</span> │ <span style="color: cyan;">if not</span> token:
<span style="opacity: 0.7;"> 7</span> │ <span style="color: cyan;">raise</span> HTTPException(status_code=<span style="color: yellow;">401</span>)
<span style="opacity: 0.7;"> 8</span> │ user = <span style="color: cyan;">await</span> validate_token(token)
<span style="opacity: 0.7;"> 9</span> │ request.state.user = user
<span style="opacity: 0.7;"> 10</span> │ <span style="color: cyan;">return</span> user
<span style="opacity: 0.7;"> </span> │ <span style="opacity: 0.5;">... (24 more lines)</span>
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> File displayed
</code></pre></div>
=== "Plain"
```
$ agents resource inspect local/api-repo --file src/api/auth/auth_middleware.py
File: src/api/auth/auth_middleware.py
Resource: local/api-repo
Size: 2.4 KB
Language: Python
Last Modified: 2026-02-10 14:32
1 | from fastapi import Request, HTTPException
2 | from .token_service import validate_token
3 |
4 | async def auth_middleware(request: Request):
5 | token = request.headers.get("Authorization")
6 | if not token:
7 | raise HTTPException(status_code=401)
8 | user = await validate_token(token)
9 | request.state.user = user
10 | return user
| ... (24 more lines)
[OK] File displayed
```
=== "JSON"
```json
{
"command": "resource inspect",
"status": "ok",
"exit_code": 0,
"data": {
"resource": "local/api-repo",
"mode": "file",
"file": {
"path": "src/api/auth/auth_middleware.py",
"size": "2.4 KB",
"language": "Python",
"last_modified": "2026-02-10T14:32:00Z",
"lines_shown": 10,
"total_lines": 34,
"content": "from fastapi import Request, HTTPException\nfrom .token_service import validate_token\n\nasync def auth_middleware(request: Request):\n token = request.headers.get(\"Authorization\")\n if not token:\n raise HTTPException(status_code=401)\n user = await validate_token(token)\n request.state.user = user\n return user\n"
}
},
"timing": { "started": "2026-02-09T10:15:00Z", "duration_ms": 30 },
"messages": ["File displayed"]
}
```
=== "YAML"
```yaml
command: resource inspect
status: ok
exit_code: 0
data:
resource: local/api-repo
mode: file
file:
path: src/api/auth/auth_middleware.py
size: 2.4 KB
language: Python
last_modified: "2026-02-10T14:32:00Z"
lines_shown: 10
total_lines: 34
content: |
from fastapi import Request, HTTPException
from .token_service import validate_token
async def auth_middleware(request: Request):
token = request.headers.get("Authorization")
if not token:
raise HTTPException(status_code=401)
user = await validate_token(token)
request.state.user = user
return user
timing:
started: "2026-02-09T10:15:00Z"
duration_ms: 30
messages:
- File displayed
```
agents resource tree
agents resource tree [(--depth|-d) <N>] [(--type|-t) <TYPE>] <RESOURCE>Purpose Display the resource DAG as a tree starting from a given resource, showing parent/child relationships.
Arguments
<RESOURCE>: Resource name or ULID.--depth/-d N: Maximum depth to display (default: 3).--type/-t TYPE: Filter to only show children of a specific type.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource tree local/api-repo <span style="color: cyan;">--depth</span> 2
╭─ Resource Tree: local/api-repo ─────────────────────────────────────╮
│ │
│ <span style="color: cyan; font-weight: 600;">git-checkout 01HXR1A1..J9K0</span> (physical) │
│ ├── <span style="color: #5599ff; font-weight: 600;">git 01HXR4D4..M2N3</span> (physical) │
│ │ ├── <span style="color: #5599ff; font-weight: 600;">git-remote 01HXR6F6..P4Q5</span> │
│ │ ├── <span style="color: magenta; font-weight: 600;">git-branch 01HXR7G7..Q5R6</span> │
│ │ │ ├── <span style="color: #66cc66; font-weight: 600;">git-commit 01HXR8H8..R6S7</span> │
│ │ │ └── <span style="opacity: 0.7;">... 22 more git-commit resources</span> │
│ │ └── <span style="color: magenta; font-weight: 600;">git-branch 01HXR9J9..S7T8</span> │
│ │ └── <span style="opacity: 0.7;">... 26 git-commit resources</span> │
│ └── <span style="color: #5599ff; font-weight: 600;">fs-directory 01HXR5E5..N3P4</span> (physical) │
│ ├── <span style="color: #66cc66; font-weight: 600;">fs-directory 01HXRAK1..T8U9</span> │
│ ├── <span style="color: #66cc66; font-weight: 600;">fs-directory 01HXRBL2..U9V0</span> │
│ └── <span style="opacity: 0.7;">... 28 more fs-file resources</span> │
│ │
╰─────────────────────────────────────────────────────────────────────╯
╭─ Summary ──────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Total shown:</span> 14 │
│ <span style="color: #5599ff; font-weight: 600;">Total in subtree:</span> 395 │
│ <span style="color: #5599ff; font-weight: 600;">Max depth:</span> 2 │
╰────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Resource tree displayed
</code></pre></div>
=== "Plain"
```
$ agents resource tree local/api-repo --depth 2
Resource Tree: local/api-repo
git-checkout 01HXR1A1..J9K0 (physical)
+-- git 01HXR4D4..M2N3 (physical)
| +-- git-remote 01HXR6F6..P4Q5
| +-- git-branch 01HXR7G7..Q5R6
| | +-- git-commit 01HXR8H8..R6S7
| | +-- ... 22 more git-commit resources
| +-- git-branch 01HXR9J9..S7T8
| +-- ... 26 git-commit resources
+-- fs-directory 01HXR5E5..N3P4 (physical)
+-- fs-directory 01HXRAK1..T8U9
+-- fs-directory 01HXRBL2..U9V0
+-- ... 28 more fs-file resources
Summary
Total shown: 14
Total in subtree: 395
Max depth: 2
[OK] Resource tree displayed
```
=== "JSON"
```json
{
"command": "resource tree",
"status": "ok",
"exit_code": 0,
"data": {
"resource": "local/api-repo",
"max_depth": 2,
"tree": {
"type": "git-checkout",
"id": "01HXR1A1..J9K0",
"physical": true,
"children": [
{
"type": "git",
"id": "01HXR4D4..M2N3",
"physical": true,
"children": [
{ "type": "git-remote", "id": "01HXR6F6..P4Q5" },
{
"type": "git-branch",
"id": "01HXR7G7..Q5R6",
"children": [
{ "type": "git-commit", "id": "01HXR8H8..R6S7" },
"... 22 more git-commit resources"
]
},
{
"type": "git-branch",
"id": "01HXR9J9..S7T8",
"children": ["... 26 git-commit resources"]
}
]
},
{
"type": "fs-directory",
"id": "01HXR5E5..N3P4",
"physical": true,
"children": [
{ "type": "fs-directory", "id": "01HXRAK1..T8U9" },
{ "type": "fs-directory", "id": "01HXRBL2..U9V0" },
"... 28 more fs-file resources"
]
}
]
},
"summary": {
"total_shown": 14,
"total_in_subtree": 395,
"max_depth": 2
}
},
"timing": { "started": "2026-02-09T10:15:00Z", "duration_ms": 85 },
"messages": ["Resource tree displayed"]
}
```
=== "YAML"
```yaml
command: resource tree
status: ok
exit_code: 0
data:
resource: local/api-repo
max_depth: 2
tree:
type: git-checkout
id: 01HXR1A1..J9K0
physical: true
children:
- type: git
id: 01HXR4D4..M2N3
physical: true
children:
- type: git-remote
id: 01HXR6F6..P4Q5
- type: git-branch
id: 01HXR7G7..Q5R6
children:
- type: git-commit
id: 01HXR8H8..R6S7
- "... 22 more git-commit resources"
- type: git-branch
id: 01HXR9J9..S7T8
children:
- "... 26 git-commit resources"
- type: fs-directory
id: 01HXR5E5..N3P4
physical: true
children:
- type: fs-directory
id: 01HXRAK1..T8U9
- type: fs-directory
id: 01HXRBL2..U9V0
- "... 28 more fs-file resources"
summary:
total_shown: 14
total_in_subtree: 395
max_depth: 2
timing:
started: "2026-02-09T10:15:00Z"
duration_ms: 85
messages:
- Resource tree displayed
```
agents resource link-child
agents resource link-child <PARENT> <CHILD>Purpose Manually link one resource as a child of another. The child resource must already be registered. The resource types must be compatible (the parent type must allow the child type). A resource can have multiple parents.
Arguments
<PARENT>: Parent resource name or ULID.<CHILD>: Child resource name or ULID.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource link-child local/api-repo 01HXR2B2C3D4E5F6G7H8J9K0L1
╭─ Child Linked ──────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Parent:</span> local/api-repo │
│ <span style="color: #5599ff; font-weight: 600;">Child:</span> 01HXR2B2C3D4E5F6G7H8J9K0L1 │
│ <span style="color: #5599ff; font-weight: 600;">Child Type:</span> fs-mount │
│ <span style="color: #66cc66; font-weight: 600;">Status:</span> linked │
╰─────────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Child resource linked
</code></pre></div>
=== "Plain"
```
$ agents resource link-child local/api-repo 01HXR2B2C3D4E5F6G7H8J9K0L1
Child Linked
Parent: local/api-repo
Child: 01HXR2B2C3D4E5F6G7H8J9K0L1
Child Type: fs-mount
Status: linked
[OK] Child resource linked
```
=== "JSON"
```json
{
"command": "resource link-child",
"status": "ok",
"exit_code": 0,
"data": {
"parent": "local/api-repo",
"child": "01HXR2B2C3D4E5F6G7H8J9K0L1",
"child_type": "fs-mount",
"status": "linked"
},
"timing": { "started": "2026-02-09T10:15:00Z", "duration_ms": 38 },
"messages": ["Child resource linked"]
}
```
=== "YAML"
```yaml
command: resource link-child
status: ok
exit_code: 0
data:
parent: local/api-repo
child: 01HXR2B2C3D4E5F6G7H8J9K0L1
child_type: fs-mount
status: linked
timing:
started: "2026-02-09T10:15:00Z"
duration_ms: 38
messages:
- Child resource linked
```
agents resource unlink-child
agents resource unlink-child [--yes|-y] <PARENT> <CHILD>Purpose Remove a manual parent/child link between two resources. Auto-discovered links cannot be manually unlinked.
Arguments
<PARENT>: Parent resource name or ULID.<CHILD>: Child resource name or ULID.--yes: Skip confirmation prompt.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource unlink-child local/api-repo 01HXR2B2C3D4E5F6G7H8J9K0L1
Unlink 01HXR2B2C3D4E5F6G7H8J9K0L1 from parent local/api-repo? [y/N]: y
╭─ Child Unlinked ────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Parent:</span> local/api-repo │
│ <span style="color: #5599ff; font-weight: 600;">Child:</span> 01HXR2B2C3D4E5F6G7H8J9K0L1 │
│ <span style="color: #66cc66; font-weight: 600;">Status:</span> unlinked │
╰─────────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Child resource unlinked
</code></pre></div>
=== "Plain"
```
$ agents resource unlink-child local/api-repo 01HXR2B2C3D4E5F6G7H8J9K0L1
Unlink 01HXR2B2C3D4E5F6G7H8J9K0L1 from parent local/api-repo? [y/N]: y
Child Unlinked
Parent: local/api-repo
Child: 01HXR2B2C3D4E5F6G7H8J9K0L1
Status: unlinked
[OK] Child resource unlinked
```
=== "JSON"
```json
{
"command": "resource unlink-child",
"status": "ok",
"exit_code": 0,
"data": {
"parent": "local/api-repo",
"child": "01HXR2B2C3D4E5F6G7H8J9K0L1",
"status": "unlinked"
},
"timing": { "started": "2026-02-09T10:15:00Z", "duration_ms": 45 },
"messages": ["Child resource unlinked"]
}
```
=== "YAML"
```yaml
command: resource unlink-child
status: ok
exit_code: 0
data:
parent: local/api-repo
child: 01HXR2B2C3D4E5F6G7H8J9K0L1
status: unlinked
timing:
started: "2026-02-09T10:15:00Z"
duration_ms: 45
messages:
- Child resource unlinked
```
agents resource stop
agents resource stop <NAME> [--yes | -y]Purpose
Stop an active devcontainer-instance or container-instance resource. Transitions the container through running → stopping → stopped. Only container-typed resources may be stopped; attempting to stop other resource types produces an error.
Arguments
<NAME>: Resource name or ULID of the devcontainer to stop.
Options
--yes/-y: Skip the confirmation prompt (useful in scripts and automation).
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource stop local/my-dc
Stopping container local/my-dc (state: running)...
<span style="color: #66cc66; font-weight: 600;">Stopped:</span> local/my-dc
</code></pre></div>
=== "Plain"
```
$ agents resource stop local/my-dc
Stopping container local/my-dc (state: running)...
Stopped: local/my-dc
```
agents resource rebuild
agents resource rebuild <NAME> [--yes | -y]Purpose
Rebuild a stopped or failed devcontainer-instance resource. Transitions the container through stopped/failed → building → running by invoking devcontainer up with the resource's workspace location. Only devcontainer-instance resources may be rebuilt since the rebuild process invokes the devcontainer CLI; generic container-instance resources do not support rebuild.
Arguments
<NAME>: Resource name or ULID of the devcontainer to rebuild.
Options
--yes/-y: Skip the confirmation prompt (useful in scripts and automation).
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource rebuild local/my-dc
Rebuilding local/my-dc...
<span style="color: #66cc66; font-weight: 600;">Rebuilt:</span> local/my-dc
</code></pre></div>
=== "Plain"
```
$ agents resource rebuild local/my-dc
Rebuilding local/my-dc...
Rebuilt: local/my-dc
```
agents plan
!!! info "Purpose" Manage ==plans== through the Strategize → Execute → Apply lifecycle (instantiated from Action templates).
??? abstract "Plan Lifecycle at a Glance"
Action ──use──▶ Strategize ──execute──▶ Execute ──apply──▶ Apply ▲ │ │ └──────────────────────┘ │ ▲ (reversion) │ └────────────────────────────────────────┘
- [x] **Action** — Reusable template defining work, actors, and constraints
- [x] **Strategize** — Strategy actor produces a decision tree
- [x] **Execute** — Execution actor implements the strategy in a sandbox
- [x] **Apply** — Changeset is merged into real project resources
!!! note "Phase Reversion"
Both Execute and Apply can revert to Strategize when constraints are too restrictive. See `delete_content` and `access_network` automation profile flags.
agents plan list
agents plan list [--phase <PHASE>] [--state <STATE>] [--project <PROJECT>]
[--action <ACTION>] [<REGEX>]Purpose List plans with optional filtering.
Arguments
--phase PHASE: Filter by phase.--state STATE: Filter by processing state.--project PROJECT: Filter by project.--action ACTION: Filter by action name.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> <span style="color: cyan;">--format</span> table plan list <span style="color: cyan;">--phase</span> execute
╭─ Plans ──────────────────────────────────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">ID</span> <span style="color: cyan; font-weight: 600;">Phase</span> <span style="color: cyan; font-weight: 600;">State</span> <span style="color: cyan; font-weight: 600;">Action</span> <span style="color: cyan; font-weight: 600;">Project</span> <span style="color: cyan; font-weight: 600;">Elapsed</span> │
│ <span style="opacity: 0.7;">──────── ─────── ────────── ─────────────────── ───────────────── ─────────</span> │
│ 01HXM7A9 execute processing local/code-coverage local/api-service 00:01:12 │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Filters ──────╮
│ <span style="color: yellow; font-weight: 600;">Phase:</span> execute │
│ <span style="color: magenta; font-weight: 600;">State:</span> (any) │
│ <span style="color: #5599ff; font-weight: 600;">Project:</span> (any) │
│ <span style="color: #5599ff; font-weight: 600;">Action:</span> (any) │
╰────────────────╯
╭─ Summary ─────────╮
│ <span style="color: yellow; font-weight: 600;">Total:</span> 1 │
│ <span style="color: cyan; font-weight: 600;">Processing:</span> 1 │
│ <span style="color: #66cc66; font-weight: 600;">Completed:</span> 0 │
│ <span style="color: #ff6666; font-weight: 600;">Errored:</span> 0 │
╰───────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 1 plan listed
</code></pre></div>
=== "Plain"
```
$ agents --format table plan list --phase execute
Plans
ID Phase State Action Project Elapsed
-------- ------- ---------- ------------------- ----------------- ---------
01HXM7A9 execute processing local/code-coverage local/api-service 00:01:12
Filters
Phase: execute
State: (any)
Project: (any)
Action: (any)
Summary
Total: 1
Processing: 1
Completed: 0
Errored: 0
[OK] 1 plan listed
```
=== "JSON"
```json
{
"command": "plan list",
"status": "ok",
"exit_code": 0,
"data": {
"plans": [
{
"id": "01HXM7A9",
"phase": "execute",
"state": "processing",
"action": "local/code-coverage",
"project": "local/api-service",
"elapsed": "00:01:12"
}
],
"filters": {
"phase": "execute",
"state": null,
"project": null,
"action": null
},
"summary": {
"total": 1,
"processing": 1,
"completed": 0,
"errored": 0
}
},
"timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 95 },
"messages": ["1 plan listed"]
}
```
=== "YAML"
```yaml
command: plan list
status: ok
exit_code: 0
data:
plans:
- id: "01HXM7A9"
phase: execute
state: processing
action: "local/code-coverage"
project: "local/api-service"
elapsed: "00:01:12"
filters:
phase: execute
state: null
project: null
action: null
summary:
total: 1
processing: 1
completed: 0
errored: 0
timing:
started: "2026-02-09T14:30:00Z"
duration_ms: 95
messages:
- "1 plan listed"
```
Listing all plans without filters shows plans across all phases and states:
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan list
╭─ Plans ──────────────────────────────────────────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">ID</span> <span style="color: cyan; font-weight: 600;">Phase</span> <span style="color: cyan; font-weight: 600;">State</span> <span style="color: cyan; font-weight: 600;">Action</span> <span style="color: cyan; font-weight: 600;">Project</span> <span style="color: cyan; font-weight: 600;">Elapsed</span> │
│ <span style="opacity: 0.7;">──────── ────────── ────────── ─────────────────── ───────────────── ─────────</span> │
│ 01HXM7A9 execute processing local/code-coverage local/api-service 00:01:12 │
│ 01HXM6R3 <span style="color: #66cc66; font-weight: 600;">apply </span> <span style="color: #66cc66; font-weight: 600;">applied </span> local/add-auth local/api-service 00:07:14 │
│ 01HXM5K2 <span style="color: #ff6666; font-weight: 600;">execute</span> <span style="color: #ff6666; font-weight: 600;">errored</span> local/migrate-db local/api-service 00:04:33 │
│ 01HXM4J1 strategize processing local/refactor-api local/web-app 00:00:45 │
│ 01HXM3H8 <span style="opacity: 0.5;">cancelled</span> <span style="opacity: 0.5;">cancelled</span> local/add-logging local/api-service 00:02:10 │
╰──────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Summary ─────────────╮
│ <span style="color: yellow;">Total:</span> 5 │
│ <span style="color: cyan; font-weight: 600;">Processing:</span> 2 │
│ <span style="color: #66cc66; font-weight: 600;">Completed:</span> 1 │
│ <span style="color: #ff6666; font-weight: 600;">Errored:</span> 1 │
│ <span style="opacity: 0.5;">Cancelled:</span> 1 │
╰───────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 5 plans listed
</code></pre></div>
=== "Plain"
```
$ agents plan list
Plans
ID Phase State Action Project Elapsed
-------- ---------- ---------- ------------------- ----------------- ---------
01HXM7A9 execute processing local/code-coverage local/api-service 00:01:12
01HXM6R3 apply applied local/add-auth local/api-service 00:07:14
01HXM5K2 execute errored local/migrate-db local/api-service 00:04:33
01HXM4J1 strategize processing local/refactor-api local/web-app 00:00:45
01HXM3H8 cancelled cancelled local/add-logging local/api-service 00:02:10
Summary
Total: 5
Processing: 2
Completed: 1
Errored: 1
Cancelled: 1
[OK] 5 plans listed
```
=== "JSON"
```json
{
"command": "plan list",
"status": "ok",
"exit_code": 0,
"data": {
"plans": [
{ "id": "01HXM7A9", "phase": "execute", "state": "processing", "action": "local/code-coverage", "project": "local/api-service", "elapsed": "00:01:12" },
{ "id": "01HXM6R3", "phase": "apply", "state": "applied", "action": "local/add-auth", "project": "local/api-service", "elapsed": "00:07:14" },
{ "id": "01HXM5K2", "phase": "execute", "state": "errored", "action": "local/migrate-db", "project": "local/api-service", "elapsed": "00:04:33" },
{ "id": "01HXM4J1", "phase": "strategize", "state": "processing", "action": "local/refactor-api", "project": "local/web-app", "elapsed": "00:00:45" },
{ "id": "01HXM3H8", "phase": "cancelled", "state": "cancelled", "action": "local/add-logging", "project": "local/api-service", "elapsed": "00:02:10" }
],
"summary": {
"total": 5,
"processing": 2,
"completed": 1,
"errored": 1,
"cancelled": 1
}
},
"timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 95 },
"messages": ["5 plans listed"]
}
```
=== "YAML"
```yaml
command: plan list
status: ok
exit_code: 0
data:
plans:
- id: "01HXM7A9"
phase: execute
state: processing
action: "local/code-coverage"
project: "local/api-service"
elapsed: "00:01:12"
- id: "01HXM6R3"
phase: apply
state: applied
action: "local/add-auth"
project: "local/api-service"
elapsed: "00:07:14"
- id: "01HXM5K2"
phase: execute
state: errored
action: "local/migrate-db"
project: "local/api-service"
elapsed: "00:04:33"
- id: "01HXM4J1"
phase: strategize
state: processing
action: "local/refactor-api"
project: "local/web-app"
elapsed: "00:00:45"
- id: "01HXM3H8"
phase: cancelled
state: cancelled
action: "local/add-logging"
project: "local/api-service"
elapsed: "00:02:10"
summary:
total: 5
processing: 2
completed: 1
errored: 1
cancelled: 1
timing:
started: "2026-02-09T14:30:00Z"
duration_ms: 95
messages:
- "5 plans listed"
```
Filtering by project with --project:
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan list <span style="color: cyan;">--project</span> local/web-app
╭─ Plans ──────────────────────────────────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">ID</span> <span style="color: cyan; font-weight: 600;">Phase</span> <span style="color: cyan; font-weight: 600;">State</span> <span style="color: cyan; font-weight: 600;">Action</span> <span style="color: cyan; font-weight: 600;">Project</span> <span style="color: cyan; font-weight: 600;">Elapsed</span> │
│ <span style="opacity: 0.7;">──────── ────────── ────────── ─────────────────── ───────────── ─────────</span> │
│ 01HXM4J1 strategize processing local/refactor-api local/web-app 00:00:45 │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Filters ─────────────────╮
│ <span style="color: yellow;">Phase:</span> (any) │
│ <span style="color: magenta; font-weight: 600;">State:</span> (any) │
│ <span style="color: #5599ff; font-weight: 600;">Project:</span> local/web-app │
│ <span style="color: #5599ff; font-weight: 600;">Action:</span> (any) │
╰───────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 1 plan listed
</code></pre></div>
=== "Plain"
```
$ agents plan list --project local/web-app
Plans
ID Phase State Action Project Elapsed
-------- ---------- ---------- ------------------- ------------- ---------
01HXM4J1 strategize processing local/refactor-api local/web-app 00:00:45
Filters
Phase: (any)
State: (any)
Project: local/web-app
Action: (any)
[OK] 1 plan listed
```
=== "JSON"
```json
{
"command": "plan list",
"status": "ok",
"exit_code": 0,
"data": {
"plans": [
{
"id": "01HXM4J1",
"phase": "strategize",
"state": "processing",
"action": "local/refactor-api",
"project": "local/web-app",
"elapsed": "00:00:45"
}
],
"filters": {
"phase": null,
"state": null,
"project": "local/web-app",
"action": null
},
"total": 1
},
"timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 85 },
"messages": ["1 plan listed"]
}
```
=== "YAML"
```yaml
command: plan list
status: ok
exit_code: 0
data:
plans:
- id: "01HXM4J1"
phase: strategize
state: processing
action: "local/refactor-api"
project: "local/web-app"
elapsed: "00:00:45"
filters:
phase: null
state: null
project: "local/web-app"
action: null
total: 1
timing:
started: "2026-02-09T14:30:00Z"
duration_ms: 85
messages:
- "1 plan listed"
```
agents plan use
agents plan use [--automation-profile <PROFILE>]
[--invariant <INVARIANT>]...
[--strategy-actor <STRATEGY_ACTOR>]
[--execution-actor <EXEC_ACTOR>]
[--estimation-actor <EST_ACTOR>]
[--invariant-actor <INV_ACTOR>]
[--execution-environment <RESOURCE_NAME>]
[--execution-env-priority (fallback|override)]
[--arg/-a name=value]...
<ACTION> <PROJECT>...Purpose Apply an action to one or more projects and start the Strategize phase.
Arguments
<ACTION_NAME>: Action name.<PROJECT>: One or more project names (positional arguments, repeatable).--arg/-a name=value: Action argument (repeatable).--automation-profile PROFILE: Automation profile name (e.g.,trusted,auto,local/careful-auto). Overrides the profile inherited from the action, project, or global config.--strategy-actor ACTOR: Override the action's strategy actor for this plan.--execution-actor ACTOR: Override the action's execution actor for this plan.--estimation-actor ACTOR: Override the action's estimation actor for this plan.--invariant-actor ACTOR: Override the action's Invariant Reconciliation Actor for this plan.--invariant TEXT: Invariant to attach to the created plan (repeatable). These are added as plan-level invariants in addition to any invariants inherited from the action, project, or global scope.--execution-environment RESOURCE_NAME: Name of acontainer-instanceordevcontainer-instanceresource to use as the execution environment for this plan. Overrides or supplements the project-levelexecution_environmentsetting depending on--execution-env-priority. See ADR-043 §3.3.--execution-env-priority fallback|override: Priority semantics for the plan-level execution environment.fallback(default): defers to auto-detected devcontainers or project-level overrides.override: always uses the specified environment, bypassing all other resolution. See §Execution Environment Routing.
All actor arguments (--strategy-actor, --execution-actor, --estimation-actor, --invariant-actor) are optional overrides. When provided, they replace whatever was set when creating the action. When omitted, the action's configured actors are used.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan use local/code-coverage local/api-service \
<span style="color: cyan;">--arg</span> target_coverage_percent=85 <span style="color: cyan;">--automation-profile</span> trusted
╭─ Plan Created ──────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Plan ID:</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
│ <span style="color: yellow; font-weight: 600;">Phase:</span> strategize │
│ <span style="color: magenta; font-weight: 600;">Action:</span> local/code-coverage │
│ <span style="color: #5599ff; font-weight: 600;">Project:</span> local/api-service │
│ <span style="color: #66cc66; font-weight: 600;">Automation:</span> trusted │
│ <span style="color: #5599ff; font-weight: 600;">Attempt:</span> 1 │
╰─────────────────────────────────────╯
╭─ Inputs ──────────────────────╮
│ - target_coverage_percent=85 │
│ - automation_profile=trusted │
╰───────────────────────────────╯
╭─ Actors ────────────────────────╮
│ <span style="color: magenta; font-weight: 600;">Strategy:</span> local/strategist │
│ <span style="color: magenta; font-weight: 600;">Execution:</span> local/executor │
│ <span style="color: #5599ff; font-weight: 600;">Estimation:</span> (none) │
╰─────────────────────────────────╯
╭─ Automation ─────────────────────────╮
│ <span style="color: magenta; font-weight: 600;">Profile:</span> trusted │
│ <span style="color: #5599ff; font-weight: 600;">Source:</span> CLI flag │
│ <span style="color: #5599ff; font-weight: 600;">Read-Only:</span> no │
╰──────────────────────────────────────╯
╭─ Context ───────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Resources:</span> 2 (repo, db) │
│ <span style="color: #5599ff; font-weight: 600;">Indexed Files:</span> 347 │
│ <span style="color: #5599ff; font-weight: 600;">View:</span> strategize │
│ <span style="color: #5599ff; font-weight: 600;">Hot Token Budget:</span> 12,000 │
╰─────────────────────────────────╯
╭─ Next Steps ─────────────────────────────────────╮
│ - agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
│ - agents plan status 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
│ - agents plan tree 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
╰──────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Plan created
</code></pre></div>
=== "Plain"
```
$ agents plan use local/code-coverage local/api-service \
--arg target_coverage_percent=85 --automation-profile trusted
Plan Created
Plan ID: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
Phase: strategize
Action: local/code-coverage
Project: local/api-service
Automation: trusted
Attempt: 1
Inputs
- target_coverage_percent=85
- automation_profile=trusted
Actors
Strategy: local/strategist
Execution: local/executor
Estimation: (none)
Automation
Profile: trusted
Source: CLI flag
Read-Only: no
Context
Resources: 2 (repo, db)
Indexed Files: 347
View: strategize
Hot Token Budget: 12,000
Next Steps
- agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J
- agents plan status 01HXM8C2ZK4Q7C2B3F2R4VYV6J
- agents plan tree 01HXM8C2ZK4Q7C2B3F2R4VYV6J
[OK] Plan created
```
=== "JSON"
```json
{
"command": "plan use",
"status": "ok",
"exit_code": 0,
"data": {
"plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
"phase": "strategize",
"action": "local/code-coverage",
"project": "local/api-service",
"automation_profile": "trusted",
"attempt": 1,
"inputs": {
"target_coverage_percent": 85,
"automation_profile": "trusted"
},
"actors": {
"strategy": "local/strategist",
"execution": "local/executor",
"estimation": null
},
"automation": {
"profile": "trusted",
"source": "CLI flag",
"read_only": false
},
"context": {
"resources": 2,
"indexed_files": 347,
"view": "strategize",
"hot_token_budget": 12000
},
"next_steps": [
"agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J",
"agents plan status 01HXM8C2ZK4Q7C2B3F2R4VYV6J",
"agents plan tree 01HXM8C2ZK4Q7C2B3F2R4VYV6J"
]
},
"timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 95 },
"messages": ["Plan created"]
}
```
=== "YAML"
```yaml
command: plan use
status: ok
exit_code: 0
data:
plan_id: "01HXM8C2ZK4Q7C2B3F2R4VYV6J"
phase: strategize
action: "local/code-coverage"
project: "local/api-service"
automation_profile: trusted
attempt: 1
inputs:
target_coverage_percent: 85
automation_profile: trusted
actors:
strategy: "local/strategist"
execution: "local/executor"
estimation: null
automation:
profile: trusted
source: "CLI flag"
read_only: false
context:
resources: 2
indexed_files: 347
view: strategize
hot_token_budget: 12000
next_steps:
- "agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J"
- "agents plan status 01HXM8C2ZK4Q7C2B3F2R4VYV6J"
- "agents plan tree 01HXM8C2ZK4Q7C2B3F2R4VYV6J"
timing:
started: "2026-02-09T14:30:00Z"
duration_ms: 95
messages:
- "Plan created"
```
Applying an action to multiple projects simultaneously, with plan-level invariants:
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan use local/security-audit local/api-service local/web-app \
<span style="color: cyan;">--invariant</span> <span style="color: #66cc66;">"Never modify production database schemas"</span> \
<span style="color: cyan;">--invariant</span> <span style="color: #66cc66;">"All changes must include test coverage"</span> \
<span style="color: cyan;">--automation-profile</span> supervised
╭─ Plan Created ──────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Plan:</span> 01HXM9D2ZK4Q7C2B3F2R4VYV6J │
│ <span style="color: #5599ff; font-weight: 600;">Action:</span> local/security-audit │
│ <span style="color: yellow;">Phase:</span> strategize (running) │
│ <span style="color: magenta; font-weight: 600;">Automation:</span> supervised │
╰─────────────────────────────────────────────────────╯
╭─ Target Projects ───────────────────╮
│ <span style="color: #66cc66; font-weight: 600;">1.</span> local/api-service (3 resources) │
│ <span style="color: #66cc66; font-weight: 600;">2.</span> local/web-app (2 resources) │
╰─────────────────────────────────────╯
╭─ Plan Invariants ──────────────────────────────────────────╮
│ <span style="color: magenta; font-weight: 600;">Scope</span> <span style="color: magenta; font-weight: 600;">Source</span> <span style="color: magenta; font-weight: 600;">Invariant</span> │
│ <span style="opacity: 0.7;">──────── ─────── ──────────────────────────────────</span> │
│ plan CLI Never modify production DB schemas │
│ plan CLI All changes must include test coverage │
│ project config API responses must be backward-compat │
│ global config Follow Python PEP 8 style guide │
╰────────────────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Plan created — strategize in progress
</code></pre></div>
=== "Plain"
```
$ agents plan use local/security-audit local/api-service local/web-app \
--invariant "Never modify production database schemas" \
--invariant "All changes must include test coverage" \
--automation-profile supervised
Plan Created
Plan: 01HXM9D2ZK4Q7C2B3F2R4VYV6J
Action: local/security-audit
Phase: strategize (running)
Automation: supervised
Target Projects
1. local/api-service (3 resources)
2. local/web-app (2 resources)
Plan Invariants
Scope Source Invariant
-------- ------- ----------------------------------
plan CLI Never modify production DB schemas
plan CLI All changes must include test coverage
project config API responses must be backward-compat
global config Follow Python PEP 8 style guide
[OK] Plan created -- strategize in progress
```
=== "JSON"
```json
{
"command": "plan use",
"status": "ok",
"exit_code": 0,
"data": {
"plan_id": "01HXM9D2ZK4Q7C2B3F2R4VYV6J",
"action": "local/security-audit",
"phase": "strategize",
"phase_state": "running",
"automation_profile": "supervised",
"target_projects": [
{ "name": "local/api-service", "resources": 3 },
{ "name": "local/web-app", "resources": 2 }
],
"invariants": [
{ "scope": "plan", "source": "CLI", "text": "Never modify production DB schemas" },
{ "scope": "plan", "source": "CLI", "text": "All changes must include test coverage" },
{ "scope": "project", "source": "config", "text": "API responses must be backward-compat" },
{ "scope": "global", "source": "config", "text": "Follow Python PEP 8 style guide" }
]
},
"timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 130 },
"messages": ["Plan created -- strategize in progress"]
}
```
=== "YAML"
```yaml
command: plan use
status: ok
exit_code: 0
data:
plan_id: "01HXM9D2ZK4Q7C2B3F2R4VYV6J"
action: "local/security-audit"
phase: strategize
phase_state: running
automation_profile: supervised
target_projects:
- name: "local/api-service"
resources: 3
- name: "local/web-app"
resources: 2
invariants:
- scope: plan
source: CLI
text: "Never modify production DB schemas"
- scope: plan
source: CLI
text: "All changes must include test coverage"
- scope: project
source: config
text: "API responses must be backward-compat"
- scope: global
source: config
text: "Follow Python PEP 8 style guide"
timing:
started: "2026-02-09T14:30:00Z"
duration_ms: 130
messages:
- "Plan created -- strategize in progress"
```
Using an action with custom actor overrides:
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan use local/code-coverage local/api-service \
<span style="color: cyan;">--strategy-actor</span> local/senior-planner \
<span style="color: cyan;">--execution-actor</span> local/fast-executor \
<span style="color: cyan;">--arg</span> target_coverage_percent=95
╭─ Plan Created ──────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Plan:</span> 01HXM9E3ZK4Q7C2B3F2R4VYV6J │
│ <span style="color: #5599ff; font-weight: 600;">Action:</span> local/code-coverage │
│ <span style="color: yellow;">Phase:</span> strategize (running) │
│ <span style="color: magenta; font-weight: 600;">Automation:</span> trusted │
╰─────────────────────────────────────────────────────╯
╭─ Actor Overrides ────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Strategy:</span> local/senior-planner │
│ <span style="color: #5599ff; font-weight: 600;">Execution:</span> local/fast-executor │
│ <span style="opacity: 0.7;">(Estimation: action default)</span> │
╰──────────────────────────────────────╯
╭─ Arguments ─────────────────╮
│ <span style="color: cyan; font-weight: 600;">target_coverage_percent:</span> 95 │
╰─────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Plan created — strategize in progress
</code></pre></div>
=== "Plain"
```
$ agents plan use local/code-coverage local/api-service \
--strategy-actor local/senior-planner \
--execution-actor local/fast-executor \
--arg target_coverage_percent=95
Plan Created
Plan: 01HXM9E3ZK4Q7C2B3F2R4VYV6J
Action: local/code-coverage
Phase: strategize (running)
Automation: trusted
Actor Overrides
Strategy: local/senior-planner
Execution: local/fast-executor
(Estimation: action default)
Arguments
target_coverage_percent: 95
[OK] Plan created -- strategize in progress
```
=== "JSON"
```json
{
"command": "plan use",
"status": "ok",
"exit_code": 0,
"data": {
"plan_id": "01HXM9E3ZK4Q7C2B3F2R4VYV6J",
"action": "local/code-coverage",
"phase": "strategize",
"phase_state": "running",
"automation_profile": "trusted",
"actor_overrides": {
"strategy": "local/senior-planner",
"execution": "local/fast-executor",
"estimation": null
},
"arguments": {
"target_coverage_percent": 95
}
},
"timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 110 },
"messages": ["Plan created -- strategize in progress"]
}
```
=== "YAML"
```yaml
command: plan use
status: ok
exit_code: 0
data:
plan_id: "01HXM9E3ZK4Q7C2B3F2R4VYV6J"
action: "local/code-coverage"
phase: strategize
phase_state: running
automation_profile: trusted
actor_overrides:
strategy: "local/senior-planner"
execution: "local/fast-executor"
estimation: null
arguments:
target_coverage_percent: 95
timing:
started: "2026-02-09T14:30:00Z"
duration_ms: 110
messages:
- "Plan created -- strategize in progress"
```
agents plan execute
agents plan execute <PLAN_ID>Purpose Start or resume execution for a plan.
Arguments
<PLAN_ID>: Plan ID (required).
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J
╭─ Execution ──────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Plan:</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
│ <span style="color: yellow; font-weight: 600;">Phase:</span> execute │
│ <span style="color: magenta; font-weight: 600;">Sandbox:</span> git_worktree │
│ <span style="color: #5599ff; font-weight: 600;">Worker:</span> local/executor │
│ <span style="color: #66cc66; font-weight: 600;">Started:</span> 12:58:10 │
│ <span style="color: #5599ff; font-weight: 600;">Attempt:</span> 1 │
╰──────────────────────────────────╯
╭─ Sandbox ──────────────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Strategy:</span> git_worktree │
│ <span style="color: #5599ff; font-weight: 600;">Path:</span> /repos/api/.worktrees/plan-01HXM8 │
│ <span style="color: #5599ff; font-weight: 600;">Branch:</span> cleveragents/plan-01HXM8C2 │
│ <span style="color: #66cc66; font-weight: 600;">Status:</span> active │
╰────────────────────────────────────────────╯
╭─ Strategy Summary ─────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Decisions:</span> 8 │
│ <span style="color: magenta; font-weight: 600;">Invariants:</span> 2 │
│ <span style="color: #5599ff; font-weight: 600;">Planned Child Plans:</span> 2+ │
│ <span style="color: #5599ff; font-weight: 600;">Estimated Files:</span> ~12 │
│ <span style="color: #5599ff; font-weight: 600;">Risk:</span> low │
╰────────────────────────────────────────╯
╭─ Progress ─────────╮
│ <span style="color: cyan; font-weight: 600;">⏳</span> Collect context │
│ <span style="color: yellow; font-weight: 600;">•</span> Run tools │
│ <span style="color: yellow; font-weight: 600;">•</span> Build changeset │
│ <span style="color: yellow; font-weight: 600;">•</span> Validate │
╰────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Execution started
</code></pre></div>
=== "Plain"
```
$ agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J
Execution
Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
Phase: execute
Sandbox: git_worktree
Worker: local/executor
Started: 12:58:10
Attempt: 1
Sandbox
Strategy: git_worktree
Path: /repos/api/.worktrees/plan-01HXM8
Branch: cleveragents/plan-01HXM8C2
Status: active
Strategy Summary
Decisions: 8
Invariants: 2
Planned Child Plans: 2+
Estimated Files: ~12
Risk: low
Progress
... Collect context
. Run tools
. Build changeset
. Validate
[OK] Execution started
```
=== "JSON"
```json
{
"command": "plan execute",
"status": "ok",
"exit_code": 0,
"data": {
"plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
"phase": "execute",
"sandbox": {
"strategy": "git_worktree",
"path": "/repos/api/.worktrees/plan-01HXM8",
"branch": "cleveragents/plan-01HXM8C2",
"status": "active"
},
"worker": "local/executor",
"started": "12:58:10",
"attempt": 1,
"strategy_summary": {
"decisions": 8,
"invariants": 2,
"planned_child_plans": "2+",
"estimated_files": 12,
"risk": "low"
},
"progress": [
{ "label": "Collect context", "status": "running" },
{ "label": "Run tools", "status": "pending" },
{ "label": "Build changeset", "status": "pending" },
{ "label": "Validate", "status": "pending" }
]
},
"timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 150 },
"messages": ["Execution started"]
}
```
=== "YAML"
```yaml
command: plan execute
status: ok
exit_code: 0
data:
plan_id: "01HXM8C2ZK4Q7C2B3F2R4VYV6J"
phase: execute
sandbox:
strategy: git_worktree
path: "/repos/api/.worktrees/plan-01HXM8"
branch: "cleveragents/plan-01HXM8C2"
status: active
worker: "local/executor"
started: "12:58:10"
attempt: 1
strategy_summary:
decisions: 8
invariants: 2
planned_child_plans: "2+"
estimated_files: 12
risk: low
progress:
- label: "Collect context"
status: running
- label: "Run tools"
status: pending
- label: "Build changeset"
status: pending
- label: "Validate"
status: pending
timing:
started: "2026-02-09T14:30:00Z"
duration_ms: 150
messages:
- "Execution started"
```
Resuming execution of a plan that was previously paused or errored:
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan execute 01HXM7K2ZK4Q7C2B3F2R4VYV6J
╭─ Execution Resumed ─────────────────╮
│ <span style="color: cyan; font-weight: 600;">Plan:</span> 01HXM7K2ZK4Q7C2B3F2R4VYV6J │
│ <span style="color: yellow; font-weight: 600;">Phase:</span> execute (resumed) │
│ <span style="color: magenta; font-weight: 600;">Sandbox:</span> git_worktree │
│ <span style="color: #5599ff; font-weight: 600;">Worker:</span> local/executor │
│ <span style="color: #5599ff; font-weight: 600;">Checkpoint:</span> cp_01HXM8C2 (loaded) │
│ <span style="color: #5599ff; font-weight: 600;">Resumed From:</span> step 4 of 6 │
╰─────────────────────────────────────╯
╭─ Previous Progress ──────────────────────╮
│ <span style="color: #66cc66; font-weight: 600;">✓</span> Step 1: Collect context (0.8s) │
│ <span style="color: #66cc66; font-weight: 600;">✓</span> Step 2: Analyze codebase (4.2s) │
│ <span style="color: #66cc66; font-weight: 600;">✓</span> Step 3: Generate migrations (6.1s) │
│ <span style="color: #ff6666; font-weight: 600;">✗</span> Step 4: Apply migrations (errored) │
│ <span style="opacity: 0.5;">○</span> Step 5: Update models (pending) │
│ <span style="opacity: 0.5;">○</span> Step 6: Run validations (pending) │
╰──────────────────────────────────────────╯
╭─ Guidance Applied ──────────────────────────────────────────────╮
│ <span style="opacity: 0.7;"><span style="color: #66cc66;">"Use smaller batch sizes for the migration to avoid timeouts"</span></span> │
╰─────────────────────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Execution resumed from checkpoint cp_01HXM8C2
</code></pre></div>
=== "Plain"
```
$ agents plan execute 01HXM7K2ZK4Q7C2B3F2R4VYV6J
Execution Resumed
Plan: 01HXM7K2ZK4Q7C2B3F2R4VYV6J
Phase: execute (resumed)
Sandbox: git_worktree
Worker: local/executor
Checkpoint: cp_01HXM8C2 (loaded)
Resumed From: step 4 of 6
Previous Progress
v Step 1: Collect context (0.8s)
v Step 2: Analyze codebase (4.2s)
v Step 3: Generate migrations (6.1s)
x Step 4: Apply migrations (errored)
o Step 5: Update models (pending)
o Step 6: Run validations (pending)
Guidance Applied
"Use smaller batch sizes for the migration to avoid timeouts"
[OK] Execution resumed from checkpoint cp_01HXM8C2
```
=== "JSON"
```json
{
"command": "plan execute",
"status": "ok",
"exit_code": 0,
"data": {
"plan_id": "01HXM7K2ZK4Q7C2B3F2R4VYV6J",
"phase": "execute",
"resumed": true,
"sandbox": "git_worktree",
"worker": "local/executor",
"checkpoint": "cp_01HXM8C2",
"resumed_from": "step 4 of 6",
"progress": [
{ "step": 1, "label": "Collect context", "status": "done", "duration_s": 0.8 },
{ "step": 2, "label": "Analyze codebase", "status": "done", "duration_s": 4.2 },
{ "step": 3, "label": "Generate migrations", "status": "done", "duration_s": 6.1 },
{ "step": 4, "label": "Apply migrations", "status": "errored" },
{ "step": 5, "label": "Update models", "status": "pending" },
{ "step": 6, "label": "Run validations", "status": "pending" }
],
"guidance": "Use smaller batch sizes for the migration to avoid timeouts"
},
"timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 180 },
"messages": ["Execution resumed from checkpoint cp_01HXM8C2"]
}
```
=== "YAML"
```yaml
command: plan execute
status: ok
exit_code: 0
data:
plan_id: "01HXM7K2ZK4Q7C2B3F2R4VYV6J"
phase: execute
resumed: true
sandbox: git_worktree
worker: "local/executor"
checkpoint: "cp_01HXM8C2"
resumed_from: "step 4 of 6"
progress:
- step: 1
label: "Collect context"
status: done
duration_s: 0.8
- step: 2
label: "Analyze codebase"
status: done
duration_s: 4.2
- step: 3
label: "Generate migrations"
status: done
duration_s: 6.1
- step: 4
label: "Apply migrations"
status: errored
- step: 5
label: "Update models"
status: pending
- step: 6
label: "Run validations"
status: pending
guidance: "Use smaller batch sizes for the migration to avoid timeouts"
timing:
started: "2026-02-09T14:30:00Z"
duration_ms: 180
messages:
- "Execution resumed from checkpoint cp_01HXM8C2"
```
agents plan apply
agents plan apply [--yes|-y] <PLAN_ID>Purpose Apply sandboxed changes to real resources.
Arguments
<PLAN_ID>: Plan ID.--yes: Skip confirmation.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan apply 01HXM8C2ZK4Q7C2B3F2R4VYV6J
Apply changes for plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J? [y/N]: y
╭─ Apply Summary ─────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Plan:</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
│ <span style="color: #5599ff; font-weight: 600;">Artifacts:</span> 6 files updated │
│ <span style="color: yellow; font-weight: 600;">Changes:</span> 42 insertions, 9 deletions │
│ <span style="color: #5599ff; font-weight: 600;">Project:</span> local/api-service │
│ <span style="color: #66cc66; font-weight: 600;">Applied At:</span> 2026-02-08 13:04 │
╰─────────────────────────────────────╯
╭─ Validation (from Execute) ────╮
│ <span style="color: #66cc66; font-weight: 600;">Tests:</span> passed (24/24) │
│ <span style="color: #66cc66; font-weight: 600;">Lint:</span> passed (0 warnings) │
│ <span style="color: #66cc66; font-weight: 600;">Type Check:</span> passed (0 errors) │
│ <span style="color: #66cc66; font-weight: 600;">Duration:</span> 12.4s │
╰────────────────────────────────╯
╭─ Sandbox Cleanup ─────────╮
│ <span style="color: #66cc66; font-weight: 600;">Worktree:</span> removed │
│ <span style="color: #66cc66; font-weight: 600;">Branch:</span> merged to main │
│ <span style="color: #5599ff; font-weight: 600;">Checkpoint:</span> archived │
╰───────────────────────────╯
╭─ Plan Lifecycle ────────────────────────╮
│ <span style="color: #66cc66; font-weight: 600;">Phase:</span> apply │
│ <span style="color: #66cc66; font-weight: 600;">State:</span> applied │
│ <span style="color: #5599ff; font-weight: 600;">Total Duration:</span> 00:06:14 │
│ <span style="color: yellow; font-weight: 600;">Total Cost:</span> $0.0847 │
│ <span style="color: #5599ff; font-weight: 600;">Decisions Made:</span> 8 │
│ <span style="color: #5599ff; font-weight: 600;">Child Plans:</span> 2 (completed) │
╰─────────────────────────────────────────╯
╭─ Next Steps ──────╮
│ - Review git diff │
│ - Commit changes │
╰───────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Changes applied
</code></pre></div>
=== "Plain"
```
$ agents plan apply 01HXM8C2ZK4Q7C2B3F2R4VYV6J
Apply changes for plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J? [y/N]: y
Apply Summary
Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
Artifacts: 6 files updated
Changes: 42 insertions, 9 deletions
Project: local/api-service
Applied At: 2026-02-08 13:04
Validation (from Execute)
Tests: passed (24/24)
Lint: passed (0 warnings)
Type Check: passed (0 errors)
Duration: 12.4s
Sandbox Cleanup
Worktree: removed
Branch: merged to main
Checkpoint: archived
Plan Lifecycle
Phase: apply
State: applied
Total Duration: 00:06:14
Total Cost: $0.0847
Decisions Made: 8
Child Plans: 2 (completed)
Next Steps
- Review git diff
- Commit changes
[OK] Changes applied
```
=== "JSON"
```json
{
"command": "plan apply",
"status": "ok",
"exit_code": 0,
"data": {
"plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
"artifacts": 6,
"changes": {
"insertions": 42,
"deletions": 9
},
"project": "local/api-service",
"applied_at": "2026-02-08T13:04:00Z",
"validation": {
"tests": { "status": "passed", "passed": 24, "total": 24 },
"lint": { "status": "passed", "warnings": 0 },
"type_check": { "status": "passed", "errors": 0 },
"duration_s": 12.4
},
"sandbox_cleanup": {
"worktree": "removed",
"branch": "merged to main",
"checkpoint": "archived"
},
"lifecycle": {
"phase": "apply",
"state": "applied",
"total_duration": "00:06:14",
"total_cost": "$0.0847",
"decisions_made": 8,
"child_plans": 2
}
},
"timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 1250 },
"messages": ["Changes applied"]
}
```
=== "YAML"
```yaml
command: plan apply
status: ok
exit_code: 0
data:
plan_id: "01HXM8C2ZK4Q7C2B3F2R4VYV6J"
artifacts: 6
changes:
insertions: 42
deletions: 9
project: "local/api-service"
applied_at: "2026-02-08T13:04:00Z"
validation:
tests:
status: passed
passed: 24
total: 24
lint:
status: passed
warnings: 0
type_check:
status: passed
errors: 0
duration_s: 12.4
sandbox_cleanup:
worktree: removed
branch: merged to main
checkpoint: archived
lifecycle:
phase: apply
state: applied
total_duration: "00:06:14"
total_cost: "$0.0847"
decisions_made: 8
child_plans: 2
timing:
started: "2026-02-09T14:30:00Z"
duration_ms: 1250
messages:
- "Changes applied"
```
When Execute-phase validations failed and were not resolved (e.g., the execution actor exhausted its retry limit or failed outright), the plan cannot be applied. Apply checks the validation record and refuses to proceed:
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan apply <span style="color: cyan;">--yes</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J
╭─ Apply Summary ─────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Plan:</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
│ <span style="color: #5599ff; font-weight: 600;">Artifacts:</span> 6 files updated │
│ <span style="color: yellow;">Changes:</span> 42 insertions, 9 deletions │
│ <span style="color: #5599ff; font-weight: 600;">Project:</span> local/api-service │
╰─────────────────────────────────────╯
╭─ Validation ───────────────────────────────────────────────╮
│ <span style="color: #ff6666; font-weight: 600;">✗</span> Tests: <span style="color: #ff6666; font-weight: 600;">FAILED</span> (22/24 passed, 2 failed) │
│ <span style="opacity: 0.7;">FAIL test_auth.py::test_session_refresh — AssertionError</span> │
│ <span style="opacity: 0.7;">FAIL test_auth.py::test_token_expiry — TimeoutError</span> │
│ <span style="color: #66cc66; font-weight: 600;">✓</span> Lint: passed (0 warnings) │
│ <span style="color: #66cc66; font-weight: 600;">✓</span> Type Check: passed (0 errors) │
│ <span style="color: #5599ff; font-weight: 600;">Duration:</span> 14.8s │
╰────────────────────────────────────────────────────────────╯
╭─ Sandbox Status ─────────────────────────────────────────────╮
│ <span style="color: yellow; font-weight: 600;">Worktree:</span> preserved (changes NOT committed) │
│ <span style="color: #5599ff; font-weight: 600;">Checkpoint:</span> cp_01HXM8C2 (pre-apply state available) │
│ <span style="opacity: 0.7;">The sandbox is preserved for correction or manual review.</span> │
╰──────────────────────────────────────────────────────────────╯
╭─ Recovery Options ──────────────────────────────────────────────────╮
│ - <span style="color: cyan;">agents plan prompt</span> <span style="opacity: 0.7;">— provide guidance to fix test failures</span> │
│ - <span style="color: cyan;">agents plan correct</span> <span style="opacity: 0.7;">— revert and re-execute with guidance</span> │
│ - <span style="color: cyan;">agents plan rollback</span> <span style="opacity: 0.7;">— restore to a previous checkpoint</span> │
│ - <span style="color: cyan;">agents plan cancel</span> <span style="opacity: 0.7;">— abort the plan entirely</span> │
╰─────────────────────────────────────────────────────────────────────╯
<span style="color: #ff6666; font-weight: 600;">✗ ERROR</span> Apply refused — 2 required Execute-phase validations did not pass
</code></pre></div>
=== "Plain"
```
$ agents plan apply --yes 01HXM8C2ZK4Q7C2B3F2R4VYV6J
Apply Summary
Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
Artifacts: 6 files updated
Changes: 42 insertions, 9 deletions
Project: local/api-service
Validation
x Tests: FAILED (22/24 passed, 2 failed)
FAIL test_auth.py::test_session_refresh -- AssertionError
FAIL test_auth.py::test_token_expiry -- TimeoutError
v Lint: passed (0 warnings)
v Type Check: passed (0 errors)
Duration: 14.8s
Sandbox Status
Worktree: preserved (changes NOT committed)
Checkpoint: cp_01HXM8C2 (pre-apply state available)
The sandbox is preserved for correction or manual review.
Recovery Options
- agents plan prompt -- provide guidance to fix test failures
- agents plan correct -- revert and re-execute with guidance
- agents plan rollback -- restore to a previous checkpoint
- agents plan cancel -- abort the plan entirely
[ERROR] Apply refused -- 2 required Execute-phase validations did not pass
```
=== "JSON"
```json
{
"command": "plan apply",
"status": "error",
"exit_code": 1,
"data": {
"plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
"artifacts": 6,
"changes": {
"insertions": 42,
"deletions": 9
},
"project": "local/api-service",
"validation": {
"tests": {
"status": "failed",
"passed": 22,
"total": 24,
"failures": [
"test_auth.py::test_session_refresh -- AssertionError",
"test_auth.py::test_token_expiry -- TimeoutError"
]
},
"lint": { "status": "passed", "warnings": 0 },
"type_check": { "status": "passed", "errors": 0 },
"duration_s": 14.8
},
"sandbox": {
"worktree": "preserved",
"checkpoint": "cp_01HXM8C2"
},
"recovery_options": [
"agents plan prompt",
"agents plan correct",
"agents plan rollback",
"agents plan cancel"
]
},
"timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 320 },
"messages": ["Apply refused -- 2 required Execute-phase validations did not pass"]
}
```
=== "YAML"
```yaml
command: plan apply
status: error
exit_code: 1
data:
plan_id: "01HXM8C2ZK4Q7C2B3F2R4VYV6J"
artifacts: 6
changes:
insertions: 42
deletions: 9
project: "local/api-service"
validation:
tests:
status: failed
passed: 22
total: 24
failures:
- "test_auth.py::test_session_refresh -- AssertionError"
- "test_auth.py::test_token_expiry -- TimeoutError"
lint:
status: passed
warnings: 0
type_check:
status: passed
errors: 0
duration_s: 14.8
sandbox:
worktree: preserved
checkpoint: "cp_01HXM8C2"
recovery_options:
- "agents plan prompt"
- "agents plan correct"
- "agents plan rollback"
- "agents plan cancel"
timing:
started: "2026-02-09T14:30:00Z"
duration_ms: 320
messages:
- "Apply refused -- 2 required Execute-phase validations did not pass"
```
agents plan status
agents plan status <PLAN_ID>Purpose Show detailed status for a plan.
Arguments
<PLAN_ID>: Plan ID (required).
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan status 01HXM8C2ZK4Q7C2B3F2R4VYV6J
╭─ Plan Status ────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Plan:</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
│ <span style="color: yellow; font-weight: 600;">Phase:</span> execute │
│ <span style="color: magenta; font-weight: 600;">State:</span> processing │
│ <span style="color: #5599ff; font-weight: 600;">Action:</span> local/code-coverage │
│ <span style="color: #66cc66; font-weight: 600;">Project:</span> local/api-service │
│ <span style="color: #5599ff; font-weight: 600;">Automation:</span> review │
│ <span style="color: #5599ff; font-weight: 600;">Attempt:</span> 1 │
╰──────────────────────────────────╯
╭─ Progress ───────╮
│ <span style="color: #66cc66; font-weight: 600;">✓</span> Strategize │
│ <span style="color: cyan; font-weight: 600;">⏳</span> Execute │
│ <span style="color: yellow; font-weight: 600;">•</span> Apply (queued) │
╰──────────────────╯
╭─ Timing ──────────╮
│ <span style="color: #66cc66; font-weight: 600;">Started:</span> 12:57:01 │
│ <span style="color: yellow; font-weight: 600;">Elapsed:</span> 00:01:12 │
│ <span style="color: #66cc66; font-weight: 600;">ETA:</span> 00:03:45 │
╰───────────────────╯
╭─ Execution Detail ──────────╮
│ <span style="color: #5599ff; font-weight: 600;">Sandbox:</span> git_worktree │
│ <span style="color: #5599ff; font-weight: 600;">Tool Calls:</span> 8 │
│ <span style="color: #5599ff; font-weight: 600;">Files Modified:</span> 3 │
│ <span style="color: #5599ff; font-weight: 600;">Child Plans:</span> 1/2 complete │
│ <span style="color: #5599ff; font-weight: 600;">Checkpoints:</span> 2 created │
╰─────────────────────────────╯
╭─ Cost ───────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Tokens Used:</span> 12,420 │
│ <span style="color: yellow; font-weight: 600;">Cost So Far:</span> $0.041 │
│ <span style="color: #5599ff; font-weight: 600;">Estimated:</span> $0.085 │
╰──────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Status refreshed
</code></pre></div>
=== "Plain"
```
$ agents plan status 01HXM8C2ZK4Q7C2B3F2R4VYV6J
Plan Status
Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
Phase: execute
State: processing
Action: local/code-coverage
Project: local/api-service
Automation: review
Attempt: 1
Progress
[OK] Strategize
... Execute
. Apply (queued)
Timing
Started: 12:57:01
Elapsed: 00:01:12
ETA: 00:03:45
Execution Detail
Sandbox: git_worktree
Tool Calls: 8
Files Modified: 3
Child Plans: 1/2 complete
Checkpoints: 2 created
Cost
Tokens Used: 12,420
Cost So Far: $0.041
Estimated: $0.085
[OK] Status refreshed
```
=== "JSON"
```json
{
"command": "plan status",
"status": "ok",
"exit_code": 0,
"data": {
"plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
"phase": "execute",
"state": "processing",
"action": "local/code-coverage",
"project": "local/api-service",
"automation": "review",
"attempt": 1,
"progress": [
{ "step": "Strategize", "status": "done" },
{ "step": "Execute", "status": "running" },
{ "step": "Apply", "status": "queued" }
],
"timing": {
"started": "12:57:01",
"elapsed": "00:01:12",
"eta": "00:03:45"
},
"execution": {
"sandbox": "git_worktree",
"tool_calls": 8,
"files_modified": 3,
"child_plans": "1/2 complete",
"checkpoints": 2
},
"cost": {
"tokens_used": 12420,
"cost_so_far": 0.041,
"estimated": 0.085
}
},
"timing": {
"started": "2026-02-08T12:57:01Z",
"duration_ms": 120
},
"messages": ["Status refreshed"]
}
```
=== "YAML"
```yaml
command: plan status
status: ok
exit_code: 0
data:
plan_id: "01HXM8C2ZK4Q7C2B3F2R4VYV6J"
phase: execute
state: processing
action: local/code-coverage
project: local/api-service
automation: review
attempt: 1
progress:
- step: Strategize
status: done
- step: Execute
status: running
- step: Apply
status: queued
timing:
started: "12:57:01"
elapsed: "00:01:12"
eta: "00:03:45"
execution:
sandbox: git_worktree
tool_calls: 8
files_modified: 3
child_plans: "1/2 complete"
checkpoints: 2
cost:
tokens_used: 12420
cost_so_far: 0.041
estimated: 0.085
timing:
started: "2026-02-08T12:57:01Z"
duration_ms: 120
messages:
- "Status refreshed"
```
Status of a plan that has completed successfully:
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan status 01HXM6R3ZK4Q7C2B3F2R4VYV6J
╭─ Plan Status ─────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Plan:</span> 01HXM6R3ZK4Q7C2B3F2R4VYV6J │
│ <span style="color: #66cc66; font-weight: 600;">Phase:</span> apply │
│ <span style="color: #66cc66; font-weight: 600;">State:</span> applied │
│ <span style="color: #5599ff; font-weight: 600;">Action:</span> local/add-auth │
│ <span style="color: #66cc66; font-weight: 600;">Project:</span> local/api-service │
│ <span style="color: #5599ff; font-weight: 600;">Automation:</span> trusted │
│ <span style="color: #5599ff; font-weight: 600;">Attempt:</span> 1 │
╰───────────────────────────────────╯
╭─ Progress ───────────╮
│ <span style="color: #66cc66; font-weight: 600;">✓</span> Strategize │
│ <span style="color: #66cc66; font-weight: 600;">✓</span> Execute │
│ <span style="color: #66cc66; font-weight: 600;">✓</span> Apply (committed) │
╰──────────────────────╯
╭─ Timing ─────────────────────────╮
│ <span style="color: #66cc66; font-weight: 600;">Started:</span> 2026-02-08 12:57:01 │
│ <span style="color: #66cc66; font-weight: 600;">Finished:</span> 2026-02-08 13:04:15 │
│ <span style="color: #5599ff; font-weight: 600;">Total Duration:</span> 00:07:14 │
╰──────────────────────────────────╯
╭─ Result ────────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Decisions Made:</span> 8 │
│ <span style="color: #5599ff; font-weight: 600;">Child Plans:</span> 2/2 complete │
│ <span style="color: #66cc66; font-weight: 600;">Artifacts:</span> 6 files updated │
│ <span style="color: #66cc66; font-weight: 600;">Validations:</span> 3/3 passed │
│ <span style="color: yellow;">Total Cost:</span> $0.085 │
╰─────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Plan completed successfully
</code></pre></div>
=== "Plain"
```
$ agents plan status 01HXM6R3ZK4Q7C2B3F2R4VYV6J
Plan Status
Plan: 01HXM6R3ZK4Q7C2B3F2R4VYV6J
Phase: apply
State: applied
Action: local/add-auth
Project: local/api-service
Automation: trusted
Attempt: 1
Progress
[OK] Strategize
[OK] Execute
[OK] Apply (committed)
Timing
Started: 2026-02-08 12:57:01
Finished: 2026-02-08 13:04:15
Total Duration: 00:07:14
Result
Decisions Made: 8
Child Plans: 2/2 complete
Artifacts: 6 files updated
Validations: 3/3 passed
Total Cost: $0.085
[OK] Plan completed successfully
```
=== "JSON"
```json
{
"command": "plan status",
"status": "ok",
"exit_code": 0,
"data": {
"plan_id": "01HXM6R3ZK4Q7C2B3F2R4VYV6J",
"phase": "apply",
"state": "applied",
"action": "local/add-auth",
"project": "local/api-service",
"automation": "trusted",
"attempt": 1,
"progress": [
{ "step": "Strategize", "status": "done" },
{ "step": "Execute", "status": "done" },
{ "step": "Apply", "status": "committed" }
],
"timing": {
"started": "2026-02-08T12:57:01Z",
"finished": "2026-02-08T13:04:15Z",
"total_duration": "00:07:14"
},
"result": {
"decisions_made": 8,
"child_plans": "2/2 complete",
"artifacts": "6 files updated",
"validations": "3/3 passed",
"total_cost": 0.085
}
},
"timing": {
"started": "2026-02-08T12:57:01Z",
"duration_ms": 434000
},
"messages": ["Plan completed successfully"]
}
```
=== "YAML"
```yaml
command: plan status
status: ok
exit_code: 0
data:
plan_id: "01HXM6R3ZK4Q7C2B3F2R4VYV6J"
phase: apply
state: applied
action: local/add-auth
project: local/api-service
automation: trusted
attempt: 1
progress:
- step: Strategize
status: done
- step: Execute
status: done
- step: Apply
status: committed
timing:
started: "2026-02-08T12:57:01Z"
finished: "2026-02-08T13:04:15Z"
total_duration: "00:07:14"
result:
decisions_made: 8
child_plans: "2/2 complete"
artifacts: "6 files updated"
validations: "3/3 passed"
total_cost: 0.085
timing:
started: "2026-02-08T12:57:01Z"
duration_ms: 434000
messages:
- "Plan completed successfully"
```
Status of a plan in the strategize phase:
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan status 01HXM9F2ZK4Q7C2B3F2R4VYV6J
╭─ Plan Status ────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Plan:</span> 01HXM9F2ZK4Q7C2B3F2R4VYV6J │
│ <span style="color: yellow;">Phase:</span> strategize │
│ <span style="color: magenta; font-weight: 600;">State:</span> processing │
│ <span style="color: #5599ff; font-weight: 600;">Action:</span> local/refactor-auth │
│ <span style="color: #5599ff; font-weight: 600;">Project:</span> local/api-service │
│ <span style="color: #5599ff; font-weight: 600;">Automation:</span> supervised │
╰──────────────────────────────────╯
╭─ Progress ───────────────╮
│ <span style="color: cyan; font-weight: 600;">⏳</span> Strategize (running) │
│ <span style="opacity: 0.5;">○</span> Execute (waiting) │
│ <span style="opacity: 0.5;">○</span> Apply (waiting) │
╰──────────────────────────╯
╭─ Strategy Progress ────────╮
│ <span style="color: #5599ff; font-weight: 600;">Decisions Made:</span> 4 │
│ <span style="color: #5599ff; font-weight: 600;">Invariants Enforced:</span> 2 │
│ <span style="color: #5599ff; font-weight: 600;">Child Plans Planned:</span> 3 │
│ <span style="color: yellow;">Elapsed:</span> 00:00:28 │
╰────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Strategize in progress
</code></pre></div>
=== "Plain"
```
$ agents plan status 01HXM9F2ZK4Q7C2B3F2R4VYV6J
Plan Status
Plan: 01HXM9F2ZK4Q7C2B3F2R4VYV6J
Phase: strategize
State: processing
Action: local/refactor-auth
Project: local/api-service
Automation: supervised
Progress
... Strategize (running)
o Execute (waiting)
o Apply (waiting)
Strategy Progress
Decisions Made: 4
Invariants Enforced: 2
Child Plans Planned: 3
Elapsed: 00:00:28
[OK] Strategize in progress
```
=== "JSON"
```json
{
"command": "plan status",
"status": "ok",
"exit_code": 0,
"data": {
"plan_id": "01HXM9F2ZK4Q7C2B3F2R4VYV6J",
"phase": "strategize",
"state": "processing",
"action": "local/refactor-auth",
"project": "local/api-service",
"automation": "supervised",
"progress": [
{ "step": "Strategize", "status": "running" },
{ "step": "Execute", "status": "waiting" },
{ "step": "Apply", "status": "waiting" }
],
"strategy_progress": {
"decisions_made": 4,
"invariants_enforced": 2,
"child_plans_planned": 3,
"elapsed": "00:00:28"
}
},
"timing": {
"started": "2026-02-08T12:57:01Z",
"duration_ms": 28000
},
"messages": ["Strategize in progress"]
}
```
=== "YAML"
```yaml
command: plan status
status: ok
exit_code: 0
data:
plan_id: "01HXM9F2ZK4Q7C2B3F2R4VYV6J"
phase: strategize
state: processing
action: local/refactor-auth
project: local/api-service
automation: supervised
progress:
- step: Strategize
status: running
- step: Execute
status: waiting
- step: Apply
status: waiting
strategy_progress:
decisions_made: 4
invariants_enforced: 2
child_plans_planned: 3
elapsed: "00:00:28"
timing:
started: "2026-02-08T12:57:01Z"
duration_ms: 28000
messages:
- "Strategize in progress"
```
Status of a plan that encountered an error:
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan status 01HXM7K2ZK4Q7C2B3F2R4VYV6J
╭─ Plan Status ────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Plan:</span> 01HXM7K2ZK4Q7C2B3F2R4VYV6J │
│ <span style="color: #ff6666; font-weight: 600;">Phase:</span> execute │
│ <span style="color: #ff6666; font-weight: 600;">State:</span> errored │
│ <span style="color: #5599ff; font-weight: 600;">Action:</span> local/migrate-db │
│ <span style="color: #5599ff; font-weight: 600;">Project:</span> local/api-service │
│ <span style="color: #5599ff; font-weight: 600;">Automation:</span> supervised │
│ <span style="color: #5599ff; font-weight: 600;">Attempt:</span> 1 │
╰──────────────────────────────────╯
╭─ Progress ───────────╮
│ <span style="color: #66cc66; font-weight: 600;">✓</span> Strategize │
│ <span style="color: #ff6666; font-weight: 600;">✗</span> Execute │
│ <span style="opacity: 0.5;">○</span> Apply (skipped) │
╰──────────────────────╯
╭─ Error Detail ──────────────────────────────────────────────────╮
│ <span style="color: #ff6666; font-weight: 600;">Error:</span> Tool invocation failed: connection refused │
│ <span style="color: #5599ff; font-weight: 600;">Tool:</span> local/db-migrate │
│ <span style="color: #5599ff; font-weight: 600;">Step:</span> 4 of 6 │
│ <span style="color: #5599ff; font-weight: 600;">Checkpoint:</span> cp_01HXM8C2 (sandbox state preserved) │
│ <span style="opacity: 0.7;">Recoverable: yes — use <span style="color: #66cc66;">"agents plan prompt"</span> to provide guidance</span> │
╰─────────────────────────────────────────────────────────────────╯
╭─ Cost ───────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Tokens Used:</span> 8,340 │
│ <span style="color: yellow;">Cost So Far:</span> $0.028 │
╰──────────────────────╯
<span style="color: #ff6666; font-weight: 600;">✗ ERROR</span> Plan errored — use `agents plan prompt` to resume or `agents plan cancel` to abort
</code></pre></div>
=== "Plain"
```
$ agents plan status 01HXM7K2ZK4Q7C2B3F2R4VYV6J
Plan Status
Plan: 01HXM7K2ZK4Q7C2B3F2R4VYV6J
Phase: execute
State: errored
Action: local/migrate-db
Project: local/api-service
Automation: supervised
Attempt: 1
Progress
[OK] Strategize
[FAIL] Execute
o Apply (skipped)
Error Detail
Error: Tool invocation failed: connection refused
Tool: local/db-migrate
Step: 4 of 6
Checkpoint: cp_01HXM8C2 (sandbox state preserved)
Recoverable: yes -- use "agents plan prompt" to provide guidance
Cost
Tokens Used: 8,340
Cost So Far: $0.028
[ERROR] Plan errored -- use `agents plan prompt` to resume or `agents plan cancel` to abort
```
=== "JSON"
```json
{
"command": "plan status",
"status": "error",
"exit_code": 1,
"data": {
"plan_id": "01HXM7K2ZK4Q7C2B3F2R4VYV6J",
"phase": "execute",
"state": "errored",
"action": "local/migrate-db",
"project": "local/api-service",
"automation": "supervised",
"attempt": 1,
"progress": [
{ "step": "Strategize", "status": "done" },
{ "step": "Execute", "status": "failed" },
{ "step": "Apply", "status": "skipped" }
],
"error": {
"message": "Tool invocation failed: connection refused",
"tool": "local/db-migrate",
"step": "4 of 6",
"checkpoint": "cp_01HXM8C2",
"recoverable": true
},
"cost": {
"tokens_used": 8340,
"cost_so_far": 0.028
}
},
"timing": {
"started": "2026-02-08T12:57:01Z",
"duration_ms": 72000
},
"messages": ["Plan errored — use `agents plan prompt` to resume or `agents plan cancel` to abort"]
}
```
=== "YAML"
```yaml
command: plan status
status: error
exit_code: 1
data:
plan_id: "01HXM7K2ZK4Q7C2B3F2R4VYV6J"
phase: execute
state: errored
action: local/migrate-db
project: local/api-service
automation: supervised
attempt: 1
progress:
- step: Strategize
status: done
- step: Execute
status: failed
- step: Apply
status: skipped
error:
message: "Tool invocation failed: connection refused"
tool: local/db-migrate
step: "4 of 6"
checkpoint: cp_01HXM8C2
recoverable: true
cost:
tokens_used: 8340
cost_so_far: 0.028
timing:
started: "2026-02-08T12:57:01Z"
duration_ms: 72000
messages:
- "Plan errored — use `agents plan prompt` to resume or `agents plan cancel` to abort"
```
agents plan cancel
agents plan cancel [(--reason|-r) <REASON>] <PLAN_ID>!!! warning "Irreversible State Transition"
Cancel a plan that is not in a terminal state. Cancellation transitions the plan to the cancelled state, which is ==terminal==. The sandbox and any child plan artifacts are preserved for inspection but cannot be resumed.
!!! tip "Recovery After Cancel"
A cancelled plan cannot be resumed, but you can re-execute the same action with `agents plan use` to create a new plan instance.
Arguments
<PLAN_ID>: Plan ID.--reason/-r TEXT: Optional reason.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan cancel 01HXM8C2ZK4Q7C2B3F2R4VYV6J <span style="color: cyan;">--reason</span> <span style="color: #66cc66;">"blocked on credentials"</span>
╭─ Plan Cancelled ─────────────────╮
│ <span style="color: cyan; font-weight: 600;">Plan:</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
│ <span style="color: yellow; font-weight: 600;">Phase:</span> execute │
│ <span style="color: magenta; font-weight: 600;">Reason:</span> blocked on credentials │
│ <span style="color: #5599ff; font-weight: 600;">State:</span> cancelled │
│ <span style="color: #5599ff; font-weight: 600;">Cancelled At:</span> 13:02:15 │
╰──────────────────────────────────╯
╭─ Sandbox ────────────────╮
│ <span style="color: yellow; font-weight: 600;">Status:</span> preserved │
│ <span style="color: #5599ff; font-weight: 600;">Files Modified:</span> 3 │
│ <span style="color: #5599ff; font-weight: 600;">Checkpoints:</span> 2 │
╰──────────────────────────╯
╭─ Child Plans ─────────────╮
│ <span style="color: #66cc66; font-weight: 600;">Completed:</span> 1 │
│ <span style="color: yellow; font-weight: 600;">Cancelled:</span> 1 │
│ <span style="color: #5599ff; font-weight: 600;">Artifacts Preserved:</span> yes │
╰───────────────────────────╯
╭─ Recovery ───────────────────────────────────────────╮
│ - Resolve credentials │
│ - Run agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
╰──────────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Plan cancelled
</code></pre></div>
=== "Plain"
```
$ agents plan cancel 01HXM8C2ZK4Q7C2B3F2R4VYV6J --reason "blocked on credentials"
Plan Cancelled
Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
Phase: execute
Reason: blocked on credentials
State: cancelled
Cancelled At: 13:02:15
Sandbox
Status: preserved
Files Modified: 3
Checkpoints: 2
Child Plans
Completed: 1
Cancelled: 1
Artifacts Preserved: yes
Recovery
- Resolve credentials
- Run agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J
[OK] Plan cancelled
```
=== "JSON"
```json
{
"command": "plan cancel",
"status": "ok",
"exit_code": 0,
"data": {
"plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
"phase": "execute",
"reason": "blocked on credentials",
"state": "cancelled",
"cancelled_at": "13:02:15",
"sandbox": {
"status": "preserved",
"files_modified": 3,
"checkpoints": 2
},
"child_plans": {
"completed": 1,
"cancelled": 1,
"artifacts_preserved": true
},
"recovery": [
"Resolve credentials",
"Run agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J"
]
},
"timing": {
"started": "2026-02-08T13:02:15Z",
"duration_ms": 340
},
"messages": ["Plan cancelled"]
}
```
=== "YAML"
```yaml
command: plan cancel
status: ok
exit_code: 0
data:
plan_id: "01HXM8C2ZK4Q7C2B3F2R4VYV6J"
phase: execute
reason: "blocked on credentials"
state: cancelled
cancelled_at: "13:02:15"
sandbox:
status: preserved
files_modified: 3
checkpoints: 2
child_plans:
completed: 1
cancelled: 1
artifacts_preserved: true
recovery:
- "Resolve credentials"
- "Run agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J"
timing:
started: "2026-02-08T13:02:15Z"
duration_ms: 340
messages:
- "Plan cancelled"
```
agents plan tree
agents plan tree [--show-superseded] <PLAN_ID>Purpose Render the decision tree for a plan.
Arguments
<PLAN_ID>: Plan ID (required).--show-superseded: Include superseded decisions.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan tree 01HXM8C2ZK4Q7C2B3F2R4VYV6J
╭─ Decision Tree ──────────────────────────────────────────────────────────────────────────╮
│ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
│ ├─ <span style="color: white;">[prompt_definition]</span> <span style="color: #66cc66;">"Increase test coverage to 85%"</span> │
│ ├─ <span style="color: magenta;">[invariant_enforced]</span> <span style="color: #66cc66;">"Prioritize financial transaction and user mgmt code"</span> │
│ ├─ <span style="color: magenta;">[invariant_enforced]</span> <span style="color: #66cc66;">"All API calls over TCP must be mocked"</span> │
│ ├─ <span style="color: #5599ff;">[strategy_choice]</span> <span style="color: #66cc66;">"Prioritize auth and payments"</span> <span style="opacity: 0.7;">(confidence: 0.82)</span> │
│ ├─ <span style="color: #66cc66;">[subplan_parallel_spawn]</span> "Implement auth and payment modules, in parallel" │
│ │ ├─ <span style="color: #66cc66;">[subplan_spawn]</span> "Write auth tests" → Plan: 01HXM9F1A │
│ │ └─ <span style="color: #66cc66;">[subplan_spawn]</span> "Write payment tests" → Plan: 01HXM9F2B │
│ └─ <span style="color: #66cc66;">[subplan_parallel_spawn]</span> "Write tests for remaining modules" │
│ └─ ... │
╰──────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Tree Summary ─────────────╮
│ <span style="color: yellow; font-weight: 600;">Nodes:</span> 9 │
│ <span style="color: #5599ff; font-weight: 600;">Depth:</span> 3 │
│ <span style="color: #66cc66; font-weight: 600;">Child Plans:</span> 2+ │
│ <span style="color: magenta; font-weight: 600;">Invariants:</span> 2 │
│ <span style="color: #5599ff; font-weight: 600;">Superseded:</span> 0 (hidden) │
╰────────────────────────────╯
╭─ Child Plans ──────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">ID</span> <span style="color: cyan; font-weight: 600;">Phase</span> <span style="color: cyan; font-weight: 600;">State</span> │
│ <span style="opacity: 0.7;">────────── ─────── ─────────</span> │
│ 01HXM9F1A execute processing │
│ 01HXM9F2B execute queued │
╰────────────────────────────────────────────────────╯
╭─ Decision IDs (for correction) ──────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Root:</span> 01HXM9A0B1Q2W3R5G8Z0P4Q1X8 │
│ <span style="color: magenta; font-weight: 600;">Invariant 1:</span> 01HXM9A0C1R3X4S6G9Z1P5Q2Y9 │
│ <span style="color: magenta; font-weight: 600;">Invariant 2:</span> 01HXM9A0D2S4Y5T7H0Z2P6Q3Z0 │
│ <span style="color: #5599ff; font-weight: 600;">Strategy:</span> 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 │
│ <span style="color: #66cc66; font-weight: 600;">Parallel 1:</span> 01HXM9A1D3R8X5S7H1Z2P5Q2Y0 │
│ <span style="color: #66cc66; font-weight: 600;">Spawn Auth:</span> 01HXM9A2D3Q8W4R6H9Z1P5Q2X0 │
│ <span style="color: #66cc66; font-weight: 600;">Spawn Payment:</span> 01HXM9A3E4Q9W5R7I0Z2P6Q3X1 │
│ <span style="color: #66cc66; font-weight: 600;">Parallel 2:</span> 01HXM9A4F5Q0W6R8J1Z3P7Q4X2 │
╰──────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Decision tree rendered
</code></pre></div>
=== "Plain"
```
$ agents plan tree 01HXM8C2ZK4Q7C2B3F2R4VYV6J
Decision Tree
Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
+-- [prompt_definition] "Increase test coverage to 85%"
+-- [invariant_enforced] "Prioritize financial transaction and user mgmt code"
+-- [invariant_enforced] "All API calls over TCP must be mocked"
+-- [strategy_choice] "Prioritize auth and payments" (confidence: 0.82)
+-- [subplan_parallel_spawn] "Implement auth and payment modules, in parallel"
| +-- [subplan_spawn] "Write auth tests" -> Plan: 01HXM9F1A
| +-- [subplan_spawn] "Write payment tests" -> Plan: 01HXM9F2B
+-- [subplan_parallel_spawn] "Write tests for remaining modules"
+-- ...
Tree Summary
Nodes: 9
Depth: 3
Child Plans: 2+
Invariants: 2
Superseded: 0 (hidden)
Child Plans
ID Phase State
---------- ------- ---------
01HXM9F1A execute processing
01HXM9F2B execute queued
Decision IDs (for correction)
Root: 01HXM9A0B1Q2W3R5G8Z0P4Q1X8
Invariant 1: 01HXM9A0C1R3X4S6G9Z1P5Q2Y9
Invariant 2: 01HXM9A0D2S4Y5T7H0Z2P6Q3Z0
Strategy: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9
Parallel 1: 01HXM9A1D3R8X5S7H1Z2P5Q2Y0
Spawn Auth: 01HXM9A2D3Q8W4R6H9Z1P5Q2X0
Spawn Payment: 01HXM9A3E4Q9W5R7I0Z2P6Q3X1
Parallel 2: 01HXM9A4F5Q0W6R8J1Z3P7Q4X2
[OK] Decision tree rendered
```
=== "JSON"
```json
{
"command": "plan tree",
"status": "ok",
"exit_code": 0,
"data": {
"plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
"tree": {
"type": "prompt_definition",
"description": "Increase test coverage to 85%",
"children": [
{ "type": "invariant_enforced", "description": "Prioritize financial transaction and user mgmt code" },
{ "type": "invariant_enforced", "description": "All API calls over TCP must be mocked" },
{ "type": "strategy_choice", "description": "Prioritize auth and payments", "confidence": 0.82 },
{
"type": "subplan_parallel_spawn",
"description": "Implement auth and payment modules, in parallel",
"children": [
{ "type": "subplan_spawn", "description": "Write auth tests", "plan_id": "01HXM9F1A" },
{ "type": "subplan_spawn", "description": "Write payment tests", "plan_id": "01HXM9F2B" }
]
},
{
"type": "subplan_parallel_spawn",
"description": "Write tests for remaining modules",
"children": ["..."]
}
]
},
"summary": {
"nodes": 9,
"depth": 3,
"child_plans": "2+",
"invariants": 2,
"superseded": 0
},
"child_plans": [
{ "id": "01HXM9F1A", "phase": "execute", "state": "processing" },
{ "id": "01HXM9F2B", "phase": "execute", "state": "queued" }
],
"decision_ids": {
"root": "01HXM9A0B1Q2W3R5G8Z0P4Q1X8",
"invariant_1": "01HXM9A0C1R3X4S6G9Z1P5Q2Y9",
"invariant_2": "01HXM9A0D2S4Y5T7H0Z2P6Q3Z0",
"strategy": "01HXM9A1C2Q7W3R5G8Z0P4Q1X9",
"parallel_1": "01HXM9A1D3R8X5S7H1Z2P5Q2Y0",
"spawn_auth": "01HXM9A2D3Q8W4R6H9Z1P5Q2X0",
"spawn_payment": "01HXM9A3E4Q9W5R7I0Z2P6Q3X1",
"parallel_2": "01HXM9A4F5Q0W6R8J1Z3P7Q4X2"
}
},
"timing": {
"started": "2026-02-08T12:58:00Z",
"duration_ms": 85
},
"messages": ["Decision tree rendered"]
}
```
=== "YAML"
```yaml
command: plan tree
status: ok
exit_code: 0
data:
plan_id: "01HXM8C2ZK4Q7C2B3F2R4VYV6J"
tree:
type: prompt_definition
description: "Increase test coverage to 85%"
children:
- type: invariant_enforced
description: "Prioritize financial transaction and user mgmt code"
- type: invariant_enforced
description: "All API calls over TCP must be mocked"
- type: strategy_choice
description: "Prioritize auth and payments"
confidence: 0.82
- type: subplan_parallel_spawn
description: "Implement auth and payment modules, in parallel"
children:
- type: subplan_spawn
description: "Write auth tests"
plan_id: "01HXM9F1A"
- type: subplan_spawn
description: "Write payment tests"
plan_id: "01HXM9F2B"
- type: subplan_parallel_spawn
description: "Write tests for remaining modules"
children:
- "..."
summary:
nodes: 9
depth: 3
child_plans: "2+"
invariants: 2
superseded: 0
child_plans:
- id: "01HXM9F1A"
phase: execute
state: processing
- id: "01HXM9F2B"
phase: execute
state: queued
decision_ids:
root: "01HXM9A0B1Q2W3R5G8Z0P4Q1X8"
invariant_1: "01HXM9A0C1R3X4S6G9Z1P5Q2Y9"
invariant_2: "01HXM9A0D2S4Y5T7H0Z2P6Q3Z0"
strategy: "01HXM9A1C2Q7W3R5G8Z0P4Q1X9"
parallel_1: "01HXM9A1D3R8X5S7H1Z2P5Q2Y0"
spawn_auth: "01HXM9A2D3Q8W4R6H9Z1P5Q2X0"
spawn_payment: "01HXM9A3E4Q9W5R7I0Z2P6Q3X1"
parallel_2: "01HXM9A4F5Q0W6R8J1Z3P7Q4X2"
timing:
started: "2026-02-08T12:58:00Z"
duration_ms: 85
messages:
- "Decision tree rendered"
```
agents plan explain
agents plan explain [--show-context] [--show-reasoning] <DECISION_ID>Purpose Show a detailed explanation for a decision.
Arguments
<DECISION_ID>: Decision ID.--show-context: Include the context snapshot.--show-reasoning: Include raw model reasoning if available.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan explain 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 <span style="color: cyan;">--show-context</span>
╭─ Decision ─────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">ID:</span> 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 │
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> strategy_choice │
│ <span style="color: magenta; font-weight: 600;">Question:</span> Which modules should be prioritized? │
│ <span style="color: #66cc66; font-weight: 600;">Chosen:</span> Auth and payments │
│ <span style="color: yellow; font-weight: 600;">Confidence:</span> 0.82 │
│ <span style="color: #5599ff; font-weight: 600;">Plan:</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
│ <span style="color: #5599ff; font-weight: 600;">Sequence:</span> 2 of 5 │
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-08 12:58 │
╰────────────────────────────────────────────────╯
╭─ Alternatives Considered ──────────────────────╮
│ 1. Auth and payments <span style="color: #66cc66; font-weight: 600;">(chosen)</span> │
│ 2. User module first (coverage 71%, med risk) │
│ 3. All modules equally (spread thin) │
╰────────────────────────────────────────────────╯
╭─ Impact ──────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Downstream Decisions:</span> 3 │
│ <span style="color: #5599ff; font-weight: 600;">Downstream Child Plans:</span> 2 │
│ <span style="color: #66cc66; font-weight: 600;">Artifacts Produced:</span> 5 │
│ <span style="color: yellow; font-weight: 600;">Correction Impact:</span> medium │
╰───────────────────────────────╯
╭─ Context Snapshot ───────────────╮
│ - Coverage < 70% in auth │
│ - Payments failures last release │
│ - Auth: 12 files, 45% coverage │
│ - Payments: 8 files, 52% cover. │
│ <span style="color: #5599ff; font-weight: 600;">Hot Context Hash:</span> sha256:4b2e... │
╰──────────────────────────────────╯
╭─ Rationale ───────────────────────────────────────╮
│ Auth and payment modules have the lowest coverage │
│ and highest business risk. Auth handles security │
│ tokens, payments handles money. Both had bugs in │
│ the last release traceable to missing tests. │
╰───────────────────────────────────────────────────╯
╭─ Correction ──────────────────────────────────────────────╮
│ agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 │
│ <span style="color: cyan;">--mode</span> revert <span style="color: cyan;">--guidance</span> <span style="color: #66cc66;">"Prioritize payments first..."</span> │
╰───────────────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Decision explained
</code></pre></div>
=== "Plain"
```
$ agents plan explain 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --show-context
Decision
ID: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9
Type: strategy_choice
Question: Which modules should be prioritized?
Chosen: Auth and payments
Confidence: 0.82
Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
Sequence: 2 of 5
Created: 2026-02-08 12:58
Alternatives Considered
1. Auth and payments (chosen)
2. User module first (coverage 71%, med risk)
3. All modules equally (spread thin)
Impact
Downstream Decisions: 3
Downstream Child Plans: 2
Artifacts Produced: 5
Correction Impact: medium
Context Snapshot
- Coverage < 70% in auth
- Payments failures last release
- Auth: 12 files, 45% coverage
- Payments: 8 files, 52% cover.
Hot Context Hash: sha256:4b2e...
Rationale
Auth and payment modules have the lowest coverage
and highest business risk. Auth handles security
tokens, payments handles money. Both had bugs in
the last release traceable to missing tests.
Correction
agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9
--mode revert --guidance "Prioritize payments first..."
[OK] Decision explained
```
=== "JSON"
```json
{
"command": "plan explain",
"status": "ok",
"exit_code": 0,
"data": {
"decision_id": "01HXM9A1C2Q7W3R5G8Z0P4Q1X9",
"type": "strategy_choice",
"question": "Which modules should be prioritized?",
"chosen": "Auth and payments",
"confidence": 0.82,
"plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
"sequence": "2 of 5",
"created": "2026-02-08T12:58:00Z",
"alternatives": [
{ "index": 1, "description": "Auth and payments", "chosen": true },
{ "index": 2, "description": "User module first (coverage 71%, med risk)", "chosen": false },
{ "index": 3, "description": "All modules equally (spread thin)", "chosen": false }
],
"impact": {
"downstream_decisions": 3,
"downstream_child_plans": 2,
"artifacts_produced": 5,
"correction_impact": "medium"
},
"context_snapshot": {
"items": [
"Coverage < 70% in auth",
"Payments failures last release",
"Auth: 12 files, 45% coverage",
"Payments: 8 files, 52% cover."
],
"hot_context_hash": "sha256:4b2e..."
},
"rationale": "Auth and payment modules have the lowest coverage and highest business risk. Auth handles security tokens, payments handles money. Both had bugs in the last release traceable to missing tests.",
"correction_hint": "agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --mode revert --guidance "Prioritize payments first...""
},
"timing": {
"started": "2026-02-08T12:58:00Z",
"duration_ms": 110
},
"messages": ["Decision explained"]
}
```
=== "YAML"
```yaml
command: plan explain
status: ok
exit_code: 0
data:
decision_id: "01HXM9A1C2Q7W3R5G8Z0P4Q1X9"
type: strategy_choice
question: "Which modules should be prioritized?"
chosen: "Auth and payments"
confidence: 0.82
plan_id: "01HXM8C2ZK4Q7C2B3F2R4VYV6J"
sequence: "2 of 5"
created: "2026-02-08T12:58:00Z"
alternatives:
- index: 1
description: "Auth and payments"
chosen: true
- index: 2
description: "User module first (coverage 71%, med risk)"
chosen: false
- index: 3
description: "All modules equally (spread thin)"
chosen: false
impact:
downstream_decisions: 3
downstream_child_plans: 2
artifacts_produced: 5
correction_impact: medium
context_snapshot:
items:
- "Coverage < 70% in auth"
- "Payments failures last release"
- "Auth: 12 files, 45% coverage"
- "Payments: 8 files, 52% cover."
hot_context_hash: "sha256:4b2e..."
rationale: >-
Auth and payment modules have the lowest coverage
and highest business risk. Auth handles security
tokens, payments handles money. Both had bugs in
the last release traceable to missing tests.
correction_hint: >-
agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9
--mode revert --guidance "Prioritize payments first..."
timing:
started: "2026-02-08T12:58:00Z"
duration_ms: 110
messages:
- "Decision explained"
```
Including the raw model reasoning with --show-reasoning:
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan explain <span style="color: cyan;">--show-reasoning</span> 01HXM9A1C2Q7W3R5G8Z0P4Q1X9
╭─ Decision ──────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">ID:</span> 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 │
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> strategy_choice │
│ <span style="color: magenta; font-weight: 600;">Choice:</span> Convert to async/await │
│ <span style="color: #5599ff; font-weight: 600;">Alternatives:</span> 3 │
╰─────────────────────────────────────────╯
╭─ Alternatives Considered ────────────────────────────────────╮
│ <span style="color: #66cc66; font-weight: 600;">1. Convert to async/await patterns</span> (chosen) │
│ <span style="opacity: 0.7;"> 2. Keep synchronous with thread pool</span> │
│ <span style="opacity: 0.7;"> 3. Use callback-based approach</span> │
╰──────────────────────────────────────────────────────────────╯
╭─ Rationale ──────────────────────────────────────────────────╮
│ Async/await is the modern Python standard for I/O-bound │
│ operations. The project already uses asyncio in 3 modules. │
│ Thread pools would add complexity without native support. │
╰──────────────────────────────────────────────────────────────╯
╭─ Model Reasoning (raw) ───────────────────────────────────────╮
│ <span style="opacity: 0.7;">I need to decide on the concurrency pattern for the payment</span> │
│ <span style="opacity: 0.7;">processing module. Let me analyze the current codebase:</span> │
│ <span style="opacity: 0.7;"></span> │
│ <span style="opacity: 0.7;">1. src/payments/api.py uses synchronous requests.</span> │
│ <span style="opacity: 0.7;">2. src/core/scheduler.py already uses asyncio.</span> │
│ <span style="opacity: 0.7;">3. The database driver (asyncpg) supports async natively.</span> │
│ <span style="opacity: 0.7;">4. Project invariant says <span style="color: #66cc66;">"prefer modern Python patterns"</span>.</span> │
│ <span style="opacity: 0.7;"></span> │
│ <span style="opacity: 0.7;">Given that 3/5 core modules already use asyncio, and the</span> │
│ <span style="opacity: 0.7;">database driver supports it, converting to async/await is</span> │
│ <span style="opacity: 0.7;">the most consistent choice. Thread pools would work but</span> │
│ <span style="opacity: 0.7;">add unnecessary complexity and don't integrate well with</span> │
│ <span style="opacity: 0.7;">the existing asyncio event loop in scheduler.py.</span> │
╰───────────────────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Decision explained
</code></pre></div>
=== "Plain"
```
$ agents plan explain --show-reasoning 01HXM9A1C2Q7W3R5G8Z0P4Q1X9
Decision
ID: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9
Type: strategy_choice
Choice: Convert to async/await
Alternatives: 3
Alternatives Considered
1. Convert to async/await patterns (chosen)
2. Keep synchronous with thread pool
3. Use callback-based approach
Rationale
Async/await is the modern Python standard for I/O-bound
operations. The project already uses asyncio in 3 modules.
Thread pools would add complexity without native support.
Model Reasoning (raw)
I need to decide on the concurrency pattern for the payment
processing module. Let me analyze the current codebase:
1. src/payments/api.py uses synchronous requests.
2. src/core/scheduler.py already uses asyncio.
3. The database driver (asyncpg) supports async natively.
4. Project invariant says "prefer modern Python patterns".
Given that 3/5 core modules already use asyncio, and the
database driver supports it, converting to async/await is
the most consistent choice. Thread pools would work but
add unnecessary complexity and don't integrate well with
the existing asyncio event loop in scheduler.py.
[OK] Decision explained
```
=== "JSON"
```json
{
"command": "plan explain",
"status": "ok",
"exit_code": 0,
"data": {
"decision_id": "01HXM9A1C2Q7W3R5G8Z0P4Q1X9",
"type": "strategy_choice",
"choice": "Convert to async/await",
"alternatives_count": 3,
"alternatives": [
{ "index": 1, "description": "Convert to async/await patterns", "chosen": true },
{ "index": 2, "description": "Keep synchronous with thread pool", "chosen": false },
{ "index": 3, "description": "Use callback-based approach", "chosen": false }
],
"rationale": "Async/await is the modern Python standard for I/O-bound operations. The project already uses asyncio in 3 modules. Thread pools would add complexity without native support.",
"model_reasoning": "I need to decide on the concurrency pattern for the payment processing module. Let me analyze the current codebase:\n\n1. src/payments/api.py uses synchronous requests.\n2. src/core/scheduler.py already uses asyncio.\n3. The database driver (asyncpg) supports async natively.\n4. Project invariant says \"prefer modern Python patterns\".\n\nGiven that 3/5 core modules already use asyncio, and the database driver supports it, converting to async/await is the most consistent choice. Thread pools would work but add unnecessary complexity and don't integrate well with the existing asyncio event loop in scheduler.py."
},
"timing": {
"started": "2026-02-08T12:58:00Z",
"duration_ms": 95
},
"messages": ["Decision explained"]
}
```
=== "YAML"
```yaml
command: plan explain
status: ok
exit_code: 0
data:
decision_id: "01HXM9A1C2Q7W3R5G8Z0P4Q1X9"
type: strategy_choice
choice: "Convert to async/await"
alternatives_count: 3
alternatives:
- index: 1
description: "Convert to async/await patterns"
chosen: true
- index: 2
description: "Keep synchronous with thread pool"
chosen: false
- index: 3
description: "Use callback-based approach"
chosen: false
rationale: >-
Async/await is the modern Python standard for I/O-bound
operations. The project already uses asyncio in 3 modules.
Thread pools would add complexity without native support.
model_reasoning: >-
I need to decide on the concurrency pattern for the payment
processing module. Let me analyze the current codebase:
1. src/payments/api.py uses synchronous requests.
2. src/core/scheduler.py already uses asyncio.
3. The database driver (asyncpg) supports async natively.
4. Project invariant says "prefer modern Python patterns".
Given that 3/5 core modules already use asyncio, and the
database driver supports it, converting to async/await is
the most consistent choice.
timing:
started: "2026-02-08T12:58:00Z"
duration_ms: 95
messages:
- "Decision explained"
```
agents plan correct
agents plan correct --mode (revert|append) (--guidance|-g) <GUIDANCE>
[--dry-run] [--yes|-y] <DECISION_ID>Purpose Correct a decision either by reverting and re-executing or by appending a fix.
Arguments
<DECISION_ID>: Decision ID.--mode revert|append: Correction mode.--guidance/-g TEXT: Guidance text.--dry-run: Show impact without executing.--yes: Skip confirmation for revert mode.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 <span style="color: cyan;">--mode</span> revert \
<span style="color: cyan;">--guidance</span> <span style="color: #66cc66;">"Prioritize payments first"</span> <span style="color: cyan;">--yes</span>
╭─ Correction ────────────────────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Mode:</span> revert │
│ <span style="color: yellow; font-weight: 600;">Impact:</span> 3 decisions, 2 child plans, 5 artifacts │
│ <span style="color: #66cc66; font-weight: 600;">New Decision:</span> 01HXM9B7Z3Q1Q8K2E9H7K3W2M8 │
│ <span style="color: magenta; font-weight: 600;">Corrects:</span> 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 │
│ <span style="color: #5599ff; font-weight: 600;">Attempt:</span> 2 │
╰─────────────────────────────────────────────────────╯
╭─ Affected Subtree ──────────────╮
│ <span style="color: yellow; font-weight: 600;">Decisions Invalidated:</span> 3 │
│ <span style="color: yellow; font-weight: 600;">Child Plans Rolled Back:</span> 2 │
│ <span style="color: yellow; font-weight: 600;">Artifacts Archived:</span> 5 │
│ <span style="color: #5599ff; font-weight: 600;">Unaffected Decisions:</span> 2 │
╰─────────────────────────────────╯
╭─ Sandbox Rollback ─────────────╮
│ <span style="color: #66cc66; font-weight: 600;">Checkpoint:</span> cp_01HXM8C2 │
│ <span style="color: #5599ff; font-weight: 600;">Files Reverted:</span> 5 │
│ <span style="color: #66cc66; font-weight: 600;">Status:</span> restored │
╰────────────────────────────────╯
╭─ Recompute ──────────────╮
│ <span style="color: yellow; font-weight: 600;">Queued:</span> 2 child plans │
│ <span style="color: #66cc66; font-weight: 600;">ETA:</span> 4m │
╰──────────────────────────╯
╭─ History ───────────────────────────────────────────╮
│ - Original decision superseded │
│ - Prior artifacts archived for comparison │
│ - agents plan diff <span style="color: cyan;">--correction</span> 01HXM9B7Z3Q1Q8K2.. │
╰─────────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Correction applied
</code></pre></div>
=== "Plain"
```
$ agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --mode revert --guidance "Prioritize payments first" --yes
Correction
Mode: revert
Impact: 3 decisions, 2 child plans, 5 artifacts
New Decision: 01HXM9B7Z3Q1Q8K2E9H7K3W2M8
Corrects: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9
Attempt: 2
Affected Subtree
Decisions Invalidated: 3
Child Plans Rolled Back: 2
Artifacts Archived: 5
Unaffected Decisions: 2
Sandbox Rollback
Checkpoint: cp_01HXM8C2
Files Reverted: 5
Status: restored
Recompute
Queued: 2 child plans
ETA: 4m
History
- Original decision superseded
- Prior artifacts archived for comparison
- agents plan diff --correction 01HXM9B7Z3Q1Q8K2..
[OK] Correction applied
```
=== "JSON"
```json
{
"command": "plan correct",
"status": "ok",
"exit_code": 0,
"data": {
"correction": {
"mode": "revert",
"impact": "3 decisions, 2 child plans, 5 artifacts",
"new_decision": "01HXM9B7Z3Q1Q8K2E9H7K3W2M8",
"corrects": "01HXM9A1C2Q7W3R5G8Z0P4Q1X9",
"attempt": 2
},
"affected_subtree": {
"decisions_invalidated": 3,
"child_plans_rolled_back": 2,
"artifacts_archived": 5,
"unaffected_decisions": 2
},
"sandbox_rollback": {
"checkpoint": "cp_01HXM8C2",
"files_reverted": 5,
"status": "restored"
},
"recompute": {
"queued": "2 child plans",
"eta": "4m"
},
"history": [
"Original decision superseded",
"Prior artifacts archived for comparison",
"agents plan diff --correction 01HXM9B7Z3Q1Q8K2.."
]
},
"timing": { "started": "2025-06-15T10:24:00Z", "duration_ms": 2350 },
"messages": ["Correction applied"]
}
```
=== "YAML"
```yaml
command: plan correct
status: ok
exit_code: 0
data:
correction:
mode: revert
impact: "3 decisions, 2 child plans, 5 artifacts"
new_decision: "01HXM9B7Z3Q1Q8K2E9H7K3W2M8"
corrects: "01HXM9A1C2Q7W3R5G8Z0P4Q1X9"
attempt: 2
affected_subtree:
decisions_invalidated: 3
child_plans_rolled_back: 2
artifacts_archived: 5
unaffected_decisions: 2
sandbox_rollback:
checkpoint: cp_01HXM8C2
files_reverted: 5
status: restored
recompute:
queued: "2 child plans"
eta: "4m"
history:
- "Original decision superseded"
- "Prior artifacts archived for comparison"
- "agents plan diff --correction 01HXM9B7Z3Q1Q8K2.."
timing:
started: "2025-06-15T10:24:00Z"
duration_ms: 2350
messages:
- "Correction applied"
```
Using --mode append to add a corrective decision without reverting existing work (useful when the original decision was partially correct):
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 <span style="color: cyan;">--mode</span> append \
<span style="color: cyan;">--guidance</span> <span style="color: #66cc66;">"Also add rate limiting to the auth endpoints"</span>
╭─ Correction ─────────────────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Mode:</span> append │
│ <span style="color: #66cc66; font-weight: 600;">Impact:</span> adds to existing subtree, no rollback │
│ <span style="color: #66cc66; font-weight: 600;">New Decision:</span> 01HXM9C3Z5T2Q8K2E9H7K3W2M8 │
│ <span style="color: #5599ff; font-weight: 600;">Appended After:</span> 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 │
│ <span style="color: #5599ff; font-weight: 600;">Attempt:</span> 2 │
╰──────────────────────────────────────────────────╯
╭─ Append Detail ─────────────────────────────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Original decision preserved:</span> yes │
│ <span style="color: #5599ff; font-weight: 600;">Existing artifacts kept:</span> yes │
│ <span style="color: #66cc66; font-weight: 600;">Additional work:</span> appended as new child plan │
│ <span style="opacity: 0.7;">The original 5 artifacts remain; a new child plan will add</span> │
│ <span style="opacity: 0.7;">rate-limiting code on top of the existing auth changes.</span> │
╰─────────────────────────────────────────────────────────────────╯
╭─ Queued ──────────╮
│ <span style="color: yellow;">New child:</span> 1 │
│ <span style="color: #66cc66; font-weight: 600;">ETA:</span> 2m │
╰───────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Append correction queued
</code></pre></div>
=== "Plain"
```
$ agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --mode append --guidance "Also add rate limiting to the auth endpoints"
Correction
Mode: append
Impact: adds to existing subtree, no rollback
New Decision: 01HXM9C3Z5T2Q8K2E9H7K3W2M8
Appended After: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9
Attempt: 2
Append Detail
Original decision preserved: yes
Existing artifacts kept: yes
Additional work: appended as new child plan
The original 5 artifacts remain; a new child plan will add
rate-limiting code on top of the existing auth changes.
Queued
New child: 1
ETA: 2m
[OK] Append correction queued
```
=== "JSON"
```json
{
"command": "plan correct",
"status": "ok",
"exit_code": 0,
"data": {
"correction": {
"mode": "append",
"impact": "adds to existing subtree, no rollback",
"new_decision": "01HXM9C3Z5T2Q8K2E9H7K3W2M8",
"appended_after": "01HXM9A1C2Q7W3R5G8Z0P4Q1X9",
"attempt": 2
},
"append_detail": {
"original_decision_preserved": true,
"existing_artifacts_kept": true,
"additional_work": "appended as new child plan",
"note": "The original 5 artifacts remain; a new child plan will add rate-limiting code on top of the existing auth changes."
},
"queued": {
"new_child": 1,
"eta": "2m"
}
},
"timing": { "started": "2025-06-15T10:26:00Z", "duration_ms": 890 },
"messages": ["Append correction queued"]
}
```
=== "YAML"
```yaml
command: plan correct
status: ok
exit_code: 0
data:
correction:
mode: append
impact: "adds to existing subtree, no rollback"
new_decision: "01HXM9C3Z5T2Q8K2E9H7K3W2M8"
appended_after: "01HXM9A1C2Q7W3R5G8Z0P4Q1X9"
attempt: 2
append_detail:
original_decision_preserved: true
existing_artifacts_kept: true
additional_work: "appended as new child plan"
note: "The original 5 artifacts remain; a new child plan will add rate-limiting code on top of the existing auth changes."
queued:
new_child: 1
eta: "2m"
timing:
started: "2025-06-15T10:26:00Z"
duration_ms: 890
messages:
- "Append correction queued"
```
Using --dry-run to preview the impact of a correction before committing to it:
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 <span style="color: cyan;">--mode</span> revert \
<span style="color: cyan;">--guidance</span> <span style="color: #66cc66;">"Use async/await pattern instead"</span> <span style="color: cyan;">--dry-run</span>
╭─ Dry Run — Correction Preview ─────────────────────────────────────╮
│ <span style="color: yellow; font-weight: 600;">⚠ This is a preview only. No changes will be made.</span> │
╰────────────────────────────────────────────────────────────────────╯
╭─ Would Revert ───────────────────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Decisions to invalidate:</span> 3 │
│ <span style="opacity: 0.7;">01HXM9A1.. strategy_choice <span style="color: #66cc66;">"sync pattern"</span></span> │
│ <span style="opacity: 0.7;">01HXM9A2.. implementation_choice <span style="color: #66cc66;">"requests"</span></span> │
│ <span style="opacity: 0.7;">01HXM9A3.. tool_invocation write_file ×4</span> │
│ <span style="color: #5599ff; font-weight: 600;">Child plans to roll back:</span> 2 │
│ <span style="color: #5599ff; font-weight: 600;">Artifacts to archive:</span> 5 files │
│ <span style="color: #5599ff; font-weight: 600;">Unaffected decisions:</span> 2 (will be kept) │
╰──────────────────────────────────────────────────────╯
╭─ Estimated Cost ──────────╮
│ <span style="color: #5599ff; font-weight: 600;">Re-strategize:</span> ~$0.012 │
│ <span style="color: #5599ff; font-weight: 600;">Re-execute:</span> ~$0.035 │
│ <span style="color: #5599ff; font-weight: 600;">Total:</span> ~$0.047 │
│ <span style="color: #5599ff; font-weight: 600;">ETA:</span> ~4 minutes │
╰───────────────────────────╯
<span style="opacity: 0.7;">To execute this correction, remove --dry-run and add --yes</span>
</code></pre></div>
=== "Plain"
```
$ agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --mode revert --guidance "Use async/await pattern instead" --dry-run
Dry Run -- Correction Preview
WARNING: This is a preview only. No changes will be made.
Would Revert
Decisions to invalidate: 3
01HXM9A1.. strategy_choice "sync pattern"
01HXM9A2.. implementation_choice "requests"
01HXM9A3.. tool_invocation write_file x4
Child plans to roll back: 2
Artifacts to archive: 5 files
Unaffected decisions: 2 (will be kept)
Estimated Cost
Re-strategize: ~$0.012
Re-execute: ~$0.035
Total: ~$0.047
ETA: ~4 minutes
To execute this correction, remove --dry-run and add --yes
```
=== "JSON"
```json
{
"command": "plan correct",
"status": "ok",
"exit_code": 0,
"data": {
"dry_run": true,
"would_revert": {
"decisions_to_invalidate": [
{ "id": "01HXM9A1..", "type": "strategy_choice", "label": "sync pattern" },
{ "id": "01HXM9A2..", "type": "implementation_choice", "label": "requests" },
{ "id": "01HXM9A3..", "type": "tool_invocation", "label": "write_file x4" }
],
"child_plans_to_roll_back": 2,
"artifacts_to_archive": 5,
"unaffected_decisions": 2
},
"estimated_cost": {
"re_strategize": "$0.012",
"re_execute": "$0.035",
"total": "$0.047",
"eta": "~4 minutes"
}
},
"timing": { "started": "2025-06-15T10:28:00Z", "duration_ms": 320 },
"messages": ["To execute this correction, remove --dry-run and add --yes"]
}
```
=== "YAML"
```yaml
command: plan correct
status: ok
exit_code: 0
data:
dry_run: true
would_revert:
decisions_to_invalidate:
- id: "01HXM9A1.."
type: strategy_choice
label: "sync pattern"
- id: "01HXM9A2.."
type: implementation_choice
label: "requests"
- id: "01HXM9A3.."
type: tool_invocation
label: "write_file x4"
child_plans_to_roll_back: 2
artifacts_to_archive: 5
unaffected_decisions: 2
estimated_cost:
re_strategize: "$0.012"
re_execute: "$0.035"
total: "$0.047"
eta: "~4 minutes"
timing:
started: "2025-06-15T10:28:00Z"
duration_ms: 320
messages:
- "To execute this correction, remove --dry-run and add --yes"
```
agents plan diff
agents plan diff (--correction <CORRECTION_ATTEMPT_ID>|<PLAN_ID>)Purpose Show diffs for a plan or a correction attempt.
Arguments
<PLAN_ID>: Show diff for a plan (positional argument). Mutually exclusive with --correction.--correction CORRECTION_ATTEMPT_ID: Show diff for a correction attempt instead.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan diff 01HXM8C2ZK4Q7C2B3F2R4VYV6J
╭─ Diff Summary ─────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Plan:</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
│ <span style="color: cyan; font-weight: 600;">Project:</span> local/api-service │
│ <span style="color: yellow; font-weight: 600;">Files Changed:</span> 2 │
│ <span style="color: #66cc66; font-weight: 600;">Insertions:</span> 12 │
│ <span style="color: #ff6666; font-weight: 600;">Deletions:</span> 4 │
│ <span style="color: #5599ff; font-weight: 600;">Net Change:</span> +8 lines │
╰────────────────────────────────────────────────╯
╭─ Files ───────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Path</span> <span style="color: cyan; font-weight: 600;">Change</span> <span style="color: cyan; font-weight: 600;">Status</span> │
│ <span style="opacity: 0.7;">─────────────────── ────── ────────</span> │
│ src/auth/session.py <span style="color: #66cc66; font-weight: 600;">+8 -2</span> modified │
│ src/auth/tokens.py <span style="color: #66cc66; font-weight: 600;">+4 -2</span> modified │
╰───────────────────────────────────────╯
╭─ Patch Preview ──────────────────────────╮
│ <span style="opacity: 0.7;">--- a/src/auth/session.py</span> │
│ <span style="opacity: 0.7;">+++ b/src/auth/session.py</span> │
│ <span style="color: cyan;">@@ -12,4 +12,10 @@</span> │
│ <span style="color: #ff6666;">- import jwt</span> │
│ <span style="color: #66cc66;">+ import sessionlib</span> │
│ <span style="color: #ff6666;">- def validate_token(...)</span> │
│ <span style="color: #66cc66;">+ def validate_session(...)</span> │
│ <span style="opacity: 0.7;">--- a/src/auth/tokens.py</span> │
│ <span style="opacity: 0.7;">+++ b/src/auth/tokens.py</span> │
│ <span style="color: cyan;">@@ -5,3 +5,7 @@</span> │
│ <span style="color: #ff6666;">- TOKEN_EXPIRY = 3600</span> │
│ <span style="color: #66cc66;">+ TOKEN_EXPIRY = 7200</span> │
╰──────────────────────────────────────────╯
╭─ Risk Assessment ────────────────╮
│ <span style="color: #66cc66; font-weight: 600;">API Compatibility:</span> preserved │
│ <span style="color: #66cc66; font-weight: 600;">Test Coverage:</span> maintained │
│ <span style="color: yellow; font-weight: 600;">Breaking Changes:</span> none detected │
╰──────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Diff generated
</code></pre></div>
=== "Plain"
```
$ agents plan diff 01HXM8C2ZK4Q7C2B3F2R4VYV6J
Diff Summary
Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
Project: local/api-service
Files Changed: 2
Insertions: 12
Deletions: 4
Net Change: +8 lines
Files
Path Change Status
------------------- ------ --------
src/auth/session.py +8 -2 modified
src/auth/tokens.py +4 -2 modified
Patch Preview
--- a/src/auth/session.py
+++ b/src/auth/session.py
@@ -12,4 +12,10 @@
- import jwt
+ import sessionlib
- def validate_token(...)
+ def validate_session(...)
--- a/src/auth/tokens.py
+++ b/src/auth/tokens.py
@@ -5,3 +5,7 @@
- TOKEN_EXPIRY = 3600
+ TOKEN_EXPIRY = 7200
Risk Assessment
API Compatibility: preserved
Test Coverage: maintained
Breaking Changes: none detected
[OK] Diff generated
```
=== "JSON"
```json
{
"command": "plan diff",
"status": "ok",
"exit_code": 0,
"data": {
"diff_summary": {
"plan": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
"project": "local/api-service",
"files_changed": 2,
"insertions": 12,
"deletions": 4,
"net_change": "+8 lines"
},
"files": [
{ "path": "src/auth/session.py", "change": "+8 -2", "status": "modified" },
{ "path": "src/auth/tokens.py", "change": "+4 -2", "status": "modified" }
],
"patch_preview": [
{
"file": "src/auth/session.py",
"hunks": [
{
"range": "@@ -12,4 +12,10 @@",
"deletions": ["import jwt", "def validate_token(...)"],
"insertions": ["import sessionlib", "def validate_session(...)"]
}
]
},
{
"file": "src/auth/tokens.py",
"hunks": [
{
"range": "@@ -5,3 +5,7 @@",
"deletions": ["TOKEN_EXPIRY = 3600"],
"insertions": ["TOKEN_EXPIRY = 7200"]
}
]
}
],
"risk_assessment": {
"api_compatibility": "preserved",
"test_coverage": "maintained",
"breaking_changes": "none detected"
}
},
"timing": { "started": "2025-06-15T10:30:00Z", "duration_ms": 750 },
"messages": ["Diff generated"]
}
```
=== "YAML"
```yaml
command: plan diff
status: ok
exit_code: 0
data:
diff_summary:
plan: "01HXM8C2ZK4Q7C2B3F2R4VYV6J"
project: local/api-service
files_changed: 2
insertions: 12
deletions: 4
net_change: "+8 lines"
files:
- path: src/auth/session.py
change: "+8 -2"
status: modified
- path: src/auth/tokens.py
change: "+4 -2"
status: modified
patch_preview:
- file: src/auth/session.py
hunks:
- range: "@@ -12,4 +12,10 @@"
deletions:
- "import jwt"
- "def validate_token(...)"
insertions:
- "import sessionlib"
- "def validate_session(...)"
- file: src/auth/tokens.py
hunks:
- range: "@@ -5,3 +5,7 @@"
deletions:
- "TOKEN_EXPIRY = 3600"
insertions:
- "TOKEN_EXPIRY = 7200"
risk_assessment:
api_compatibility: preserved
test_coverage: maintained
breaking_changes: none detected
timing:
started: "2025-06-15T10:30:00Z"
duration_ms: 750
messages:
- "Diff generated"
```
Showing the diff for a specific correction attempt, comparing what changed between the original and corrected execution:
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan diff <span style="color: cyan;">--correction</span> 01HXM9B7Z3Q1Q8K2E9H7K3W2M8
╭─ Correction Diff ───────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Correction:</span> 01HXM9B7Z3Q1Q8K2E9H7K3W2M8 │
│ <span style="color: #5599ff; font-weight: 600;">Original Decision:</span> 01HXM9A1C2Q7W3R5.. │
│ <span style="color: #5599ff; font-weight: 600;">Mode:</span> revert │
│ <span style="color: yellow;">Files Changed:</span> 3 │
│ <span style="color: #66cc66;">New Insertions:</span> 18 │
│ <span style="color: #ff6666;">New Deletions:</span> 6 │
╰─────────────────────────────────────────────────╯
╭─ Comparison ─────────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">File</span> <span style="color: cyan; font-weight: 600;">Before (original)</span> <span style="color: cyan; font-weight: 600;">After (corrected)</span> │
│ <span style="opacity: 0.7;">──────────────────── ──────────────── ────────────────────</span> │
│ src/payments/api.py +12 -4 +18 -6 (expanded) │
│ src/auth/tokens.py +8 -2 (unchanged) │
│ tests/test_payments.py (new file) (new file, larger) │
╰──────────────────────────────────────────────────────────────────╯
╭─ Patch Preview (corrected vs original) ───────────╮
│ <span style="opacity: 0.7;">--- a/src/payments/api.py (original)</span> │
│ <span style="opacity: 0.7;">+++ b/src/payments/api.py (corrected)</span> │
│ <span style="color: cyan;">@@ -1,12 +1,18 @@</span> │
│ <span style="color: #ff6666;">- # sync payment processing</span> │
│ <span style="color: #66cc66;">+ # async payment processing (corrected)</span> │
│ <span style="color: #66cc66;">+ import asyncio</span> │
│ <span style="color: #66cc66;">+ from aiohttp import ClientSession</span> │
│ <span style="opacity: 0.7;">...</span> │
╰───────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Correction diff generated
</code></pre></div>
=== "Plain"
```
$ agents plan diff --correction 01HXM9B7Z3Q1Q8K2E9H7K3W2M8
Correction Diff
Correction: 01HXM9B7Z3Q1Q8K2E9H7K3W2M8
Original Decision: 01HXM9A1C2Q7W3R5..
Mode: revert
Files Changed: 3
New Insertions: 18
New Deletions: 6
Comparison
File Before (original) After (corrected)
-------------------- ----------------- --------------------
src/payments/api.py +12 -4 +18 -6 (expanded)
src/auth/tokens.py +8 -2 (unchanged)
tests/test_payments.py (new file) (new file, larger)
Patch Preview (corrected vs original)
--- a/src/payments/api.py (original)
+++ b/src/payments/api.py (corrected)
@@ -1,12 +1,18 @@
- # sync payment processing
+ # async payment processing (corrected)
+ import asyncio
+ from aiohttp import ClientSession
...
[OK] Correction diff generated
```
=== "JSON"
```json
{
"command": "plan diff",
"status": "ok",
"exit_code": 0,
"data": {
"correction_diff": {
"correction": "01HXM9B7Z3Q1Q8K2E9H7K3W2M8",
"original_decision": "01HXM9A1C2Q7W3R5..",
"mode": "revert",
"files_changed": 3,
"new_insertions": 18,
"new_deletions": 6
},
"comparison": [
{ "file": "src/payments/api.py", "before": "+12 -4", "after": "+18 -6 (expanded)" },
{ "file": "src/auth/tokens.py", "before": "+8 -2", "after": "(unchanged)" },
{ "file": "tests/test_payments.py", "before": "(new file)", "after": "(new file, larger)" }
],
"patch_preview": [
{
"file": "src/payments/api.py",
"context": "corrected vs original",
"hunks": [
{
"range": "@@ -1,12 +1,18 @@",
"deletions": ["# sync payment processing"],
"insertions": ["# async payment processing (corrected)", "import asyncio", "from aiohttp import ClientSession"]
}
]
}
]
},
"timing": { "started": "2025-06-15T10:32:00Z", "duration_ms": 920 },
"messages": ["Correction diff generated"]
}
```
=== "YAML"
```yaml
command: plan diff
status: ok
exit_code: 0
data:
correction_diff:
correction: "01HXM9B7Z3Q1Q8K2E9H7K3W2M8"
original_decision: "01HXM9A1C2Q7W3R5.."
mode: revert
files_changed: 3
new_insertions: 18
new_deletions: 6
comparison:
- file: src/payments/api.py
before: "+12 -4"
after: "+18 -6 (expanded)"
- file: src/auth/tokens.py
before: "+8 -2"
after: "(unchanged)"
- file: tests/test_payments.py
before: "(new file)"
after: "(new file, larger)"
patch_preview:
- file: src/payments/api.py
context: "corrected vs original"
hunks:
- range: "@@ -1,12 +1,18 @@"
deletions:
- "# sync payment processing"
insertions:
- "# async payment processing (corrected)"
- "import asyncio"
- "from aiohttp import ClientSession"
timing:
started: "2025-06-15T10:32:00Z"
duration_ms: 920
messages:
- "Correction diff generated"
```
agents plan artifacts
agents plan artifacts <PLAN_ID>Purpose List artifacts produced by a plan.
Arguments
<PLAN_ID>: Plan ID.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan artifacts 01HXM8C2ZK4Q7C2B3F2R4VYV6J
╭─ Artifacts ─────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Path</span> <span style="color: cyan; font-weight: 600;">Type</span> <span style="color: cyan; font-weight: 600;">Size</span> <span style="color: cyan; font-weight: 600;">Change</span> <span style="color: cyan; font-weight: 600;">Child Plan</span> │
│ <span style="opacity: 0.7;">───────────────────── ───── ────── ───────── ───────</span> │
│ src/auth/session.py write 2.1 KB <span style="color: #66cc66; font-weight: 600;">+8 -2</span> root │
│ tests/test_session.py write 4.7 KB <span style="color: #66cc66; font-weight: 600;">+47 -0</span> root │
│ src/auth/tokens.py edit 1.8 KB <span style="color: #66cc66; font-weight: 600;">+4 -2</span> root │
│ tests/test_tokens.py write 3.2 KB <span style="color: #66cc66; font-weight: 600;">+32 -0</span> auth │
╰─────────────────────────────────────────────────────────────╯
╭─ Summary ───────────╮
│ <span style="color: yellow; font-weight: 600;">Total:</span> 4 │
│ <span style="color: #66cc66; font-weight: 600;">Writes:</span> 2 (new) │
│ <span style="color: #5599ff; font-weight: 600;">Edits:</span> 2 (modified) │
│ <span style="color: #ff6666; font-weight: 600;">Deletes:</span> 0 │
│ <span style="color: #5599ff; font-weight: 600;">Total Size:</span> 11.8 KB │
╰─────────────────────╯
╭─ By Plan ─────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Root Plan:</span> 3 artifacts │
│ <span style="color: #5599ff; font-weight: 600;">auth-tests:</span> 1 artifact │
│ <span style="color: #5599ff; font-weight: 600;">payment-tests:</span> (pending) │
╰───────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 4 artifacts listed
</code></pre></div>
=== "Plain"
```
$ agents plan artifacts 01HXM8C2ZK4Q7C2B3F2R4VYV6J
Artifacts
Path Type Size Change Child Plan
--------------------- ----- ------ --------- ----------
src/auth/session.py write 2.1 KB +8 -2 root
tests/test_session.py write 4.7 KB +47 -0 root
src/auth/tokens.py edit 1.8 KB +4 -2 root
tests/test_tokens.py write 3.2 KB +32 -0 auth
Summary
Total: 4
Writes: 2 (new)
Edits: 2 (modified)
Deletes: 0
Total Size: 11.8 KB
By Plan
Root Plan: 3 artifacts
auth-tests: 1 artifact
payment-tests: (pending)
[OK] 4 artifacts listed
```
=== "JSON"
```json
{
"command": "plan artifacts",
"status": "ok",
"exit_code": 0,
"data": {
"artifacts": [
{ "path": "src/auth/session.py", "type": "write", "size": "2.1 KB", "change": "+8 -2", "child_plan": "root" },
{ "path": "tests/test_session.py", "type": "write", "size": "4.7 KB", "change": "+47 -0", "child_plan": "root" },
{ "path": "src/auth/tokens.py", "type": "edit", "size": "1.8 KB", "change": "+4 -2", "child_plan": "root" },
{ "path": "tests/test_tokens.py", "type": "write", "size": "3.2 KB", "change": "+32 -0", "child_plan": "auth" }
],
"summary": {
"total": 4,
"writes": 2,
"edits": 2,
"deletes": 0,
"total_size": "11.8 KB"
},
"by_plan": {
"root": 3,
"auth-tests": 1,
"payment-tests": "pending"
}
},
"timing": { "started": "2025-06-15T10:33:00Z", "duration_ms": 480 },
"messages": ["4 artifacts listed"]
}
```
=== "YAML"
```yaml
command: plan artifacts
status: ok
exit_code: 0
data:
artifacts:
- path: src/auth/session.py
type: write
size: "2.1 KB"
change: "+8 -2"
child_plan: root
- path: tests/test_session.py
type: write
size: "4.7 KB"
change: "+47 -0"
child_plan: root
- path: src/auth/tokens.py
type: edit
size: "1.8 KB"
change: "+4 -2"
child_plan: root
- path: tests/test_tokens.py
type: write
size: "3.2 KB"
change: "+32 -0"
child_plan: auth
summary:
total: 4
writes: 2
edits: 2
deletes: 0
total_size: "11.8 KB"
by_plan:
root: 3
auth-tests: 1
payment-tests: pending
timing:
started: "2025-06-15T10:33:00Z"
duration_ms: 480
messages:
- "4 artifacts listed"
```
agents plan prompt
agents plan prompt <PLAN_ID> <GUIDANCE>Purpose Provide additional guidance to a plan, typically when it is errored or awaiting input.
Arguments
<PLAN_ID>: Plan ID."<GUIDANCE>": Guidance text.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan prompt 01HXM8C2ZK4Q7C2B3F2R4VYV6J <span style="color: #66cc66;">"Use mocks for database tests"</span>
╭─ Guidance Added ────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Plan:</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
│ <span style="color: magenta; font-weight: 600;">Guidance:</span> Use mocks for database tests │
│ <span style="color: #5599ff; font-weight: 600;">Scope:</span> next execution step │
│ <span style="color: #5599ff; font-weight: 600;">Phase:</span> execute │
│ <span style="color: #5599ff; font-weight: 600;">State:</span> errored → processing │
╰─────────────────────────────────────────╯
╭─ Decision Created ────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> user_intervention │
│ <span style="color: #5599ff; font-weight: 600;">ID:</span> 01HXM9C5G7R2X8S3K4Z5Q8R6Y3 │
│ <span style="color: #5599ff; font-weight: 600;">Parent:</span> 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 │
╰───────────────────────────────────────────╯
╭─ Queue ────╮
│ <span style="color: yellow; font-weight: 600;">Pending:</span> 1 │
│ <span style="color: #66cc66; font-weight: 600;">Applied:</span> 0 │
╰────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Guidance queued
</code></pre></div>
=== "Plain"
```
$ agents plan prompt 01HXM8C2ZK4Q7C2B3F2R4VYV6J "Use mocks for database tests"
Guidance Added
Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
Guidance: Use mocks for database tests
Scope: next execution step
Phase: execute
State: errored -> processing
Decision Created
Type: user_intervention
ID: 01HXM9C5G7R2X8S3K4Z5Q8R6Y3
Parent: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9
Queue
Pending: 1
Applied: 0
[OK] Guidance queued
```
=== "JSON"
```json
{
"command": "plan prompt",
"status": "ok",
"exit_code": 0,
"data": {
"guidance_added": {
"plan": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
"guidance": "Use mocks for database tests",
"scope": "next execution step",
"phase": "execute",
"state_transition": "errored -> processing"
},
"decision_created": {
"type": "user_intervention",
"id": "01HXM9C5G7R2X8S3K4Z5Q8R6Y3",
"parent": "01HXM9A1C2Q7W3R5G8Z0P4Q1X9"
},
"queue": {
"pending": 1,
"applied": 0
}
},
"timing": { "started": "2025-06-15T10:35:00Z", "duration_ms": 620 },
"messages": ["Guidance queued"]
}
```
=== "YAML"
```yaml
command: plan prompt
status: ok
exit_code: 0
data:
guidance_added:
plan: "01HXM8C2ZK4Q7C2B3F2R4VYV6J"
guidance: "Use mocks for database tests"
scope: next execution step
phase: execute
state_transition: "errored -> processing"
decision_created:
type: user_intervention
id: "01HXM9C5G7R2X8S3K4Z5Q8R6Y3"
parent: "01HXM9A1C2Q7W3R5G8Z0P4Q1X9"
queue:
pending: 1
applied: 0
timing:
started: "2025-06-15T10:35:00Z"
duration_ms: 620
messages:
- "Guidance queued"
```
agents plan rollback
agents plan rollback [--yes|-y] <PLAN_ID> <CHECKPOINT_ID>!!! danger "Destructive Operation" Rollback a plan sandbox to a previous checkpoint. All changes made ==after== the target checkpoint are reverted: files are restored or removed, decisions are discarded, and tool calls are undone. Child plans spawned after the checkpoint are invalidated.
Arguments
<PLAN_ID>: Plan ID.<CHECKPOINT_ID>: Checkpoint ID.--yes: Skip confirmation.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan rollback 01HXM8C2ZK4Q7C2B3F2R4VYV6J cp_01HXM8C2
Rollback plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J to cp_01HXM8C2? [y/N]: y
╭─ Rollback Summary ───────────────╮
│ <span style="color: cyan; font-weight: 600;">Plan:</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
│ <span style="color: magenta; font-weight: 600;">Checkpoint:</span> cp_01HXM8C2 │
│ <span style="color: yellow; font-weight: 600;">Label:</span> before auth refactor │
│ <span style="color: yellow; font-weight: 600;">Files:</span> 6 reverted │
╰──────────────────────────────────╯
╭─ Changes Reverted ──────────────────╮
│ <span style="color: yellow; font-weight: 600;">File</span> <span style="color: yellow; font-weight: 600;">Action</span> │
│ <span style="opacity: 0.7;">────────────────────── ──────────</span> │
│ src/auth/session.py restored │
│ src/auth/tokens.py restored │
│ tests/test_session.py removed │
│ tests/test_tokens.py removed │
│ src/auth/fixtures.py restored │
│ src/auth/__init__.py restored │
╰─────────────────────────────────────╯
╭─ Impact ──────────────────────────────╮
│ <span style="color: yellow; font-weight: 600;">Child Plans Invalidated:</span> 2 │
│ <span style="color: #5599ff; font-weight: 600;">Sandbox:</span> restored to cp_01HXM8C2 │
│ <span style="color: #5599ff; font-weight: 600;">Decisions After CP:</span> 2 discarded │
│ <span style="color: #5599ff; font-weight: 600;">Tool Calls After CP:</span> 5 undone │
╰───────────────────────────────────────╯
╭─ Post-Rollback State ──────────╮
│ <span style="color: yellow; font-weight: 600;">Phase:</span> execute │
│ <span style="color: #5599ff; font-weight: 600;">State:</span> queued (awaiting input) │
│ <span style="color: #5599ff; font-weight: 600;">Checkpoints Remaining:</span> 2 │
╰────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Rollback complete
</code></pre></div>
=== "Plain"
```
$ agents plan rollback 01HXM8C2ZK4Q7C2B3F2R4VYV6J cp_01HXM8C2
Rollback plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J to cp_01HXM8C2? [y/N]: y
Rollback Summary
Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
Checkpoint: cp_01HXM8C2
Label: before auth refactor
Files: 6 reverted
Changes Reverted
File Action
---------------------- ----------
src/auth/session.py restored
src/auth/tokens.py restored
tests/test_session.py removed
tests/test_tokens.py removed
src/auth/fixtures.py restored
src/auth/__init__.py restored
Impact
Child Plans Invalidated: 2
Sandbox: restored to cp_01HXM8C2
Decisions After CP: 2 discarded
Tool Calls After CP: 5 undone
Post-Rollback State
Phase: execute
State: queued (awaiting input)
Checkpoints Remaining: 2
[OK] Rollback complete
```
=== "JSON"
```json
{
"command": "plan rollback",
"status": "ok",
"exit_code": 0,
"data": {
"rollback_summary": {
"plan": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
"checkpoint": "cp_01HXM8C2",
"label": "before auth refactor",
"files_reverted": 6
},
"changes_reverted": [
{ "file": "src/auth/session.py", "action": "restored" },
{ "file": "src/auth/tokens.py", "action": "restored" },
{ "file": "tests/test_session.py", "action": "removed" },
{ "file": "tests/test_tokens.py", "action": "removed" },
{ "file": "src/auth/fixtures.py", "action": "restored" },
{ "file": "src/auth/__init__.py", "action": "restored" }
],
"impact": {
"child_plans_invalidated": 2,
"sandbox": "restored to cp_01HXM8C2",
"decisions_after_cp": "2 discarded",
"tool_calls_after_cp": "5 undone"
},
"post_rollback_state": {
"phase": "execute",
"state": "queued (awaiting input)",
"checkpoints_remaining": 2
}
},
"timing": { "started": "2025-06-15T10:37:00Z", "duration_ms": 1850 },
"messages": ["Rollback complete"]
}
```
=== "YAML"
```yaml
command: plan rollback
status: ok
exit_code: 0
data:
rollback_summary:
plan: "01HXM8C2ZK4Q7C2B3F2R4VYV6J"
checkpoint: cp_01HXM8C2
label: before auth refactor
files_reverted: 6
changes_reverted:
- file: src/auth/session.py
action: restored
- file: src/auth/tokens.py
action: restored
- file: tests/test_session.py
action: removed
- file: tests/test_tokens.py
action: removed
- file: src/auth/fixtures.py
action: restored
- file: src/auth/__init__.py
action: restored
impact:
child_plans_invalidated: 2
sandbox: "restored to cp_01HXM8C2"
decisions_after_cp: "2 discarded"
tool_calls_after_cp: "5 undone"
post_rollback_state:
phase: execute
state: "queued (awaiting input)"
checkpoints_remaining: 2
timing:
started: "2025-06-15T10:37:00Z"
duration_ms: 1850
messages:
- "Rollback complete"
```
agents action
!!! info "Purpose" Manage ==reusable actions== — named templates that define a complete unit of work including strategy actors, execution actors, definition of done, arguments, and invariants. Actions serve as the entry point to the plan lifecycle.
??? tip "Action vs Plan"
An action is a ==template==; a plan is an ==instance==. When you run agents plan use <ACTION> <PROJECT>, the action template spawns a new plan that progresses through the lifecycle phases. Actions can be reused many times (default) or configured as single-use (reusable: false).
agents action create
agents action create --config|-c <CFG_FILE>Purpose
Create a new action template from a YAML configuration file. The --config file is required and must fully define the action.
Arguments
--config/-c FILE: YAML configuration file defining the action (required). The file must fully define the action, including thenamefield,strategy-actor,execution-actor, anddefinition-of-done.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> action create <span style="color: cyan;">--config</span> ./actions/code-coverage.yaml
╭─ Action Created ────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/code-coverage │
│ <span style="color: yellow; font-weight: 600;">State:</span> available │
│ <span style="color: magenta; font-weight: 600;">Strategy Actor:</span> local/strategist │
│ <span style="color: magenta; font-weight: 600;">Execution Actor:</span> local/executor │
│ <span style="color: #66cc66; font-weight: 600;">Reusable:</span> yes │
│ <span style="color: #5599ff; font-weight: 600;">Read Only:</span> no │
│ <span style="color: #66cc66; font-weight: 600;">Config:</span> ./actions/code-coverage.yaml │
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-08 12:20 │
╰─────────────────────────────────────────╯
╭─ Definition of Done ─╮
│ Coverage reaches 85% │
╰──────────────────────╯
╭─ Arguments ──────────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name</span> <span style="color: cyan; font-weight: 600;">Type</span> <span style="color: cyan; font-weight: 600;">Required</span> <span style="color: cyan; font-weight: 600;">Description</span> │
│ <span style="opacity: 0.7;">─────────────────────── ────── ──────── ─────────────────────</span> │
│ target_coverage_percent int yes Target coverage % │
│ test_command string no Test framework to use │
╰──────────────────────────────────────────────────────────────────╯
╭─ Automation ──────────────────────────╮
│ <span style="color: magenta; font-weight: 600;">Profile:</span> supervised │
│ <span style="color: #5599ff; font-weight: 600;">Source:</span> default │
╰───────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Action created
</code></pre></div>
=== "Plain"
```
$ agents action create --config ./actions/code-coverage.yaml
Action Created
Name: local/code-coverage
State: available
Strategy Actor: local/strategist
Execution Actor: local/executor
Reusable: yes
Read Only: no
Config: ./actions/code-coverage.yaml
Created: 2026-02-08 12:20
Definition of Done
Coverage reaches 85%
Arguments
Name Type Required Description
----------------------- ------ -------- ---------------------
target_coverage_percent int yes Target coverage %
test_command string no Test framework to use
Automation
Profile: supervised
Source: default
[OK] Action created
```
=== "JSON"
```json
{
"command": "action create",
"status": "ok",
"exit_code": 0,
"data": {
"name": "local/code-coverage",
"state": "available",
"strategy_actor": "local/strategist",
"execution_actor": "local/executor",
"reusable": true,
"read_only": false,
"config": "./actions/code-coverage.yaml",
"created": "2026-02-08T12:20:00Z",
"definition_of_done": "Coverage reaches 85%",
"arguments": [
{ "name": "target_coverage_percent", "type": "int", "required": true, "description": "Target coverage %" },
{ "name": "test_command", "type": "string", "required": false, "description": "Test framework to use" }
],
"automation": {
"profile": "supervised",
"source": "default"
}
},
"timing": { "started": "2026-02-08T12:20:00Z", "duration_ms": 110 },
"messages": ["Action created"]
}
```
=== "YAML"
```yaml
command: action create
status: ok
exit_code: 0
data:
name: local/code-coverage
state: available
strategy_actor: local/strategist
execution_actor: local/executor
reusable: true
read_only: false
config: "./actions/code-coverage.yaml"
created: "2026-02-08T12:20:00Z"
definition_of_done: "Coverage reaches 85%"
arguments:
- name: target_coverage_percent
type: int
required: true
description: "Target coverage %"
- name: test_command
type: string
required: false
description: "Test framework to use"
automation:
profile: supervised
source: default
timing:
started: "2026-02-08T12:20:00Z"
duration_ms: 110
messages:
- "Action created"
```
agents action list
agents action list [(--namespace|-n) <NS>] [(--state|-s) <STATE>] [<REGEX>]Purpose List actions with optional filters.
Arguments
--namespace/-n NS: Filter by namespace.--state/-s STATE: Filter by state.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> action list
╭─ Actions ──────────────────────────────────────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name</span> <span style="color: cyan; font-weight: 600;">State</span> <span style="color: cyan; font-weight: 600;">Strategy Actor</span> <span style="color: cyan; font-weight: 600;">Execution Actor</span> <span style="color: cyan; font-weight: 600;">Reusable</span> <span style="color: cyan; font-weight: 600;">Plans</span> │
│ <span style="opacity: 0.7;">─────────────────── ───────── ──────────────── ─────────────── ──────── ─────</span> │
│ local/code-coverage available local/strategist local/executor ✓ 3 │
╰────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Filters ────────╮
│ <span style="color: yellow; font-weight: 600;">State:</span> available │
│ <span style="color: #5599ff; font-weight: 600;">Namespace:</span> (any) │
╰──────────────────╯
╭─ Summary ──────────────╮
│ <span style="color: yellow; font-weight: 600;">Total:</span> 1 │
│ <span style="color: #66cc66; font-weight: 600;">Available:</span> 1 │
│ <span style="color: yellow; font-weight: 600;">Archived:</span> 0 │
│ <span style="color: #5599ff; font-weight: 600;">Total Plans Created:</span> 3 │
╰────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 1 action listed
</code></pre></div>
=== "Plain"
```
$ agents action list
Actions
Name State Strategy Actor Execution Actor Reusable Plans
------------------- --------- ---------------- --------------- -------- -----
local/code-coverage available local/strategist local/executor yes 3
Filters
State: available
Namespace: (any)
Summary
Total: 1
Available: 1
Archived: 0
Total Plans Created: 3
[OK] 1 action listed
```
=== "JSON"
```json
{
"command": "action list",
"status": "ok",
"exit_code": 0,
"data": {
"actions": [
{
"name": "local/code-coverage",
"state": "available",
"strategy_actor": "local/strategist",
"execution_actor": "local/executor",
"reusable": true,
"plans": 3
}
],
"filters": { "state": "available", "namespace": null },
"summary": { "total": 1, "available": 1, "archived": 0, "total_plans_created": 3 }
},
"timing": { "started": "2026-02-08T12:21:00Z", "duration_ms": 45 },
"messages": ["1 action listed"]
}
```
=== "YAML"
```yaml
command: action list
status: ok
exit_code: 0
data:
actions:
- name: local/code-coverage
state: available
strategy_actor: local/strategist
execution_actor: local/executor
reusable: true
plans: 3
filters:
state: available
namespace: null
summary:
total: 1
available: 1
archived: 0
total_plans_created: 3
timing:
started: "2026-02-08T12:21:00Z"
duration_ms: 45
messages:
- "1 action listed"
```
agents action show
agents action show <ACTION_NAME>Purpose Show details for an action.
Arguments
<ACTION_NAME>: Action name.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> action show local/code-coverage
╭─ Action Details ──────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/code-coverage │
│ <span style="color: yellow; font-weight: 600;">State:</span> available │
│ <span style="color: magenta; font-weight: 600;">Strategy Actor:</span> local/strategist │
│ <span style="color: magenta; font-weight: 600;">Execution Actor:</span> local/executor │
│ <span style="color: #66cc66; font-weight: 600;">Reusable:</span> yes │
│ <span style="color: #5599ff; font-weight: 600;">Read Only:</span> no │
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-08 12:20 │
╰───────────────────────────────────────╯
╭─ Definition of Done ─╮
│ Coverage reaches 85% │
╰──────────────────────╯
╭─ Arguments ──────────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name</span> <span style="color: cyan; font-weight: 600;">Type</span> <span style="color: cyan; font-weight: 600;">Required</span> <span style="color: cyan; font-weight: 600;">Description</span> │
│ <span style="opacity: 0.7;">─────────────────────── ────── ──────── ─────────────────────</span> │
│ target_coverage_percent int yes Target coverage % │
│ test_command string no Test framework to use │
╰──────────────────────────────────────────────────────────────────╯
╭─ Automation ──────────────────────────╮
│ <span style="color: magenta; font-weight: 600;">Profile:</span> supervised │
│ <span style="color: #5599ff; font-weight: 600;">Source:</span> default │
╰───────────────────────────────────────╯
╭─ History ────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Plans Created:</span> 3 │
│ <span style="color: #66cc66; font-weight: 600;">Plans Completed:</span> 2 │
│ <span style="color: #ff6666; font-weight: 600;">Plans Failed:</span> 0 │
│ <span style="color: yellow; font-weight: 600;">Avg Duration:</span> 00:04:30 │
│ <span style="color: #5599ff; font-weight: 600;">Avg Cost:</span> $0.072 │
╰──────────────────────────────╯
╭─ Usage ───────────────────────────────────────────────────────────╮
│ - agents plan use local/code-coverage local/api-service │
│ <span style="color: cyan;">--arg</span> target_coverage_percent=85 │
╰───────────────────────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Action loaded
</code></pre></div>
=== "Plain"
```
$ agents action show local/code-coverage
Action Details
Name: local/code-coverage
State: available
Strategy Actor: local/strategist
Execution Actor: local/executor
Reusable: yes
Read Only: no
Created: 2026-02-08 12:20
Definition of Done
Coverage reaches 85%
Arguments
Name Type Required Description
----------------------- ------ -------- ---------------------
target_coverage_percent int yes Target coverage %
test_command string no Test framework to use
Automation
Profile: supervised
Source: default
History
Plans Created: 3
Plans Completed: 2
Plans Failed: 0
Avg Duration: 00:04:30
Avg Cost: $0.072
Usage
agents plan use local/code-coverage local/api-service
--arg target_coverage_percent=85
[OK] Action loaded
```
=== "JSON"
```json
{
"command": "action show",
"status": "ok",
"exit_code": 0,
"data": {
"name": "local/code-coverage",
"state": "available",
"strategy_actor": "local/strategist",
"execution_actor": "local/executor",
"reusable": true,
"read_only": false,
"created": "2026-02-08T12:20:00Z",
"definition_of_done": "Coverage reaches 85%",
"arguments": [
{ "name": "target_coverage_percent", "type": "int", "required": true, "description": "Target coverage %" },
{ "name": "test_command", "type": "string", "required": false, "description": "Test framework to use" }
],
"automation": { "profile": "supervised", "source": "default" },
"history": {
"plans_created": 3,
"plans_completed": 2,
"plans_failed": 0,
"avg_duration": "00:04:30",
"avg_cost": "$0.072"
}
},
"timing": { "started": "2026-02-08T12:21:00Z", "duration_ms": 60 },
"messages": ["Action loaded"]
}
```
=== "YAML"
```yaml
command: action show
status: ok
exit_code: 0
data:
name: local/code-coverage
state: available
strategy_actor: local/strategist
execution_actor: local/executor
reusable: true
read_only: false
created: "2026-02-08T12:20:00Z"
definition_of_done: "Coverage reaches 85%"
arguments:
- name: target_coverage_percent
type: int
required: true
description: "Target coverage %"
- name: test_command
type: string
required: false
description: "Test framework to use"
automation:
profile: supervised
source: default
history:
plans_created: 3
plans_completed: 2
plans_failed: 0
avg_duration: "00:04:30"
avg_cost: "$0.072"
timing:
started: "2026-02-08T12:21:00Z"
duration_ms: 60
messages:
- "Action loaded"
```
agents action archive
agents action archive <ACTION_NAME>Purpose Archive an action.
Arguments
<ACTION_NAME>: Action name.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> action archive local/old-action
╭─ Action Archived ───────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/old-action │
│ <span style="color: yellow; font-weight: 600;">State:</span> available → archived │
│ <span style="color: #66cc66; font-weight: 600;">Archived:</span> 2026-02-08 12:22 │
╰─────────────────────────────╯
╭─ Impact ───────────────────────╮
│ <span style="color: yellow; font-weight: 600;">Availability:</span> hidden from list │
│ <span style="color: #5599ff; font-weight: 600;">Existing Plans:</span> unchanged │
│ <span style="color: #5599ff; font-weight: 600;">Active Plans:</span> 0 affected │
╰────────────────────────────────╯
╭─ History ─────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Total Plans:</span> 5 │
│ <span style="color: #66cc66; font-weight: 600;">Completed:</span> 4 │
│ <span style="color: #ff6666; font-weight: 600;">Failed:</span> 1 │
│ <span style="color: #5599ff; font-weight: 600;">Last Used:</span> 2026-02-06 │
╰───────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Action archived
</code></pre></div>
=== "Plain"
```
$ agents action archive local/old-action
Action Archived
Name: local/old-action
State: available -> archived
Archived: 2026-02-08 12:22
Impact
Availability: hidden from list
Existing Plans: unchanged
Active Plans: 0 affected
History
Total Plans: 5
Completed: 4
Failed: 1
Last Used: 2026-02-06
[OK] Action archived
```
=== "JSON"
```json
{
"command": "action archive",
"status": "ok",
"exit_code": 0,
"data": {
"name": "local/old-action",
"state_transition": "available -> archived",
"archived": "2026-02-08T12:22:00Z",
"impact": {
"availability": "hidden from list",
"existing_plans": "unchanged",
"active_plans_affected": 0
},
"history": {
"total_plans": 5,
"completed": 4,
"failed": 1,
"last_used": "2026-02-06"
}
},
"timing": { "started": "2026-02-08T12:22:00Z", "duration_ms": 55 },
"messages": ["Action archived"]
}
```
=== "YAML"
```yaml
command: action archive
status: ok
exit_code: 0
data:
name: local/old-action
state_transition: "available -> archived"
archived: "2026-02-08T12:22:00Z"
impact:
availability: hidden from list
existing_plans: unchanged
active_plans_affected: 0
history:
total_plans: 5
completed: 4
failed: 1
last_used: "2026-02-06"
timing:
started: "2026-02-08T12:22:00Z"
duration_ms: 55
messages:
- "Action archived"
```
agents automation-profile
!!! info "Purpose"
Manage ==automation profiles== — named collections of confidence thresholds (floating-point values from 0.0 to 1.0) that control which tasks are automated vs. require human approval. Each threshold specifies the minimum confidence level at which the system proceeds automatically; below the threshold, the system drops to manual mode.
!!! tip "Threshold Scale"
| Value | Meaning |
| :---: | :------ |
| 0.0 | ==Always automatic== — no human approval needed |
| 0.5 | Automatic when confidence ≥ 50% |
| 1.0 | ==Always manual== — always requires human approval |
??? example "Built-in Profiles" The following profiles are always available and cannot be removed:
| Profile | Description |
| :------ | :---------- |
| `manual` | All thresholds at `1.0` — everything requires approval |
| `review` | Automatic strategize and execute, manual apply |
| `supervised` | Automatic strategize, manual execute and apply |
| `cautious` | Most operations automatic, manual for risky decisions |
| `trusted` | Nearly fully automatic, manual only for apply |
| `auto` | Fully automatic except apply |
| `ci` | Optimized for CI/CD pipelines |
| `full-auto` | All thresholds at `0.0` — fully autonomous |
Custom profiles follow the same `<namespace>/<name>` naming convention as other entities.
agents automation-profile add
agents automation-profile add --config|-c <FILE> [--update]Purpose
Register a new custom automation profile from a YAML configuration file. The profile is fully defined by the config file. If a profile with the same name already exists, the command fails unless the --update flag is provided.
Arguments
--config/-c FILE: YAML configuration file defining the profile (required). The file must fully define the profile, including thenamefield which determines the profile's registered name.--update: Replace an existing profile with the same name.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> automation-profile add <span style="color: cyan;">--config</span> ./profiles/careful-auto.yaml
╭─ Profile Registered ─────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/careful-auto │
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> Autonomous execution with mandatory sandbox │
│ and manual apply │
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-08 14:30 │
╰──────────────────────────────────────────────────────────────────╯
╭─ Confidence Thresholds ────────────────╮
│ <span style="color: #66cc66; font-weight: 600;">decompose_task:</span> 0.0 │
│ <span style="color: #66cc66; font-weight: 600;">create_tool:</span> 0.0 │
│ <span style="color: #ff6666; font-weight: 600;">select_tool:</span> 1.0 │
│ <span style="color: #66cc66; font-weight: 600;">edit_code:</span> 0.0 │
│ <span style="color: #66cc66; font-weight: 600;">execute_command:</span> 0.0 │
│ <span style="color: #66cc66; font-weight: 600;">create_file:</span> 0.0 │
│ <span style="color: #ff6666; font-weight: 600;">delete_content:</span> 1.0 │
│ <span style="color: #ff6666; font-weight: 600;">access_network:</span> 1.0 │
│ <span style="color: #66cc66; font-weight: 600;">install_dependency:</span> 0.0 │
│ <span style="color: #66cc66; font-weight: 600;">modify_config:</span> 0.0 │
│ <span style="color: #66cc66; font-weight: 600;">approve_plan:</span> 0.0 │
│ <span style="color: #66cc66; font-weight: 600;">require_sandbox:</span> true │
│ <span style="color: #66cc66; font-weight: 600;">require_checkpoints:</span> true │
│ <span style="color: #ff6666; font-weight: 600;">allow_unsafe_tools:</span> false │
╰────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Profile registered
</code></pre></div>
=== "Plain"
```
$ agents automation-profile add --config ./profiles/careful-auto.yaml
Profile Registered
Name: local/careful-auto
Description: Autonomous execution with mandatory sandbox and manual apply
Created: 2026-02-08 14:30
Confidence Thresholds
decompose_task: 0.0
create_tool: 0.0
select_tool: 1.0
edit_code: 0.0
execute_command: 0.0
create_file: 0.0
delete_content: 1.0
access_network: 1.0
install_dependency: 0.0
modify_config: 0.0
approve_plan: 0.0
require_sandbox: true
require_checkpoints: true
allow_unsafe_tools: false
[OK] Profile registered
```
=== "JSON"
```json
{
"command": "automation-profile add",
"status": "ok",
"exit_code": 0,
"data": {
"name": "local/careful-auto",
"description": "Autonomous execution with mandatory sandbox and manual apply",
"created": "2026-02-08T14:30:00Z",
"thresholds": {
"decompose_task": 0.0,
"create_tool": 0.0,
"select_tool": 1.0,
"edit_code": 0.0,
"execute_command": 0.0,
"create_file": 0.0,
"delete_content": 1.0,
"access_network": 1.0,
"install_dependency": 0.0,
"modify_config": 0.0,
"approve_plan": 0.0
},
"flags": {
"require_sandbox": true,
"require_checkpoints": true,
"allow_unsafe_tools": false
}
},
"timing": { "started": "2026-02-08T14:30:00Z", "duration_ms": 70 },
"messages": ["Profile registered"]
}
```
=== "YAML"
```yaml
command: automation-profile add
status: ok
exit_code: 0
data:
name: local/careful-auto
description: "Autonomous execution with mandatory sandbox and manual apply"
created: "2026-02-08T14:30:00Z"
thresholds:
decompose_task: 0.0
create_tool: 0.0
select_tool: 1.0
edit_code: 0.0
execute_command: 0.0
create_file: 0.0
delete_content: 1.0
access_network: 1.0
install_dependency: 0.0
modify_config: 0.0
approve_plan: 0.0
flags:
require_sandbox: true
require_checkpoints: true
allow_unsafe_tools: false
timing:
started: "2026-02-08T14:30:00Z"
duration_ms: 70
messages:
- "Profile registered"
```
agents automation-profile remove
agents automation-profile remove [--yes|-y] <NAME>!!! warning "Destructive Operation" Remove a custom automation profile. ==Built-in profiles cannot be removed.== Plans and projects currently referencing this profile will fall back to their inherited or global default profile.
Arguments
<NAME>: Profile name.--yes, -y: Skip confirmation prompt.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> automation-profile remove local/careful-auto
Remove automation profile local/careful-auto? [y/N]: y
╭─ Profile Removed ──────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/careful-auto │
╰────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Profile removed
</code></pre></div>
=== "Plain"
```
$ agents automation-profile remove local/careful-auto
Remove automation profile local/careful-auto? [y/N]: y
Profile Removed
Name: local/careful-auto
[OK] Profile removed
```
=== "JSON"
```json
{
"command": "automation-profile remove",
"status": "ok",
"exit_code": 0,
"data": {
"name": "local/careful-auto"
},
"timing": { "started": "2026-02-08T14:31:00Z", "duration_ms": 40 },
"messages": ["Profile removed"]
}
```
=== "YAML"
```yaml
command: automation-profile remove
status: ok
exit_code: 0
data:
name: local/careful-auto
timing:
started: "2026-02-08T14:31:00Z"
duration_ms: 40
messages:
- "Profile removed"
```
agents automation-profile list
agents automation-profile list [<REGEX>]Purpose List all available automation profiles (built-in and custom).
Arguments
[REGEX]: Optional filter pattern.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> automation-profile list
╭─ Automation Profiles ──────────────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name</span> <span style="color: cyan; font-weight: 600;">Source</span> <span style="color: cyan; font-weight: 600;">Auto-Apply</span> <span style="color: cyan; font-weight: 600;">Sandbox</span> <span style="color: cyan; font-weight: 600;">Description</span> │
│ <span style="opacity: 0.7;">────────────────── ──────── ────────── ─────── ────────────────────────</span> │
│ manual built-in 1.0 yes Human-driven (default) │
│ review built-in 1.0 yes Auto-phase, manual decisions │
│ supervised built-in 1.0 yes Auto-plan, manual exec │
│ cautious built-in 1.0 yes Confidence-gated automation │
│ trusted built-in 1.0 yes Auto-exec, manual apply │
│ auto built-in 1.0 yes Full auto except apply │
│ ci built-in 0.0 yes Full auto, safe CI/CD │
│ full-auto built-in 0.0 no Complete automation │
│ local/careful-auto custom 0.8 yes Custom careful profile │
╰────────────────────────────────────────────────────────────────────────────────╯
╭─ Summary ───────────╮
│ <span style="color: #5599ff; font-weight: 600;">Built-in:</span> 8 │
│ <span style="color: #5599ff; font-weight: 600;">Custom:</span> 1 │
│ <span style="color: #5599ff; font-weight: 600;">Total:</span> 9 │
╰─────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 9 profiles listed
</code></pre></div>
=== "Plain"
```
$ agents automation-profile list
Automation Profiles
Name Source Auto-Apply Sandbox Description
------------------ -------- ---------- ------- ----------------------------
manual built-in 1.0 yes Human-driven (default)
review built-in 1.0 yes Auto-phase, manual decisions
supervised built-in 1.0 yes Auto-plan, manual exec
cautious built-in 1.0 yes Confidence-gated automation
trusted built-in 1.0 yes Auto-exec, manual apply
auto built-in 1.0 yes Full auto except apply
ci built-in 0.0 yes Full auto, safe CI/CD
full-auto built-in 0.0 no Complete automation
local/careful-auto custom 0.8 yes Custom careful profile
Summary
Built-in: 8
Custom: 1
Total: 9
[OK] 9 profiles listed
```
=== "JSON"
```json
{
"command": "automation-profile list",
"status": "ok",
"exit_code": 0,
"data": {
"profiles": [
{ "name": "manual", "source": "built-in", "select_tool": 1.0, "sandbox": true, "description": "Human-driven (default)" },
{ "name": "review", "source": "built-in", "select_tool": 1.0, "sandbox": true, "description": "Auto-phase, manual decisions" },
{ "name": "supervised", "source": "built-in", "select_tool": 1.0, "sandbox": true, "description": "Auto-plan, manual exec" },
{ "name": "cautious", "source": "built-in", "select_tool": 1.0, "sandbox": true, "description": "Confidence-gated automation" },
{ "name": "trusted", "source": "built-in", "select_tool": 1.0, "sandbox": true, "description": "Auto-exec, manual apply" },
{ "name": "auto", "source": "built-in", "select_tool": 1.0, "sandbox": true, "description": "Full auto except apply" },
{ "name": "ci", "source": "built-in", "select_tool": 0.0, "sandbox": true, "description": "Full auto, safe CI/CD" },
{ "name": "full-auto", "source": "built-in", "select_tool": 0.0, "sandbox": false, "description": "Complete automation" },
{ "name": "local/careful-auto", "source": "custom", "select_tool": 0.8, "sandbox": true, "description": "Custom careful profile" }
],
"summary": { "built_in": 8, "custom": 1, "total": 9 }
},
"timing": { "started": "2026-02-08T14:31:00Z", "duration_ms": 50 },
"messages": ["9 profiles listed"]
}
```
=== "YAML"
```yaml
command: automation-profile list
status: ok
exit_code: 0
data:
profiles:
- name: manual
source: built-in
select_tool: 1.0
sandbox: true
description: "Human-driven (default)"
- name: review
source: built-in
select_tool: 1.0
sandbox: true
description: "Auto-phase, manual decisions"
- name: supervised
source: built-in
select_tool: 1.0
sandbox: true
description: "Auto-plan, manual exec"
- name: cautious
source: built-in
select_tool: 1.0
sandbox: true
description: "Confidence-gated automation"
- name: trusted
source: built-in
select_tool: 1.0
sandbox: true
description: "Auto-exec, manual apply"
- name: auto
source: built-in
select_tool: 1.0
sandbox: true
description: "Full auto except apply"
- name: ci
source: built-in
select_tool: 0.0
sandbox: true
description: "Full auto, safe CI/CD"
- name: full-auto
source: built-in
select_tool: 0.0
sandbox: false
description: "Complete automation"
- name: local/careful-auto
source: custom
select_tool: 0.8
sandbox: true
description: "Custom careful profile"
summary:
built_in: 8
custom: 1
total: 9
timing:
started: "2026-02-08T14:31:00Z"
duration_ms: 50
messages:
- "9 profiles listed"
```
agents automation-profile show
agents automation-profile show <NAME>Purpose Show full details for an automation profile, including all flag values.
Arguments
<NAME>: Profile name.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> automation-profile show trusted
╭─ Automation Profile ───────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> trusted │
│ <span style="color: #5599ff; font-weight: 600;">Source:</span> built-in │
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> Auto-exec, manual apply. Day-to-day development │
╰────────────────────────────────────────────────────────────────╯
╭─ Phase Transitions (thresholds) ─────╮
│ <span style="color: #66cc66; font-weight: 600;">decompose_task:</span> 0.0 │
│ <span style="color: #66cc66; font-weight: 600;">create_tool:</span> 0.0 │
│ <span style="color: #ff6666; font-weight: 600;">select_tool:</span> 1.0 │
╰──────────────────────────────────────╯
╭─ Decision Automation (thresholds) ───╮
│ <span style="color: #66cc66; font-weight: 600;">edit_code:</span> 0.0 │
│ <span style="color: #66cc66; font-weight: 600;">execute_command:</span> 0.0 │
╰──────────────────────────────────────╯
╭─ Self-Repair (thresholds) ───────────╮
│ <span style="color: #66cc66; font-weight: 600;">create_file:</span> 0.0 │
│ <span style="color: #ff6666; font-weight: 600;">delete_content:</span> 1.0 │
│ <span style="color: #ff6666; font-weight: 600;">access_network:</span> 1.0 │
│ <span style="color: #66cc66; font-weight: 600;">modify_config:</span> 0.0 │
│ <span style="color: #ff6666; font-weight: 600;">approve_plan:</span> 1.0 │
╰──────────────────────────────────────╯
╭─ Execution Controls (thresholds) ────╮
│ <span style="color: #66cc66; font-weight: 600;">install_dependency:</span> 0.0 │
│ <span style="color: #66cc66; font-weight: 600;">require_sandbox:</span> true │
│ <span style="color: #66cc66; font-weight: 600;">require_checkpoints:</span> true │
│ <span style="color: #ff6666; font-weight: 600;">allow_unsafe_tools:</span> false │
╰──────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Profile loaded
</code></pre></div>
=== "Plain"
```
$ agents automation-profile show trusted
Automation Profile
Name: trusted
Source: built-in
Description: Auto-exec, manual apply. Day-to-day development
Phase Transitions (thresholds)
decompose_task: 0.0
create_tool: 0.0
select_tool: 1.0
Decision Automation (thresholds)
edit_code: 0.0
execute_command: 0.0
Self-Repair (thresholds)
create_file: 0.0
delete_content: 1.0
access_network: 1.0
modify_config: 0.0
approve_plan: 1.0
Execution Controls (thresholds)
install_dependency: 0.0
require_sandbox: true
require_checkpoints: true
allow_unsafe_tools: false
[OK] Profile loaded
```
=== "JSON"
```json
{
"command": "automation-profile show",
"status": "ok",
"exit_code": 0,
"data": {
"name": "trusted",
"source": "built-in",
"description": "Auto-exec, manual apply. Day-to-day development",
"phase_transitions": {
"decompose_task": 0.0,
"create_tool": 0.0,
"select_tool": 1.0
},
"decision_automation": {
"edit_code": 0.0,
"execute_command": 0.0
},
"self_repair": {
"create_file": 0.0,
"delete_content": 1.0,
"access_network": 1.0,
"modify_config": 0.0,
"approve_plan": 1.0
},
"execution_controls": {
"install_dependency": 0.0,
"require_sandbox": true,
"require_checkpoints": true,
"allow_unsafe_tools": false
}
},
"timing": { "started": "2026-02-08T14:31:00Z", "duration_ms": 55 },
"messages": ["Profile loaded"]
}
```
=== "YAML"
```yaml
command: automation-profile show
status: ok
exit_code: 0
data:
name: trusted
source: built-in
description: "Auto-exec, manual apply. Day-to-day development"
phase_transitions:
decompose_task: 0.0
create_tool: 0.0
select_tool: 1.0
decision_automation:
edit_code: 0.0
execute_command: 0.0
self_repair:
create_file: 0.0
delete_content: 1.0
access_network: 1.0
modify_config: 0.0
approve_plan: 1.0
execution_controls:
install_dependency: 0.0
require_sandbox: true
require_checkpoints: true
allow_unsafe_tools: false
timing:
started: "2026-02-08T14:31:00Z"
duration_ms: 55
messages:
- "Profile loaded"
```
agents config
!!! info "Purpose"
Manage ==global configuration values== that control system-wide defaults. Configuration keys use hierarchical dot-path notation (e.g., core.automation-profile, core.log.level).
??? tip "Key Configuration Categories"
| Category | Example Keys | Description |
| :------- | :----------- | :---------- |
| Core | core.automation-profile, core.format, core.log.level | System-wide defaults |
| Actor | actor.default.invariant | Default actor assignments |
| Output | core.format | Default rendering format (rich, json, yaml, etc.) |
agents config set
agents config set <key> <value>Purpose Set a configuration key.
Arguments
<key>: Hierarchical dot-path key name (e.g.,core.automation-profile,core.log.level,actor.default.invariant,core.format). See Global Configuration Keys for the complete reference.<value>: Value to set.
The actor.default.invariant key sets the default Invariant Reconciliation Actor used globally. This actor is used to reconcile invariant conflicts when neither the plan nor the project specifies one.
The core.format key sets the default output rendering format used by all commands. Accepted values are rich, color, table, plain, json, yaml. When set, this value is used unless overridden by the --format CLI flag. See Output Rendering Framework for details.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> config set core.automation-profile trusted
╭─ Config Updated ──────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Key:</span> core.automation-profile │
│ <span style="color: #66cc66; font-weight: 600;">Value:</span> trusted │
│ <span style="color: yellow; font-weight: 600;">Previous:</span> manual │
│ <span style="color: #5599ff; font-weight: 600;">Source:</span> config │
│ <span style="color: yellow; font-weight: 600;">Scope:</span> global │
╰───────────────────────────────────────╯
╭─ Effective ────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Sessions:</span> new sessions │
│ <span style="color: yellow; font-weight: 600;">Plans:</span> future plans (unless set) │
│ <span style="color: #5599ff; font-weight: 600;">Existing:</span> unchanged │
╰────────────────────────────────────╯
╭─ Saved To ──────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">File:</span> ~/.cleveragents/config.toml │
│ <span style="color: #5599ff; font-weight: 600;">Line:</span> 8 │
╰─────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Config updated
</code></pre></div>
=== "Plain"
```
$ agents config set core.automation-profile trusted
Config Updated
Key: core.automation-profile
Value: trusted
Previous: manual
Source: config
Scope: global
Effective
Sessions: new sessions
Plans: future plans (unless set)
Existing: unchanged
Saved To
File: ~/.cleveragents/config.toml
Line: 8
[OK] Config updated
```
=== "JSON"
```json
{
"command": "config set",
"status": "ok",
"exit_code": 0,
"data": {
"key": "core.automation-profile",
"value": "trusted",
"previous": "manual",
"source": "config",
"scope": "global",
"effective": {
"sessions": "new sessions",
"plans": "future plans (unless set)",
"existing": "unchanged"
},
"saved_to": { "file": "~/.cleveragents/config.toml", "line": 8 }
},
"timing": { "started": "2026-02-08T14:32:00Z", "duration_ms": 30 },
"messages": ["Config updated"]
}
```
=== "YAML"
```yaml
command: config set
status: ok
exit_code: 0
data:
key: core.automation-profile
value: trusted
previous: manual
source: config
scope: global
effective:
sessions: new sessions
plans: "future plans (unless set)"
existing: unchanged
saved_to:
file: "~/.cleveragents/config.toml"
line: 8
timing:
started: "2026-02-08T14:32:00Z"
duration_ms: 30
messages:
- "Config updated"
```
Setting the default output format:
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> config set core.format table
╭─ Config Updated ─────────────────╮
│ <span style="color: cyan; font-weight: 600;">Key:</span> core.format │
│ <span style="color: #5599ff; font-weight: 600;">Previous:</span> rich │
│ <span style="color: #66cc66; font-weight: 600;">New Value:</span> table │
│ <span style="color: #5599ff; font-weight: 600;">Scope:</span> user (~/.cleveragents) │
╰──────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Set core.format = table
</code></pre></div>
=== "Plain"
```
$ agents config set core.format table
Config Updated
Key: core.format
Previous: rich
New Value: table
Scope: user (~/.cleveragents)
[OK] Set core.format = table
```
=== "JSON"
```json
{
"command": "config set",
"status": "ok",
"exit_code": 0,
"data": {
"key": "core.format",
"previous": "rich",
"value": "table",
"scope": "user (~/.cleveragents)"
},
"timing": { "started": "2026-02-08T14:32:00Z", "duration_ms": 25 },
"messages": ["Set core.format = table"]
}
```
=== "YAML"
```yaml
command: config set
status: ok
exit_code: 0
data:
key: core.format
previous: rich
value: table
scope: "user (~/.cleveragents)"
timing:
started: "2026-02-08T14:32:00Z"
duration_ms: 25
messages:
- "Set core.format = table"
```
Setting a global invariant actor:
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> config set actor.default.invariant local/invariant-resolver
╭─ Config Updated ──────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Key:</span> actor.default.invariant │
│ <span style="color: #5599ff; font-weight: 600;">Previous:</span> (not set) │
│ <span style="color: #66cc66; font-weight: 600;">New Value:</span> local/invariant-resolver │
│ <span style="color: #5599ff; font-weight: 600;">Scope:</span> user (~/.cleveragents) │
╰───────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Set actor.default.invariant = local/invariant-resolver
</code></pre></div>
=== "Plain"
```
$ agents config set actor.default.invariant local/invariant-resolver
Config Updated
Key: actor.default.invariant
Previous: (not set)
New Value: local/invariant-resolver
Scope: user (~/.cleveragents)
[OK] Set actor.default.invariant = local/invariant-resolver
```
=== "JSON"
```json
{
"command": "config set",
"status": "ok",
"exit_code": 0,
"data": {
"key": "actor.default.invariant",
"previous": null,
"value": "local/invariant-resolver",
"scope": "user (~/.cleveragents)"
},
"timing": { "started": "2026-02-08T14:32:00Z", "duration_ms": 28 },
"messages": ["Set actor.default.invariant = local/invariant-resolver"]
}
```
=== "YAML"
```yaml
command: config set
status: ok
exit_code: 0
data:
key: actor.default.invariant
previous: null
value: local/invariant-resolver
scope: "user (~/.cleveragents)"
timing:
started: "2026-02-08T14:32:00Z"
duration_ms: 28
messages:
- "Set actor.default.invariant = local/invariant-resolver"
```
agents config get
agents config get <key>Purpose Get a configuration value.
Arguments
<key>: Key to read.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> config get core.automation-profile
╭─ Config ──────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Key:</span> core.automation-profile │
│ <span style="color: #66cc66; font-weight: 600;">Value:</span> trusted │
│ <span style="color: #5599ff; font-weight: 600;">Source:</span> config │
│ <span style="color: yellow; font-weight: 600;">Overridden:</span> no │
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> string │
╰───────────────────────────────────╯
╭─ Origin ──────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">File:</span> ~/.cleveragents/config.toml │
│ <span style="color: #66cc66; font-weight: 600;">Line:</span> 8 │
│ <span style="color: #5599ff; font-weight: 600;">Default:</span> supervised │
╰───────────────────────────────────╯
╭─ Resolution Chain ──────────────╮
│ 1. CLI flag: (not set) │
│ 2. Env var: (not set) │
│ 3. Config file: trusted │
│ 4. Default: supervised │
│ <span style="color: #66cc66; font-weight: 600;">Winner:</span> config file (level 3) │
╰─────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Config read
</code></pre></div>
=== "Plain"
```
$ agents config get core.automation-profile
Config
Key: core.automation-profile
Value: trusted
Source: config
Overridden: no
Type: string
Origin
File: ~/.cleveragents/config.toml
Line: 8
Default: supervised
Resolution Chain
1. CLI flag: (not set)
2. Env var: (not set)
3. Config file: trusted
4. Default: supervised
Winner: config file (level 3)
[OK] Config read
```
=== "JSON"
```json
{
"command": "config get",
"status": "ok",
"exit_code": 0,
"data": {
"key": "core.automation-profile",
"value": "trusted",
"source": "config",
"overridden": false,
"type": "string",
"origin": {
"file": "~/.cleveragents/config.toml",
"line": 8,
"default": "supervised"
},
"resolution_chain": [
{ "level": 1, "source": "CLI flag", "value": null },
{ "level": 2, "source": "Env var", "value": null },
{ "level": 3, "source": "Config file", "value": "trusted" },
{ "level": 4, "source": "Default", "value": "supervised" }
],
"winner": { "source": "config file", "level": 3 }
},
"timing": { "started": "2026-02-08T14:33:00Z", "duration_ms": 20 },
"messages": ["Config read"]
}
```
=== "YAML"
```yaml
command: config get
status: ok
exit_code: 0
data:
key: core.automation-profile
value: trusted
source: config
overridden: false
type: string
origin:
file: "~/.cleveragents/config.toml"
line: 8
default: supervised
resolution_chain:
- level: 1
source: "CLI flag"
value: null
- level: 2
source: "Env var"
value: null
- level: 3
source: "Config file"
value: trusted
- level: 4
source: Default
value: supervised
winner:
source: "config file"
level: 3
timing:
started: "2026-02-08T14:33:00Z"
duration_ms: 20
messages:
- "Config read"
```
agents config list
agents config list [--filter-values <REGEX>] [<REGEX>]Purpose List all configuration values.
Arguments
None.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> config list
╭─ Config ───────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Key</span> <span style="color: cyan; font-weight: 600;">Value</span> <span style="color: cyan; font-weight: 600;">Source</span> <span style="color: cyan; font-weight: 600;">Modified</span> │
│ <span style="opacity: 0.7;">──────────────── ────────────────── ─────── ────────</span> │
│ core.automation-profile trusted config yes │
│ actor.default.invariant local/reconciler config yes │
│ core.log.level FATAL default no │
╰────────────────────────────────────────────────────────────╯
╭─ Overrides ─────╮
│ <span style="color: yellow; font-weight: 600;">Env:</span> none │
│ <span style="color: #5599ff; font-weight: 600;">CLI Flags:</span> none │
╰─────────────────╯
╭─ Config File ───────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Path:</span> ~/.cleveragents/config.toml │
│ <span style="color: #5599ff; font-weight: 600;">Size:</span> 284 bytes │
│ <span style="color: #66cc66; font-weight: 600;">Valid:</span> yes │
╰─────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 6 settings listed
</code></pre></div>
=== "Plain"
```
$ agents config list
Config
Key Value Source Modified
----------------------- ------------------ ------- --------
core.automation-profile trusted config yes
actor.default.invariant local/reconciler config yes
core.log.level FATAL default no
Overrides
Env: none
CLI Flags: none
Config File
Path: ~/.cleveragents/config.toml
Size: 284 bytes
Valid: yes
[OK] 6 settings listed
```
=== "JSON"
```json
{
"command": "config list",
"status": "ok",
"exit_code": 0,
"data": {
"settings": [
{ "key": "core.automation-profile", "value": "trusted", "source": "config", "modified": true },
{ "key": "actor.default.invariant", "value": "local/reconciler", "source": "config", "modified": true },
{ "key": "core.log.level", "value": "FATAL", "source": "default", "modified": false }
],
"overrides": { "env": null, "cli_flags": null },
"config_file": {
"path": "~/.cleveragents/config.toml",
"size_bytes": 284,
"valid": true
}
},
"timing": { "started": "2026-02-08T14:33:00Z", "duration_ms": 25 },
"messages": ["6 settings listed"]
}
```
=== "YAML"
```yaml
command: config list
status: ok
exit_code: 0
data:
settings:
- key: core.automation-profile
value: trusted
source: config
modified: true
- key: actor.default.invariant
value: local/reconciler
source: config
modified: true
- key: core.log.level
value: FATAL
source: default
modified: false
overrides:
env: null
cli_flags: null
config_file:
path: "~/.cleveragents/config.toml"
size_bytes: 284
valid: true
timing:
started: "2026-02-08T14:33:00Z"
duration_ms: 25
messages:
- "6 settings listed"
```
agents invariant
!!! info "Purpose" Manage ==invariants== — named constraints that guide and constrain plan execution. Invariants can be attached to any scope: global (all plans), project (all plans targeting that project), plan (a specific plan and its child plans), or action (carried forward when the action is used).
!!! warning "Scope Requirements"
Exactly ==one scope flag== is required for add and list. The available scopes are:
| Scope | Flag | Applies To |
| :---- | :--- | :--------- |
| **Global** | `--global` | All plans across all projects |
| **Project** | `--project <NAME>` | All plans targeting that project |
| **Plan** | `--plan <ID>` | A specific plan and its child plans |
| **Action** | `--action <NAME>` | Carried forward when the action is used |
When multiple scopes apply to a plan, the ==union== of all applicable invariants is enforced.
agents invariant add
agents invariant add [--global] [(--project|-p) PROJECT] [--plan PLAN_ID]...
[--action ACTION]... <INVARIANT_TEXT>Purpose Add an invariant at the specified scope.
Arguments
<INVARIANT_TEXT>: The invariant text (positional argument at end of command).--global: Attach as a global invariant (applies to all plans).--project/-p PROJECT: Attach to a project (applies to all plans targeting this project).--plan PLAN_ID: Attach to a plan (plan-level invariant). Repeatable.--action ACTION: Attach to an action (action-level invariant). Repeatable.
At least one scope flag (--global, --project, --plan, or --action) must be provided. --plan and --action can be repeated to attach the same invariant to multiple plans or actions.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> invariant add <span style="color: cyan;">--global</span> <span style="color: #66cc66;">"All public APIs must maintain backward compatibility"</span>
╭─ Invariant Added ──────────────────────────────────────────────────────╮
│ <span style="color: #66cc66; font-weight: 600;">Invariant:</span> All public APIs must maintain backward compatibility │
│ <span style="color: #5599ff; font-weight: 600;">Scope:</span> global │
│ <span style="color: #5599ff; font-weight: 600;">ID:</span> inv_01HXM9A1B │
╰────────────────────────────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Invariant added
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> invariant add <span style="color: cyan;">--project</span> local/api-service <span style="color: #66cc66;">"All endpoints must validate auth tokens"</span>
╭─ Invariant Added ──────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Project:</span> local/api-service │
│ <span style="color: #66cc66; font-weight: 600;">Invariant:</span> All endpoints must validate auth tokens │
│ <span style="color: #5599ff; font-weight: 600;">Scope:</span> project │
│ <span style="color: #5599ff; font-weight: 600;">ID:</span> inv_01HXM9A2C │
╰────────────────────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Invariant added
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> invariant add <span style="color: cyan;">--plan</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J <span style="color: #66cc66;">"All database queries must use parameterized statements"</span>
╭─ Invariant Added ─────────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Plan:</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
│ <span style="color: #66cc66; font-weight: 600;">Invariant:</span> All database queries must use parameterized statements │
│ <span style="color: #5599ff; font-weight: 600;">Scope:</span> plan │
│ <span style="color: #5599ff; font-weight: 600;">ID:</span> inv_01HXM9G3A │
╰───────────────────────────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Invariant added
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> invariant add <span style="color: cyan;">--action</span> local/code-coverage <span style="color: #66cc66;">"Test files must not import production secrets"</span>
╭─ Invariant Added ──────────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Action:</span> local/code-coverage │
│ <span style="color: #66cc66; font-weight: 600;">Invariant:</span> Test files must not import production secrets │
│ <span style="color: #5599ff; font-weight: 600;">Scope:</span> action │
│ <span style="color: #5599ff; font-weight: 600;">ID:</span> inv_01HXM9H4B │
╰────────────────────────────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Invariant added
</code></pre></div>
=== "Plain"
```
$ agents invariant add --global "All public APIs must maintain backward compatibility"
Invariant Added
Invariant: All public APIs must maintain backward compatibility
Scope: global
ID: inv_01HXM9A1B
[OK] Invariant added
$ agents invariant add --project local/api-service "All endpoints must validate auth tokens"
Invariant Added
Project: local/api-service
Invariant: All endpoints must validate auth tokens
Scope: project
ID: inv_01HXM9A2C
[OK] Invariant added
$ agents invariant add --plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J "All database queries must use parameterized statements"
Invariant Added
Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
Invariant: All database queries must use parameterized statements
Scope: plan
ID: inv_01HXM9G3A
[OK] Invariant added
$ agents invariant add --action local/code-coverage "Test files must not import production secrets"
Invariant Added
Action: local/code-coverage
Invariant: Test files must not import production secrets
Scope: action
ID: inv_01HXM9H4B
[OK] Invariant added
```
=== "JSON"
```json
{
"command": "invariant add",
"status": "ok",
"exit_code": 0,
"data": [
{
"invariant": "All public APIs must maintain backward compatibility",
"scope": "global",
"id": "inv_01HXM9A1B"
},
{
"project": "local/api-service",
"invariant": "All endpoints must validate auth tokens",
"scope": "project",
"id": "inv_01HXM9A2C"
},
{
"plan": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
"invariant": "All database queries must use parameterized statements",
"scope": "plan",
"id": "inv_01HXM9G3A"
},
{
"action": "local/code-coverage",
"invariant": "Test files must not import production secrets",
"scope": "action",
"id": "inv_01HXM9H4B"
}
],
"timing": { "started": "2026-02-08T14:35:00Z", "duration_ms": 45 },
"messages": ["Invariant added"]
}
```
=== "YAML"
```yaml
command: invariant add
status: ok
exit_code: 0
data:
- invariant: "All public APIs must maintain backward compatibility"
scope: global
id: inv_01HXM9A1B
- project: local/api-service
invariant: "All endpoints must validate auth tokens"
scope: project
id: inv_01HXM9A2C
- plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
invariant: "All database queries must use parameterized statements"
scope: plan
id: inv_01HXM9G3A
- action: local/code-coverage
invariant: "Test files must not import production secrets"
scope: action
id: inv_01HXM9H4B
timing:
started: "2026-02-08T14:35:00Z"
duration_ms: 45
messages:
- "Invariant added"
```
agents invariant list
agents invariant list [--global] [(--project|-p) PROJECT] [--plan PLAN_ID] [--action ACTION]
[--effective] [<REGEX>]Purpose
List invariants at a given scope. Use --effective with --plan to show the final reconciled view of invariants (after precedence resolution) rather than just the invariants directly attached at that scope.
Arguments
--global: List global invariants.--project/-p PROJECT: List invariants attached to a project.--plan PLAN_ID: List invariants attached to a plan.--action ACTION: List invariants attached to an action.--effective: (Only with--plan) Show the reconciled invariant view after precedence resolution across all scopes.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> invariant list <span style="color: cyan;">--global</span>
╭─ Global Invariants ──────────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">ID</span> <span style="color: cyan; font-weight: 600;">Text</span> │
│ <span style="opacity: 0.7;">────────────── ────────────────────────────────────────────────────</span> │
│ inv_01HXM9A1B All public APIs must maintain backward compatibility │
│ inv_01HXM9A1C Payment processing must be idempotent │
╰──────────────────────────────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 2 invariants
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> invariant list <span style="color: cyan;">--plan</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J <span style="color: cyan;">--effective</span>
╭─ Effective Invariants (Plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J) ──────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">ID</span> <span style="color: cyan; font-weight: 600;">Source</span> <span style="color: cyan; font-weight: 600;">Text</span> │
│ <span style="opacity: 0.7;">────────────── ─────── ──────────────────────────────────────────────────────</span> │
│ inv_01HXM9A1B global All public APIs must maintain backward compatibility │
│ inv_01HXM9A2C project All endpoints must validate auth tokens │
│ inv_01HXM9G3A plan All database queries must use parameterized statements │
╰───────────────────────────────────────────────────────────────────────────────────────────╯
│ <span style="color: yellow; font-weight: 600;">Conflicts Resolved:</span> 1 │
│ <span style="opacity: 0.7;"> Global <span style="color: #66cc66;">"Use shared DB pool"</span> overridden by plan "All database queries must use │
│ parameterized statements"</span> │
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 3 effective invariants (1 global, 1 project, 1 plan; 1 conflict resolved)
</code></pre></div>
=== "Plain"
```
$ agents invariant list --global
Global Invariants
ID Text
-------------- --------------------------------------------------------
inv_01HXM9A1B All public APIs must maintain backward compatibility
inv_01HXM9A1C Payment processing must be idempotent
[OK] 2 invariants
$ agents invariant list --plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J --effective
Effective Invariants (Plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J)
ID Source Text
-------------- ------- --------------------------------------------------
inv_01HXM9A1B global All public APIs must maintain backward compatibility
inv_01HXM9A2C project All endpoints must validate auth tokens
inv_01HXM9G3A plan All database queries must use parameterized statements
Conflicts Resolved: 1
Global "Use shared DB pool" overridden by plan "All database queries must use
parameterized statements"
[OK] 3 effective invariants (1 global, 1 project, 1 plan; 1 conflict resolved)
```
=== "JSON"
```json
{
"command": "invariant list",
"status": "ok",
"exit_code": 0,
"data": {
"scope": "plan",
"plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
"effective": true,
"invariants": [
{ "id": "inv_01HXM9A1B", "source": "global", "text": "All public APIs must maintain backward compatibility" },
{ "id": "inv_01HXM9A2C", "source": "project", "text": "All endpoints must validate auth tokens" },
{ "id": "inv_01HXM9G3A", "source": "plan", "text": "All database queries must use parameterized statements" }
],
"conflicts_resolved": [
{
"overridden": { "source": "global", "text": "Use shared DB pool" },
"by": { "source": "plan", "text": "All database queries must use parameterized statements" }
}
]
},
"timing": { "started": "2026-02-08T14:35:00Z", "duration_ms": 35 },
"messages": ["3 effective invariants (1 global, 1 project, 1 plan; 1 conflict resolved)"]
}
```
=== "YAML"
```yaml
command: invariant list
status: ok
exit_code: 0
data:
scope: plan
plan_id: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
effective: true
invariants:
- id: inv_01HXM9A1B
source: global
text: "All public APIs must maintain backward compatibility"
- id: inv_01HXM9A2C
source: project
text: "All endpoints must validate auth tokens"
- id: inv_01HXM9G3A
source: plan
text: "All database queries must use parameterized statements"
conflicts_resolved:
- overridden:
source: global
text: "Use shared DB pool"
by:
source: plan
text: "All database queries must use parameterized statements"
timing:
started: "2026-02-08T14:35:00Z"
duration_ms: 35
messages:
- "3 effective invariants (1 global, 1 project, 1 plan; 1 conflict resolved)"
```
agents invariant remove
agents invariant remove [--yes|-y] <INVARIANT_ID>!!! warning "Constraint Removal" Remove an invariant by ID. The invariant is removed from whichever scope it was originally attached to. ==Active plans== that have already incorporated this invariant into their decision trees are not retroactively affected, but future plans will no longer enforce this constraint.
Arguments
<INVARIANT_ID>: Invariant ID to remove.--yes: Skip confirmation.
Examples
=== "Rich"
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> invariant remove inv_01HXM9A1C
Remove invariant inv_01HXM9A1C (<span style="color: #66cc66;">"Payment processing must be idempotent"</span>, scope: global)? [y/N]: y
╭─ Invariant Removed ──────────────────────────────────────────────╮
│ <span style="color: yellow; font-weight: 600;">Removed:</span> Payment processing must be idempotent │
│ <span style="color: #5599ff; font-weight: 600;">Scope:</span> global │
│ <span style="color: #5599ff; font-weight: 600;">ID:</span> inv_01HXM9A1C │
╰──────────────────────────────────────────────────────────────────╯
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Invariant removed
</code></pre></div>
=== "Plain"
```
$ agents invariant remove inv_01HXM9A1C
Remove invariant inv_01HXM9A1C ("Payment processing must be idempotent", scope: global)? [y/N]: y
Invariant Removed
Removed: Payment processing must be idempotent
Scope: global
ID: inv_01HXM9A1C
[OK] Invariant removed
```
=== "JSON"
```json
{
"command": "invariant remove",
"status": "ok",
"exit_code": 0,
"data": {
"removed": "Payment processing must be idempotent",
"scope": "global",
"id": "inv_01HXM9A1C"
},
"timing": { "started": "2026-02-08T14:36:00Z", "duration_ms": 30 },
"messages": ["Invariant removed"]
}
```
=== "YAML"
```yaml
command: invariant remove
status: ok
exit_code: 0
data:
removed: "Payment processing must be idempotent"
scope: global
id: inv_01HXM9A1C
timing:
started: "2026-02-08T14:36:00Z"
duration_ms: 30
messages:
- "Invariant removed"
```