Agent Baton CLI Reference¶
Complete command reference for the baton CLI. Every command, flag, and
option is documented here with syntax, defaults, and usage examples.
Overview¶
The baton CLI is a flat-subcommand tool powered by argparse. All
command modules live under agent_baton/cli/commands/ and are
auto-discovered at startup. Each module exposes register(subparsers)
and handler(args).
Commands are organized into functional groups:
| Group | Concern | Commands |
|---|---|---|
| Execution | Plan, execute, and manage orchestrated tasks | plan, execute, status, daemon, async, decide |
| Manager Mode | PMO planning overlay -- charter, team blueprint, scope contracts, knowledge-pack lifecycle | plan --manager-mode, config, report, team, knowledge list/scan/show/audit/propose |
| Observe | Traces, usage, dashboards, telemetry | dashboard, trace, usage, telemetry, context-profile, retro, context, cleanup |
| Guardrails | Risk, policy, compliance, validation | classify, compliance, policy, escalations, validate, spec-check, detect |
| Improve | Scoring, learning, patterns, budgets | scores, learn, patterns, budget, changelog, anomalies |
| Knowledge | Knowledge pack validation, search, briefing, lifecycle, effectiveness | knowledge doctor, knowledge search, knowledge resolve, knowledge brief, knowledge harvest, knowledge stale, knowledge deprecate, knowledge retire, knowledge sweep, knowledge usage, knowledge effectiveness, knowledge ranking, knowledge ab |
| Distribute | Packaging, publishing, installation | package, publish, pull, install, transfer |
| Agents | Agent discovery, routing, events | agents, route, events, incident |
| PMO | Portfolio management overlay | pmo serve, pmo status, pmo add, pmo health |
| Sync | Federated data sync | sync, sync status |
| Query | Project-local structured queries | query |
| Cross-Project Query | Cross-project SQL against central.db | cquery |
| Source | External work-item connections | source add, source list, source sync, source remove, source map |
| Diagnostics | Installation and workspace health checks | doctor |
| API | HTTP API server | serve |
Installation & Setup¶
# Install the package in editable mode with dev dependencies
pip install -e ".[dev]"
# Install with API server support (FastAPI + uvicorn)
pip install -e ".[api]"
# Deploy agent definitions to ~/.claude/agents/ and references
scripts/install.sh
# Or use the CLI installer
baton install --scope user --source /path/to/agent-baton-repo
After installation, the baton command is available globally via the
console script entry point.
Execution Commands¶
baton plan¶
Create a data-driven execution plan for an orchestrated task.
| Argument | Required | Default | Description |
|---|---|---|---|
SUMMARY |
Yes | -- | Natural-language task summary |
--task-type TYPE |
No | auto-detected | Override task type: new-feature, bug-fix, refactor, data-analysis, documentation, migration, test |
--agents LIST |
No | auto-selected | Comma-separated agent names; bypasses auto-selection |
--project PATH |
No | cwd | Project root for stack detection |
--json |
No | false | Output plan as JSON instead of markdown |
--save |
No | false | Write plan.json and plan.md to .claude/team-context/ |
--explain |
No | false | Print explanation of plan choices |
--manager-mode |
No | false | Post-process the plan into manager-mode PMO sidecar artifacts (project charter, scope map, team blueprint, role cards, knowledge plan, scope contracts, context bundles, manager brief) under .claude/team-context/executions/<task_id>/. Also enabled by manager_mode.enabled_by_default in .claude/baton.yaml. See Manager Mode Commands below. |
--dry-run |
No | false | Preview the plan + cost/token forecast without saving. Mutually exclusive with --save (exits 2 if both are passed). |
--gate-scope SCOPE |
No | sentinel (unset) | How broadly gate commands run: focused (scopes pytest to test files covering changed source paths), full (legacy unscoped pytest / pytest --cov), smoke (import-only / collect-only). When omitted, the planner's own default applies; in manager mode, an omitted flag lets gates.gate_scope from the manager config apply instead (see below). |
--knowledge PATH |
No | -- | Attach a knowledge document file globally to all steps (repeatable) |
--knowledge-pack PACK |
No | -- | Attach a knowledge pack by name globally to all steps (repeatable) |
--intervention LEVEL |
No | low |
Escalation threshold for knowledge gaps: low, medium, high |
--goal CONDITION |
No | -- | Completion condition (G1). The engine evaluates the goal after each gate passes and uses amend_plan to round out gaps until met, exhausted, or the token ceiling is hit. |
--max-amend-cycles N |
No | 3 |
Goal round-out budget (meaningful only with --goal). |
Manager mode:
--manager-mode sets plan.manager_mode = true regardless of --save/--dry-run, but the PMO artifacts (charter, scope map, blueprint, role cards, knowledge plan, scope contracts, context bundles, manager-brief.md) are only built when combined with one of those two flags:
--manager-mode --save: builds and writes the full artifact set to.claude/team-context/executions/<task_id>/, prints anArtifacts:path list after the normal save output. The PMO layer'sPhasePolicyApplier(adversarial-review step injection, gate rescoping) runs beforeplan.json/plan.mdare written, so the saved plan already reflects any injected review steps.--manager-mode --dry-run: builds the same artifact set in memory only and prints it as a preview list (Manager Mode artifacts (preview only -- nothing written)) alongside the compact plan forecast; nothing touches disk.--json --dry-run --manager-modeincludes the preview under amanager_mode_artifactskey.--manager-modealone (no--save, no--dry-run): prints markdown/JSON like a normal plan withmanager_mode: truestamped on it, but builds no PMO artifacts.--manager-mode --explain --save: appends a## Manager Modesection (workstreams + owners, team roles, and the effective adversarial-review/handoff/gate-scope policy) toexplanation.md.--manager-mode+--gate-scope: an explicit--gate-scopealways wins over the manager config'sgates.gate_scope. Left unset, gates are rescoped togates.gate_scopeonly whengates.mode(in.claude/baton.yaml) isproject_configured(the default); othergates.modevalues are recorded on the blueprint but do not change gate commands this increment.
A malformed .claude/baton.yaml manager section is a hard error only when --manager-mode was explicitly passed; otherwise it downgrades to a warning and manager mode stays off. See docs/internal/manager-mode-pmo-design.md for the full artifact schema.
Examples:
# Create and save a plan with explanation
baton plan "Add JWT authentication middleware and integration tests" --save --explain
# Create a plan with explicit agents
baton plan "Migrate database schema" --save --agents "backend-engineer--python,test-engineer"
# Create a plan with attached knowledge
baton plan "Implement payment processing" --save \
--knowledge docs/payment-api.md \
--knowledge-pack compliance-rules
# Output plan as JSON for programmatic consumption
baton plan "Add caching layer" --json
# Preview manager-mode PMO artifacts without writing anything
baton plan "Roll out multi-tenant billing" --manager-mode --dry-run
# Save a plan with the full manager-mode PMO layer
baton plan "Roll out multi-tenant billing" --manager-mode --save --explain
Related: baton execute start, baton classify, baton detect, baton config, baton report, baton team
baton goal¶
Plan against a completion condition and let the engine drive amend cycles until met (G1).
| Argument | Required | Default | Description |
|---|---|---|---|
CONDITION |
Yes | -- | A single quoted sentence describing what "done" means |
--max-amend-cycles N |
No | 3 |
Maximum goal-driven round-out cycles |
--task-type TYPE |
No | auto | Passed through to baton plan |
--complexity LEVEL |
No | auto | light / medium / heavy |
--project PATH |
No | cwd | Project root |
--knowledge PATH |
No | -- | Repeatable; passed through |
--knowledge-pack PACK |
No | -- | Repeatable; passed through |
--model NAME |
No | -- | Default model for dispatched agents |
--gate-scope SCOPE |
No | focused |
focused / full / smoke |
--intervention LEVEL |
No | low |
Knowledge-gap escalation aggressiveness |
--explain |
No | false | Write an explanation.md alongside the saved plan |
--verbose |
No | false | Print the full plan markdown after save |
--no-execute |
No | false | Stop after planning; do not print "next: baton execute start" |
Behavior: equivalent to baton plan CONDITION --save --goal CONDITION --max-amend-cycles N followed by guidance to run baton execute start. The engine evaluates the goal at every gate-pass boundary; if not met and budget remains, it inserts evaluator-suggested phases via amend_plan. Termination conditions: goal met, amend budget exhausted, or BATON_RUN_TOKEN_CEILING hit.
Evaluator selection (via BATON_GOAL_EVALUATOR env var):
- stub — deterministic, no LLM (default fallback)
- haiku (default when ANTHROPIC_API_KEY is set) — Claude Haiku 4.5
- opus — Claude Opus 4.8
Safety rail: any evaluator that returns met=True is overridden to met=False unless the most-recent gate passed. This prevents premature claims.
Example:
See docs/internal/agent-teams-and-goal-design.md for the design rationale.
baton execute¶
Drive an orchestrated task through the execution engine. This is a command group with multiple subcommands.
For a plan saved with plan.manager_mode = true (see baton plan
--manager-mode), dispatch prompts additionally carry a
scope-contract and context-bundle section per step, and phase
completion/final completion best-effort refresh the phase handoff and
manager-report.md sidecars -- the action loop and _print_action()
output shape are unchanged. When a dispatched agent reports a
SCOPE_EXPANSION: <path> — <reason> signal, scoping.scope_expansion_policy
(.claude/baton.yaml) routes it to one of three outcomes: allow_with_note
(proceed, record a bead), queue_for_manager (create a manager decision
packet, proceed), or block (the step fails immediately, pending a plan
amendment to bring the work into scope).
baton execute start¶
Initialize execution state from a saved plan and return the first action.
| Argument | Required | Default | Description |
|---|---|---|---|
--plan PATH |
No | .claude/team-context/plan.json |
Path to plan.json |
--task-id ID |
No | auto | Target a specific execution by task ID |
Side effects:
- Creates execution-state.json in the task-scoped directory
- Starts an in-memory trace
- Publishes a task.started event
- Sets the active execution marker
- Prints Session binding: export BATON_TASK_ID=<task-id>
Example:
baton plan "Add API endpoints" --save --explain
baton execute start
# Copy the BATON_TASK_ID export from the output
export BATON_TASK_ID=task-abc123
baton execute next¶
Return the next action the orchestrator should perform.
| Argument | Required | Default | Description |
|---|---|---|---|
--all |
No | false | Return all dispatchable actions as a JSON array (for parallel dispatch) |
--task-id ID |
No | auto | Target a specific execution |
Without --all, prints a single action in human-readable format.
With --all, prints a JSON array of all steps whose dependencies are
satisfied.
Action types returned: DISPATCH, GATE, APPROVAL, COMPLETE,
FAILED, WAIT, TEAM_DISPATCH.
baton execute dispatched¶
Mark a step as in-flight (dispatched but not yet complete).
| Argument | Required | Description |
|---|---|---|
--step-id ID |
Yes | Step identifier, e.g. 1.1 |
--agent NAME |
Yes | Agent name, e.g. backend-engineer--python |
Output: {"status": "dispatched", "step_id": "1.1"}
Call this immediately after spawning a subagent, before baton execute record.
baton execute record¶
Record the outcome of a completed or failed step.
| Argument | Required | Default | Description |
|---|---|---|---|
--step-id ID |
Yes | -- | Step identifier, e.g. 1.1 |
--agent NAME |
Yes | -- | Agent name |
--status STATUS |
No | complete |
complete or failed (no other values accepted) |
--outcome TEXT |
No | "" |
Free-text summary of what the agent did |
--files LIST |
No | "" |
Comma-separated list of files changed |
--commit HASH |
No | "" |
Git commit hash |
--tokens N |
No | 0 |
Estimated token count |
--duration N |
No | 0.0 |
Duration in seconds (float) |
--error TEXT |
No | "" |
Error detail if --status failed |
Example:
baton execute record \
--step-id 1.1 \
--agent backend-engineer--python \
--status complete \
--outcome "Added JWT middleware with login/logout endpoints" \
--files "app/auth.py,app/routes.py" \
--commit abc123f
baton execute gate¶
Record the result of a QA gate check.
| Argument | Required | Description |
|---|---|---|
--phase-id N |
Yes | Integer phase ID (1-based) |
--result |
Yes | pass or fail |
--output TEXT |
No | Gate command output or reviewer notes |
Example:
# Run the gate command, then record the result
pytest tests/ > /tmp/gate-output.txt 2>&1
baton execute gate --phase-id 1 --result pass --output "$(cat /tmp/gate-output.txt)"
baton execute approve¶
Record a human approval decision for a phase with approval_required=True.
| Argument | Required | Description |
|---|---|---|
--phase-id N |
Yes | Phase ID requiring approval |
--result |
Yes | approve, reject, or approve-with-feedback |
--feedback TEXT |
No | Feedback text (required for approve-with-feedback) |
State transitions:
- approve -- execution continues to gate or next phase
- reject -- engine sets status to failed
- approve-with-feedback -- inserts a remediation phase with the feedback injected
Example:
baton execute approve --phase-id 2 --result approve-with-feedback \
--feedback "Add error handling for the edge case where token is expired"
baton execute amend¶
Amend the running plan by adding phases or steps during execution.
| Argument | Required | Description |
|---|---|---|
--description TEXT |
Yes | Why this amendment is needed (audit log) |
--add-phase NAME:AGENT |
No | Add a phase (repeatable) |
--after-phase N |
No | Insert new phases after this phase ID (default: append) |
--add-step PHASE_ID:AGENT:DESC |
No | Add step to existing phase (repeatable) |
Example:
# Add a security review phase after phase 2
baton execute amend \
--description "Security review needed for auth changes" \
--add-phase "security-review:security-reviewer" \
--after-phase 2
# Add a step to an existing phase
baton execute amend \
--description "Need migration script for schema change" \
--add-step "1:backend-engineer--python:Write database migration script"
baton execute team-record¶
Record a team member completion within a team step.
| Argument | Required | Default | Description |
|---|---|---|---|
--step-id S |
Yes | -- | Parent team step ID, e.g. 2.1 |
--member-id M |
Yes | -- | Team member ID, e.g. 2.1.a |
--agent NAME |
Yes | -- | Agent name |
--status |
No | complete |
complete or failed |
--outcome TEXT |
No | "" |
Summary of work done |
--files F |
No | "" |
Comma-separated files changed |
--hook-source SOURCE |
No | "" |
When invoked from an external Claude Code Agent Teams hook, set to claude-teams. Tags the team mailbox event with the source for audit. See A1.c in docs/internal/agent-teams-and-goal-design.md. |
baton execute complete¶
Finalize a completed execution run.
Side effects:
- Sets execution state status = complete
- Writes trace file to .claude/team-context/traces/
- Writes usage record to usage-log.jsonl
- Generates retrospective to retrospectives/
- Publishes task.completed event
- Auto-syncs to central.db (best-effort)
baton execute status¶
Show current execution state without advancing it.
Output:
Task: abc123
Bound: BATON_TASK_ID
Status: running
Phase: 1
Steps: 2/4
Gates: 1 passed, 0 failed
Elapsed: 145s
baton execute resume¶
Resume execution after a crash or interrupted session.
Loads execution-state.json from disk, reconnects the trace, and
returns the next action. Steps in dispatched status will be
re-dispatched.
baton execute export¶
Snapshot an execution's full state to a JSON file (read-only).
Replaces the legacy FileStorage primary backend (removed from the
factory in slice 15 of the SQLite-parity migration). The default
output path is execution-state.json in the current working directory;
the parent directory is created if it doesn't exist.
The exported JSON is state.to_dict() — exactly the on-disk shape the
file backend used to write — so existing tooling that consumed
execution-state.json continues to work against the export.
Storage-internal fields like the OCC version and the in-memory
_loaded_version PrivateAttr are intentionally omitted.
baton execute list¶
List all executions (active and completed).
Output:
TASK ID STATUS STEPS PID SUMMARY
------------------------------------------------------------------------------------------
* task-auth-abc running 2/4 - Add JWT auth middleware...
task-fix-xyz complete 3/3 - Fix dashboard rendering...
Active execution is marked with *.
baton execute switch¶
Switch the active execution to a different task ID.
| Argument | Required | Description |
|---|---|---|
TASK_ID |
Yes | Task ID to switch to |
baton status¶
Show team-context file status (which recovery files exist).
Output:
Related: baton execute status
baton daemon¶
Background execution management. Runs the async worker (and optionally the HTTP API server) as a daemon process.
baton daemon start¶
| Argument | Required | Default | Description |
|---|---|---|---|
--plan FILE |
Yes* | -- | Path to MachinePlan JSON file (*required unless --resume) |
--max-parallel N |
No | 3 |
Maximum parallel agents |
--dry-run |
No | false | Use DryRunLauncher (no real agent calls) |
--foreground |
No | false | Run in foreground (don't daemonize) |
--resume |
No | false | Resume from saved execution state |
--project-dir DIR |
No | cwd | Project directory for execution |
--serve |
No | false | Also start HTTP API server in the same process |
--port PORT |
No | 8741 |
Port for API server (with --serve) |
--host HOST |
No | 127.0.0.1 |
Bind address for API server (with --serve) |
--token TOKEN |
No | -- | Bearer token for API auth (with --serve) |
--task-id ID |
No | -- | Namespace this daemon under a specific task ID |
Example:
# Start background daemon with API server
baton daemon start --plan .claude/team-context/plan.json \
--serve --port 8741 --max-parallel 4
# Dry-run in foreground for testing
baton daemon start --plan plan.json --dry-run --foreground
# Resume a crashed daemon
baton daemon start --resume --task-id task-abc123
baton daemon status¶
Shows whether the daemon is running, its PID, task ID, phase, step progress, gates, and elapsed time.
baton daemon stop¶
Sends a stop signal to the running daemon process.
baton daemon list¶
Lists all daemon workers with their task IDs, PIDs, and liveness status.
baton async¶
Dispatch and track asynchronous tasks.
| Argument | Required | Description |
|---|---|---|
--dispatch COMMAND |
No | Dispatch a new async task |
--show ID |
No | Show a specific task's status |
--pending |
No | List only pending tasks |
--task-id ID |
No | Task ID for --dispatch (auto-generated if omitted) |
--type TYPE |
No | Dispatch type: shell, script, or manual (default: shell) |
Without flags, lists all async tasks with their status.
Examples:
# Dispatch a shell command
baton async --dispatch "pytest tests/ -x" --task-id my-test-run
# Check status
baton async --show my-test-run
# List pending tasks
baton async --pending
baton decide¶
Manage human decision requests generated during daemon/async execution.
| Argument | Required | Description |
|---|---|---|
--list |
No | List pending decision requests (default action) |
--all |
No | List all decision requests regardless of status |
--show ID |
No | Show full details of a single decision request |
--resolve ID |
No | Resolve a pending decision request |
--option OPTION |
No | Chosen option when using --resolve (required) |
--rationale TEXT |
No | Optional rationale for the decision |
Examples:
# List pending decisions
baton decide
# Show details of a decision request
baton decide --show req-abc123
# Resolve a decision
baton decide --resolve req-abc123 --option "approve" --rationale "Looks good after review"
Manager Mode Commands¶
Commands for the manager-mode PMO layer: config profile, status
reporting, and the knowledge-pack lifecycle. See
baton plan --manager-mode to opt a plan into this
layer, and
docs/internal/manager-mode-pmo-design.md
for the full artifact schema and locked design decisions.
baton config¶
Inspect, validate, or scaffold the project's baton.yaml config. Every
subcommand accepts --profile {project,manager} (default project);
both profiles read/write the same baton.yaml file and each ignores
the other's top-level keys.
baton config show [--start-dir DIR] [--profile {project,manager}]
baton config validate [PATH] [--profile {project,manager}]
baton config init [--path PATH] [--force] [--profile {project,manager}]
| Subcommand | Description |
|---|---|
show |
Print the discovered baton.yaml path and the effective merged config (JSON for --profile project, YAML for --profile manager). |
validate |
Parse and validate a baton.yaml file; exits non-zero on failure. --profile manager errors name the offending key/value/valid-options. |
init |
Write a starter baton.yaml to the target path. --profile project writes ./baton.yaml (the default_agents/default_gates/... template); --profile manager writes ./.claude/baton.yaml (the full manager_mode/team/scoping/context/knowledge_packs/policies/gates/reporting template from the PRD). |
| Argument | Applies to | Description |
|---|---|---|
--start-dir DIR |
show |
Directory to start the upward config search from (default: cwd) |
PATH |
validate |
Optional explicit file path (defaults to discovery from cwd) |
--path PATH |
init |
Output path (default per profile, see above) |
--force |
init |
Overwrite an existing file at the target path |
--profile {project,manager} |
all | Which config surface to operate on (default project) |
Exit codes: 0 success (including calling baton config with no subcommand, which prints a usage hint); 1 file missing/unreadable, or --profile project parse error; 2 --profile manager parse error (ManagerConfigError).
Examples:
# Scaffold the manager-mode config template
baton config init --profile manager
# Validate it after editing
baton config validate --profile manager
# Show the effective merged manager config (defaults < user < project)
baton config show --profile manager
baton report¶
Manager-mode status report for a task: brief (post-planning) or
progress report (during/after execution). Degrades gracefully when
execution hasn't started -- a plan saved with --manager-mode --save
alone still produces a report from the scope-map/team-blueprint/
knowledge-plan sidecars and plan.json.
| Argument | Required | Default | Description |
|---|---|---|---|
--task-id TASK_ID |
No | active task | Target a specific execution by task ID (resolution ladder: --task-id -> BATON_TASK_ID -> active-task marker) |
--json |
No | false | Emit machine-readable JSON instead of Markdown |
Output: prints the rendered report and (best-effort) writes/refreshes manager-report.md under .claude/team-context/executions/<task_id>/.
Example:
baton team¶
Ad-hoc team status and role cards for a manager-mode task. Requires a
team blueprint (team-blueprint.json) written by
baton plan --manager-mode --save.
| Subcommand | Description |
|---|---|
status |
Team purpose, roles (with owned-workstream counts), workstream ownership, completed handoffs, open knowledge gaps, open scope changes, and manager decisions needed. |
show |
Everything status shows, plus each role's full role-card content. |
| Argument | Description |
|---|---|
--task-id TASK_ID |
Target a specific execution by task ID (defaults to the active task) |
Workstream ownership is always read from TeamBlueprint.workstream_assignments -- a role that owns zero workstreams is listed under Roles only, never as a workstream's owner.
Example:
baton knowledge list / show / scan / audit / propose¶
Knowledge-pack lifecycle verbs on the shared baton knowledge
cooperative parser (see baton knowledge --help for the full
subcommand list, including the pre-existing brief/effectiveness/
harvest/stale/deprecate/retire/sweep/usage/ranking/ab
verbs not covered here). These five read/write the existing
knowledge.yaml manifest -- there is no separate pack.yaml.
baton knowledge list [--root ROOT]
baton knowledge show PACK_NAME [--root ROOT]
baton knowledge scan [--root ROOT]
baton knowledge audit [--root ROOT]
baton knowledge propose [--root ROOT]
| Subcommand | Description |
|---|---|
list |
List discovered knowledge packs with status, confidence, doc count, and token estimate. |
show PACK_NAME |
Show one pack's status, confidence, description, source path/files, target agents, last-reviewed date, stale-after window, and documents. |
scan |
Discover knowledge packs and candidate docs; writes knowledge-scan.json under .claude/team-context/. |
audit |
Audit packs for invalid status, staleness, and missing metadata against the loaded ManagerConfig. Prints Knowledge audit: no issues found. and exits 0 when clean; otherwise lists each issue and exits 1. |
propose |
Propose new knowledge packs from repeated knowledge-gap signals recorded under .claude/team-context/; writes each proposal to .claude/team-context/knowledge-proposals/<slug>.md when any are found. |
| Argument | Description |
|---|---|
--root ROOT |
Project root to scan/discover packs from (default: cwd) |
PACK_NAME |
(positional, show only) Pack name to display |
Exit codes: 0 success (including "no issues"/"nothing to propose"); 1 audit found issues, or show was given an unknown pack name.
Example:
Observe Commands¶
baton dashboard¶
Generate or display the usage dashboard.
| Argument | Required | Description |
|---|---|---|
--write |
No | Write dashboard to disk instead of printing to stdout |
baton trace¶
List and inspect structured task execution traces.
| Argument | Required | Description |
|---|---|---|
TASK_ID |
No | Show timeline for a specific task |
--last |
No | Show timeline for the most recent task |
--summary TASK_ID |
No | Show compact summary for a specific task |
--count N |
No | Number of recent traces to list (default: 10) |
Examples:
# List recent traces
baton trace
# Show timeline for most recent task
baton trace --last
# Show timeline for a specific task
baton trace task-abc123
# Show compact summary
baton trace --summary task-abc123
baton usage¶
Show usage statistics from the usage log.
| Argument | Required | Description |
|---|---|---|
--recent N |
No | Show the N most recent records |
--agent NAME |
No | Show stats for a specific agent |
Without flags, prints an aggregate usage summary including total tasks, agents used, tokens consumed, outcomes, and top agents.
Examples:
# Summary view
baton usage
# Last 5 usage records
baton usage --recent 5
# Stats for a specific agent
baton usage --agent backend-engineer--python
baton telemetry¶
Show or clear agent telemetry events.
| Argument | Required | Description |
|---|---|---|
--agent NAME |
No | Show events for a specific agent |
--recent N |
No | Show the N most recent events |
--clear |
No | Clear the telemetry log |
Without flags, prints a telemetry summary grouped by agent and event type, with file read/write counts.
baton context-profile¶
List and inspect agent context efficiency profiles.
| Argument | Required | Description |
|---|---|---|
TASK_ID |
No | Show context profile for a specific task |
--agent NAME |
No | Show aggregate context stats for a specific agent |
--generate TASK_ID |
No | Generate and save a context profile from trace data |
--report |
No | Print a full markdown context efficiency report |
--count N |
No | Number of recent profiles to list (default: 10) |
Examples:
# Generate a profile from trace data
baton context-profile --generate task-abc123
# View a generated profile
baton context-profile task-abc123
# Agent-level aggregate stats
baton context-profile --agent backend-engineer--python
# Full report
baton context-profile --report
baton retro¶
Show retrospectives generated after task completion.
| Argument | Required | Description |
|---|---|---|
--task-id ID |
No | Show a specific retrospective |
--search KEYWORD |
No | Search retrospectives by keyword |
--recommendations |
No | Extract roster recommendations from all retrospectives |
--count N |
No | Number of recent retrospectives to list (default: 10) |
Examples:
# List recent retrospectives
baton retro
# View a specific retrospective
baton retro --task-id task-abc123
# Search for retrospectives mentioning "auth"
baton retro --search auth
# Extract roster recommendations
baton retro --recommendations
baton context¶
Situational awareness for Claude agents. Queries baton.db for current task state, agent briefings, and knowledge gaps.
baton context current¶
Shows what task, phase, step, and agent are currently active.
baton context briefing¶
| Argument | Required | Description |
|---|---|---|
AGENT |
Yes | Agent name to brief (e.g. backend-engineer--python) |
Prints a performance briefing for an agent about to be dispatched.
baton context gaps¶
| Argument | Required | Default | Description |
|---|---|---|---|
--min-frequency N |
No | 1 |
Minimum occurrence count to include a gap |
--agent NAME |
No | -- | Filter gaps to a specific agent |
Shows knowledge gaps identified across recent retrospectives.
Shared flags (all context subcommands):
| Flag | Description |
|---|---|
--db PATH |
Explicit path to baton.db |
--central |
Query central database at ~/.baton/central.db |
--json |
Machine-readable JSON output |
baton cleanup¶
Remove old execution artifacts (traces, events, retrospectives).
| Argument | Required | Default | Description |
|---|---|---|---|
--retention-days N |
No | 90 |
Keep files newer than this many days |
--dry-run |
No | false | Show what would be removed without deleting |
--team-context PATH |
No | .claude/team-context |
Path to team-context directory |
Example:
# Preview what would be cleaned up
baton cleanup --dry-run --retention-days 30
# Actually clean up files older than 60 days
baton cleanup --retention-days 60
baton migrate-storage (deprecated)¶
Deprecated. Use
baton sync --migrate-storageinstead. The shim still works and prints aDEPRECATED:warning to stderr.
Guardrails Commands¶
baton classify¶
Classify task sensitivity and select a guardrail preset.
| Argument | Required | Description |
|---|---|---|
DESCRIPTION |
Yes | Task description to classify |
--files FILE... |
No | File paths affected (elevates risk from path patterns) |
Output:
Risk Level: MEDIUM
Preset: regulated-data
Confidence: 0.82
Signals: payment, user-data
Explanation: Task touches payment processing and user PII fields.
Risk levels: LOW, MEDIUM, HIGH, CRITICAL
Example:
baton classify --activate¶
Write .claude/active-policy.json after classifying a task, so that the
baton policy-check hook uses the correct guardrail preset for the session.
| Argument | Required | Description |
|---|---|---|
DESCRIPTION |
Yes | Task description to classify |
--files FILE... |
No | File paths affected (elevates risk from path patterns) |
--activate |
No | Write .claude/active-policy.json with the resolved preset key |
Written file (.claude/active-policy.json):
{
"preset": "standard_dev",
"preset_display_name": "Standard Development",
"risk_level": "LOW",
"confidence": "high",
"signals": [],
"activated_at": "2026-01-15T12:00:00+00:00",
"activated_by": "baton classify --activate",
"task_hint": "first 120 chars of the description"
}
Preset keys: standard_dev, data_analysis, infrastructure,
regulated, security.
Example:
baton classify "Add JWT auth middleware" --activate
# → Active policy written to .claude/active-policy.json (preset: security)
Related: baton policy-check, baton comply-record
baton policy-check¶
Claude Code PreToolUse hook: evaluate a tool call against the active guardrail policy and emit a deny decision when a blocking rule is triggered.
Reads a PreToolUse JSON payload from stdin and prints a deny JSON to
stdout when a path_block or tool_restrict rule with severity=="block"
matches. Exits 0 in all cases (fail-open); set BATON_POLICY_FAIL_CLOSED=1
to exit 2 on errors.
| Argument | Required | Description |
|---|---|---|
--agent NAME |
No | Agent name (overrides $CLAUDE_AGENT_NAME) |
--cwd DIR |
No | Project root for policy resolution (default: cwd) |
Stdin format (Claude Code PreToolUse payload):
Deny output (stdout, exit 0):
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "standard_dev rule block_env_files (path_block): Block writes to .env files. Matched: /project/.env against pattern '**/.env'."
}
}
Policy resolution order:
1. .claude/active-policy.json → preset key
2. .claude/team-context/plan.json → risk_level (LOW/MEDIUM → standard_dev; HIGH/CRITICAL → regulated)
3. Fallback: standard_dev
Environment variables:
| Variable | Effect |
|---|---|
BATON_POLICY_FAIL_CLOSED |
1 → exit 2 on errors (stdin errors, unreadable policy) |
CLAUDE_AGENT_NAME |
Agent name used for scope-based rule matching |
Example (hook configuration in settings.json):
{"matcher": "Bash|Write|Edit|MultiEdit",
"hooks": [{"type": "command", "command": "baton policy-check", "timeout": 10}]}
Related: baton classify --activate, baton comply-record
baton packs¶
Manage Assurance Packs — org-authored domain governance units stored under
.claude/packs/<name>/.
baton packs init¶
Scaffold a new pack directory with all required files from a minimal valid template.
| Argument | Required | Default | Description |
|---|---|---|---|
NAME |
Yes | -- | Pack name (becomes the directory name under .claude/packs/) |
--dir DIR |
No | cwd | Project root containing .claude/ |
Behaviour:
- Creates .claude/packs/<NAME>/ with pack.json, policy.json,
signals.json, rubric.md, gates.json, evidence.json, and
knowledge/overview.md.
- Substitutes all [YOUR_PACK_NAME] placeholders with NAME.
- Refuses if the directory already exists (exit 1).
- Prints a next-steps hint on success.
Example:
baton packs init phi-hipaa
# → Scaffolded pack 'phi-hipaa' at .claude/packs/phi-hipaa/
# Next steps: ...
baton packs validate¶
Validate one or all packs against all 7 spec checks. Exits 2 if any error is found.
| Argument | Required | Default | Description |
|---|---|---|---|
NAME |
No | all packs | Pack name to validate |
--dir DIR |
No | cwd | Project root containing .claude/ |
Exit codes:
| Code | Meaning |
|---|---|
| 0 | All packs valid |
| 2 | One or more validation errors found |
Validation checks:
1. Required files exist (pack.json, policy.json, signals.json, rubric.md).
2. pack.json has name, version, description; name matches directory.
3. policy.json parses as PolicySet with name == "pack:<dirname>".
4. signals.json categories ⊆ {regulated, pii, security, infrastructure, database}; path_patterns is a list; preset_name present.
5. rubric.md has ≥1 ## heading and ≥1 - [ ] checkbox.
6. gates.json entries each have id, description, command.
7. evidence.json required_artifacts each have id, description.
Output:
[OK] phi-hipaa
[OK] secure-coding-owasp
All packs valid.
# On error:
[ERROR] my-pack/policy.json: PolicySet name 'pack:wrong' must be 'pack:my-pack'
baton packs list¶
List all packs with key metadata. Invalid packs are shown with [INVALID] prefix.
| Argument | Required | Default | Description |
|---|---|---|---|
--dir DIR |
No | cwd | Project root containing .claude/ |
Output:
NAME VERSION DOMAIN RISK DESCRIPTION
------------------------------------------------------------------------------------------
phi-hipaa 1.0.0 healthcare HIGH HIPAA PHI handling guardrails...
secure-coding-owasp 1.0.0 security HIGH OWASP Top-10 secure coding guardrails...
Related: baton classify --activate, baton policy-check
baton comply-record¶
Claude Code PostToolUse and Stop hook: append a hash-chained entry to the compliance audit log.
Reads a PostToolUse or Stop JSON payload from stdin and appends an entry
via ComplianceChainWriter to .claude/team-context/compliance-audit.jsonl.
Always exits 0 (fail-open); BATON_COMPLIANCE_FAIL_CLOSED=1 exits 1 on
write errors. Malformed stdin is silently ignored.
| Argument | Required | Default | Description |
|---|---|---|---|
--event-type TYPE |
No | hook_tool_use |
Event type label in the audit entry |
--log PATH |
No | .claude/team-context/compliance-audit.jsonl |
Audit log path |
--cwd DIR |
No | cwd | Project root for log path resolution |
Event types: hook_tool_use (PostToolUse), session_stop (Stop hooks).
Log entry fields: event_type, tool_name, file_paths, session_id,
agent_name, timestamp, prev_hash, entry_hash.
Environment variables:
| Variable | Effect |
|---|---|
BATON_COMPLIANCE_FAIL_CLOSED |
1 → exit 1 on write errors |
CLAUDE_AGENT_NAME |
Agent name recorded in the log entry |
Example (Stop hook configuration):
{"hooks": [{"type": "command",
"command": "baton comply-record --event-type session_stop",
"timeout": 5}]}
Related: baton compliance verify, baton compliance rechain, baton policy-check
baton compliance¶
Show compliance reports generated during task execution.
| Argument | Required | Default | Description |
|---|---|---|---|
--task-id ID |
No | -- | Show a specific compliance report |
--count N |
No | 5 |
Number of recent reports to list |
baton policy¶
List, show, or evaluate guardrail policy presets.
| Argument | Required | Description |
|---|---|---|
--show NAME |
No | Show rules of a named policy preset |
--check AGENT |
No | Agent name to evaluate (use with --preset) |
--preset NAME |
No | Policy preset name to evaluate against (use with --check) |
--paths PATHS |
No | Comma-separated allowed file paths (use with --check) |
--tools TOOLS |
No | Comma-separated tools available (use with --check) |
Without flags, lists all available policy presets.
Examples:
# List all presets
baton policy
# Show a specific preset's rules
baton policy --show regulated-data
# Check an agent against a preset
baton policy --check backend-engineer--python \
--preset regulated-data \
--paths "app/,tests/" \
--tools "Bash,Read,Edit"
baton escalations¶
Show, resolve, or clear agent escalations.
| Argument | Required | Description |
|---|---|---|
--all |
No | Show all escalations, including resolved |
--resolve AGENT ANSWER |
No | Resolve the oldest pending escalation for AGENT with ANSWER |
--clear |
No | Remove all resolved escalations |
Without flags, shows only pending escalations.
Example:
# Resolve an escalation
baton escalations --resolve backend-engineer--python "Use the v2 API endpoint instead"
baton validate¶
Validate agent definition .md files for correct structure and YAML
frontmatter.
| Argument | Required | Description |
|---|---|---|
PATHS... |
Yes | File or directory paths to validate |
--strict |
No | Treat warnings as errors (exit code 1 if any warnings) |
Example:
# Validate all agents in a directory
baton validate agents/
# Validate a specific file in strict mode
baton validate agents/backend-engineer.md --strict
Exit code: 1 if any errors found (or warnings in strict mode).
baton spec-check¶
Validate agent output against a spec (JSON schema, file structure, or module exports).
| Argument | Required | Description |
|---|---|---|
--json DATA_FILE |
No | JSON data file to validate |
--files ROOT |
No | Directory root to check for expected files |
--exports MODULE |
No | Python module file to check for expected exports |
--schema SCHEMA_FILE |
No | JSON Schema file (use with --json) |
--expect NAMES |
No | Comma-separated expected files or names (use with --files/--exports) |
One of three modes must be specified:
# Validate JSON against a schema
baton spec-check --json output.json --schema schema.json
# Check file structure
baton spec-check --files src/ --expect "models.py,routes.py,tests/"
# Check module exports
baton spec-check --exports app/models.py --expect "User,Session,Token"
Exit code: 1 if validation fails.
baton detect¶
Detect the project stack (language and framework) from config files.
| Argument | Required | Default | Description |
|---|---|---|---|
--path PATH |
No | cwd | Project root path |
Output:
baton evidence¶
Build and verify per-task evidence bundles (007 Phase H). A bundle is a
self-contained directory (or .tar.gz) of verifiable artifacts that prove
what ran, what was approved, and that nothing was tampered with after the
fact.
baton evidence bundle¶
baton evidence bundle <task_id>
[--output DIR]
[--sign]
[--tar]
[--db PATH]
[--compliance-log PATH]
[--packs-dir PATH]
[--soul-db PATH]
| Argument | Required | Default | Description |
|---|---|---|---|
<task_id> |
Yes | -- | Task ID to bundle evidence for |
--output DIR |
No | .claude/team-context/ |
Root directory; bundle lands at <DIR>/evidence/<task-id>/ |
--sign |
No | false | Sign the manifest with a soul key (requires BATON_SOULS_ENABLED=1) |
--tar |
No | false | Package bundle as .tar.gz and remove the directory |
--db PATH |
No | .claude/team-context/baton.db |
Override baton.db location |
--compliance-log PATH |
No | auto | Override compliance-audit.jsonl path |
--packs-dir PATH |
No | .claude/packs/ |
Override assurance packs directory |
--soul-db PATH |
No | ~/.baton/central.db |
Override central.db for soul signing |
Output: Evidence bundle written to: <path>
Bundle contents:
| File | What it proves |
|---|---|
manifest.json |
Inventory of all files with SHA-256 hashes; optional soul signature |
aibom.json |
AI Bill of Materials — models, agents, gates, knowledge |
aibom.md |
Human-readable AIBOM |
compliance-segment.jsonl |
Task-scoped compliance-audit entries (omitted if no log exists) |
gates.json |
Full gate_results dump for this task |
verdicts.json |
Auditor/reviewer step verdicts with extracted AuditorVerdict |
approvals.json |
approval_results + pending approval request if present |
packs.json |
Assurance packs + active-policy snapshot (omitted if none found) |
Example:
baton evidence bundle task-abc123 --output /tmp/bundles --tar
# → /tmp/bundles/evidence/task-abc123.tar.gz
baton evidence bundle task-abc123 --sign
# → .claude/team-context/evidence/task-abc123/ (signed manifest)
baton evidence verify¶
| Argument | Required | Default | Description |
|---|---|---|---|
<path> |
Yes | -- | Path to bundle directory or .tar.gz |
--strict |
No | false | Exit on the first failure (default: report all) |
Exit codes:
| Code | Meaning |
|---|---|
| 0 | All checks passed (warnings are OK) |
| 1 | One or more integrity failures |
| 2 | Bundle is unusable (manifest missing or unparseable) |
Checks performed:
- manifest.json present and valid JSON
- Per-file SHA-256 matches manifest
- compliance-segment.jsonl internal chain consistency
- AIBOM chain_anchor vs segment tail (WARNING on mismatch, not failure)
- Soul signature verification when soul_signature is present
Example:
# CI-runnable, no network or database needed
baton evidence verify .claude/team-context/evidence/task-abc123/
# → Bundle OK — all checks passed.
baton evidence verify /tmp/bundles/task-abc123.tar.gz
# → Bundle OK — all checks passed.
Related: baton govern aibom, baton compliance
Improve Commands¶
baton scores¶
Show agent performance scorecards.
| Argument | Required | Description |
|---|---|---|
--agent NAME |
No | Show scorecard for a specific agent |
--write |
No | Write scorecard report to disk |
--trends |
No | Show performance trends for all agents |
Without flags, prints the full scorecard report to stdout.
Example:
# View trends for all agents
baton scores --trends
# Specific agent scorecard
baton scores --agent backend-engineer--python
baton evolve (deprecated)¶
Deprecated. Prompt-evolution proposals are now produced by the unified learning loop. Use
baton learn run-cycleinstead. The shim still works and prints aDEPRECATED:warning to stderr.
baton patterns¶
Display and refresh learned orchestration patterns.
| Argument | Required | Default | Description |
|---|---|---|---|
--refresh |
No | false | Re-analyse the usage log and update learned-patterns.json |
--task-type TYPE |
No | -- | Show patterns for a specific task type |
--min-confidence N |
No | 0.0 |
Filter patterns by minimum confidence (0.0-1.0) |
--recommendations |
No | false | Show sequencing recommendations for each task type |
Examples:
# Refresh patterns from usage log
baton patterns --refresh
# View high-confidence patterns only
baton patterns --min-confidence 0.8
# Sequencing recommendations
baton patterns --recommendations
baton budget¶
Show or refresh budget tier recommendations based on usage history.
| Argument | Required | Description |
|---|---|---|
--recommend |
No | Re-analyse the usage log and display fresh recommendations |
--save |
No | Save recommendations to budget-recommendations.json |
--auto-apply |
No | Show only auto-applicable (downgrade) recommendations above 80% confidence |
Without flags, shows previously saved recommendations.
Example:
# Generate and save budget recommendations
baton budget --recommend --save
# View auto-applicable downgrades
baton budget --auto-apply
baton changelog¶
Show agent changelog entries or list backup files.
| Argument | Required | Description |
|---|---|---|
--agent NAME |
No | Show history for a specific agent |
--backups [NAME] |
No | List backup files. With a name: filter to that agent. Without: all backups. |
Examples:
# Show full changelog
baton changelog
# Show changelog for one agent
baton changelog --agent backend-engineer--python
# List all backup files
baton changelog --backups
# List backups for a specific agent
baton changelog --backups backend-engineer--python
baton anomalies¶
Detect and display system anomalies.
| Argument | Required | Description |
|---|---|---|
--watch |
No | Show anomaly detection status and trigger readiness |
Without flags, detects and displays current anomalies with severity, agent, metric, current value, threshold, and evidence.
baton experiment (deprecated)¶
Deprecated. Experiment tracking is folded into the unified learning loop. Use
baton learn run-cycle(which handles auto-apply, escalate, and experiment rollback automatically) instead. The shim still works and prints aDEPRECATED:warning to stderr.
baton improve (deprecated)¶
Deprecated. Use
baton learn improveinstead. The shim still works and prints aDEPRECATED:warning to stderr.
baton learn¶
Learning automation — track, analyze, propose, and apply fixes for recurring issues. This is a command group with subcommands.
| Subcommand | Description |
|---|---|
status |
Dashboard: open issues by type/severity, auto-apply stats |
issues |
List learning issues (filterable by --type, --severity, --status) |
analyze |
Run analysis: compute confidence, mark auto-apply candidates |
apply |
Apply a specific fix (--issue ID) or all proposed (--all-safe) |
interview |
Interactive structured dialogue for human-directed decisions |
history |
Show resolution history (--limit N, default 20) |
reset |
Reopen an issue and rollback its applied override (--issue ID) |
run-cycle |
Instantiate the learning-cycle plan template (and optionally execute it) |
improve |
Run the improvement loop or view reports (formerly baton improve) |
baton learn run-cycle¶
Instantiate the learning-cycle plan template. The cycle collects execution data, analyzes patterns, proposes improvements, requires human approval, applies changes, and documents outcomes.
| Flag | Default | Description |
|---|---|---|
--run |
false | Execute the cycle immediately via baton execute run after creating the plan |
--dry-run |
false | Print the baton execute run command that would be invoked, without executing |
--template PATH |
bundled | Path to a custom learning-cycle plan template JSON file |
baton learn improve¶
Run a full improvement cycle (formerly baton improve). Detects
anomalies, generates recommendations, auto-applies safe changes,
escalates risky ones, and starts experiments.
baton learn improve [--run | --force | --report | --experiments | --history] [--min-tasks N] [--interval N]
| Flag | Description |
|---|---|
--run |
Run a full improvement cycle |
--force |
Force-run a cycle bypassing the data-threshold check |
--report |
Show the latest improvement report |
--experiments |
Show active experiments |
--history |
Show all improvement reports |
--min-tasks N |
Minimum total tasks before analysis fires (overrides BATON_MIN_TASKS) |
--interval N |
Re-analyze every N new tasks (overrides BATON_ANALYSIS_INTERVAL) |
Examples:
# Dashboard
baton learn status
# List high-severity issues
baton learn issues --severity high
# Analyze and auto-apply safe fixes
baton learn analyze
baton learn apply --all-safe
# Run a full improvement cycle
baton learn improve --run
# Instantiate and execute the learning cycle
baton learn run-cycle --run
Knowledge Commands¶
baton knowledge¶
Knowledge utilities: validate packs, search metadata, simulate resolver attachments, generate codebase briefings, harvest knowledge from existing artefacts, manage item lifecycle, and report effectiveness. This is a command group with subcommands.
| Subcommand | Description |
|---|---|
doctor |
Validate knowledge packs and print actionable warnings |
search |
Search knowledge metadata with the registry TF-IDF index |
resolve |
Simulate knowledge attachments for an agent and task |
brief |
Generate a concise codebase briefing for new agents |
harvest |
Harvest knowledge entries from existing artefacts (ADRs, PR reviews) |
stale |
List active knowledge items that look stale |
deprecate |
Flag a knowledge item as deprecated |
retire |
Retire a knowledge item immediately (skips grace window) |
sweep |
Auto-retire deprecated items whose grace period has elapsed |
usage |
Show usage count and last-used time for a single item |
effectiveness |
Show per-doc effectiveness + ROI scores |
ranking |
Show all known docs ranked by historical effectiveness |
ab |
Manage knowledge A/B experiments |
baton knowledge doctor¶
Validate knowledge packs and print actionable warnings (missing or
invalid knowledge.yaml, declared documents that don't exist, empty
descriptions, duplicate document names, documents too large for inline
delivery, or a pack/root directory that can't be listed or read). Runtime
loading tolerates these issues; doctor reports them as actionable edits
without changing loading semantics.
A declared document with a known non-Markdown extension (.json,
.yaml, .yml, .txt, .py, .toml, .csv) must exist under that
exact name — it is not satisfied by a same-named .md shadow file (e.g.
a manifest declaring config.json is not satisfied by config.json.md).
Only genuinely extensionless declared names fall back to a .md suffix.
A pack directory (or the root itself) that raises an OS-level error when
listed or read is reported as an unreadable-pack issue and skipped, so
one bad directory (permissions, a cloud-sync placeholder, etc.) doesn't
abort the rest of the run. Repeated --knowledge-root arguments that
resolve to the same (non-existent) directory now report a single
missing-root issue instead of one per repetition.
| Flag | Default | Description |
|---|---|---|
--knowledge-root DIR |
global + project | Knowledge root to validate; repeatable and de-duplicated after resolving to an absolute path (default: ~/.claude/knowledge and ./.claude/knowledge) |
--format FORMAT |
text |
Output format: text or json |
--json |
-- | Alias for --format json |
--strict |
false | Exit non-zero when any warning is found |
baton knowledge search¶
Search knowledge metadata with the registry TF-IDF index.
| Argument | Required | Default | Description |
|---|---|---|---|
QUERY |
Yes | -- | Search query text (one or more words) |
--knowledge-root DIR |
No | global + project | Knowledge root to search; repeatable |
--limit N |
No | 10 |
Maximum results to return |
--format FORMAT |
No | table |
Output format: table or json |
--json |
No | -- | Alias for --format json |
baton knowledge resolve¶
Simulate the knowledge attachments the resolver would produce for an agent and task, without dispatching anything.
| Flag | Required | Default | Description |
|---|---|---|---|
--agent NAME |
Yes | -- | Agent name |
--task TEXT |
Yes | -- | Task description |
--knowledge-root DIR |
No | global + project | Knowledge root to load; repeatable |
--task-type TYPE |
No | -- | Optional task type used by resolver keyword extraction |
--risk LEVEL |
No | LOW |
Risk level passed through to resolver simulation |
--knowledge-pack PACK |
No | -- | Explicit pack to include; repeatable |
--knowledge PATH |
No | -- | Explicit document path to include; repeatable |
--format FORMAT |
No | table |
Output format: table or json |
--json |
No | -- | Alias for --format json |
baton knowledge brief¶
Generate a concise codebase briefing (stack, layout, entry points, conventions, tests, health snapshot) that dispatched agents can read instead of re-discovering the basics every run.
| Flag | Default | Description |
|---|---|---|
--project DIR |
cwd | Project directory to brief |
--save |
false | Write to .claude/team-context/codebase-brief.md (or codebase-brief.json with --format json) instead of stdout |
--format FORMAT |
markdown |
Output format: markdown or json |
baton knowledge harvest¶
Convert existing artefacts into knowledge entries. Both harvesters are idempotent: re-running on unchanged input is a no-op.
baton knowledge harvest adrs [--source-dir DIR] [--target-pack PACK] [--knowledge-root DIR]
baton knowledge harvest reviews --pr N [--repo OWNER/NAME] [--knowledge-root DIR]
adrs walks a docs tree for Architecture Decision Records and converts
each into a knowledge document:
| Flag | Default | Description |
|---|---|---|
--source-dir DIR |
docs/ |
Root to walk for ADR markdown files |
--target-pack PACK |
decisions |
Knowledge pack name to write into |
--knowledge-root DIR |
.claude/knowledge |
Override the knowledge root |
reviews pulls PR review comments via the gh CLI and distils salient
ones into a lessons document:
| Flag | Required | Default | Description |
|---|---|---|---|
--pr N |
Yes | -- | Pull-request number to harvest |
--repo OWNER/NAME |
No | auto-detect via gh |
Repository slug |
--knowledge-root DIR |
No | .claude/knowledge |
Override the knowledge root |
baton knowledge stale¶
List active knowledge items that look stale. Lifecycle subcommands
(stale, deprecate, retire, sweep, usage) operate on the
project database at .claude/team-context/baton.db.
| Flag | Default | Description |
|---|---|---|
--days N |
90 |
Days since last use threshold |
--max-usage N |
5 |
Items with a usage count below this are eligible |
baton knowledge deprecate¶
Flag a knowledge item as deprecated; schedules retirement after the grace period elapses.
| Argument | Required | Default | Description |
|---|---|---|---|
KNOWLEDGE_ID |
Yes | -- | Item ID in the form <pack_name>/<doc_name> |
--grace N |
No | 30 |
Grace period in days before auto-retirement |
--reason TEXT |
No | -- | Optional human-readable reason recorded with the deprecation |
baton knowledge retire¶
Retire a knowledge item immediately, skipping the grace window.
baton knowledge sweep¶
Auto-retire deprecated items whose grace period has elapsed. Safe to schedule (e.g. in a daily cron) — it only retires items the operator has already deprecated.
baton knowledge usage¶
Show lifecycle state, usage count, last-used time, and staleness for a single item.
baton knowledge effectiveness¶
Show per-doc effectiveness + ROI scores as a sorted Markdown table or JSON document.
baton knowledge effectiveness [--pack PACK] [--since-days N] [--format markdown|json] [--stale] [--threshold-days N]
| Flag | Default | Description |
|---|---|---|
--pack PACK |
all packs | Restrict the report to a single knowledge pack |
--since-days N |
30 |
Rolling window in days for the effectiveness rollup (0 = all time) |
--format FORMAT |
markdown |
Output format: markdown or json |
--stale |
false | Show only stale candidates |
--threshold-days N |
90 |
Stale-by-age threshold in days (used with --stale) |
baton knowledge ranking¶
Show all known docs ranked by historical effectiveness. Reads
v_knowledge_effectiveness from the central database.
| Flag | Default | Description |
|---|---|---|
--output FORMAT |
table |
Output format: table or json |
--db PATH |
~/.baton/central.db |
Path to the SQLite database |
baton knowledge ab¶
Manage knowledge A/B experiments.
baton knowledge ab list
baton knowledge ab create --kid KNOWLEDGE_ID --a PATH_A --b PATH_B [--ratio RATIO]
baton knowledge ab results EXPERIMENT_ID
baton knowledge ab stop EXPERIMENT_ID
create flags:
| Flag | Required | Default | Description |
|---|---|---|---|
--kid KNOWLEDGE_ID |
Yes | -- | Canonical pack/doc id (e.g. security/owasp.md) |
--a PATH_A |
Yes | -- | Relative path to the variant A document |
--b PATH_B |
Yes | -- | Relative path to the variant B document |
--ratio RATIO |
No | 0.5 |
Fraction routed to variant A (between 0.0 and 1.0) |
Examples:
# Validate knowledge packs, failing CI on warnings
baton knowledge doctor --strict
# Search the knowledge index
baton knowledge search payment idempotency --limit 5
# Preview what the resolver would attach for a dispatch
baton knowledge resolve --agent backend-engineer--python \
--task "Add JWT authentication middleware" --risk MEDIUM
# Generate and save a codebase brief
baton knowledge brief --save
# Harvest ADRs into the decisions pack
baton knowledge harvest adrs --source-dir docs
# Lifecycle: deprecate with a 14-day grace period, then sweep later
baton knowledge deprecate security/owasp --grace 14 --reason "superseded"
baton knowledge sweep
Related: baton plan --knowledge / --knowledge-pack, baton learn
Distribute Commands¶
baton package¶
Create, inspect, or install agent-baton package archives.
| Argument | Required | Description |
|---|---|---|
--name NAME |
No | Create a package archive with this name |
--info ARCHIVE |
No | Show manifest of an existing .tar.gz package |
--install ARCHIVE |
No | Install an agent-baton package |
--version VER |
No | Package version (default: 1.0.0) |
--description TEXT |
No | Package description |
--include-knowledge |
No | Include knowledge packs in the package |
--no-agents |
No | Exclude agents from the package |
--no-references |
No | Exclude references from the package |
--output-dir DIR |
No | Directory to write the archive to (default: cwd) |
--scope SCOPE |
No | Install scope: user or project (default: project) |
--force |
No | Overwrite existing files when installing |
--project ROOT |
No | Source project root (default: cwd) |
Examples:
# Create a package
baton package --name my-agents --version 2.0.0 \
--description "Custom agent definitions" --include-knowledge
# Inspect a package
baton package --info my-agents-2.0.0.tar.gz
# Install a package to user scope
baton package --install my-agents-2.0.0.tar.gz --scope user --force
baton publish¶
Publish a package archive to a local registry directory, or initialize a new registry.
| Argument | Required | Description |
|---|---|---|
ARCHIVE |
Yes* | Path to the .tar.gz archive (*unless using --init) |
--registry PATH |
Yes* | Path to the local registry directory (*required when publishing) |
--init PATH |
No | Initialize a new empty registry at PATH |
Examples:
# Initialize a registry
baton publish --init /shared/baton-registry
# Publish a package
baton publish my-agents-2.0.0.tar.gz --registry /shared/baton-registry
baton pull¶
Install a package from a local registry directory.
| Argument | Required | Description |
|---|---|---|
NAME |
No | Name of the package to install |
--registry PATH |
Yes | Path to the local registry directory |
--version VERSION |
No | Specific version to install (default: latest) |
--scope SCOPE |
No | Install scope: project or user (default: project) |
--force |
No | Overwrite existing files |
--list |
No | List all available packages in the registry |
--search QUERY |
No | Search packages by name substring |
Examples:
# List available packages
baton pull --list --registry /shared/baton-registry
# Search for packages
baton pull --search "auth" --registry /shared/baton-registry
# Install a specific version
baton pull my-agents --registry /shared/baton-registry --version 2.0.0 --scope user
baton verify-package (deprecated)¶
Deprecated. Use
baton sync --verify ARCHIVEinstead. The shim still works and prints aDEPRECATED:warning to stderr.
baton install¶
Install agents and references from the agent-baton repo to user or project scope.
| Argument | Required | Default | Description |
|---|---|---|---|
--scope SCOPE |
Yes | -- | user (~/.claude/) or project (.claude/) |
--source PATH |
No | . |
Path to the agent-baton repo root |
--force |
No | false | Overwrite ALL existing files |
--upgrade |
No | false | Overwrite agents + references but preserve settings, CLAUDE.md, knowledge, team-context |
--verify |
No | false | Run post-install verification checks |
Upgrade mode merges hooks into settings.json (preserving user keys)
while overwriting agents and references. CLAUDE.md and knowledge packs
are preserved.
Examples:
# Fresh install to user scope
baton install --scope user --source /path/to/agent-baton
# Upgrade agents + references, preserve settings
baton install --scope project --upgrade --verify
# Force overwrite everything
baton install --scope user --force --verify
baton transfer¶
Transfer agents, knowledge, and references between projects.
| Argument | Required | Description |
|---|---|---|
--discover |
No | Show what is available to transfer from this project |
--export TARGET |
No | Export items to a target project root |
--import SOURCE |
No | Import items from another project root |
--project ROOT |
No | Source project root (default: cwd) |
--agents NAMES |
No | Comma-separated agent names or filenames |
--knowledge PACKS |
No | Comma-separated knowledge pack directory names |
--references NAMES |
No | Comma-separated reference filenames |
--all |
No | Transfer all discoverable items |
--min-score RATE |
No | Minimum first-pass rate for --discover (0.0-1.0) |
--force |
No | Overwrite existing files at the destination |
Examples:
# Discover transferable items
baton transfer --discover
# Export specific agents to another project
baton transfer --export /path/to/other-project \
--agents "backend-engineer,test-engineer" \
--knowledge "api-patterns"
# Import everything from another project
baton transfer --import /path/to/source-project --all --force
Agent Commands¶
baton agents¶
List all available agents grouped by category.
Output:
engineering:
backend-engineer [sonnet]
backend-engineer--python [sonnet] (flavor: python)
frontend-engineer [sonnet]
governance:
auditor [opus]
code-reviewer [sonnet]
19 agents loaded.
baton route¶
Route base agent role names to their stack-specific flavored variants.
| Argument | Required | Default | Description |
|---|---|---|---|
ROLES |
No | backend-engineer frontend-engineer |
Base role names to route |
--path PATH |
No | cwd | Project root for stack detection |
Output:
Stack: python/fastapi
backend-engineer -> backend-engineer--python *
frontend-engineer -> frontend-engineer
Entries marked with * were remapped to a flavored variant.
baton events¶
Query the event log for a task.
| Argument | Required | Description |
|---|---|---|
--task TASK_ID |
No | Task ID to query events for |
--topic PATTERN |
No | Filter events by topic pattern (glob, e.g. step.*) |
--last N |
No | Show only the last N events |
--json |
No | Output events as JSON |
--summary |
No | Show a projected summary view instead of raw events |
--list-tasks |
No | List all task IDs that have event logs |
Without flags, lists all tasks with event logs.
Examples:
# List tasks with events
baton events --list-tasks
# View events for a task
baton events --task task-abc123
# Filter by topic
baton events --task task-abc123 --topic "step.*" --last 10
# Summary view
baton events --task task-abc123 --summary
# JSON output
baton events --task task-abc123 --json
baton incident¶
Manage incident response workflows.
| Argument | Required | Description |
|---|---|---|
--templates |
No | Show all built-in incident templates |
--show ID |
No | Show a specific incident document |
--create ID |
No | Create an incident document with the given ID |
--severity LEVEL |
No | Severity level for --create: P1, P2, P3, P4 |
--desc TEXT |
No | Description for --create |
Without flags, lists all incidents.
Example:
# Show available templates
baton incident --templates
# Create an incident
baton incident --create INC-2024-001 --severity P2 --desc "API latency spike"
# View an incident
baton incident --show INC-2024-001
PMO Commands¶
baton pmo serve¶
Start the PMO HTTP server (requires pip install agent-baton[api]).
| Argument | Required | Default | Description |
|---|---|---|---|
--port PORT |
No | 8741 |
Port to listen on |
--host HOST |
No | 127.0.0.1 |
Host to bind to |
baton pmo status¶
Print a terminal Kanban board summary of all registered projects.
Shows per-project progress bars and a cards table with execution status.
baton pmo add¶
Register a project with the PMO.
| Argument | Required | Description |
|---|---|---|
--id ID |
Yes | Project slug identifier (e.g. nds) |
--name NAME |
Yes | Human-readable project name |
--path PATH |
Yes | Absolute filesystem path to the project root |
--program PROGRAM |
Yes | Program this project belongs to (e.g. NDS, ATL) |
--color COLOR |
No | Optional display color |
Example:
baton pmo add --id nds --name "NDS Platform" \
--path /home/user/projects/nds --program NDS --color blue
baton pmo health¶
Print program health bar summary showing completion percentage and task status across all programs.
Output:
Program Health
NDS ████████████████████ 85% (3 active, 12 complete)
ATL ██████████░░░░░░░░░░ 50% (2 active, 1 blocked, 5 complete)
Sync Commands¶
baton sync¶
Sync project data from project-local baton.db to ~/.baton/central.db.
Also hosts two utilities folded in from removed top-level commands:
--migrate-storage (formerly baton migrate-storage) and --verify
(formerly baton verify-package).
| Argument | Required | Default | Description |
|---|---|---|---|
SUBCOMMAND |
No | -- | status (or omit for default sync) |
--all |
No | false | Sync all registered projects |
--project ID |
No | -- | Sync a specific project by ID |
--rebuild |
No | false | Full rebuild (delete all central rows then re-sync) |
--migrate-storage |
No | false | Migrate JSON/JSONL flat files to SQLite (baton.db). Formerly baton migrate-storage. |
--dry-run |
No | false | (with --migrate-storage) Show what would be migrated without writing |
--keep-files |
No | true | (with --migrate-storage) Keep originals after migration |
--remove-files |
No | false | (with --migrate-storage) Archive originals to pre-sqlite-backup/ |
--team-context PATH |
No | .claude/team-context |
(with --migrate-storage) Path to team-context directory |
--migrate-verify |
No | false | (with --migrate-storage) Verify row counts after migration |
--verify [ARCHIVE] |
No | -- | Validate a .tar.gz agent-baton package. Formerly baton verify-package. |
--checksums |
No | false | (with --verify) Display per-file SHA-256 checksums |
Default behavior (no flags): syncs the current project by auto-detecting from the working directory.
Examples:
# Sync current project
baton sync
# Sync all registered projects
baton sync --all
# Sync a specific project
baton sync --project nds
# Full rebuild
baton sync --rebuild
# Show sync watermarks
baton sync status
# Migrate JSON/JSONL flat files to SQLite (replaces 'baton migrate-storage')
baton sync --migrate-storage --dry-run
baton sync --migrate-storage --migrate-verify
baton sync --migrate-storage --remove-files --migrate-verify
# Validate a package archive (replaces 'baton verify-package')
baton sync --verify my-agents-2.0.0.tar.gz --checksums
Exit code: 1 if --verify validation fails or sync errors occur.
Query Commands¶
baton query¶
Query execution history, agent performance, and cross-project data from
the project-local baton.db.
Predefined queries (subcommands):
| Subcommand | Description | Argument |
|---|---|---|
agent-reliability |
Agent success rates and token costs | -- |
agent-history NAME |
Recent step results for a specific agent | Agent name |
tasks |
Recent task list | -- |
task-detail TASK_ID |
Full breakdown for one task | Task ID |
knowledge-gaps |
Recurring knowledge gaps across tasks | -- |
roster-recommendations |
Consensus roster recommendations | -- |
gate-stats |
Gate pass rates by type | -- |
cost-by-type |
Token costs grouped by task type | -- |
cost-by-agent |
Token costs grouped by agent | -- |
current |
What is running right now | -- |
patterns |
Learned patterns with confidence scores | -- |
Shared options:
| Flag | Default | Description |
|---|---|---|
--format FORMAT |
table |
Output format: table, json, csv |
--days N |
30 |
Days window for time-bounded queries |
--limit N |
20 |
Maximum rows for list queries |
--status STATUS |
-- | Filter tasks by status (for tasks subcommand) |
--min-frequency N |
1 |
Minimum occurrence for knowledge-gaps |
--db PATH |
-- | Explicit path to baton.db |
--central |
false | Query ~/.baton/central.db instead |
Ad-hoc SQL:
Examples:
# Agent reliability report
baton query agent-reliability --format json
# Task detail
baton query task-detail task-abc123
# Cost analysis
baton query cost-by-agent --days 90
# Cross-project query
baton query tasks --central --limit 50
baton cquery¶
Cross-project SQL queries exclusively against ~/.baton/central.db.
| Argument | Required | Description |
|---|---|---|
QUERY |
No | SQL statement or shortcut name |
--format FORMAT |
No | Output format: table (default), json, csv |
--tables |
No | List all tables and views in central.db |
--table TABLE |
No | Describe a specific table's columns |
--db PATH |
No | Override path to central.db |
Shortcuts:
| Name | Query |
|---|---|
agents |
SELECT * FROM v_agent_reliability |
costs |
SELECT * FROM v_cost_by_task_type |
gaps |
SELECT * FROM v_recurring_knowledge_gaps |
failures |
SELECT * FROM v_project_failure_rate |
mapping |
SELECT * FROM v_external_plan_mapping |
Examples:
# Use a shortcut
baton cquery agents
# Custom SQL
baton cquery "SELECT * FROM executions LIMIT 10" --format json
# Schema introspection
baton cquery --tables
baton cquery --table executions
Source Commands¶
baton source¶
Manage external work-item source connections. Adapters: ado, github,
jira, linear, and beads. The beads adapter is local interop — it reads
an external Beads project's exported
.beads/issues.jsonl interchange file (no bd Go binary or Dolt dependency).
baton source add¶
| Argument | Required | Description |
|---|---|---|
TYPE |
Yes | Source type: ado, github, jira, linear, beads |
--name NAME |
Yes | Display name for this source |
--org ORG |
No | Organization or account name (ADO/GitHub; email for Jira) |
--project PROJECT |
No | Project name within the source (ADO/Jira/Linear) |
--pat-env ENV_VAR |
No | Environment variable name holding the PAT/token |
--url URL |
No | Base URL for self-hosted instances |
--config JSON |
No | Extra adapter config as a JSON object, merged into the stored config. The beads adapter uses {"beads_dir": ".beads"} |
Examples:
# Azure DevOps
baton source add ado --name "Team Board" \
--org contoso --project "Data Platform" --pat-env ADO_PAT
# Local Beads project (reads .beads/issues.jsonl; run `bd export` first)
baton source add beads --name "Local Beads" \
--config '{"beads_dir": ".beads"}'
baton source sync beads-beads
baton source list¶
Lists all registered external sources with type, name, enabled status, and last sync time.
baton source sync¶
| Argument | Required | Description |
|---|---|---|
SOURCE_ID |
No | Source ID to sync (see baton source list) |
--all |
No | Sync all registered sources |
baton source remove¶
Removes a registered external source from central.db.
baton source map¶
| Argument | Required | Default | Description |
|---|---|---|---|
SOURCE_ID |
Yes | -- | Source ID |
EXTERNAL_ID |
Yes | -- | External item ID (e.g. ADO work item number) |
PROJECT_ID |
Yes | -- | Baton project ID |
TASK_ID |
Yes | -- | Baton task/execution ID |
--type TYPE |
No | implements |
Relationship type: implements, blocks, related |
Example:
Diagnostics Commands¶
baton doctor¶
Read-only installation and workspace health report: Python and package
versions, bundled and project agents, knowledge packs, assurance packs,
PMO UI assets, package resources, optional CLIs (bd, claude), the
.beads workspace, git and git-worktree status, .claude/team-context
writability, saved-plan (planner) validation, and terminology. Makes no
changes to the project.
| Flag | Default | Description |
|---|---|---|
--json |
false | Emit the report as JSON (schema-versioned) instead of the human-readable summary |
Exits non-zero (1) if any check reports error status.
Planner validation check¶
The planner_validation check validates the most relevant saved
plan.json with the same rules as baton plan-validate. Doctor picks which
plan to validate by resolving an active task the same way the rest of
the CLI does — BATON_TASK_ID env var, then the active-task marker in
the project's SQLite store (honoring BATON_DB_PATH if set), then the
.claude/team-context/active-task-id.txt file marker — and reports
which path it took in the check's details.plan_selection field:
plan_selection |
Meaning |
|---|---|
active-task |
An active task resolved; its plan.json was validated |
fallback-first-found |
No active task resolved; doctor validated the first saved plan found, in fixed order: .claude/team-context/plan.json, project-root plan.json, then each executions/*/plan.json (sorted) |
When plan_selection is fallback-first-found and a plan was actually
found, the human-readable message adds a caveat: (caveat: no active
task resolved; validating the first saved plan found, not necessarily
the current one). No caveat is added when no plan was found at all —
that case is reported separately as No saved plan is available to
validate, not a guess.
API Server¶
baton serve¶
Start the HTTP API server (requires pip install agent-baton[api]).
| Argument | Required | Default | Description |
|---|---|---|---|
--port PORT |
No | 8741 |
Port to listen on |
--host HOST |
No | 127.0.0.1 |
Host to bind to |
--token TOKEN |
No | -- | API token for authentication (also reads BATON_API_TOKEN env var) |
--team-context DIR |
No | .claude/team-context |
Path to the team-context root directory |
Example:
Common Workflows¶
Full Orchestrated Task (Sequential)¶
# 1. Create a plan
baton plan "Add JWT auth middleware and integration tests" --save --explain
# 2. Create a feature branch
git checkout -b feat/jwt-auth
# 3. Start execution
baton execute start
export BATON_TASK_ID=<task-id-from-output>
# 4. Loop through actions
baton execute next
# -> DISPATCH: spawn subagent, then record
baton execute dispatched --step-id 1.1 --agent backend-engineer--python
# (subagent does work)
baton execute record --step-id 1.1 --agent backend-engineer--python \
--status complete --outcome "Added JWT middleware" --files "app/auth.py"
baton execute next
# -> GATE: run the gate command
baton execute gate --phase-id 1 --result pass --output "All tests passed"
baton execute next
# -> COMPLETE
baton execute complete
Background Daemon with API¶
# 1. Create a plan
baton plan "Refactor data pipeline" --save
# 2. Start daemon with API server
baton daemon start --plan .claude/team-context/plan.json \
--serve --port 8741 --max-parallel 3
# 3. Monitor progress
baton daemon status
baton execute list
# 4. Check for decisions that need human input
baton decide
baton decide --resolve req-123 --option approve
Cross-Project Analysis¶
# 1. Register projects with PMO
baton pmo add --id nds --name "NDS Platform" --path /home/user/nds --program NDS
baton pmo add --id atl --name "ATL Service" --path /home/user/atl --program ATL
# 2. Sync all projects to central.db
baton sync --all
# 3. Query across projects
baton cquery agents
baton cquery "SELECT project_id, COUNT(*) as tasks FROM executions GROUP BY project_id"
# 4. View portfolio health
baton pmo health
Improvement Cycle¶
# 1. Check for anomalies
baton anomalies
# 2. Run improvement cycle
baton learn improve --run
# 3. Review recommendations
baton budget --recommend
baton learn run-cycle
# 4. Refresh learned patterns
baton patterns --refresh
# 5. Check experiment status (folded into the learn loop)
baton learn improve --experiments
Package Distribution¶
# 1. Create a package
baton package --name my-agents --version 1.0.0 \
--description "Custom agent set" --include-knowledge
# 2. Verify the package
baton sync --verify my-agents-1.0.0.tar.gz --checksums
# 3. Initialize a registry and publish
baton publish --init /shared/registry
baton publish my-agents-1.0.0.tar.gz --registry /shared/registry
# 4. Pull from registry on another machine
baton pull my-agents --registry /shared/registry --scope user
Environment Variables¶
The full list of Baton environment variables. The same table is mirrored in references/baton-engine.md.
| Variable | Purpose | Default |
|---|---|---|
BATON_TASK_ID |
Bind a shell session to a specific execution. Set after baton execute start to scope all subsequent commands. |
auto-detected |
BATON_DB_PATH |
Override the project baton.db location. CLI walks upward from cwd if unset. |
discovered |
BATON_APPROVAL_MODE |
PMO approval policy: local (self-approve) or team (different reviewer required). |
local |
BATON_RUN_TOKEN_CEILING |
Per-run cumulative spend cap (USD float). Read fresh on every check; restored on baton execute resume. The immune system respects it; main Executor.dispatch() only warns at HIGH/CRITICAL run start (bd-3f80). |
unset |
BATON_SOULS_ENABLED |
Wave 6.1 Part B persistent agent souls (signing + revocation). | 0 |
BATON_BD_BACKEND |
ADR-13b WP-G bead backend. bd is the only supported value — SQLite fallback removed. Other values log a deprecation warning and BdNotAvailable is raised if bd is missing. |
bd |
BATON_BD_ENABLED |
Kept for backward compatibility; has no effect after WP-G — bd is always required. |
1 |
BATON_BD_BIN |
bd binary path/name. |
bd |
BATON_BD_PREFIX |
Issue prefix for bd init (matches baton's bd-<hash> IDs). |
bd |
BATON_IMMUNE_ENABLED |
Immune-system monitoring loop. | 0 |
BATON_EXEC_BEADS_ENABLED |
Wave 6.1 Part C executable beads. Sandbox is process-level only — see references/baton-patterns.md trust-boundary section before extending to external-origin input. |
0 |
BATON_GATE_RETRY |
Enable single gate-retry: on first gate failure, re-dispatch the failing step once with gate output appended to the prompt. Second failure is terminal. Writes gate_retry_dispatched or gate_failed_terminal to compliance-audit.jsonl. |
0 |
BATON_WORKTREE_STALE_HOURS |
Worktree GC stale threshold in hours; legacy alias BATON_WORKTREE_GC_HOURS. GC runs on every baton execute complete. |
4 |
BATON_API_TOKEN |
Bearer token for the FastAPI server (baton serve). CLI --token flag takes precedence. |
unset |
ANTHROPIC_API_KEY |
Required for AI risk classification and the Haiku planner classifier. | unset |
Task-ID Resolution Order¶
Every baton execute subcommand resolves the target execution through
this priority chain:
| Mechanism | Scope | Notes |
|---|---|---|
--task-id FLAG |
Single invocation | Highest priority |
BATON_TASK_ID |
Shell session | Set with export; persists for session lifetime |
active-task-id.txt |
Repository | Updated by baton execute switch; single-execution fallback |
For agentic callers (Claude Code's orchestrator): env vars do not
persist across independent Bash tool calls. Pass --task-id explicitly
on every CLI call when driving concurrent executions from an agent context.
Exit Codes¶
| Code | Meaning |
|---|---|
0 |
Success |
1 |
Error: missing prerequisites, validation failure, failed gate, or invalid arguments |
2 |
Experimental feature not opted in (feature flag required but not set) |
Commands that exit with code 1:
- baton execute start -- plan file not found
- baton validate -- errors found (or warnings in --strict mode)
- baton spec-check -- validation failed
- baton sync --verify -- package validation failed (formerly baton verify-package)
- baton sync -- sync failures
- baton source -- source not found or connection failed
Troubleshooting¶
"status must be one of: complete, failed, dispatched"¶
Cause: baton execute record --status pass (or done, success).
Fix: Use only complete or failed:
# Wrong
baton execute record --step-id 1.1 --agent foo --status pass
# Correct
baton execute record --step-id 1.1 --agent foo --status complete
"No active execution state found"¶
Cause: baton execute next or baton execute record was called
before baton execute start, or execution-state.json was deleted.
Fix: Run baton execute start (or baton execute resume if state
exists from a previous session).
Stack detection returns unknown¶
Cause: baton plan or baton detect cannot find config files in
the current directory.
Fix: Pass --project PATH pointing to the directory containing
pyproject.toml, package.json, go.mod, etc.
Plan has generic descriptions¶
Cause: The planner received a vague task summary.
Fix: Pass a richer description:
# Too vague
baton plan "auth" --save
# Better
baton plan "Add JWT authentication middleware to the FastAPI app, including login/logout endpoints and test coverage" --save
"API dependencies not installed"¶
Cause: baton serve or baton pmo serve requires FastAPI + uvicorn.
Fix:
Concurrent executions interfere with each other¶
Cause: Multiple executions without proper session binding.
Fix: After each baton execute start, set the BATON_TASK_ID
environment variable from the printed session binding:
Or pass --task-id explicitly on every command.
"No sync watermarks found"¶
Cause: No projects have been synced to central.db yet.
Fix: Register a project with baton pmo add, then run baton sync.
"No adapter implemented for source type"¶
Cause: Only the ADO adapter is currently implemented.
Fix: For other sources, implement ExternalSourceAdapter in
agent_baton/core/storage/adapters/<type>.py.
File Layout Reference¶
All engine files live under .claude/team-context/ relative to the
project root:
.claude/team-context/
+-- plan.json Machine-readable execution plan
+-- plan.md Human-readable plan
+-- execution-state.json Live engine state (crash recovery)
+-- context.md Shared project context
+-- mission-log.md Structured log of agent completions
+-- usage-log.jsonl Token and cost records per task
+-- baton.db SQLite database (project-local)
+-- active-task-id.txt Active execution marker
+-- executions/
| +-- <task-id>/
| +-- execution-state.json
| +-- plan.json
| +-- plan.md
+-- traces/
| +-- <task-id>.json Full execution trace
+-- retrospectives/
| +-- <task-id>.md Post-execution analysis
+-- events/
| +-- <task-id>.jsonl Event log per task
+-- evolution-proposals/ Prompt improvement proposals
+-- context-profiles/ Agent context efficiency profiles
+-- learned-patterns.json Learned orchestration patterns
+-- budget-recommendations.json
Central database: ~/.baton/central.db (cross-project data, PMO state).