ACE Swarm MCP Server and CLI

Autonomous Coding Entity (ACE) is a local MCP server and CLI for agent-assisted coding.

ace-swarm provides Claude Code, Codex, Cursor, GitHub Copilot CLI, VS Code, and provider-backed workflows with a shared runtime: durable workspace state, typed handoffs, scheduler support, change intelligence, and operator tooling. All state lives in a single binary file — agent-state/ace-state.ace — with .agents/ACE/ace-state.ace kept only as a legacy fallback for older workspaces.

Modern coding agents can already read files, write code, run commands, and call tools. The missing layer is coordination that survives restarts, model switches, and multi-agent work. ACE keeps the workflow in the store and projects only the files external clients still need. For provider-backed runs, ACE supplies task context, tool surfaces, status events, evidence trails, and resumable state.

The full MCP surface spans 119 registered tools across 13 domain modules — handoffs, scheduler, goals, file ops, drift detection, git, memory, discovery, skills, lifecycle events, vericify, tracker, and framework orchestration — plus resources and prompts. For premium hosts (Claude Code, Codex) a curated ace mcp --profile host-min exposes 22 high-value tools; the rest remain reachable via run_orchestrator delegation or --profile full. See the MCP Tool Reference for the full catalog.

ACE Manifesto

• Agent work should survive restarts, handoffs, and review.
• Handoffs should be typed, evidence-linked, and validated.
• Shared workflow state should live in the workspace, not only in chat history.
• ACE-Orchestrator is the default entrypoint, and every provider can delegate through the full agent set.
• Provider-backed runs should get the same structure and observability.
• Bootstrap should be contained and reversible: ACE writes into agent-state/ace-state.ace, with legacy fallback reads from .agents/ACE/ace-state.ace where needed.

Serving model providers

ACE provides model providers with the context they cannot infer on their own: task state, tool surfaces, status events, evidence trails, and the next move in the loop.

• ace init --llm <provider> records the selected runtime profile in the store.
• ace connect records an explicit runtime profile from a user-chosen local runtime endpoint or hosted provider.
• ace doctor validates local or hosted runtime wiring and checks the selected model when the provider exposes listings.
• ace doctor --scan probes common Ollama and llama.cpp endpoints and writes the selected profile back into the store.
• ace tui is provider-aware for ollama, llama.cpp, codex, claude, gemini, and copilot when credentials or base URLs are configured.
• ace mcp and ace tui expose the same workspace truth to the host, the terminal, and the model.
• ace mcp-shadow --tools <csv> starts a filtered stdio server that exposes only the listed tools — used by the Hermes bridge so a local model sees a scoped, safe subset of the surface.

Why This Exists Now

Frontier models are getting more capable and more restricted at the same time. Providers are tightening scope, access windows, and usage limits, which makes the hosted path less dependable for long-running agent work. Local models are slower, but they are available, and with ACE they can still do real work because ACE gives them the missing eyes and ears: shared context, tool surfaces, status events, evidence trails, and resumable state.

• Claude Code proved the terminal-native agent loop.
• OpenAI connectors and MCP widened the tool surface.
• Ollama and llama.cpp keep local runtimes in play.
• MCP remains the common protocol surface across clients and runtimes.

ACE sits underneath that stack. It does not compete with the host you already use — it provides that host with a durable local runtime, plus scheduler primitives for queued work, dependency gates, leases, and resource locks so multi-agent runs stay coordinated.

ACEPACK State Model

Most agent frameworks scatter runtime state across dozens of generated files — status logs, handoff records, todo lists, indexes — that drift apart and get re-parsed on every read. ACEPACK closes that gap: it is a custom binary format that presents all workspace state as one structured, single-file store at agent-state/ace-state.ace.

• A random-access KV region holds agent instructions, skills, topology, task indexes, and scheduler queues as append-only chunks.
• A columnar event section stores the typed handoff and status log so time/kind scans read a few bytes per event instead of parsing full JSON.
• Store-backed projections mean external tools read the same truth through a single authority instead of divergent files.

The result is one coherent source of truth that survives restarts, compacts to reclaim space, and keeps a full replayable event history. For the on-disk byte layout, KV mechanics, and columnar details, see the ACEPACK State Model reference.

Reading hidden state

Generated state is store-only by default — the workspace stays clean and agents read through MCP tools. Humans stay in the loop through the CLI:

ace ls agent-state              # list hidden artifacts by logical path
ace read agent-state/kanban.json
ace read agent-state/STORE_AUTHORITY_AUDIT.md --out /tmp/audit.md

ace read is exact-length by construction: it returns the complete stored block or fails loudly — never a truncated or delimiter-clipped view.

Quick Start

Bootstrap a workspace:

npx -y @voybio/ace-swarm turnkey --project "My Project"
ace mcp

