APEXMA

APEXMA is a local-first runtime and control plane for autonomous coding agents.

Package:

• npm: https://www.npmjs.com/package/apexma
• GitHub: https://github.com/AnThophicous/apex-multi-agent

It is not trying to replace Codex, Claude Code, Cursor Agents, or Copilot. Those systems already know how to reason, plan, and spawn sub-agents. The hard problem now is coordination: who is doing what, in which workspace, with which context, under which permissions, with which validation, and how the master can understand the whole swarm without trusting a black box.

APEXMA is the runtime that sits under that problem.

What APEXMA Actually Is

APEXMA is a machine-local orchestration layer with:

• durable runtime state in SQLite WAL
• structured channels for agent-to-agent and agent-to-master communication
• optional shared project sandboxes for cross-agent architecture and coordination
• task graph, wakes, traces, runs, workspaces, and proposals as first-class records
• native adapters for Codex, Claude Code, Cursor, and Copilot
• MCP and CLI control surfaces
• a supervising overmap for the master agent
• scoped worktrees and internal PR-style proposals
• Guardian review gates for command, plan, spawn, package, and proposal risk
• workspace checkpoints, rollback paths, and append-only runtime events
• Shared File handoff memory with bounded token cost

The model is closer to a hybrid of Temporal, Kubernetes, Git worktrees, and a local agent OS than a prompt wrapper.

Core Direction

Modern coding agents can already delegate internally.

The bottleneck is now:

• coordination
• shared state
• observability
• recovery
• permission boundaries
• scoped execution
• reproducibility

APEXMA is designed around that reality.

Architectural Model

At runtime, APEXMA keeps durable records for:

• agents
• memory
• channels
• messages
• tasks
• supervised runs
• sandboxes and sandbox members
• workspaces
• workspace checkpoints
• proposals
• runtime events
• traces and spans
• wake events

This lets the swarm operate as a real system instead of a pile of opaque subprocesses.

Control Plane

The local control plane exposes:

• MCP server for tool-driven agents
• JSON-first CLI for operators and scripts
• overmap snapshot for the master
• command center for broadcast and direct directives
• optional shared sandbox gateway for local real-time collaboration
• integration bootstrap for supported clients

Execution Plane

Workers execute through supervised adapters:

• Codex via codex exec --json
• Claude Code via claude -p --output-format stream-json
• Cursor via cursor-agent --print --output-format stream-json
• Copilot via copilot --output-format=json

Each worker run is wrapped by APEXMA, not trusted blindly.

Workspace Plane

When isolation is enabled, APEXMA creates a dedicated worktree per agent branch:

main
├── agent/coder-01
├── agent/researcher-02
├── agent/tester-03
└── agent/ui-04

Workers do not need to mutate the main branch directly. They can produce internal proposals with branch, base branch, changed files, diff stats, test result, and risk label.

Proposal Plane

Every serious change can become an internal PR-style record:

{
  "title": "Fix overflow in dashboard grid",
  "branch": "agent/coder-01",
  "baseBranch": "main",
  "tests": "passed",
  "risk": "low"
}

This gives the runtime merge lineage, review state, and a path toward replay and rollback.

Sandbox Plane

APEXMA now supports an optional Shared Project Sandbox.

The model is:

• each agent keeps its own private workspace
• the sandbox is a separate collaboration layer
• agents can join as members with explicit roles
• members can talk in real time, share architecture decisions, and target the owner of a specific workspace without dumping full project context

That matters for both coordination quality and token cost. A frontend agent that only needs one API contract can ask the backend agent that owns that workspace instead of pulling the whole repository context.

The sandbox can run over:

• persistent channel messages in the local runtime
• optional local WebSocket transport for real-time agent collaboration

This is not a replacement for isolated workspaces. It sits above them as a shared team space.

Master, Agents, and Communication

APEXMA treats the master as a real runtime identity.

The master is not supposed to be the strongest coding worker. The master is the local tech lead and control-plane operator.

The master should:

• inspect the overmap
• arbitrate architecture and product uncertainty
• enforce scope and policy
• call Guardian and security review when needed
• approve, reject, or redirect proposals

Workers should:

