maestro

maestro

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/.

Quick Start

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 feature

All commands auto-detect the active feature -- no need to pass --feature after feature-create.

Prerequisites

• bun (runtime and package manager)
• git (repo state and audit capture)

Optional integrations

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

Building

bun install
bun run build

Produces:

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>.

Architecture

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.

Pipeline

discovery --> research --> planning --> approval --> execution --> done