Current stable release: v1.0.29.

The VERSION file uses standard stable SemVer. The auto-version workflow resumes from this value and applies normal patch/minor/major bumps after merged PRs.

This release ships the Pi adapter, the A2A adapter, and the echo dry-run adapter. Claude Code and Codex adapters are planned work and should not be documented as shipped until they have end-to-end smoke coverage.

• Multi-Model Orchestration -- Route tasks through Pi, A2A-compatible services, or dry-run echo adapters with per-agent model tier control
• 10 Chain Types -- From quick reviews to full-SDLC pipelines with plan → build → parallel validate → swarm review
• Cross-Model Verification -- Parallel teams run on different model families, catching blind spots no single model finds
• Real-Time Dashboard -- Go API + React dashboard with SSE live agent activity, run history, and pipeline visualization
• Red Team / Blue Team -- Adversarial + correctness review running in parallel, synthesized by an orchestrator
• Pi SDK Integration -- First-class adapter for the Pi coding agent, with A2A support for protocol-compatible agents
• Sandbox Pooling -- Agents execute in isolated sandboxes with pooled resource management
• Pipeline State & Resume -- Chains checkpoint state so interrupted runs can resume from the last completed step
• Cost Tracking -- Per-run token usage and cost breakdown across all model tiers
• Damage Control Rules -- Configurable guardrails prevent agents from running destructive commands

🚧 Coming soon -- GIF / video walkthrough of a full plan-build-review run with the live dashboard.

                            User / CLI
                                │
                           Orchestrator
                          (quality model)
                         ╱      │       ╲
                   Planning  Engineering  Validation
                     Lead       Lead        Lead
                      │          │           │
                    Scout     Builder    Reviewer
                                        Security
                                        Adversarial
                                        Correctness
                                        Quality

    ┌─────────────────────────────────────────────────────────┐
    │  Parallel teams (Engineering B, Validation B) use       │
    │  different model families for cross-model verification. │
    │                                                         │
    │  Swarm mode splits into Red Team + Blue Team for        │
    │  adversarial vs. correctness review in parallel.        │
    └─────────────────────────────────────────────────────────┘

    Dashboard (Go API + React SPA) ─▶ SSE event stream

The engine CLI and dashboard can run on different hosts. The CLI streams events to a central dashboard over HTTP:

  Host A (CLI)  ──── events ────▶  Dashboard Server (Go + PG)
  Host B (CLI)  ──── events ────▶  Dashboard Server (Go + PG)
                                              │
                                     Reverse Proxy (optional)
                                              │
                                     your-dashboard.example.com

CLI-only hosts only need bun. Go is only needed on the dashboard server. Node.js is only needed when rebuilding the React dashboard assets.

# Clone
git clone https://github.com/King-Capital/multi-agent-engine.git
cd multi-agent-engine

# Install dependencies
cd engine && bun install && cd ..

# (Optional) Build standalone CLI binary
just build

# Point at the dashboard server (set in ~/.mae/config or shell profile)
export MAE_DASHBOARD_URL="http://your-dashboard-host:8400"

# Optional: expose a small run-specific scratch folder to worker worktrees.
# Use a narrow path; MAE does not copy the entire .goal-runs tree by default.
export MAE_WORKTREE_CONTEXT_PATHS=".goal-runs/current-run"

# Run your first task -- plan, build, and review
just task "add input validation to the signup handler"

# Dry run (echo adapter, no real API calls)
just dry "refactor the auth module"

# Start the dashboard (dashboard server only)
just dashboard-build && just dashboard

# Add to ~/.zshrc, ~/.bashrc, or ~/.mae/config for persistence
export MAE_DASHBOARD_URL="http://your-dashboard-host:8400"

# Or pass per-invocation
bun engine/cli.ts task "your task" --dashboard "$MAE_DASHBOARD_URL"

Any host with bun can run agent teams and stream results to the central dashboard.

