Harness for long-running AI coding agents -- structured memory, cross-feature learning, and plan-approve-execute workflow.
A CLI-first tool that gives AI coding agents persistent state, workflow guardrails, and a plan-first pipeline. Agents interact via maestro <command> --json through Bash. All durable state lives under .maestro/.
maestro init # initialize project
maestro feature-create my-feature # create feature
maestro memory-write --name findings \
--file research.md # save research
maestro plan-write --file plan.md # write plan (auto-detects active feature)
maestro plan-approve # approve plan
maestro task-sync # generate tasks from plan
maestro task-next --json # find next runnable task
maestro task-claim --task 01-example \
--agent-id worker-1 # claim task for an agent
maestro task-brief --task 01-example --json # get compiled worker context
maestro task-done --task 01-example \
--file summary.md # mark task complete
maestro feature-complete # close the featureAll commands auto-detect the active feature -- no need to pass --feature after feature-create.
The following tools power optional adapters. maestro degrades gracefully when any are absent.
| Tool | Adapter | Purpose |
|---|---|---|
| br (beads_rust) | sync backend | Task tracking and bead persistence |
| bv (beads viewer) | bv-graph |
Dependency graph insights, next-task recommendations, execution plans |
| cass (Coding Agent Session Search) | cass-search |
Full-text search across coding agent sessions (Claude Code, Codex, Cursor, Gemini) |
| agent-mail (MCP Agent Mail) | agent-mail-handoff |
Cross-agent handoff notifications via HTTP API |
bun install
bun run buildProduces:
| Output | Purpose |
|---|---|
dist/maestro |
Standalone binary |
dist/cli.js |
npm CLI entry |
hooks/*.mjs |
5 Claude Code hook scripts |
dist/server.bundle.mjs |
Plugin server (empty, for hook registration) |
Development mode: bun src/surfaces/cli/index.ts <command>.
maestro is a CLI-first harness -- the AI agent is the orchestrator, maestro is the filing cabinet with opinions. Agents call maestro <command> --json via Bash. Hooks inject context automatically.
surfaces/ --> app/ --> domain/ports/ <-- infra/adapters/
(CLI, (rules, (interfaces) (implementations)
hooks) DCP, skills)
src/
domain/ # Pure domain: ports (interfaces), types, errors
ports/ # 11 port interfaces (task, feature, plan, memory, doctrine,
# verification, graph, handoff, search, settings, host)
app/ # Application layer: use cases, DCP, skills, workflow engine
dcp/ # Dynamic Context Pruning (budget-based memory scoring)
doctrine/ # Cross-feature learning compiler
skills/ # Skill loader and registry generator
tasks/ # Task state machine, graph, verification, spec builder
workflow/ # Pipeline stages, playbook, execution insights
... # Plus domain orchestration (features, plans, memory, etc.)
infra/ # Infrastructure: adapters, settings, utilities
adapters/ # Port implementations (fs-based + toolbox-provided)
toolbox/ # Plugin registry and loader (br, bv, cass, agent-mail)
utils/ # Filesystem, git, paths, validation, output
visual/ # HTML/CSS renderer for visualization
surfaces/ # External interfaces
cli/ # 89 CLI commands (citty framework)
mcp/ # Empty server shell (hooks require plugin recognition)
hooks/ # 5 Claude Code hooks
container.ts # Immutable DI container -- wires ports to adapters
services.ts # Service locator (thin shim over container)
skills/ # Bundled SKILL.md workflow guides
hooks/ # Installable Claude Code hooks (build output)
The container (createContainer()) returns an Object.freeze()-d service object. Domain ports have zero dependencies on infrastructure. Optional ports (graph, search, handoff) resolve via toolbox at startup.
discovery --> research --> planning --> approval --> execution --> done
Stages are skippable. Hooks inject pipeline context automatically.
6 states: pending --> claimed --> done | blocked | review --> revision
Stale claims expire after a configurable timeout (default 120 min) and auto-reset to pending on task-next.
All commands accept --json for structured output. All feature-scoped commands auto-detect the active feature. Use maestro <command> --help for full usage.
Content-accepting commands support three input modes: --content "..." (inline), --file path (from file), or --stdin (piped).
| Domain | Commands | Count |
|---|---|---|
| Feature | create, list, info, active, complete | 5 |
| Plan | write, read, approve, revoke, comment, comments-clear | 6 |
| Task | sync, list, next, info, claim, done, block, unblock, accept, reject, brief, spec-read, spec-write, report-read, report-write | 15 |
| Memory | write, read, list, delete, compile, consolidate, archive, stats, promote, compress, connect, insights | 12 |
| Doctrine | list, read, write, deprecate, suggest, approve | 6 |
| Graph | insights, next, plan, discovery, reserve | 5 |
| Handoff | send, receive, ack, read, list, status | 6 |
| Search | sessions, related, similar | 3 |
| Skill | load, list, install, create, remove, sync | 6 |
| Stage | jump, skip, back | 3 |
| Config | get, set, agent | 3 |
| Toolbox | add, create, install, list, remove, test | 6 |
| Visual | visual, debug-visual | 2 |
| Other | init, install, ping, status, agents-md, dcp-preview, doctor, history, execution-insights, self-update, update | 11 |
Installable Claude Code hooks that integrate maestro into the agent lifecycle:
| Hook | File | Trigger | Purpose |
|---|---|---|---|
| SessionStart | sessionstart.mjs | Session begins | Inject pipeline state and recommended skills |
| PreToolUse:Bash | pretooluse.mjs | Before Bash tool | Remind agent to finish maestro tasks on git commit |
| PreToolUse:Agent | pre-agent.mjs | Before agent spawn | Inject task spec + DCP-scored memories + doctrine |
| PostToolUse | posttooluse.mjs | After tool execution | Track tool usage and state changes |
| PreCompact | precompact.mjs | Before context compaction | Preserve critical maestro state |
Install with maestro install.
21 bundled workflow skills, all using maestro: colon-prefixed naming:
maestro:design-- deep discovery and specification (16-step process with reference files)maestro:implement-- task execution with TDD, parallel, and team modesmaestro:review-- track-aware code review with automated checksmaestro:brainstorming-- creative exploration before implementationmaestro:parallel-exploration-- parallel read-only explorationmaestro:dispatching-- parallel agent dispatchmaestro:debugging-- systematic debugging methodologymaestro:tdd-- test-driven development guidancemaestro:verification-- verification before completionmaestro:agents-md-- AGENTS.md quality discipline and generationmaestro:docker-- Docker container workflowsmaestro:prompt-leverage-- prompt engineering for AI agentsmaestro:new-feature-- create feature/bug tracks with spec and planmaestro:note-- capture decisions and context to persistent notepadmaestro:plan-review-loop-- iterative adversarial plan reviewmaestro:revert-- git-aware undo of track implementationmaestro:next-move-- strategic analysis for highest-leverage next stepmaestro:simplify-- review changed code for reuse, quality, and efficiencymaestro:visual-- generate visual explanations of systems and data
Load with maestro skill <name>, list with maestro skill-list.
Skills with reference/ subdirectories support progressive disclosure:
maestro skill maestro:design --ref steps/step-01-init.md
Old skill names (e.g., writing-plans) are aliased with deprecation warnings.
.maestro/
config.json # Project configuration
doctrine/ # Doctrine items (cross-feature operating rules)
<name>.json # Structured rule with effectiveness metrics
memory/ # Global project-scoped memory files
features/
<feature>/
feature.json # Feature metadata and state
plan.md # Implementation plan
comments.json # Plan review comments
memory/ # Feature-scoped memory files
tasks/
<task>/
task.json # Task state, claims, summaries
spec.md # Compiled task specification
report.md # Task completion report
doctrine-trace.json # Doctrine injection trace
MIT