The bare ace commands throughout the docs assume a global install (npm install -g @voybio/ace-swarm); without one, prefix each with npx -y @voybio/ace-swarm.

Then, in your MCP host:

initiate ACE

Local-model path with Ollama:

npx -y @voybio/ace-swarm turnkey --project "My Project" --llm ollama --model qwen3:8b --base-url http://localhost:11434
ollama serve
ollama pull qwen3:8b
ace doctor --llm ollama --model qwen3:8b --base-url http://localhost:11434
ace mcp

Local-model path with llama.cpp:

npx -y @voybio/ace-swarm turnkey --project "My Project" --llm llama.cpp --model local-model --base-url http://localhost:8080
llama-server -m /path/to/model.gguf --port 8080
ace doctor --llm llama.cpp --model local-model --base-url http://localhost:8080
ace mcp

Hosted provider path with Codex:

npx -y @voybio/ace-swarm turnkey --project "My Project" --llm codex --model gpt-5
export OPENAI_API_KEY=...
ace doctor --llm codex --model gpt-5
ace mcp

If you already have a local runtime running, ace doctor --scan will probe common Ollama and llama.cpp endpoints and write the selected profile back into the store. For the optional Hermes engine path, see Local Models & Hermes and the Hermes reference. The full command list lives in the CLI Reference.

What Bootstrap Writes

ACE bootstrap is intentionally contained. The store is authoritative at agent-state/ace-state.ace; only a few host-facing files land in the workspace when requested.