• send messages directly to other agents
• read their own inbox
• ask the master for missing product or architecture decisions
• inspect the overmap before a major change
• collaborate inside a shared sandbox when the user enables that mode

New control-plane primitives:

• apex.agent.message
• apex.agent.inbox
• apex.master.ask
• apex.master.respond
• apex.master.inbox
• apex.sandbox.create
• apex.sandbox.join
• apex.sandbox.message
• apex.sandbox.snapshot
• apex.sandbox.decision
• apex.overmap.snapshot

This means the swarm can coordinate explicitly instead of smuggling intent through brittle prompt text.

TIC System Contract

Every isolated workspace can now be primed with a system document:

.apex/AGENT_SYSTEM.md

That file is not decorative. It encodes a Task / Instructions / Context contract plus a hard reasoning policy:

• stay inside scope
• do not improvise missing requirements
• ask the master when stack, acceptance criteria, architecture, or deployment constraints are missing
• ask peer agents when local ownership or dependent outputs are unclear
• use overmap, inbox, traces, and Shared File as real runtime surfaces

This is the runtime version of "do not hallucinate architecture under ambiguity".

The document also contains a Thinking Absolute section:

• reasoning is constrained comprehension, not freeform guessing
• invalid context must be escalated
• broad requests must be narrowed before implementation

Security Model

APEXMA is built assuming hostile conditions:

• poisoned prompts
• weak plans
• risky dependency installs
• destructive commands
• task drift
• context leakage
• replay attempts
• accidental branch damage

Current hardening includes:

• scoped permissions
• nonce replay protection
• HMAC-ready MAP framing
• Guardian reviews for package, command, plan, spawn, and proposal
• worktree isolation
• shared sandbox membership checks
• workspace-targeted messaging instead of unrestricted branch access
• worker wall/cpu/rss execution limits
• rollback and checkpoint records for repair and audit
• proposal review state
• master-side whisper MCP endpoint for narrow risk critique

The Guardian is not cosmetic. It is already wired into the spawn and proposal path, and it can deny destructive or production-risky behavior.

Observability

The overmap is the operator surface for the master.

It now shows:

• agents and roles
• active tasks
• supervised runs
• runtime duration
• heartbeat lag
• sandboxes and sandbox membership
• recent activity span
• workspaces
• checkpoints
• proposals
• directives
• recent messages
• append-only runtime events
• Shared File entries
• usage data when the provider exposes token metrics

When provider events contain usage, APEXMA aggregates:

• input tokens
• output tokens
• reasoning tokens
• total tokens
• optional estimated USD cost

Cost estimation is opt-in through environment prices:

APEX_PRICE_INPUT_PER_1M=3
APEX_PRICE_OUTPUT_PER_1M=15
APEX_PRICE_REASONING_PER_1M=0

If the provider does not emit usage, APEXMA does not invent numbers.

Installation

Requirements

• Node.js >= 20.12.0
• a git repository when using worktree isolation
• one or more supported agent CLIs installed locally if you want native worker execution

Local Development

npm install
npm run build
npm test

Install from npm:

npm install -g apexma

Start the MCP server:

npm run dev:mcp

Or directly:

node dist/bin/apex.js mcp

The runtime database defaults to:

.apex/apex.db

Override it with:

APEX_DB=/path/to/apex.db node dist/bin/apex.js mcp

Fast Bootstrap on a New Machine

The fastest way to make the repository usable for multiple clients is:

node dist/bin/apex.js integrate bootstrap all --portable --force

That will:

• write project MCP config for Claude Code
• write project MCP config for Cursor
• write project MCP config for VS Code Copilot
• return the remaining manual Codex install command

Audit what already exists:

node dist/bin/apex.js integrate audit all

Main Operator Flows

1. Start and Inspect

node dist/bin/apex.js init --analyze
node dist/bin/apex.js status
node dist/bin/apex.js doctor
node dist/bin/apex.js panel --watch 2

2. Register and Coordinate Agents

node dist/bin/apex.js agent register --id researcher-02 --role research --capability search
node dist/bin/apex.js agent register --id coder-04 --role coder --capability typescript
node dist/bin/apex.js agent send coder-04 --from researcher-02 --text "Need the API contract shape"
node dist/bin/apex.js agent inbox coder-04
node dist/bin/apex.js master ask --from coder-04 --question "Should I split this change into two proposals?"
node dist/bin/apex.js master inbox

