Skip to content

README.md

Latest commit

 

History

History
55 lines (45 loc) · 4.61 KB

README.md

File metadata and controls

55 lines (45 loc) · 4.61 KB

Maestro Documentation Index

Use this index to jump to the right guide quickly and see how the pieces connect.

Start Here

  • Quickstart — installation, environment prep, builds, and the fast path to running the CLI/TUI/Web.
  • Contributor Runbook — day-one flow for contributors (build, lint, verify).
  • Feature Guide — user-facing capabilities across the TUI and CLI with power-user tips.
  • Web UI Guide — browser workflow and TUI/Web parity appendix.
  • Conductor Bridge — connect the Conductor extension to a local Maestro server.
  • Ambient Agent Design — always-on GitHub agent daemon architecture.
  • Any-Agent EvalOps Control Plane - options and shim strategy for bringing any coding agent into EvalOps registration, governance, traces, evidence, and memory.

Core Reference

  • Tools Reference — authoritative slash command and flag definitions.
  • Safety — approvals, sandboxing, and firewall behavior.
  • Agent Safety Boundary — how MCP workspace trust, guarded files, approvals, audit, and sandbox policy compose.
  • Threat Model — security architecture, trust boundaries, and attack mitigations.
  • Models — provider/model registry sources, overrides, defaults, and OpenAI-compat quirks.
  • Sessions — session formats, storage locations, and management commands.
  • Prompt Queue — queue lifecycle, prioritization, and diagnostics hooks.
  • MCP Guide — Model Context Protocol setup and usage.
  • Headless Protocol Reference — versioned JSON-over-stdio contract for Chat, TUIs, and other embedders.
  • Codex Parity Conformance — compact anchors for Codex-inspired auth, patching, MCP, queue, and hosted-runtime surfaces.
  • Hosted Runner Contract — provider-neutral runtime contract for account-scoped remote Maestro sessions.
  • Platform AgentRuntime Session Bridge — how hosted session starts are projected to Platform AgentRuntime/A2A with trace and support correlation.
  • AgentRuntime Task Mapping — how local todo, background-task, checkpoint, and swarm concepts project into Platform AgentRuntime phases.
  • Pending Request Contract — unified session projection for approvals, user input, MCP elicitations, tool retries, and Platform waits.

Architecture & Patterns

Feature Design Docs

  • Design Index — comprehensive design documentation for all major subsystems.
    • Headless Control Plane — session/control-plane design for headless remote attach, server requests, and subscriber backpressure.
    • Any-Agent EvalOps Control Plane - agent-neutral control-plane, registry, shim, trace, evidence, and memory integration strategy.
    • Platform AgentRuntime Session Bridge — hosted-session trigger projection, A2A fallback, trace context, and boundary normalization.
    • AgentRuntime Task Mapping — next-phase todo/background/swarm projection into Platform AgentRuntime.
    • Core Systems: Tool System, Agent State Machine, Context Management, Session Persistence
    • User Interface: TUI Rendering, Web UI Architecture
    • Safety & Security: Safety Firewall, Enterprise RBAC, OAuth Authentication
    • Supporting Systems: Hooks, MCP Integration, LSP Integration, Telemetry, Database

Deployment & Operations

  • Enterprise — deployment, configuration, and hardening guidance for controlled environments.

  • CI Version Pins — where Node/Bun/action SHAs are pinned and how to update them safely.

  • Changelog — release history and notable changes.

When in doubt, start with the Quickstart, skim the Feature Guide, keep the Tools Reference nearby, and use the Contributor Runbook before opening a PR.