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

The full MCP surface spans ~70 registered tools across 12 domain modules — handoffs, scheduler, file ops, drift detection, git, memory, discovery, skills, lifecycle events, vericify, tracker, and framework orchestration — plus resources and prompts.

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 without inventing a local model preset.
• ace doctor validates local or hosted runtime wiring, checks the selected model when the provider exposes listings, and keeps the runtime honest.
• 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 internally by the Hermes bridge so the 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.

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 agent-state/ace-state.ace as a structured single-file store. Existing workspaces that still carry .agents/ACE/ace-state.ace are read through the legacy fallback path. 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.

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 @voybio/ace-swarm turnkey --project "My Project"
ace mcp

Then, in your MCP host:

initiate ACE

Local-model path with Ollama:

npx -y @voybio/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 @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

Optional local-model path with the Hermes execution engine:

ace init --project "My Project" --llm llama.cpp --base-url http://localhost:8080
llama-server -m /path/to/model.gguf --port 8080
ace doctor --scan          # auto-detect endpoint and model
ACE_HERMES_ROOT=/path/to/hermes-agent HERMES_PYTHON=/path/to/python \
  ace doctor --llm llama.cpp --base-url http://127.0.0.1:8080/v1 --model <model> --hermes
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 <model> --hermes

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 @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

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                            (full surface, ~70 tools)
  │       │
  │       ├── 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           | ~70 tools across 12 domain modules (stdio transport)          |
| 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    |
| 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               |
+----------------------+--------------------------------------------------------------+

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 & Hermes Companion Engine

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.

What Hermes is

Hermes is an optional, user-supplied companion execution substrate. ACE does not install Hermes, clone it, or make it a package dependency. When the operator explicitly passes --hermes or --engine hermes_local, Hermes handles local provider quirks, streaming delivery, and robust tool-call framing. The local model provider is still Ollama or llama.cpp. ACE remains the system of record — state, evidence, verification, scheduler — and exports a scoped shadow MCP tool surface to Hermes so the local model only sees the tools it needs for a given task scope.

ACE TUI  (ace tui --hermes / --engine hermes_local)
        │  user input → ChatSession.sendMessage();
        │  ACE owns session identity, policy, state
        ▼
runLocalModelTask()                    ← src/local-model-runtime.ts
        │  ACE dispatches, ACE controls the turn
        ▼
HermesSubprocessExecutor               ← Node.js class, src/hermes/session-manager.ts
        │  spawns Python worker; ACE controls lifecycle
        ├── writes hermesHome/config.yaml (provider, model, user-supplied Hermes path, shadow MCP entry)
        ├── pipes ace mcp-shadow --tools <csv>  ← scoped tools-only shadow server (stdio)
        │         (ACE-owned; local model sees only allowed tools, not public prompts/resources)
        ▼
hermes_bridge_worker.py                ← Python subprocess
        │  reads config.yaml; calls shadow MCP & local model
        ├── streams framed NDJSON events → HermesBridgeFrameDecoder
        └── calls local model (ollama / llama.cpp)
        │
        ▼  bridge frames validated and applied by ACE
ACE store (ace-state.ace)              ← authoritative output; ACE-owned
        evidence, continuity, run ledger persisted here

Bridge protocol

The Node ↔ Hermes channel is a strictly typed newline-delimited JSON frame stream. Each frame carries a type field:

| Frame type | Direction | Purpose | |---|---|---| | session_open | N→H | start session with config | | turn_run | N→H | submit a task turn | | interrupt | N→H | cancel in-flight turn | | session_close | N→H | shut down the worker | | status | H→N | heartbeat / progress | | delta | H→N | streaming token chunk | | reasoning | H→N | chain-of-thought (optional) | | assistant_interim | H→N | partial assistant message | | tool_start | H→N | tool call initiated | | tool_progress | H→N | tool call in flight | | tool_complete | H→N | tool call result | | final | H→N | complete assistant response | | error | H→N | fatal bridge error |

