convez.ai
AgenteAutomaçãoAvançado
DaveGerson

Agent Baton

DaveGerson/agent-baton

Governance e auditoria para Claude Code com orquestração de agentes

Ver no GitHub
InicialPluginScore · de 0 a 100

Sistema de orquestração multi-agente para Claude Code que implementa governance, auditoria e controle de políticas em tarefas de engenharia de software complexas. Quebra trabalhos em fases especializadas, automatiza gates de QA e mantém rastreabilidade completa com bundles de evidência verificáveis.

Instalação

$npx convez-ai DaveGerson/agent-baton

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
1
Saúde
57%
Último commit
há 3 meses
Versão
—
Issues abertas
7
Contribuidores
3

Casos de uso

  • Automação de tarefas de engenharia de software com múltiplas fases
  • Enforçamento de políticas de conformidade e segregação de deveres
  • Classificação de risco de dados e aprovações escaladas
  • Auditoria e rastreabilidade de mudanças feitas por IA

Veredito

Ferramenta madura e bem-documentada para equipes que precisam de controle rigoroso sobre IA em produção. Essencial em contextos regulados; complexa demais para casos simples sem benefício de compliance.

README

A tradução para o português deste README ainda está na fila.

Agent Baton

📖 Docs: https://davegerson.github.io/agent-baton/

Governance and assurance for Claude Code.

Agent Baton is a governance and assurance harness for Claude Code. It enforces domain-specific policy on every AI-authored change — data-classification risk, required expert reviewers, compliance gates, segregation-of-duties approval — and makes the outcome auditable through a verifiable evidence bundle. Claude Code owns the work; Baton owns the accountability.

Harness mode (zero loop overhead): install the hooks (policy-check, comply-record, classify --activate), activate an assurance pack, and every tool call Claude Code makes is evaluated against your policy. Evidence bundles are generated automatically. No plan. No execution loop. No API keys beyond Claude.

Managed mode (for regulated work): set BATON_PLAN_REVIEW or use the spec queue — Baton runs the full plan→DISPATCH→GATE→APPROVAL loop, activated automatically when the data classifier flags a task as HIGH or CRITICAL risk.

Spec federation: submit or import specs from Azure DevOps / GitHub Issues → AI-derived risk + cost forecast → senior review before firing. The cheapest control point for org AI spend.


Why Agent Baton?

The problem: Claude Code is powerful, but complex tasks -- the ones that touch multiple files, need testing, and require different expertise -- benefit from structure. Without it, you get context bloat, missed test coverage, and no audit trail.

The solution: Agent Baton gives Claude Code a project management layer. It breaks work into phases, assigns each phase to a specialist agent, runs automated QA gates between them, and tracks everything. You stay in control while the agents do the heavy lifting.

Without BatonWith Baton
One long conversation doing everythingPhases with specialist agents
Manual "did you run the tests?"Automated pytest/lint gates between phases
No record of what happenedFull traces, usage logs, retrospectives
Hope the AI remembers contextScoped delegation prompts per agent
Single point of failureCrash recovery via baton execute resume

Get Started in 5 Minutes

1. Install agent definitions

git clone https://github.com/DaveGerson/agent-baton.git
cd agent-baton
scripts/install.sh          # Linux/macOS
# or: scripts/install.ps1   # Windows (no admin required)

The installer prompts for scope (user-level ~/.claude/ for all projects, or project-level .claude/ for the current project only) and copies agent definitions, reference procedures, a template CLAUDE.md, and settings.json hooks.

2. Install the Python engine

From PyPI (recommended):

pip install agent-baton          # Core engine + CLI
pip install agent-baton[pmo]     # + REST API and PMO server
pip install agent-baton[classify] # + AI risk classification

From source (for development):

git clone https://github.com/DaveGerson/agent-baton.git
cd agent-baton
pip install -e ".[dev]"          # Core engine + CLI + test deps

3. Verify

# In Claude Code
/agents                     # Should list ~30 agents

# In terminal
baton agents                # List agents from Python registry
baton detect                # Detect your project's stack

4. Optional: install cymbal (recommended)

cymbal is a tree-sitter code indexer that agents use for symbol lookup and impact analysis. Without it, agents fall back to LSP or grep.

# Check if cymbal is installed
cymbal --help

# If not, install the binary to ~/.local/bin/
# (see cymbal docs for platform-specific instructions)

5. Run your first task