• agent-state/ace-state.ace — runtime state, agent instructions, skills, topology, schemas, and the event log
• .agents/ACE/ace-state.ace — legacy fallback for existing workspaces
• .agents/ACE/ace-hook-context.json — compact hook snapshot for external clients
• .agents/ACE/tasks/todo.md — human-facing todo surface
• Optional workspace-root stubs — AGENTS.md, CLAUDE.md, .cursorrules, .github/copilot-instructions.md, and .vscode/mcp.json
• Store-backed host snippets — .mcp-config/*, exported by ace mcp-config for optional global install

That containment matters. ACE is meant to structure the workflow, not contaminate the application tree. One store keeps the truth coherent, and the projections keep outside tools happy without turning the workspace into a generated-file forest.

Where ACE Fits

Developer or MCP host
  │
  ├── Claude Code / Codex / Cursor / VS Code / Antigravity
  │       │
  │       └── calls ace-swarm over MCP
  │
  ├── agent-state/
  │       │
  │       ├── ace-state.ace              (ACEPACK binary store)
  │       └── STATUS.md / kanban.html / HANDOFF.json projections
  │
  ├── ace mcp [--profile host-min|full]  (full surface 119 tools; host-min 22)
  │       │
  │       ├── tools, prompts, resources
  │       ├── typed handoff validation
  │       ├── scheduler and resource locks
  │       └── state-aware workflow tools
  │
  ├── ace tui
  │       │
  │       ├── chat, agent tabs, telemetry
  │       └── provider-aware runtime (direct | optional hermes_local)
  │               │
  │               └── [hermes_local] HermesSubprocessExecutor
  │                       │  spawns Python worker per turn
  │                       ├── ace mcp-shadow --tools <csv>  (scoped surface for Hermes)
  │                       └── hermes_bridge_worker.py → local model (Ollama / llama.cpp)
  │
  ├── .agents/ACE/
  │       │
  │       ├── ace-hook-context.json
  │       ├── tasks/todo.md
  │       └── host config bundles

What Ships Today

+----------------------+--------------------------------------------------------------+
| Surface              | Current scope                                                |
+----------------------+--------------------------------------------------------------+
| Runtime roles        | ACE-Orchestrator, Coders, QA, Spec, Docs, Research, Ops,     |
|                      | Security, Memory, Release, Eval, Skeptic, astgrep, Builder   |
| MCP server           | 119 tools across 13 domain modules (stdio); host-min         |
|                      | profile exposes 22 curated tools                             |
| Durable state        | Single `agent-state/ace-state.ace` authority for handoffs,   |
|                      | status events, todos, run ledger, job queue, and discovery   |
| Projections          | Hook context, todo surface, and host config bundles          |
| Coordination         | Scheduler queues, dependency gates, leases, resource locks,  |
|                      | in-process job worker, heartbeat watchdog, circuit breakers  |
| Goal engine          | `ace goal` self-paced objective loop with evidence-gated     |
|                      | completion, tick/replan budgets, and operator stop           |
| Change intelligence  | Delta scan, semantic snapshots, drift reports, rewrite hints |
| Structural editing   | ast-grep query, locate, rewrite, compile, patch              |
| Hermes bridge        | Optional, user-supplied subprocess engine selected only with |
|                      | `--hermes`; scoped shadow MCP tools, evidence tracking       |
| Terminal UI          | Provider-aware TUI with chat, tabs, telemetry, and agent UI  |
| Local models         | Ollama and llama.cpp bootstrap, doctor checks, and bridges   |
| Tracker integration  | GitHub Issues, Linear adapter layer with snapshot cache      |
| Vericify             | Test evidence log, process post trail (incl. blocker         |
|                      | routing), bridge snapshot                                    |
| Skills               | Packaged skills with catalog, audit, and triage              |
| Experience playbook  | Evidence-gated lessons store (experimental, injection off by |
|                      | default; `ace playbook` / `ace eval --adapt`)                |
+----------------------+--------------------------------------------------------------+

Agent-Assisted Coding, Structured

ACE is for teams and solo operators who already like their coding host and want the workflow around it to stop leaking.

• Use Claude Code, Codex, Cursor, or VS Code as the front end.
• Use MCP as the tool protocol.
• Use ACE as the shared local runtime.
• Use Ollama or another OpenAI-compatible backend when you want the model local or provider-swappable.

In that setup, the host remains the interface. ACE becomes the state contract underneath it.

For hosted Codex, Claude, Gemini, and Copilot backends, use the hosted provider quick setup to configure credentials, endpoints, current default models, and a provider-specific doctor preflight.

Local Models & Hermes

Local models are good at generating text. They usually need help seeing the workspace, hearing the handoff trail, and remembering what changed two turns ago. ACE closes that gap by giving any OpenAI-compatible local runtime — Ollama or llama.cpp — the same shared context, tool surfaces, evidence trails, and resumable state that hosted providers get. The direct provider path works out of the box; no extra runtime is required.

Hermes is an optional layer on top of that. Local providers vary in how they stream tokens, frame tool calls, and handle interrupts. Rather than special-case every quirk in ACE, the operator can point ACE at Hermes — a user-supplied companion execution engine — to handle streaming delivery and robust tool-call framing. ACE does not install Hermes or bundle it; it discovers and launches the operator's own Hermes/Python setup only when --hermes (or --engine hermes_local) is passed. ACE stays the system of record — state, evidence, verification, scheduler — and exposes only a scoped shadow MCP tool surface to Hermes, so the local model sees just the tools its task scope needs.

Hermes-local is opt-in. The local model provider is still Ollama or llama.cpp; Hermes is only the optional execution bridge around that provider.

# Direct path (no Python, no Hermes) — just a local model
ace tui --provider ollama --model qwen3:8b

# Optional Hermes engine, operator-supplied
ACE_HERMES_ROOT=/path/to/hermes-agent HERMES_PYTHON=/path/to/python \
  ace tui --provider llama.cpp --base-url http://127.0.0.1:8080/v1 --model gemma-3-4b-it --hermes

Hermes launch configuration can be supplied with --hermes-root, --hermes-python, and --hermes-uv-project, or with the matching environment variables ACE_HERMES_ROOT, HERMES_PYTHON, and ACE_HERMES_UV_PROJECT.

Tool evidence, not model prose, authorizes completion: a completed claim from a mutation-intent run is demoted to blocked unless the declared artifacts and evidence actually exist. For the bridge architecture, frame protocol, doctor checks, and evidence model, see the Hermes reference.

Compatible Surfaces

+-------------------+------------------------------------------------------------------+
| Layer             | Current integration                                               |
+-------------------+------------------------------------------------------------------+
| MCP clients       | Codex, VS Code, Claude Desktop, Cursor, Antigravity              |
| Hook bundles      | Codex, VS Code, Claude, Cursor, Antigravity, Gemini-compatible   |
| Model backends    | Ollama, llama.cpp, and OpenAI-compatible providers               |
| Operator surface  | `ace tui`                                                        |
| Bootstrap entry   | `ace init` (store-first), `ace turnkey` (store + host stubs)     |
+-------------------+------------------------------------------------------------------+

Documentation

| Reference | Contents | |---|---| | CLI Reference | Every ace command and worked examples | | MCP Tool Reference | The full 119-tool surface across 13 domain modules | | ACEPACK State Model | On-disk binary format, KV region, columnar event log | | Hermes Companion Engine | Bridge architecture, frame protocol, doctor checks, evidence model | | TUI Operator Guide | Provider setup, navigation, interrupt behavior, and recovery | | Provider Security | Hosted/local credentials, endpoint setup, and trust boundaries | | Evaluation Safety | Disposable eval roots, fixtures, provenance, and reproducibility | | Troubleshooting | Symptom-driven diagnostics and recovery commands | | Library API | Supported programmatic entry points and stability boundaries | | Experience Playbook | Experimental evidence-gated lessons store | | Development | Build, test, live driver, and key source files | | CHANGELOG | Release history |

References

• Claude Code overview
• OpenAI connectors and MCP servers
• Ollama tool calling and agent loops
• llama.cpp
• Model Context Protocol SDKs

License

Apache-2.0

Collaborations, ideas, or concerns: [email protected]