Frame decoding is handled by HermesBridgeFrameDecoder in src/hermes/bridge-protocol.ts. The decoder strips control bytes, sanitizes the line, and validates against the event schema before handing frames to the session manager.

Running with Hermes

# User owns Hermes/Python setup. ACE only discovers and launches it when asked.
ACE_HERMES_ROOT=/path/to/hermes-agent \
HERMES_PYTHON=/path/to/python \
ace doctor --llm llama.cpp --base-url http://127.0.0.1:8080/v1 --model <model> --hermes

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 <model> --hermes

# Optional uv-managed Hermes project, still operator supplied.
ACE_HERMES_ROOT=/path/to/hermes-agent \
ACE_HERMES_UV_PROJECT=/path/to/hermes-agent \
ace tui --provider llama.cpp --base-url http://127.0.0.1:8080/v1 --model <model> --hermes

Or use the TUI with explicit engine selection:

ace tui --provider llama.cpp --base-url http://localhost:8080 --engine hermes_local
# shorthand
ace tui --provider ollama --model llama3.1:8b --hermes

Note: Hermes-local is opt-in. Without --hermes or --engine hermes_local, the TUI uses the direct provider path and does not require Python, uv, or Hermes. When Hermes is selected, ACE launches the user-supplied Hermes/Python setup for that session and exposes only the scoped shadow MCP tool surface. Tool evidence, not model prose, determines executable mutation.

Doctor checks for Hermes

ace doctor surfaces Hermes-local readiness gates only when --hermes is passed:

ACE_HERMES_ROOT=/path/to/hermes-agent HERMES_PYTHON=/path/to/python \
  ace doctor --llm llama.cpp --model gemma-4 --base-url http://localhost:8080 --hermes

Checks performed:

• Hermes bridge worker packaged (scripts/hermes_bridge_worker.py present)
• Hermes checkout supplied by the operator (ACE_HERMES_ROOT or --hermes-root)
• Python supplied by the operator (HERMES_PYTHON or --hermes-python)
• Optional uv project supplied by the operator (ACE_HERMES_UV_PROJECT or --hermes-uv-project)
• Shadow MCP command available for scoped tools-only transport
• Local runtime reachable and model available

# Auto-scan common Ollama + llama.cpp endpoints
ace doctor --scan

Evidence model

ACE persists tool evidence only when the model invokes write_workspace_file successfully through the shadow MCP surface. If Hermes returns a complete artifact in its final response but never called the write tool, the live driver materializes the artifact for inspection and records materialized_from_hermes_final — diagnostic only, not counted as tool_write_done.

Operator-restricted models (e.g. deepseek-r1:8b) are blocked in local-model-policy.ts before a session even starts.

MCP Tool Surface

ACE exposes tools through a domain-modular registration system (src/tools.ts delegates to 12 domain modules). Tools can be allow-listed at startup; ace mcp-shadow uses this to give Hermes a scoped tools-only subset. Public ace mcp still exposes the full tools, prompts, and resources surface.

Agent & Runtime

| Tool | Purpose | |---|---| | get_agent_instructions | Read instruction content for any ACE agent role | | get_agent_manifest | Read the manifest for a given agent role | | get_all_agents_summary | List all registered agents with role metadata | | get_kernel_artifact | Read a named kernel artifact from the store | | get_runtime_profile | Read the active runtime profile (provider, model, base URL) | | validate_runtime_profile | Schema-validate the stored runtime profile | | get_transition_log | Read recent agent state-transition history | | get_capability_snapshot | Summarize current capability coverage across agents | | get_runtime_tool_specs | Read the tool-spec registry for the active runtime | | validate_runtime_tool_specs | Schema-validate the tool-spec registry | | list_runtime_tool_specs | List all registered tool specs | | execute_runtime_tool | Execute a named runtime tool by spec |

Orchestration & Planning