Project-specific skills can be added under .mae/skills/ or .mae/project-skills/ as Markdown/YAML files. Optional frontmatter supports name and scope; scope: all applies to every agent, while a role or persona-name scope only injects into matching prompts.

For dogfood/audit runs, MAE_WORKTREE_CONTEXT_PATHS accepts comma- or colon-separated relative paths. Each path is copied into worker git worktrees with symlinks skipped and size/file-count caps applied.

10 composable chain types, from surgical reviews to full SDLC pipelines:

The real-time dashboard is a Go API server with an embedded React SPA from dashboard-next/src/ and SSE for live updates. Session streams emit stable SSE id: values for persisted events and honor Last-Event-ID plus ?last_event_id= replay, so browser reconnects catch up missed events. Legacy templ files remain in dashboard/templates/ but are not the active UI.

Access: Set MAE_DASHBOARD_URL in ~/.mae/config and open in your browser.

The dashboard protects all /api/*, /htmx/*, and /metrics endpoints by default. Public paths are limited to the SPA shell/assets, /api/health, and /api/auth/login.

• Browser users sign in through the React login page. Successful login creates a Secure, HttpOnly mae_session cookie backed by the auth_sessions table. Run the dashboard behind HTTPS in deployed environments; plain-HTTP localhost browser login is not supported by the secure cookie.
• API clients use Authorization: Bearer <token>. New admin-managed tokens live in api_tokens; legacy users.api_token values still load for compatibility.
• Admin users can open /admin to create/revoke API tokens. Newly generated token secrets are shown once; store bootstrap credentials and generated operational tokens in Vaultwarden (for the public deployment, item: MAE Dashboard bootstrap credentials - ai-agents.rodaddy.live).
• The Sessions sidebar loads the newest 100 sessions by default, with an explicit Load more control for older runs and a text Filter next to Sort. The main overview stats/charts remain all-session aggregates, so the sidebar count shows loaded/filtered rows while the center cards show global totals.
• Session detail includes Stream, Agents, Board, Progress, Files, Cost, and Replay tabs. The Board tab derives Kanban-style cards from agent/till-done/error events; the Agents tab hydrates colors/models/status from event history plus live SSE so reloads preserve swarm state.
• Steering messages can target the orchestrator or a selected agent. Targeted messages are stored in the message event to field and routed by exact agent id when the engine SSE listener receives them.
• First-run bootstrap: set MAE_BOOTSTRAP_USERNAME=<existing admin username> and MAE_BOOTSTRAP_PASSWORD=<temporary strong password> before starting the dashboard. Startup sets that user's password only when password_hash is empty, so later restarts will not overwrite a rotated password. Remove the env vars after login and rotate/store the final password in Vaultwarden.
• Legacy users.api_token bearer tokens still work for migration compatibility, but they are not visible in /admin, do not track last_used_at, and cannot be revoked there. Prefer creating replacement api_tokens from /admin, updating clients, then removing legacy tokens from users.api_token.
• If the database is unavailable, auth-required endpoints fail closed instead of falling back to anonymous API access.

Thinking levels: off < minimal < low < medium < high < xhigh

Cross-model pairs are configured in configs/model-routing.yaml to ensure builder and verifier always use different model families.

See deploy/README.md for full setup instructions:

• Dashboard server provisioning
• Remote CLI setup for multi-host streaming
• Caddy reverse proxy configuration
• User seeding and PostgreSQL setup

Contributions are welcome! Here's how to get started:

1. Fork the repo and create a feature branch from main
2. Install dependencies: cd engine && bun install
3. Make your changes -- follow existing code style and patterns
4. Test your changes: just test
5. Type-check: just check
6. Submit a pull request with a clear description of what changed and why

• All work happens on feature/fix branches -- never commit directly to main
• Keep PRs focused: one feature or fix per PR
• Add tests for new chain types or agents
• Update this README if you add new commands, agents, or chains
• Run just check && just test before submitting

This project is licensed under the MIT License.

MIT License

Copyright (c) 2026 King Capital

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.