In a Claude Code session:

Use the orchestrator to add a health check endpoint with tests

That's it. The orchestrator plans, dispatches agents, runs gates, and delivers tested code.

See QUICKSTART.md for a detailed walkthrough, or docs/examples/first-run.md for a complete end-to-end example with command output.


Features

30 Specialist Agents

Stack-aware agents that the orchestrator selects and routes automatically. First time on a Go project? The talent-builder creates backend-engineer--go. Next time, the routing table finds it.

CategoryAgents
Orchestrationorchestrator
Backendbackend-engineer, --python, --node
Frontendfrontend-engineer, --react, --dotnet
Architecturearchitect
Qualitytest-engineer, code-reviewer, security-reviewer
Governanceauditor (independent veto power)
Datadata-engineer, data-analyst, data-scientist
Visualizationvisualization-expert
Operationsdevops-engineer
Domainsubject-matter-expert
Metatalent-builder (creates new agent definitions)

Orchestration Engine

A deterministic state machine that plans, sequences, and tracks multi-agent tasks:

  • Intelligent planning -- auto-detects your stack, classifies risk, assigns budget tiers, sequences phases with dependency awareness. Supports complexity override (--complexity light|medium|heavy) and AI-driven classification.
  • Execution loop -- DISPATCH / GATE / APPROVAL / COMPLETE with full state persistence and crash recovery
  • Concurrent execution -- run multiple plans in parallel, each bound by BATON_TASK_ID
  • Plan amendments -- add phases or steps mid-execution
  • Team steps -- dispatch multiple agents to a single step with configurable synthesis strategies and conflict detection/escalation
  • Selective MCP pass-through -- per-step MCP server declarations prevent input token bloat from unused tool schemas
  • Resource governance -- concurrent agent caps and token budget warnings across budget tiers
  • Team intelligence -- composition tracking, cost prediction per team, and baton scores --teams effectiveness reporting
  • Async sessions -- multi-day workflow support with checkpoints, participant tracking, and multi-party contribution protocol

Risk-Tiered Safety

Every task is classified by risk level:

  • LOW -- guardrail presets applied inline, no subagent overhead
  • MEDIUM -- auditor reviews the plan before execution
  • HIGH -- auditor runs as independent subagent with veto authority; regulated domains require subject-matter-expert involvement

15 Reference Procedures

Shared knowledge documents encoding planning strategy, guardrail rules, communication protocols, failure handling, cost models, design patterns, and more. Agents get the knowledge they need without duplicating it across context windows.

ReferenceTopic
baton-engine.mdFull CLI reference and engine protocol
task-sequencing.mdPhase ordering and dependency logic
agent-routing.mdHow the router selects agent flavors
guardrail-presets.mdSafety policies by risk tier
cost-budget.mdToken budget tiers and cost models
comms-protocols.mdInter-agent communication contracts
failure-handling.mdRetry, escalation, and recovery
git-strategy.mdBranch and commit conventions
hooks-enforcement.mdPre-commit and CI hook rules
decision-framework.mdHuman-in-the-loop decision protocol
adaptive-execution.mdRuntime plan adaptation
research-procedures.mdInvestigation and discovery protocols
doc-generation.mdDocumentation generation standards
baton-patterns.mdReusable orchestration patterns
knowledge-architecture.mdKnowledge pack design and delivery

Knowledge Delivery

Curated knowledge packs resolved at plan time and injected into each agent's delegation prompt. A feedback loop learns which agents need what knowledge for which task types.

Three knowledge packs ship with the project:

PackContents
agent-batonArchitecture, conventions, and development workflow (3 docs)
ai-orchestrationMulti-agent patterns, evaluation, prompt engineering, context economics (4 docs)
case-studiesReal-world failure modes, framework comparisons, scaling patterns (3 docs)

Attach knowledge at plan time with --knowledge (individual files) or --knowledge-pack (named packs).

Structured Agent Memory (Beads)

Inspired by Steve Yegge's Beads agent memory system. Agents emit BEAD_DISCOVERY, BEAD_DECISION, BEAD_WARNING, BEAD_OUTCOME, and BEAD_PLANNING signals during execution that are automatically parsed and persisted to SQLite. Beads form a typed dependency graph with status tracking (open -> closed -> archived), tag-based retrieval, time-based decay, and promotion to persistent knowledge documents.