| Tool | Purpose | |---|---| | propose_plan | Generate a multi-step task plan proposal | | validate_plan | Validate a plan proposal against acceptance contracts | | run_local_model | Dispatch a task to the configured local model runtime | | run_orchestrator | Run an ACE orchestrator session for a given task | | route_task | Route an incoming task to the appropriate agent role | | bootstrap_state | Seed or repair the ACE store for the current workspace | | get_framework_status | Read aggregate framework health and readiness | | validate_framework | Run the full framework validation gate suite | | audit_public_surface | Audit schema-bound tools, resources, and prompts | | audit_store_authority | Verify store authority and projection consistency | | execute_gates | Run named gate conditions (dependency, handoff, time) |

Handoffs

| Tool | Purpose | |---|---| | create_handoff | Create a typed, validated handoff record | | validate_handoff | Validate a handoff payload against the schema | | get_handoff_template | Retrieve the handoff template for a given role pair | | get_handoff_status | Read the status of a specific handoff | | ack_handoff | Acknowledge a handoff as received and accepted |

Example — creating a handoff from orchestrator to qa:

# via any MCP client
create_handoff {
  "from_role": "orchestrator",
  "to_role": "qa",
  "summary": "Auth module implementation complete, ready for test coverage review",
  "evidence": ["src/auth.ts", "src/auth.test.ts"],
  "priority": "P1"
}

Scheduler

| Tool | Purpose | |---|---| | enqueue_job | Add a job to the queue with priority, deps, and resource locks | | dispatch_jobs | Tick the scheduler and dispatch ready jobs | | acknowledge_job | Mark a job as accepted by a worker | | complete_job | Mark a job done or failed | | get_job_queue | Read the current job queue | | get_job_lock_table | Read active resource locks | | get_scheduler_lease | Read the current scheduler lease |

Example — queuing a blocked job:

enqueue_job {
  "kind": "handoff.lifecycle",
  "priority": "P1",
  "dependencies": [{ "kind": "handoff", "ref": "HNDOFF-abc123", "expected": "ack" }],
  "resource_requirements": ["agent-state/handoff-registry.json"],
  "run_after": "2026-05-08T18:00:00Z"
}

Files & Structural Editing

| Tool | Purpose | |---|---| | read_workspace_file | Read any file in the workspace | | write_workspace_file | Write or overwrite a file (evidence-tracked) | | list_workspace | Directory listing with optional glob filter | | safe_edit_file | Edit a file with collision-safe write semantics | | diff_files | Produce a unified diff between two workspace paths | | read_file_lines | Read a line range from a file | | outline_file | Extract structural outline (symbols, headings) from a file | | astgrep_query | Run an ast-grep query pattern against the workspace index | | astgrep_locate | Locate a specific symbol or construct with ast-grep | | compile_structural_edit | Compile an ast-grep rewrite to a patch | | preview_structural_edit | Preview a structural edit without applying | | astgrep_rewrite | Apply an ast-grep rewrite rule across matched files | | apply_patch | Apply a unified diff patch to the workspace |

Change Intelligence & Drift

| Tool | Purpose | |---|---| | snapshot_state | Take a semantic snapshot of the current workspace state | | semantic_diff | Diff two semantic snapshots | | drift_report | Produce a drift report between baseline and current state | | list_snapshots | List available workspace snapshots | | rewrite_targets | Identify files that are candidates for rewrite based on drift |

Discovery & Indexing

| Tool | Purpose | |---|---| | refresh_astgrep_index | Rebuild the ast-grep structural index | | scan_workspace_delta | Scan for file changes since the last index pass | | web_research_packet | Package a web research context for agent consumption | | mcp_ingestion_probe | Probe an MCP server and ingest its tool/resource surface | | codemunch_snapshot | Take a full codemunch snapshot of the workspace | | codemunch_index | Index a codemunch snapshot for search |

Git

