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, 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 — .agents/ACE/ace-state.ace — so the workspace keeps one source of truth instead of a forest of generated state files.

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 provides task context, tool surfaces, status events, evidence trails, and resumable state.

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 .agents/ACE/ace-state.ace.

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 doctor validates local or hosted runtime wiring, checks the selected model when the provider exposes listings, and keeps the runtime honest.
• ace mcp and ace tui expose the same workspace truth to the host, the terminal, and the model.

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.

ACE also provides scheduler primitives for queued work, dependency gates, leases, and resource locks so multi-agent runs stay coordinated.

ACEPACK State Model

ACE uses a custom binary format called ACEPACK to present .agents/ACE/ace-state.ace as a structured single-file store. The file has three regions:

ace-state.ace
├── Header (128 bytes)
│     magic · version · flags
│     kv_index_offset · kv_index_length · kv_chunk_end
│     evt_offset · evt_length · evt_count · evt_base_id
├── KV Chunk Region  (append-only, random-access)
│     knowledge/agents/{name}/{file}  →  agent instruction text
│     knowledge/skills/{name}/{file}  →  skill content
│     topology/{kind}                 →  swarm registry, route tables
│     state/{...}                     →  handoffs, todo, ledger, scheduler
│     meta/{...}                      →  schema version, project name
│     Each chunk: [uint32 length][bytes]
└── Columnar Event Section  (rewritten on commit)
      uint32    event count
      int64[N]  timestamps      (epoch ms, big-endian)
      uint8[N]  kinds           (EntityKind enum)
      uint8[N]  sources         (ContentSource enum)
      uint8[N]  flags           (0x01 = deleted)
      uint32[N] payload offsets (→ payload pool)
      uint32[N] payload lengths
      uint32    pool length
      bytes[M]  payload pool    (UTF-8 JSON blobs)

KV region — random-access blob cache

All persistent state — agent instructions, skills, topology, task indexes, scheduler queues — lives in the KV region. Each key maps to an immutable chunk appended at write time. commit() rewrites the KV index (a small JSON map at the file tail) to reflect the live keys. compact() rewrites the KV region to remove dead space from overwritten keys, atomically via tmp-rename.

Write cost: O(1) append + O(index_size) index rewrite. Read cost: O(1) seek + O(chunk_length) read.

Columnar event section — typed handoff log

Every appendEntry() call — handoffs, status events, ledger entries, session events — lands in an in-memory buffer and is flushed to the columnar section on commit(). The columnar layout stores fixed-width fields (timestamp, kind, source, flags) separately from payloads. This means:

• Scanning "all handoffs in the last hour" reads only timestamps[] + kinds[] — 9 bytes per event, never touching the payload pool.
• Per-event overhead is ~19 bytes fixed vs ~150 bytes for equivalent JSON.
• At 100,000 events, the fixed columns are ~1.9 MB; a full JSON log would be ~15 MB.

Events accumulate for the workspace lifetime and survive compact(). Full historical replay is always available. See HOT_COLD_EVENT_TIERING.md for the future branch that adds compressed batch archiving for very long-lived workspaces.

Why one state file

| One .ace authority | What it avoids | |---|---| | Single append-only file | Hundreds of generated state files drifting apart | | KV region with typed keys | Hand-rolled file sprawl for runtime state, instructions, indexes | | Columnar event log | Repeated full-JSON parsing for timestamp and kind scanning | | Store-backed projections | External tools reading the same truth through different paths |

The store holds runtime state, agent instructions, skills, topology, schemas, and the complete event history. Materialized files exist only when an external client still needs a path on disk.

Quick Start

Bootstrap a workspace:

npx -y ace-swarm turnkey --project "My Project"
ace mcp

Then, in your MCP host:

initiate ACE

Local-model path with Ollama:

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

Local-model path with llama.cpp:

npx -y 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

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.

Hosted provider path with Codex:

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

What Bootstrap Writes

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

• .agents/ACE/ace-state.ace — runtime state, agent instructions, skills, topology, schemas, and the event log
• .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
  |
  +-- ace mcp
  |       |
  |       +-- tools, prompts, resources
  |       +-- typed handoff validation
  |       +-- scheduler and resource locks
  |       `-- state-aware workflow tools
  |
  +-- .agents/ACE/
  |       |
  |       +-- ace-state.ace
  |       +-- ace-hook-context.json
  |       +-- tasks/todo.md
  |       `-- host config bundles
  |
  `-- ace tui
          |
          +-- chat
          +-- agent tabs
          +-- telemetry
          `-- provider-aware runtime

What Ships Today

+----------------------+--------------------------------------------------------------+
| Surface              | Current scope                                                |
+----------------------+--------------------------------------------------------------+
| Runtime roles        | swarm and composable runtime roles                           |
| Skills               | packaged skills                                              |
| MCP server           | stdio surface for tools, prompts, resources, and workflows   |
| Durable state        | single .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, and resource locks |
| Change intelligence  | delta scan, semantic snapshots, drift reports, rewrite hints |
| Terminal UI          | provider-aware TUI with chat, tabs, telemetry, and agent UI  |
| Local models         | Ollama and llama.cpp bootstrap, doctor checks, and bridges   |
| Verification         | automated test suite and regression coverage                 |
+----------------------+--------------------------------------------------------------+

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.

Local Models

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.

• ace init --llm <provider> seeds the profile inside .agents/ACE/ace-state.ace.
• ace doctor verifies that the selected runtime is configured and, when possible, reachable.
• ace tui can talk to either local runtime and surface the same workspace state the MCP server sees.
• The ACE model bridge gives local runs tool selection, execution flow, and persisted state instead of a fragile one-shot chat loop.

If you want local agents with memory, evidence, and handoff discipline, this is the point of the package.

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)     |
+-------------------+------------------------------------------------------------------+

CLI

+---------------------------------------------+---------------------------------------------------+
| Command                                     | Purpose                                           |
+---------------------------------------------+---------------------------------------------------+
| `ace init [options]`                        | seed the ACE store and optional host stubs        |
| `ace turnkey [options]`                     | project the store-backed host surface              |
| `ace mcp` / `ace serve`                     | start the MCP server over stdio                   |
| `ace tui [options]`                         | open the terminal operator surface                |
| `ace doctor [options]`                      | validate ACE runtime readiness                    |
| `ace mcp-config [--client <name>|--all]`    | print baked client snippets for optional install  |
| `ace paths`                                 | show resolved package and workspace paths         |
+---------------------------------------------+---------------------------------------------------+

Development

cd ace-mcp-server
npm install
npm run build
npm test
npm run start

See CHANGELOG.md for 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]