ace-swarm
v2.3.1
Published
ACE Framework MCP server and CLI bootstrap for prompts, skills, handoffs, and stateful swarm orchestration.
Maintainers
vedatonuryilmazReadme
ACE Swarm MCP Server
ACE Swarm is an MCP server and terminal-first CLI for durable multi-agent orchestration and agent runtime infrastructure.
It exposes 90+ MCP tools that turn agent workflow coordination into a local control plane with explicit state, typed handoffs, resource locks, semantic diffs, runtime profiles, and operator tooling. No signup. No API key required for the Ollama path. One command to bootstrap.
System Map
ACE Swarm
|
+-- bootstrap
| +-- `ace init` / `ace turnkey`
| +-- workspace scaffolding
| `-- MCP client config bundle
|
+-- control plane
| +-- agents
| | +-- swarm: orchestrator, vos, ui, coders
| | `-- composable: skeptic, ops, research, spec, builder, qa, docs, ...
| +-- contracts
| | +-- prompts
| | +-- schemas
| | `-- handoff templates
| +-- runtime state
| | +-- run ledger
| | +-- todo state
| | +-- handoff registry
| | +-- status events
| | +-- job queue
| | +-- lock table
| | `-- scheduler lease
| `-- dispatch
| +-- immediate scheduling
| +-- priority bands
| +-- persistent resource locks
| `-- recovery semantics
|
+-- change intelligence
| +-- workspace delta scan
| +-- semantic snapshots
| +-- semantic diff / drift report
| +-- rewrite targets
| `-- safe edit rollback
|
`-- operator surface
+-- MCP server on stdio
`-- TUI: chat, tabs, telemetry, provider-aware runtimeQuick Start
+----+-----------------------------------------------+-----------------------------------------------+
| # | Command | Result |
+----+-----------------------------------------------+-----------------------------------------------+
| 1 | npx -y ace-swarm turnkey --project "My Proj" | Seeds workspace state, agents, skills, tasks |
| 2 | ace mcp | Starts the MCP server over stdio |
| 3 | initiate ACE | Kicks off the ACE workflow in your MCP host |
+----+-----------------------------------------------+-----------------------------------------------+30 seconds later the workspace has 17 agent roles, 15 packaged skills, a durable state layer, and MCP client configs for Codex, VS Code, Claude Desktop, Cursor, Gemini, and Antigravity.
Recent Releases
+------------+------------+------------------------------------------------------------------+
| Version | Date | Highlights |
+------------+------------+------------------------------------------------------------------+
| 2.3.0 | 2026-03-28 | Orchestrator supervisor, context-aware model bridge, ACE |
| | | compliance enforcement, Vericify integration, tool governance |
| 2.2.0 | 2026-03-26 | turnkey bootstrap, TUI, expanded skills/roles, client configs |
| 2.1.0 | 2026-03-13 | README redesign, ASCII docs, packaged changelog |
+------------+------------+------------------------------------------------------------------+See CHANGELOG.md for detailed release notes.
What's New in 2.3.0
Orchestrator Supervisor (run_orchestrator MCP tool):
- Full task-plan execution loop with explicit step routing and sequential/parallel dispatch
- Handoff create/ack flows with fallback ID generation
- Vericify context carry-forward and delta recovery for state continuity
- Circuit breaker open/close for upstream failure handling
- Plan amendment support during execution
Model Bridge Context Management:
- Context budget calculation with configurable reserve (default 25%)
- Tier fallback (full → compressed → brief) when context overflows
- Automatic conversation history compaction (summarize older messages, retain recent + system)
- Large tool-result write-through to disk with configurable truncation
- Retry-once on transient provider errors (abort, timeout, rate-limit)
ACE Compliance Enforcement (5 Stacked Layers):
- Layer 1: MCP server initialization instructions (all hosts)
- Layer 2: Per-host instruction files (CLAUDE.md, .cursorrules, .github/copilot-instructions.md)
- Layer 3: Lifecycle hooks with role-aware tool hints (7 hosts)
- Layer 4: Tool-level soft enforcement (guidance on all tool results)
- Layer 5: Bootstrap-on-first-tool lazy enforcement
Tool Governance & Vericify:
- Named sets for explicit tool classification (BOOTSTRAP_TOOLS, REFRESH_TOOLS, NAMED_MUTATION_TOOLS)
- Vericify resolution scoping to prevent parent-directory leakage
- Full Vericify API integration with graceful degradation fallback
Test Coverage: 208 passing tests (up from 202)
Core Surfaces
+------------------+----------------------------------------------+------------------------------------------------------+
| Surface | Internals | Public entrypoints |
+------------------+----------------------------------------------+------------------------------------------------------+
| Bootstrap | workspace state, tasks, configs | `ace init`, `ace turnkey`, `ace mcp-config` |
| Agent runtime | swarm roles, model bridge, tool planning | MCP server, TUI `/agent`, packaged agent assets |
| Durable state | ledgers, TODOs, handoffs, status events | runtime stores under `agent-state/*` |
| Dispatch | job queue, lock table, lease, recovery | `enqueue_job`, `dispatch_jobs`, `complete_job` |
| Supervision | plan amendment, handoff, Vericify, breakers | `superviseTaskPlan`, `amendTaskPlan` |
| Change analysis | delta scan, semantic diff, rewrite hints | `scan_workspace_delta`, `semantic_diff`, etc. |
| Operator UI | tabs, ACE chat bridge, telemetry, providers | `ace tui` |
+------------------+----------------------------------------------+------------------------------------------------------+Workspace Internals
+----------------------------------+--------------------------------------------------+
| Path | What lives there |
+----------------------------------+--------------------------------------------------+
| `agent-state/run-ledger.json` | major updates, regressions, runtime history |
| `agent-state/todo-state.json` | TODO nodes, dependencies, transition truth |
| `agent-state/handoff-registry.json` | handoff lifecycle state |
| `agent-state/STATUS_EVENTS.ndjson` | append-only lifecycle/status event log |
| `agent-state/job-queue.json` | queued work with dependency and priority metadata |
| `agent-state/job-locks.json` | active resource lock table |
| `agent-state/scheduler-lease.json` | active dispatcher owner and lease state |
| `agent-state/index.json` | workspace delta index |
| `.tmp/cache/semantic/*` | semantic snapshots and diff cache |
| `.ace/llm-profile.json` | local runtime profile when configured |
+----------------------------------+--------------------------------------------------+Change And Safety Internals
+-------------------------+----------------------------------------------+
| Capability | Current surface |
+-------------------------+----------------------------------------------+
| Coarse workspace diff | `scan_workspace_delta` |
| Semantic snapshot | `snapshot_state` |
| Semantic diff | `semantic_diff` |
| Drift gate | `drift_report` |
| Rewrite targeting | `rewrite_targets` |
| Exact diff summary | `diff_files`, `git_diff` |
| Safe write + rollback | `safe_edit_file` |
+-------------------------+----------------------------------------------+CLI
+---------------------------------------------+----------------------------------------------+
| Command | Purpose |
+---------------------------------------------+----------------------------------------------+
| `ace mcp` / `ace serve` | start MCP server over stdio |
| `ace tui [options]` | launch terminal operator console |
| `ace init [options]` | bootstrap ACE files into current workspace |
| `ace turnkey [options]` | bootstrap + client config bundle |
| `ace doctor [options]` | validate local LLM + MCP readiness |
| `ace mcp-config [--client <name>|--all]` | print one or all MCP client snippets |
| `ace paths` | show resolved package and workspace paths |
+---------------------------------------------+----------------------------------------------+Key Options
+-------------------------------+---------------------------------------------+
| Command group | Options |
+-------------------------------+---------------------------------------------+
| `init` / `turnkey` | `--project`, `--force`, `--no-mcp-config` |
| | `--no-client-config-bundle` |
| | `--llm`, `--model`, `--ollama-url` |
| `tui` | `--provider`, `--model`, `--ollama-url` |
| `doctor` | `--llm`, `--model`, `--ollama-url` |
+-------------------------------+---------------------------------------------+TUI
+----------------------+----------------------------------------------+
| Command | Description |
+----------------------+----------------------------------------------+
| `/provider [name]` | show or switch active provider |
| `/providers` | list discovered providers |
| `/models` | list available models |
| `/model <name>` | switch active model |
| `/pull <name>` | download an Ollama model |
| `/ollama` | show Ollama connection status |
| `/agent <role>` | launch a subagent tab |
| `/agents` | list agent roles and status |
| `/status` | show orchestrator status |
| `/chat` | open a chat tab |
| `/logs` | open logs tab |
| `/help` | list commands |
| `/quit` | exit the TUI |
+----------------------+----------------------------------------------++----------------------+----------------------------------------------+
| Shortcut | Action |
+----------------------+----------------------------------------------+
| `Alt+1-9` | switch tabs |
| `Tab` / `Shift+Tab` | cycle tabs |
| `Ctrl+N` | new chat |
| `Ctrl+R` | refresh |
| `Ctrl+D` | quit |
+----------------------+----------------------------------------------+Provider notes:
- Ollama works directly through
ace tui— a zero-cost local AI agent runtime with no API keys required. - ACE workspaces automatically route chat tabs through the ACE model bridge, handling the full AI agent lifecycle from tool selection through execution, with streamed tool/result updates in the transcript.
- OpenAI-compatible providers use
OPENAI_API_KEYand optionalOPENAI_BASE_URL, or provider-scoped equivalents such asCODEX_API_KEYandCODEX_BASE_URL. /agentsessions can now accept follow-up input while blocked or idle, so operators can continue a run without relaunching the worker tab.- VS Code Copilot model hints may appear in discovery, but the standalone TUI does not directly execute through the VS Code chat runtime without an extension-side bridge.
Supervisor And Bridge Notes
ModelBridgeperforms a tool-planning turn before execution — selecting from the 90+ registered tools — and can amend the model-selected scope mid-run when another valid ACE tool is required.- Supervisor helpers support sequential task-plan execution with amendments, typed agent handoff protocol flows with schema validation, Vericify context carry-forward for state continuity, and circuit-breaker open/close hooks for upstream failure handling.
- Hook dispatch emits richer role-aware ACE context across workspace lifecycle events, including Codex, Claude Code, VS Code Copilot, Cursor, Gemini, and Antigravity hook bundles.
Bootstrap Outputs
+-----------------------------------+------------------------------------------------------+
| Path | Output |
+-----------------------------------+------------------------------------------------------+
| `agent-state/*` | state, ledgers, schemas, reports |
| `.agents/ACE/*` | packaged agent instructions |
| `.agents/skills/*` | packaged skills |
| `tasks/*` | task packs, examples, handoff templates |
| `scripts/ace/*` | helper scripts |
| `.vscode/mcp.json` | VS Code MCP config |
| `.vscode/ace-hooks.json` | VS Code hook bundle |
| `.cursor/hooks.json` | Cursor hook bundle |
| `.mcp-config/codex.hooks.toml` | Codex hook config |
| `.mcp-config/gemini.hooks.json` | Gemini hook bundle |
| `.mcp-config/antigravity.hooks.json` | Antigravity hook bundle |
| `.mcp-config/*` | client configs for Codex / VS Code / Claude / Cursor / Gemini / Antigravity |
| `.github/hooks/*.json` | optional workspace hook policies |
+-----------------------------------+------------------------------------------------------+Local-model bootstrap (no API key, no cloud dependency):
npx -y ace-swarm turnkey --project "My Project" --llm ollama --model llama3.1:8b
ollama serve
ollama pull llama3.1:8b
ace doctor --llm ollama --model llama3.1:8bClient Config Targets
+---------------+---------------------------------------------------------------------+
| Client | Target |
+---------------+---------------------------------------------------------------------+
| Codex | `$CODEX_HOME/config.toml` or `~/.codex/config.toml` |
| VS Code | `.vscode/mcp.json` and `.vscode/ace-hooks.json` |
| Claude | macOS: `~/Library/Application Support/Claude/...` |
| | Linux: `~/.config/Claude/claude_desktop_config.json` |
| Cursor | `~/.cursor/mcp.json` or workspace `.cursor/hooks.json` |
| Gemini | import `.mcp-config/gemini.hooks.json` with the generated MCP config |
| Antigravity | import `.mcp-config/antigravity.mcp.json` and `.mcp-config/antigravity.hooks.json` |
+---------------+---------------------------------------------------------------------+Included Assets
+----------------------+-----------------------------------------------------------+
| Asset class | Included |
+----------------------+-----------------------------------------------------------+
| Swarm agents | 4: orchestrator, vos, ui, coders |
| Composable agents | 13: astgrep, skeptic, ops, research, spec, builder, ... |
| Skills | 15 packaged skills including orchestrator, codemunch, |
| | codesnipe, state-auditor, schema-forge, release-sentry |
| Tasks / templates | `todo.md`, `lessons.md`, `role_tasks.md`, |
| | `cli_work_split.md`, `SWARM_HANDOFF.template.json` |
+----------------------+-----------------------------------------------------------+Open Ideas
+---------------------------------------------------------------+
| Not shipped guarantees |
+---------------------------------------------------------------+
| high-certainty shadow workspace promotion mode |
| explicit promotion manifests for exact patch + AST evidence |
| richer operator views for rejected promotions and drift spikes|
+---------------------------------------------------------------+Development
cd ace-mcp-server
npm install
npm run build
npm test
npm run startReferences
Collaborations, ideas, or concerns: [email protected]