| Tool | Purpose | |---|---| | git_status | Read working-tree status | | git_commit | Stage and commit changes with a message | | git_diff | Diff staged, unstaged, or between refs | | git_log | Read recent commit history |

Memory & Continuity

| Tool | Purpose | |---|---| | context_snapshot | Capture a structured context snapshot for the current session | | build_continuity_packet | Build a continuity packet for cross-session handoff | | recall_context | Recall a previous context snapshot by ID or recency |

Example — before switching models mid-task:

build_continuity_packet {
  "session_summary": "Implemented auth module, blocked on integration test setup",
  "next_step": "Write integration tests for /api/auth endpoints"
}

Lifecycle & Status Events

| Tool | Purpose | |---|---| | emit_status_event | Append a typed lifecycle event to STATUS_EVENTS.ndjson | | get_framework_status | Read aggregate status across all modules | | refresh_kanban | Rebuild the kanban board from current state |

Example:

emit_status_event {
  "source_module": "capability-ops",
  "event_type": "TASK_COMPLETE",
  "status": "pass",
  "summary": "Auth integration tests green across all providers"
}

Todo & Run Ledger

| Tool | Purpose | |---|---| | get_todo | Read the current todo surface | | get_todo_state | Read structured todo state from the store | | update_todo | Update one or more todo items | | get_run_ledger | Read the run ledger (history of major tool invocations) |

Vericify (Verification)

| Tool | Purpose | |---|---| | get_vericify_context | Get the current verification context packet | | get_vericify_delta | Get the incremental verification delta | | get_vericify_bridge | Read the vericify bridge snapshot | | refresh_vericify_bridge | Refresh the bridge snapshot from test runner output | | validate_vericify_bridge | Schema-validate the bridge snapshot | | get_vericify_process_posts | Read the vericify process post log | | append_vericify_process_post | Append a test result post to the process log | | validate_vericify_process_post_log | Schema-validate the process post log |

Tracker Integration

| Tool | Purpose | |---|---| | get_tracker_snapshot | Read the cached tracker snapshot (GitHub Issues, Linear, etc.) | | validate_tracker_snapshot | Schema-validate the tracker snapshot | | list_tracker_adapter_kinds | List available tracker adapters | | get_tracker_adapter_health | Check health of the active tracker adapter | | list_tracker_items | List items from the tracker | | create_tracker_comment | Post a comment to a tracker item | | update_tracker_item_state | Update the state of a tracker item | | refresh_tracker_snapshot | Pull fresh data from the tracker into the snapshot |

Skills & Tasks

| Tool | Purpose | |---|---| | skill_catalog_summary | List all available skills with brief descriptions | | skill_audit | Audit skill freshness and coverage | | problem_triage | Triage a problem description against known skills | | list_skills | List skills in the store | | get_skill_instructions | Read full instructions for a named skill | | get_task_pack | Read a named task pack | | get_lessons | Read the lessons log | | add_lesson | Append a lesson to the log |

Workspace Sessions

| Tool | Purpose | |---|---| | list_workspace_sessions | List managed workspace sessions | | create_workspace_session | Create a new managed workspace session | | remove_workspace_session | Remove a workspace session | | validate_managed_workspace_path | Validate a workspace path against the session registry |

Unattended Sessions

| Tool | Purpose | |---|---| | list_unattended_sessions | List registered unattended agent sessions | | get_unattended_session | Read details of a specific unattended session | | start_unattended_session | Launch an unattended agent session | | stop_unattended_session | Stop a running unattended session | | wait_for_unattended_session | Block until a session reaches a terminal state | | validate_unattended_session_registry | Schema-validate the session registry |

Framework & Config