baton beads list --type decision --status open
baton beads ready                               # Unblocked open beads
baton beads graph TASK_ID                       # Dependency graph
baton beads promote bd-a1b2 --pack my-pack      # Promote to knowledge doc
baton beads cleanup --ttl 168 --dry-run         # Memory decay preview

Smart Forge

AI-driven task planning via headless Claude Code subprocess. Generates real LLM-quality plans (not rule-based templates). Includes interactive interview-based refinement, SSE progress streaming through 5 stages (Analyzing, Routing, Sizing, Generating, Validating), and integrates with the PMO UI.

Headless Execution

Run the full loop without a Claude Code session:

baton execute run --plan .claude/team-context/plan.json

Dispatches agents via claude --print, runs gates as subprocesses, loops until complete. Supports --model, --max-steps, and --dry-run flags. The PMO UI can also launch executions from its Kanban board.

Daemon Mode

Background execution with parallel agent dispatch:

baton daemon start --plan plan.json --max-parallel 3
baton daemon status
baton daemon stop

Supports --foreground, --resume, --dry-run, and --serve (co-hosts the HTTP API in the same process). Human decision requests raised during daemon execution are managed via baton decide.

Worktree Isolation (Wave 1.3)

When the planner classifies a task as parallelizable, the engine provisions a linked git worktree per agent so concurrent edits never clobber each other. Worktrees live under .claude/worktrees/<short-id>/ and are reclaimed automatically:

  • Aggressive GC. baton execute complete runs WorktreeManager.gc_stale() on a daemon thread (errors emit BEAD_WARNING and never block completion).
  • Stale threshold. Default is 4 hours (was 72h pre-2026-04-28). Override with BATON_WORKTREE_STALE_HOURS=<hours>. The legacy BATON_WORKTREE_GC_HOURS env var is still honoured.
  • In-flight guard. The GC skips worktrees referenced by any status='running' execution in baton.db and logs skipping in-flight worktree X (active execution Y).
  • Parent-repo detection. When baton is invoked from inside a linked worktree, WorktreeManager resolves the canonical repo root via git worktree list --porcelain so all repo-level operations (worktree add/remove/prune, branch ops, rebase, merge) target the main repository — fixing the dogfood failure where running baton inside an agent worktree silently disabled isolation. (PR #69, bd-c071.)

Run-Level Spend Ceiling (PR #67)

Set BATON_RUN_TOKEN_CEILING=<USD> to cap total cumulative spend per execution. BudgetEnforcer reads the env var fresh on every check (never cached), tracks a run-level counter that survives crash recovery, and raises RunTokenCeilingExceeded before any record_* call would push the total over the limit. The immune-system daemon checks the ceiling before each sweep and suspends with 'ceiling-abort' rather than overspending.

Known gap (bd-3f80). The main Executor.dispatch() path does not yet block individual agent dispatches when the projected spend would breach the cap; it only emits a warning at HIGH/CRITICAL run start. Enforcement is handled by the policy hooks. Full executor wiring is tracked in bd-3f80.

Persistent Agent Souls (EXPERIMENTAL — Wave 6.1 Part B)

Cross-project cryptographic identities for agents stored in ~/.baton/central.db. Each soul has an Ed25519 keypair (private key in ~/.config/baton/souls/<soul_id>.ed25519, mode 0600) and accumulates an expertise vector across runs.

baton souls mint <role> <domain>     # Mint a new operator-issued soul
baton souls list [--role ROLE]       # List active souls
baton souls show <soul_id>           # Show metadata + expertise
baton souls retire <soul_id> [--successor SUCC]
baton souls revoke <soul_id> --confirm

Schema v33 added the soul_revocations table (PR #68). The Python API exposes SoulRegistry.revoke(), is_revoked(), list_revocations(), and rotate() (mints a successor keypair atomically). The revocation-aware verification path is SoulRouter.verify_signature().

Known gap (bd-1ca2). The CLI revoke subcommand only accepts --confirm; the --reason, list-revocations, and rotate subcommands are available via the Python SoulRegistry API but not yet wired into the CLI. Existing callers of the legacy soul.verify are not migrated to the revocation-aware SoulRouter.verify_signature() path either; tracked in bd-1ca2.

Executable Beads (EXPERIMENTAL — Wave 6.1 Part C)

bead_type="executable" beads carry their script body inline in the bead's bd metadata (script_body, verified against script_sha on load). Pipeline: ScriptLinter (denylist of dangerous patterns) -> optional soul signature -> BdBeadStore.write() (via bead_backend.make_bead_store()) with status="quarantine" -> AuditorGate.approve(bead_id) flips status to open -> ExecutableBeadRunner.run() executes the script through Sandbox (wall-clock timeout + memory limit + captured I/O) and writes a child discovery bead linked via validates/contradicts. Gated behind BATON_EXEC_BEADS_ENABLED=1.

Trust boundary. The sandbox is process-level only — no filesystem namespacing, network namespacing, or syscall filter. Trust model assumes locally-authored, version-controlled, team-reviewed scripts. Beads from external origins (federation, downloaded packs, fork PRs) emit a [security] warning to stderr from baton beads exec. Single source of truth: references/baton-patterns.md -> "Pattern: Executable Beads — Trust Boundary".

Bead Persistence — bd backend (ADR-13b)

Beads are stored by the external beads tool (bd) in a per-project .beads/ workspace (Dolt-backed). baton talks to it through BdBeadStore (via bead_backend.make_bead_store()); all baton-specific bead fields round-trip losslessly through bd's metadata (under a baton key) plus queryable labels. bd is a mandatory runtime dependency that the installer (scripts/install.sh / install.ps1) auto-installs. Derived analytics (inferred edges/clusters/handoffs) live in a rebuildable baton-derived.db; central.db keeps a read-only beads projection for cross-project analytics. (The earlier SQLite bead store and git-notes mirror were removed in ADR-13b — see docs/design-decisions.md.)

Cross-Project Intelligence

Execution data syncs to ~/.baton/central.db. Query agent reliability, token costs, and failure rates across projects:

baton sync                   # Sync current project
baton sync --all             # Sync all registered projects
baton sync status            # Show sync watermarks
baton cquery agents          # Agent reliability across projects
baton cquery costs           # Token costs by task type
baton cquery gaps            # Recurring knowledge gaps
baton cquery failures        # Project failure rates
baton cquery mapping         # External item -> plan mapping

Local Project Queries

Query the current project's execution history with predefined views or ad-hoc SQL:

baton query agent-reliability       # Agent success rates
baton query tasks                   # Recent task list
baton query task-detail TASK_ID     # Full breakdown for one task
baton query gate-stats              # Gate pass rates
baton query cost-by-agent           # Token costs by agent
baton query patterns                # Learned patterns
baton query stalled --hours 4       # Stalled executions
baton query --sql "SELECT ..."      # Ad-hoc SQL

Pattern Learning

The engine learns from past executions -- identifies recurring agent combinations, recommends budget adjustments, proposes prompt improvements, and surfaces anomalies. The learning pipeline includes:

  • Pattern detection -- baton patterns surfaces recurring orchestration patterns with confidence scores
  • Budget tuning -- baton budget recommends tier adjustments based on historical cost data
  • Prompt evolution -- baton evolve proposes prompt improvements backed by performance data
  • Anomaly detection -- baton anomalies flags statistical deviations in agent behavior
  • Experiments -- baton experiment manages controlled trials to validate improvement recommendations
  • Full-cycle improvement -- baton learn improve --run executes the complete loop: detect anomalies, generate recommendations, auto-apply safe changes, escalate risky ones, start experiments

Learning Automation

A closed-loop system that detects operational issues and auto-corrects them with confidence thresholds:

  • Detection -- after each execution, the engine scans for routing mismatches, agent degradations, knowledge gaps, gate errors, roster bloat, and pattern drift
  • Issue ledger -- structured SQLite-backed ledger with occurrence tracking, severity classification, and status lifecycle (open -> proposed -> applied -> resolved)
  • Auto-correction -- issues that recur above a confidence threshold (e.g., 3 routing mismatches) are automatically proposed and can be applied to learned-overrides.json, which the router and planner consume at plan time
  • Structured interview -- baton learn interview walks through open issues interactively, collecting human decisions for cases that require judgment (pattern drift, prompt evolution)
  • Rollback -- any applied fix can be reset with baton learn reset, reopening the issue and removing the override

REST API and PMO UI

A FastAPI server exposes the full engine over HTTP with 10 route modules:

RoutePurpose
/api/v1/healthLiveness and readiness probes
/api/v1/plansPlan creation and retrieval
/api/v1/executionsExecution lifecycle (start, record, gate, complete)
/api/v1/agentsAgent registry queries
/api/v1/observeDashboard, traces, usage records
/api/v1/decisionsHuman-in-the-loop decision management
/api/v1/eventsSSE event streaming
/api/v1/webhooksOutbound webhook subscription CRUD
/api/v1/pmoPortfolio management (board, projects, forge, execute, gates, changelist, review, signals)
/api/v1/learnLearning issues and auto-correction

The API supports Bearer token authentication, CORS configuration, user identity middleware (BATON_APPROVAL_MODE), and outbound webhooks with HMAC-SHA256 signing and Slack Block Kit payloads.

A React/Vite PMO frontend provides a complete plan-to-merge lifecycle:

  • Kanban board with 6 columns (queued, executing, awaiting_human, validating, review, deployed) and program health dashboards
  • Smart Forge with SSE progress streaming (5-stage indicator)
  • Advanced plan editor with model selection, dependency multi-select, tag inputs, and gate editing
  • Execution controls -- pause/resume/cancel (SIGSTOP/SIGCONT/SIGTERM), retry-step and skip-step for failed steps, bead alert flags
  • Changelist review -- post-execution file tree grouped by agent with diff stats, merge and PR buttons
  • Role-based approval -- request-review workflow with audit trail (approval_log table)
baton serve --port 8741              # API only
baton pmo serve --port 8741          # API + PMO UI

External Source Adapters

Connect Azure DevOps, Jira, GitHub, or Linear as work-item sources. Items sync to central.db and link to baton plans. The Azure DevOps adapter is fully implemented; Jira, GitHub, and Linear adapters can be added by implementing the ExternalSourceAdapter protocol.

baton source add ado --name "My ADO" --org myorg --project myproj --pat-env ADO_PAT
baton source list
baton source sync --all
baton source map EXTERNAL_ID --project PROJECT_ID --task TASK_ID

How It Works

Human  <-->  Claude Code  <-->  baton CLI  <-->  Python engine
        (natural language)  (structured text)  (state machine)

Claude never imports the Python package. It reads structured text output from baton commands and acts on it. The CLI output format is the only contract between Claude and the engine.

                    +----------------------------------------------------+
                    |                    ORCHESTRATOR                     |
                    |  Reads 19 reference procedures inline               |
                    +------------------------+---------------------------+
                                             |
                          baton plan --------+-------- baton execute
                                             |
              +------------------------------+-------------------------------+
              |                              |                               |
              v                              v                               v
    +------------------+          +--------------------+          +------------------+
    |     AUDITOR      |          |    SPECIALIST      |          |   TALENT         |
    |  (veto power)    |          |    AGENTS          |          |   BUILDER        |
    +------------------+          +--------------------+          +------------------+

    +--------------------------------------------------------------------+
    |                     EXECUTION ENGINE (Python)                       |
    |                                                                    |
    |  Planner --> Executor --> Dispatcher --> Gates --> Persistence      |
    |  Events  --> Telemetry --> Traces --> Retrospectives                |
    |  Pattern Learner --> Budget Tuner --> Prompt Evolution              |
    |  Federated Sync --> Central DB --> Cross-Project Queries            |
    |  PMO Store --> Smart Forge --> REST API --> PMO UI                  |
    |  Bead Store --> Knowledge Resolver --> Learning Automation          |
    +--------------------------------------------------------------------+

Design Principle

Pay for context only when you need isolation. Every subagent costs a full context window, startup latency, and information loss. Agent Baton minimizes this: research and routing run inline, specialists get their own context only for substantial work, shared knowledge lives in reference documents instead of being duplicated.


Usage

Orchestrated Tasks (complex, multi-domain work)

Use the orchestrator to build a health check API with tests and documentation

Engine-Driven Workflow (explicit control)

baton plan "Add input validation to the API" --save --explain
baton execute start
baton execute next              # Get next action
baton execute record --step-id 1.1 --agent backend-engineer --status complete
baton execute gate --phase-id 2 --result pass
baton execute complete

Direct Agent Invocation (simple, single-domain tasks)

Use the data-analyst to investigate our fleet utilization trends
Use the security-reviewer to audit our authentication flow
Use the test-engineer to add unit tests for the payment module

Autonomous Execution (no Claude Code session)

baton execute run               # Full loop: plan -> dispatch -> gate -> complete

CLI Reference

The baton CLI provides 50+ commands organized into ten groups:

CommandDescription
baton planCreate a data-driven execution plan
baton plan --dry-runPreview plan + token/cost forecast without saving
baton execute startStart execution from a saved plan
baton execute next [--all]Get next action(s) to perform
baton execute recordRecord a step completion
baton execute dispatchedMark a step as in-flight
baton execute gateRecord a QA gate result
baton execute approveRecord a human approval decision
baton execute amendAdd phases or steps mid-execution
baton execute team-recordRecord team member completions
baton execute runAutonomous execution loop
baton execute completeFinalize execution
baton execute statusShow current execution state
baton execute resumeResume after crash or interruption
baton execute listList all executions
baton execute switchSwitch active execution
baton statusShow team-context file status
CommandDescription
baton daemon start/stop/status/listBackground execution management
baton async --dispatch/--pending/--showDispatch and track asynchronous tasks
baton decide --list/--show/--resolveManage human decision requests
CommandDescription
baton usageToken usage statistics
baton dashboard [--write]Generate usage dashboard
baton traceExecution traces
baton retroTask retrospectives
baton telemetryAgent telemetry events
baton context-profileContext efficiency profiles
baton context current/briefing/gapsSituational awareness for agents
baton query <subcommand>SQL queries against this project's baton.db
baton cleanupArchive old execution artifacts
baton sync --migrate-storageMigrate JSON flat files to SQLite
CommandDescription
baton classifyClassify task sensitivity
baton complianceShow compliance reports
baton policyList or evaluate guardrail presets
baton escalationsShow or resolve agent escalations
baton validateValidate agent definitions
baton spec-checkValidate agent output against a spec
baton detectDetect project stack
CommandDescription
baton scores [--agent/--trends/--teams]Agent performance scorecards
baton evolvePropose prompt improvements
baton patternsLearned orchestration patterns
baton budgetBudget tier recommendations
baton changelogAgent changelog and backup management
baton anomalies [--watch]Detect system anomalies
baton experiment list/show/conclude/rollbackManage improvement experiments
baton learn improve --run/--force/--reportRun the full improvement loop
baton learn statusDashboard of open learning issues
baton learn issuesList issues with filters (--type, --severity, --status)
baton learn analyzeDetect patterns across issues, propose fixes
baton learn applyApply a specific fix or all auto-applicable fixes
baton learn interviewStructured dialogue for human-directed decisions
baton learn historyResolution history with outcomes
baton learn resetReopen an issue or rollback an applied fix
CommandDescription
baton installInstall agents and references to a project
baton uninstallRemove agent-baton files (project or user scope)
baton packageCreate or install package archives
baton publishPublish to a local registry
baton pullPull from a registry
baton sync --verify ARCHIVEVerify a package archive
baton transferTransfer between projects
CommandDescription
baton agentsList available agents
baton route [ROLES]Route roles to agent flavors
baton eventsQuery the event log
baton incidentManage incident response
CommandDescription
baton beads listList beads with filters (--type, --status, --task, --tag)
baton beads show <id>Show a single bead in detail (JSON)
baton beads readyShow unblocked open beads
baton beads close <id>Close a bead with optional --summary
baton beads link <src> --relates-to|--contradicts|--extends|--blocks|--validates <tgt>Link two beads
baton beads cleanupArchive old closed beads (memory decay)
baton beads promote <id> --pack NAMEPromote a bead to a knowledge document
baton beads graph <task-id>Show the dependency graph for a task's beads
CommandDescription
baton sync [--all]Sync to ~/.baton/central.db
baton sync statusShow sync watermarks
baton cqueryCross-project SQL queries against central.db
baton source add/list/sync/remove/mapExternal source connections
CommandDescription
baton pmo serveStart the PMO HTTP server with UI
baton pmo statusTerminal Kanban board summary
baton pmo addRegister a project with the PMO
baton pmo healthProgram health bar summary
baton serveStart the HTTP API server (API only)

These top-level commands still execute but print a deprecation warning to stderr on every invocation. Update scripts to use the new paths.

Old commandNew canonical pathBead
baton migrate-storagebaton sync --migrate-storagebd-8eef
baton verify-package ARCHIVEbaton sync --verify ARCHIVEbd-7eec
baton improvebaton learn improvebd-5049

PR #70 (end-user-readiness #12) consolidated the three top-level commands into the canonical sync and learn groups. Old aliases keep working for the v0.1 series but emit a deprecation warning to stderr on every invocation.


Project Structure

agents/            <- 30 agent definitions (markdown + YAML frontmatter)
references/        <- 19 reference procedures (shared knowledge)
templates/         <- CLAUDE.md + settings.json + skills for target projects
scripts/           <- Install scripts (Linux + Windows)
docs/              <- Architecture docs, ADRs, invariants, troubleshooting
agent_baton/       <- Python package
  models/          <- Data models (24 modules)
  core/            <- Business logic (11 sub-packages)
    engine/        <- Planner, executor, dispatcher, gates, persistence,
    |                 knowledge resolver, bead store, bead signals
    orchestration/ <- Agent registry, router, context manager,
    |                 knowledge registry
    pmo/           <- PMO store, scanner, Smart Forge
    storage/       <- Central DB, federated sync, external adapters
    govern/        <- Classification, compliance, policy
    observe/       <- Tracing, usage, dashboard, telemetry
    improve/       <- Scoring, evolution, experiments, proposals, rollback
    learn/         <- Pattern learner, budget tuner, learning automation
    distribute/    <- Packaging, sharing, registry (+ experimental)
    events/        <- Event bus, domain events, projections
    runtime/       <- Async worker, supervisor, headless Claude, decisions
  api/             <- FastAPI REST API (10 route modules, webhooks, middleware)
  cli/             <- CLI interface (50+ commands)
tests/             <- Test suite (~6202 tests, pytest)
pmo-ui/            <- React/Vite PMO frontend

Configuration

Environment Variables

VariablePurposeDefault
BATON_TASK_IDTarget a specific execution in multi-task scenariosauto-detected
BATON_DB_PATHOverride the project baton.db location (subagents in worktrees can rely on the upward-walk discovery)discovered
BATON_API_TOKENBearer token for API authenticationnone
BATON_APPROVAL_MODEApproval policy: local (self-approve) or team (different reviewer required).local
BATON_GATE_RETRYEnable single gate-retry: on first gate failure, re-dispatch the failing step once with gate output appended to the prompt. Second failure is terminal.0
BATON_RUN_TOKEN_CEILINGPer-run cumulative spend cap (USD float). When set, BudgetEnforcer.check_run_ceiling() raises RunTokenCeilingExceeded before exceeding the cap; the immune daemon aborts. Counter is restored on baton execute resume. (See PR #67/#73, bd-3f80.)unset
BATON_WORKTREE_STALE_HOURSMax age (hours) for the worktree GC to reclaim a stale linked worktree. New canonical name; BATON_WORKTREE_GC_HOURS is kept as a legacy alias.4
BATON_SOULS_ENABLED / BATON_EXEC_BEADS_ENABLEDFeature flags for persistent agent souls (Wave 6.1B) and executable beads (Wave 6.1C).unset
BATON_BD_BACKENDBead-store backend (ADR-13b). bd (the external beads CLI) is now the only supported value and the system of record; sqlite/auto are removed and log a deprecation warning.bd
BATON_BD_BIN / BATON_BD_PREFIXPath/name of the bd binary and the bd init issue prefix (matches baton's bd-<hash> IDs).bd / bd
BATON_BD_ENABLED / BATON_BD_BIN / BATON_BD_PREFIXBeads backend master switch (1), bd binary path (bd), and bd init issue prefix (bd).—
BATON_SKIP_GIT_NOTES_SETUPSet to 1 to silence the install-time git-notes replication setup and the runtime warning emitted by NotesAdapter.write() when the wildcard refspec is missing.unset
ANTHROPIC_API_KEYRequired for AI classification (pip install agent-baton[classify]) and the Haiku planner classifiernone

Note on experimental features. The Wave 6.2 immune-system daemon and the predictive watcher (Wave 6.2 Part C) are explicitly marked EXPERIMENTAL and gated behind feature flags. They emit stub warnings to stderr on every invocation and must not be relied on for production work. See Known Integration Gaps for the current paper-functionality matrix.

Plan Command Flags

FlagDescription
--saveWrite plan.json and plan.md to .claude/team-context/
--explainShow reasoning behind plan decisions
--jsonOutput plan as JSON instead of markdown
--task-type TYPEOverride task type (new-feature, bug-fix, refactor, etc.)
--agents NAMESOverride auto-selected agents (comma-separated)
--knowledge PATHAttach a knowledge document (repeatable)
--knowledge-pack NAMEAttach a knowledge pack (repeatable)
--intervention LEVELEscalation threshold: low, medium, high
--model MODELDefault model for dispatched agents (haiku, sonnet, opus)
--complexity LEVELOverride complexity: light, medium, heavy

Files Installed to Target Projects

FilePurpose
.claude/agents/*.mdAgent definitions (30 files)
.claude/references/*.mdReference procedures (15 files)
.claude/CLAUDE.mdProject development guide (from template)
.claude/settings.jsonHook configuration

For Developers

git clone https://github.com/DaveGerson/agent-baton.git
cd agent-baton
pip install -e ".[dev]"        # Core + test deps
pip install -e ".[dev,api]"    # Everything including REST API
pytest                         # ~6202 tests

Requires Python 3.10+. The only runtime dependency is PyYAML.

Optional Dependencies

ExtraPackagesPurpose
devpytest, pytest-covTest suite
pmoFastAPI, uvicorn, httpx, sse-starlette, pydanticREST API and PMO server
apisame as pmoBackward-compatible alias
daemonuvicornBackground daemon runner
classifyanthropicAI-powered risk classification
allpmo + classifyEverything except dev tools

Key Documentation

DocumentContents
CLAUDE.mdDevelopment guide and conventions
QUICKSTART.mdGetting started for new users
docs/architecture.mdPackage layout and dependency graph
docs/design-decisions.mdADR log
docs/invariants.mdInterface boundaries (CLI output contract)
docs/troubleshooting.mdCommon issues and solutions
CONTRIBUTING.mdHow to contribute
SECURITY.mdVulnerability reporting

Project Status

Agent Baton is in active development (v0.1.0). The orchestration engine, all 30 agents, 19 references, knowledge delivery, bead memory system, PMO subsystem with end-to-end workflow (plan, edit, execute, review, merge), REST API with webhooks, federated sync, event system, learning automation, and the improvement pipeline are implemented and tested.

  • Python: 3.10+
  • Runtime dependency: PyYAML only
  • Optional: FastAPI + uvicorn (REST API), Anthropic SDK (AI classification)
  • Test suite: ~6202 tests (pytest)
  • External adapters: Azure DevOps implemented; Jira, GitHub, Linear protocols defined

End-User Readiness Sweep — 2026-04-28

The v0.1 series shipped a 12-concern end-user-readiness sweep (PRs #59 + #61–#73) that closed paper-functionality gaps, hardened worktree isolation, added the run-level token ceiling, gated stub features behind BATON_EXPERIMENTAL, and consolidated the CLI surface. Three integration gaps remain:

GapBeadSurface
Executor wiring of BATON_RUN_TOKEN_CEILINGbd-3f80Main Executor.dispatch() only warns at HIGH/CRITICAL risk; enforcement by policy hooks
Soul callers not migratedbd-1ca2Existing soul.verify callers not yet routed through revocation-aware SoulRouter.verify_signature()
Wave 6.1 Part A integrationbd-971dGit-notes bead persistence + executor BeadStore handoff

See Known Integration Gaps for the full matrix.

Experimental Features

The following surfaces are explicitly EXPERIMENTAL and gated behind feature flags. Stub implementations emit warnings to stderr; do not rely on them for production work.

FeatureFlagStatus
Immune-system daemonfeature flag in core/intel/immune.pyWave 6.2 Part B stub (bd-dd52)
Predictive watcherfeature flag in core/intel/predictive.pyWave 6.2 Part C stub (bd-708a)
Executable beadsBATON_EXEC_BEADS_ENABLED=1Process-level sandbox only; not safe for external-origin beads (bd-fe40)
Persistent agent soulsBATON_SOULS_ENABLED=1CLI partial: rotate/list-revocations API-only (bd-b05e)

Tips

  • Say "use the orchestrator" explicitly for your first few runs so Claude Code routes to the right agent.
  • 3-5 specialists per task. More than that and coordination overhead outweighs benefits.
  • Crash recovery is automatic. Session dies mid-task? New session + baton execute resume.
  • Run tasks in parallel. Each baton execute start prints export BATON_TASK_ID=.... Run that in each terminal.
  • Use baton query for local data, baton cquery for cross-project. They target different databases.
  • Beads are automatic. Agents emit bead signals during execution. Use baton beads ready to surface unblocked work items.

License

License pending. Contact the maintainers for terms.

Ver o original no GitHub

Bom para

Relacionados