3. Isolated Execution

node dist/bin/apex.js workspace prepare --agent coder-04 --root . --base-branch main
node dist/bin/apex.js codex spawn --agent coder-04 --objective "Fix the scheduler edge case" --cwd . --isolate

This creates a worktree, primes .apex/AGENT_SYSTEM.md, and lets the adapter execute in that workspace instead of the main branch.

4. Proposal Lifecycle

node dist/bin/apex.js proposal create --agent coder-04 --title "Fix scheduler edge case" --summary "Scoped fix with focused verification." --tests "passed" --risk low
node dist/bin/apex.js proposal list
node dist/bin/apex.js proposal review <proposal> --state approved
node dist/bin/apex.js proposal merge <proposal>

5. Shared Sandbox Collaboration

node dist/bin/apex.js sandbox create --title "dashboard delivery" --owner master --root . --prod-branch main
node dist/bin/apex.js sandbox join <sandbox> --agent backend-01 --workspace <workspace>
node dist/bin/apex.js sandbox join <sandbox> --agent frontend-01 --workspace <workspace>
node dist/bin/apex.js sandbox send <sandbox> --from frontend-01 --target-workspace <backend-workspace> --text "Need the API contract for the dashboard route"
node dist/bin/apex.js sandbox decision <sandbox> --from backend-01 --summary "Dashboard contract shape" --decision "Expose GET /api/dashboard with summary+activity blocks"
node dist/bin/apex.js sandbox snapshot <sandbox> --agent master

When real-time collaboration is needed:

node dist/bin/apex.js sandbox serve --host 127.0.0.1 --port 46321

This starts a local WebSocket gateway for sandbox members. Private workspaces stay isolated. The shared sandbox only exposes the collaboration layer and explicit member-linked context.

6. Native Worker Planning

node dist/bin/apex.js codex plan --agent codex-01 --objective "Inspect the scheduler" --cwd . --isolate
node dist/bin/apex.js claude plan --agent claude-01 --objective "Review auth boundaries" --cwd . --isolate
node dist/bin/apex.js cursor plan --agent cursor-01 --objective "Inspect UI state" --cwd . --isolate
node dist/bin/apex.js copilot plan --agent copilot-01 --objective "Review repository instructions" --cwd . --isolate

MCP Surface

Important MCP tools include:

• apex.runtime.status
• apex.runtime.benchmark
• apex.integration.bootstrap
• apex.integration.audit
• apex.overmap.snapshot
• apex.agent.message
• apex.agent.inbox
• apex.master.ask
• apex.master.respond
• apex.master.inbox
• apex.sandbox.create
• apex.sandbox.join
• apex.sandbox.message
• apex.sandbox.read
• apex.sandbox.snapshot
• apex.sandbox.decision
• apex.workspace.prepare
• apex.workspace.list
• apex.proposal.create
• apex.proposal.review
• apex.proposal.merge
• apex.guardian.proposal_review

The full CLI is documented in docs/CLI.md. Integration details live in docs/INTEGRATIONS.md. Security assumptions live in docs/SECURITY.md. Protocol notes live in docs/MAP.md. Architectural details live in docs/ARCHITECTURE.md.

Version 0.2.0

0.2.0 is the first version where APEXMA starts to behave like a real local agent operating layer instead of just a coordination prototype.

Major additions in 0.2.0:

• shared project sandbox with explicit membership and workspace-linked collaboration
• optional real-time local WebSocket sandbox gateway
• workspace checkpoints and rollback paths
• append-only runtime event log
• stronger execution hardening with worker limits
• richer overmap state for master-side supervision

Current Limits

APEXMA is already a serious local control plane, but some things are still intentionally unfinished:

• rollback is strong for workspaces and proposals, not yet a universal full-runtime checkpoint restore
• event sourcing is present and durable, but not yet the only source of truth for every subsystem
• the real-time sandbox transport is local WebSocket, not yet a broader distributed bus
• worker limits are stronger now, but still depend on local OS visibility and are currently more Linux-friendly than platform-neutral
• exact AI cost reporting depends on provider usage events and optional pricing config

Contributors

• AnThophicous
• Brenno Leon