| Tool | Purpose | |---|---| | get_mcp_config | Read the baked MCP config for a named client | | run_tests | Run the ACE test suite | | get_cli_split | Read the CLI split configuration |

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 mcp` / `ace serve`                       | Start MCP server over stdio                       |
| `ace mcp-shadow --tools <csv>`                | Start filtered shadow MCP server (Hermes use)     |
| `ace tui [options]`                           | Open the terminal operator surface                |
| `ace init [options]`                          | Seed the ACE store and optional host stubs        |
| `ace connect [provider] [options]`            | Register a live local runtime or hosted provider  |
| `ace turnkey [options]`                       | Project store-backed host surface stubs           |
| `ace doctor [options]`                        | Validate ACE runtime + Hermes readiness           |
| `ace cache [options]`                         | Cache ACE artifacts into ace-state.ace            |
| `ace mcp-config [--client <name>|--all]`      | Print baked client snippets for optional install  |
| `ace preconfig`                               | Write .mcp-config/ bundle for all clients         |
| `ace paths`                                   | Show resolved package and workspace paths         |
| `ace help`                                    | Show help                                         |
+-----------------------------------------------+---------------------------------------------------+

CLI examples

# Bootstrap a workspace with a hosted provider
ace init --project "My App" --llm claude --client-config-bundle

# Bootstrap with local Ollama model and write VS Code MCP config
ace init --project "My App" --llm ollama --model llama3.1:8b \
  --base-url http://localhost:11434 --mcp-config

# Connect to a running llama.cpp server from a Hugging Face model
ace connect llama-server --hf bartowski/gemma-3-4b-it-GGUF \
  --base-url http://localhost:8080

# Run doctor checks with auto-scan of common local endpoints
ace doctor --scan

# Run doctor checks for a specific provider + model
ace doctor --llm ollama --model llama3.1:8b --base-url http://localhost:11434

# Run optional Hermes checks with user-supplied Hermes/Python
ACE_HERMES_ROOT=/path/to/hermes-agent HERMES_PYTHON=/path/to/python \
  ace doctor --llm llama.cpp --model gemma-4 --base-url http://localhost:8080 --hermes

# Repair a missing Ollama model found during doctor
ace doctor --llm ollama --model llama3.1:8b --repair-ollama

# Print VS Code MCP config snippet to stdout
ace mcp-config --client vscode

# Write config bundles for every supported client at workspace root
ace preconfig

# Launch TUI with optional Hermes engine against a local llama.cpp server
ACE_HERMES_ROOT=/path/to/hermes-agent HERMES_PYTHON=/path/to/python \
  ace tui --provider llama.cpp --base-url http://localhost:8080 --model gemma-4 --hermes

# Cache all ACE artifacts into ace-state.ace (dry run first)
ace cache --dry-run
ace cache

Development

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

Run the Hermes live driver against your workspace:

npm run build
# with a local llama.cpp or Ollama runtime running:
ACE_WORKSPACE_ROOT=$PWD \
  ACE_LIVE_PROVIDERS=llama.cpp \
  ACE_LIVE_LLAMA_CPP_BASE_URL=http://127.0.0.1:8080/v1 \
  ACE_LIVE_LLAMA_CPP_MODEL=gemma-4-it \
  ACE_LIVE_HERMES_MAX_TURNS=3 \
  ACE_LIVE_OUTPUT_ONLY=1 \
  node scripts/dev/run_hermes_crispr_live.mjs

Key source files:

| File | Role | |---|---| | src/index.ts | Package entry point | | src/cli.ts | CLI command dispatch | | src/server.ts | MCP server setup and stdio transport | | src/tools.ts | Tool registration hub (delegates to domain modules) | | src/hermes/session-manager.ts | HermesSubprocessExecutor — Hermes subprocess lifecycle | | src/hermes/bridge-protocol.ts | Frame decoder for the Hermes bridge protocol | | src/model-bridge.ts | Model bridge interface and process orchestration | | src/public-surface.ts | Public surface audit and schema-bound entry map | | src/store/ace-packed-store.ts | ACEPACK binary store read/write | | src/local-model-policy.ts | Operator allow/block policy for local models | | scripts/hermes_bridge_worker.py | Packaged Python worker for the Hermes bridge |

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]