AgentForge Command

A premium mission-control cockpit for a swarm of Claude Code agents.

Quickstart · Mission Control · Auto-enter · Architecture · Rust accelerator

---

AgentForge Command is a local cockpit for orchestrating multiple Claude Code sessions in one window. Atlas Prime is the only lead — you talk to Atlas, Atlas dispatches the right specialists, every specialist reports back to Atlas so he always knows what the swarm is doing. You can also broadcast directly to the entire swarm, or open any specialist's drawer and talk to that single agent.

There is no mock activity. If you haven't configured the LLM bridge and nothing is running, the cockpit stays honestly idle and tells you exactly what to set. Everything you see is either a real PTY's output or a live Claude stream.

Local-first, file-coordinated and dependency-light. The optional Rust accelerator (forge-pulse) sharpens prompt detection but is never required.

⚠️ Policy notice (April 2026)

Anthropic restricts Pro/Max subscription access for third-party, PTY-based agent frameworks. In practice, for AgentForge:

• Test-harness mode (no key): ✅ Works — deterministic, no LLM calls.
• Your own Anthropic API key: ✅ Works — your account, your key, your consumption, via the official Messages API.
• A shared Pro/Max account driven through this framework: ❌ Not permitted by Anthropic's terms.

You are responsible for ensuring your usage complies with the Anthropic Usage Policies and Consumer/Commercial Terms. This is our good-faith reading, not legal advice, and AgentForge ships no mechanism to circumvent any provider limit. See docs/THREAT_MODEL.md for the full breakdown.

The cockpit

The redesigned cockpit — Atlas Prime is the central figure with a large, readable answer area.

A swarm-check in flight: your message, Atlas's streamed answer, the workflow stepper, and the Dispatch & reports panel naming every specialist (here shown via the deterministic test harness, hence the badge — no fake activity).

Sentinel specialist drawer	Ledger drawer · spend + forecast
Spawn-Builder modal · Alt+N	Mobile · stacked layout

The swarm

Agent	Mascot	Domain
ATLAS PRIME	Cyber Turtle	Chief Orchestrator
SENTINEL	Guardian Owl	Risk & Safety
AURORA	Neon Fox	Premium UI / Motion
FORGE	Forge Mole	Build & Release
PRISM	Prism Chameleon	Visualization & Graphs
ECHO	Signal Bat	Event Stream & Replay
VEGA	Neon Hummingbird	Performance / Motion Engine
SCRIBE	Scribe Raven	Documentation
LEDGER	Accountant Raccoon	Tokens & Cost
RAVEN	Debug Raven	Debug & Failure Analysis
LUMA	Firefly	Accessibility
NOVA	Star Dragon	Product Story / Positioning

Mascots are rendered from gui/public/arena/mascots.js via node scripts/render-mascots.mjs — same source, two outputs (live arena + static docs).

Note

The .team/ file-based protocol that started this project is preserved — the board, the per-lane logs, the atomic mkdir locks, the green gate, the MCP server and the bash test suite all stay in place. AgentForge specialists each map onto a lane (lead, backend, frontend, quality) via gui/agents.json and write into that lane's log. The original 4-terminal flow now lives directly in the cockpit as well — Atlas is the lead, the others fall into the backend / frontend / quality lanes by role.

Contents

• Quickstart
• Mission Control
• Three ways to talk to the swarm
• Auto-enter
• Persistence
• Spawn-Builder
• Architecture
• Optional Rust accelerator
• Quality and security
• How it compares
• License

How it compares

A fair look at where AgentForge sits among local Claude-agent orchestrators. The AgentForge column reflects what's verifiable in this repo (tests, docs, CI). Competitor cells are from the survey in ROADMAP.md §1 (≈ May 2026) — verify before quoting; star counts and features move.

	AgentForge Command	Ruflo	Octogent	ccpm
Premium web cockpit	✅	◑ chat UI	✅	☐ CLI
Try without a key	✅ harness mode	✅ hosted	☐	☐
Git worktree isolation	✅	✅	✅	✅
Session reattach	✅ honest (no fake)	✅	◑	✅
Playwright E2E	✅	?	?	?
Automated a11y (axe)	✅	?	?	?
Cross-platform CI (3 OS × 3 Node)	✅	?	?	?
Documented threat model + privacy	✅	◑	?	◑
License	MIT	MIT	MIT	MIT
Stars		~31k	~472	~7.9k

We're new and small — the honest pitch isn't "most stars"; it's the most polished local cockpit, with no fake activity, the lowest activation energy (harness mode), and production-grade testing to back the claims. Where we can't verify a competitor's capability we mark it ? rather than guess.

Quickstart

Important

Prerequisites: Bash, Git, the Claude Code CLI, and Node.js 18+. Optional: Rust / Cargo for the forge-pulse accelerator.

git clone https://github.com/BEKO2210/AgentForge-Command
cd AgentForge-Command
npm install     # installs the gui + mcp workspaces from the root
npm start       # → http://localhost:4173/   (Mission Control)

Prefer no local toolchain? Try it in Docker (Harness Mode, no API key):

docker compose up --build      # → http://localhost:4173/

Build details, per-OS prerequisites, the full environment-variable reference, and node-pty troubleshooting live in docs/INSTALL.md.

Optional — build the Rust accelerator (auto-detected on next launch):

cd tools/forge-pulse
cargo build --release

Optional — live LLM briefings:

ANTHROPIC_API_KEY=sk-ant-... node gui/server.js
# Atlas now briefs the swarm through the Anthropic Messages API,
# streaming text deltas and reporting tokens + cost in its own terminal.

Optional — launch a real Claude session per specialist:

In the cockpit, every card has a ▶ launch button. Click it (or open the detail drawer and use the launch control there) — the server starts a PTY for that specialist, pastes its role-specific briefing from gui/agents.json and presses Enter so the session boots into role. Specialists don't autostart, because 12 concurrent claude sessions is rarely what you want. Set AUTOSTART=lead to start just Atlas, or AUTOSTART=all to start everyone.

Three ways to talk to the swarm

	Where	What happens
🪐 Talk to Atlas	Broadcast bar (mode = ATLAS)	Your message goes straight to Atlas Prime via the LLM bridge. Atlas plans, dispatches specialists by name in @<id> form, and integrates their reports. Default mode.
📢 Broadcast to all	Broadcast bar (mode = SWARM)	Raw text is written to every running specialist's PTY simultaneously. Useful for "everyone — state" style nudges.
💬 Talk to one specialist	Detail drawer → Direct message	Open any card's drawer, the chat box at the bottom writes straight into that specialist's PTY. Atlas still sees the result via the mission stream.

Atlas's command center shows his answer large and readable, a workflow stepper (User → Atlas → plan → dispatch → work → reports → summary → done), a Dispatch & reports panel naming every specialist he addressed (honestly flagged running / dispatched / skipped), and a collapsible Technical events panel for tool calls, hooks and raw PTY output — so the answer is never buried.

Prove the workflow (deterministic, no key needed)

cd gui && npm run smoke:atlas        # → _handoff/agentforge-command/WORKFLOW_TEST_REPORT.md
# or the assertion suite:
npm run test:workflow                # agentforge-real-workflow-smoke

Without an API key this runs a TEST HARNESS: a deterministic Atlas that drives the real routing pipeline (parse → dispatch → reports → summary) offline. It never pretends an LLM ran — every event is tagged harness:true and the cockpit shows a TEST HARNESS badge. Set AGENTFORGE_LIVE_TEST=1 ANTHROPIC_API_KEY=sk-ant-... for a real run. A full operator handover lives in _handoff/agentforge-command/.

Mission Control

The default surface (/) is Mission Control. Atlas Prime sits at the top, the swarm below.

• Atlas Prime — Chief Orchestrator (Cyber Turtle). Scans the repo, runs the spawn rules, holds the integration window.
• Sentinel — Risk & Safety (Guardian Owl). Audits gates, blocks unsafe outputs.
• Aurora — Premium UI / Motion (Neon Fox). Visual hierarchy, restrained motion, atmosphere.
• Forge — Build & Release (Forge Mole). CI, deps, release stability.
• Prism — Visualisation & Graphs (Prism Chameleon). Renders agent graphs and tool-call flows.
• Echo — Event Stream & Replay (Signal Bat). Subscribes to hooks, surfaces patterns.
• Vega — Performance & Motion Engine (Neon Hummingbird). FPS, jank, RAF.
• Scribe — Documentation (Scribe Raven). README, tutorials, changelog.
• Ledger — Cost & Tokens (Accountant Raccoon). Budget guardrails, burn rate.
• Raven — Debug & Failure Analysis (Debug Raven). Stack traces, bisects.
• Luma — Accessibility (Firefly). Contrast, ARIA, keyboard flow.
• Nova — Product Story (Star Dragon). Demo arc, positioning.

Each specialist has its own terminal card with:

• An animated SVG mascot that reflects its current state across the full 10-state vocabulary (idle / listening / thinking / typing / working / reading / success / warning / error / celebrating). Every mascot has its own keyframe set, so the same working reads differently on Sentinel (security scan sweep), Forge (anvil sparks), Ledger (spinning coin), Nova (mouth fire), etc. A side-by-side preview lives at /mascot-preview.html.
• Channel callsign (CH·01), role badge, status pill with a pulsing dot.
• Live terminal lines with a blinking cursor and a sweeping activity glow while the agent is busy.
• Confidence / Risk / Evolution mini-bars.
• Per-card ⏎ auto toggle and ★ evolve button.

The broadcast bar at the bottom is how you drive the swarm. In ATLAS mode your message goes to Atlas — through the live LLM bridge if ANTHROPIC_API_KEY is set, otherwise straight into Atlas's real claude PTY (the first message launches it with your text as the mission). In SWARM mode the text is written into every running specialist's PTY. Specialist cards only move when something real happens — a real PTY byte, a hook event or a live LLM stream. Nothing is simulated; an idle swarm stays idle. Press / to focus, Enter to dispatch, Esc to close any drawer.

Auto-enter

„Tell the system once: You can press Enter - and it will do it for you from now on ."

A per-PTY watchdog presses Enter on clear permission prompts so the operator doesn't keep approving them by hand.

Warning

Responsible use. Auto-enter auto-approves permission prompts on your behalf — including tool/command approvals in the agent's session. Only arm it in repositories and tasks you trust, and only for agents you're actively supervising. It's off by default, fires once per prompt with a 1.5 s cooldown, and every fire is announced in the timeline — but it is still you consenting in advance. See SECURITY.md.

Server-side, the watchdog matches a conservative whitelist:

(y/n)   [y/n]   (yes/no)   [yes/no]
press enter to continue   press any key
approve?   approve this?
do you want to ...   are you sure ...   continue?   confirm?
allow this to run   allow this tool to run

When armed, the server presses \r (single fire, 1.5s cooldown so it can't loop on a stuck prompt) and broadcasts an auto-fired note back to the arena so the operator sees exactly when and why it acted.

Arm per agent with the ⏎ auto card toggle, or hit ⏎ Auto · all in the toolbar. The choice is persisted (see below) — turn it off any time.

Tool hooks

The cockpit can be driven authoritatively by Claude Code's native hook system instead of inferring agent state from PTY stdout. The server exposes a single endpoint:

POST /api/hooks            { "agent": "<id>", "event": "<hook>", "tool": "<name>" }

The same payload is accepted as JSON body, application/x-www-form-urlencoded, or a GET query string — pick whichever is easiest from the hook script. The event + tool resolve to one of the 11 activity states (reading, working, thinking, listening, success, warning, idle, …) and propagate to the agent's mascot through the same WebSocket the cockpit already uses.

Every spawned PTY sees AGENTFORGE_AGENT_ID and AGENTFORGE_HOOK_URL in its environment, so the bundled .claude/agentforge-hooks.example.json template drops straight into a project's settings.json and just works.

Persistence

Arena UI state lives at <repo>/.team/arena.json:

{
  "evolution":    { "sentinel": 3, "aurora": 2 },
  "autoEnter":    ["lead", "backend"],
  "customAgents": [ /* operator-defined specialists */ ],
  "atlasMission": ""
}

The file is gitignored: it is runtime state, not a source of truth. Reset it from the UI ("↺ Reset") or by deleting the file.

Spawn-Builder

Atlas's seed roster is 12 specialists. To add more on the fly, click + New agent (or press Alt+N):

• Name, title, role, super-skill
• Mascot (pick one of 12 SVG templates — turtle, owl, fox, mole, chameleon, bat, hummingbird, raven, raccoon, debug-raven, firefly, dragon)
• Accent colour

The new agent appears in the grid immediately, is persisted to arena.json and survives restarts. The mascot library lives in gui/public/arena/mascots.js — drop in another SVG template if you want a new species.

Architecture

gui/server.js                          Node HTTP + WebSocket bridge
  ├── http   /             → Mission Control (default)
  ├── http   /console      → 302 redirect to / (legacy console retired)
  ├── http   /api/agents   → swarm config (no prompts) + leadId
  ├── http   /api/state    → folded .team state
  ├── http   /api/arena    → arena server state (autoEnter, llm, claudeCli, pulse, spend…)
  ├── http   /api/hooks    → Claude Code tool-hook receiver (GET/POST)
  ├── ws     /             → legacy PTY bridge (compat shim)
  └── ws     /arena        → arena protocol (auto-enter, persistence, live)

gui/public/arena/
  ├── arena.html      ← Mission Control shell
  ├── styles.css      ← cockpit theme + per-species mascot animations
  ├── data.js         ← registry (identities, briefings, priors)
  ├── mascots.js      ← 12 SVG mascot templates, 5 evolution levels
  ├── state.js        ← tiny reactive store
  ├── spawner.js      ← swarm registry + live-state engine
  ├── broadcast.js    ← no-op stub (the mock simulator was removed — no fake activity)
  ├── ui.js           ← renderers (hero, lead panel, grid, drawer, modal, timeline)
  └── main.js         ← app entry; ties store, engine, UI, persistence, WS

tools/forge-pulse/    ← OPTIONAL Rust accelerator (see below)
.team/                ← file-based coordination scaffold (unchanged)

Worktree isolation

Each specialist runs in its own git worktree on branch agentforge/<id>, so two specialists can edit the same file in parallel without stomping each other; Atlas (the lead) stays on the shared repo and integrates. Worktrees live under .agentforge/worktrees/<id>/ and are kept after a run for review unless you set AGENTFORGE_WORKTREE_CLEANUP=1. Disable the whole feature with AGENTFORGE_WORKTREES=0 (falls back to the shared repo dir); a non-git repo auto-disables it. Session metadata is persisted to .team/sessions.json, so after a server restart the cockpit surfaces the previous run's sessions as orphaned with a one-click relaunch (PTYs don't survive a restart — no fake reattach).

MCP server

AgentForge ships a read-only MCP server (mcp/server.js) that exposes the .team/ coordination state (board, logs, memory, metrics, folded JSON) plus a read-only swarm_status. Add it to Claude Code:

claude mcp add agentforge -- node mcp/server.js

The launch_specialist / dispatch_goal tools are guidance-only placeholders by design: spawning a PTY or dispatching a goal is a state-changing action that must go through the cockpit's authenticated /arena WebSocket (origin + session token). The read-only MCP process holds no token and must never become an unauthenticated control path — see docs/THREAT_MODEL.md.

Optional Rust accelerator

Most of the runtime is I/O-bound; Node handles it comfortably. The one place that benefits from a tighter implementation is the hot loop that watches every PTY byte for permission prompts and activity changes. As the swarm grows we want that loop to stay sub-millisecond and crash-isolated.

tools/forge-pulse/ is a single-file, zero-dependency Rust binary that does exactly this. The Node server pipes PTY bytes into its stdin and forwards its stdout as {t:"pulse", kind:"prompt"|"activity", …} events to the arena WebSocket. It is purely advisory — Node's JS matcher still drives auto-enter, so removing or skipping the binary changes nothing functionally.

cd tools/forge-pulse
cargo build --release          # produces target/release/forge-pulse
cargo test --release           # 5 unit tests
cargo clippy --release -- -D warnings   # lint clean

Auto-detected by the server on the next start. Set FORGE_PULSE=0 to disable even when present.

Why Rust here and not the rest of the stack? The UI must stay in the browser. The server is I/O-bound — JavaScript is fine for that. But the matcher is in the hot path of every byte coming out of every PTY, and Rust gives us crash isolation, headroom for richer detection (token streams, multi-line context, diff-aware logs) and an easy export point to a remote VM later. It is a contained, well-scoped use of Rust — exactly the way a polyglot stack should grow.

Quality and security

• Tests — bash tests/run.sh runs 165 checks (87 bash against the coordination scripts + 40 arena unit tests for the cockpit modules + 30 server integration tests that boot the real gui/server.js over HTTP + WebSocket — covering the hook receiver, auto-enter scoping, launch failure and corrupt-state recovery + 8 workflow checks that prove the full routing chain). cargo test --release in tools/forge-pulse adds 5 Rust unit tests.
• Lint — bash scripts/team-check.sh (bash -n + shellcheck + tests) and cargo clippy --release -- -D warnings are both clean.
• Concurrency safety — locks are atomic mkdir directories with stale detection (unchanged from the original kit).
• Privacy — everything is local. The server binds to 127.0.0.1. Arena state lives in .team/arena.json and is gitignored. No external trackers, no telemetry, no LLM calls leave the machine unless you wire them yourself.
• Accessibility — focus rings on every interactive element, keyboard shortcuts for the broadcast bar (/), drawer (Esc), and spawn-builder (Alt+N). All animations honour prefers-reduced-motion: reduce.

The .team/ coordination substrate

The original file-based coordination kit lives on underneath the cockpit. The board, role lanes, atomic mkdir locks, the green gate, the MCP server and the team-*.sh scripts in .team/ and scripts/ work exactly as before — Mission Control sits on top of them. (The old 4-agent terminal console UI has been retired; /console now redirects to Mission Control.)

See gui/README.md for the server's own documentation, and .team/PROTOCOL.md for the file-based coordination rules.

Documentation

Doc	What
docs/INSTALL.md	Per-OS setup, Docker, env-var reference
ROADMAP.md	The full Phase 0–6 plan + competitive survey
docs/THREAT_MODEL.md	Trust boundaries, STRIDE, Anthropic policy, fallbacks
SECURITY.md	Disclosure policy + Phase 1–4 audit history
docs/BENCHMARKS.md	Auto-enter matcher benchmark (sub-ms proof)
KNOWN_LIMITS.md	Honest boundaries & trade-offs
PRIVACY.md	Local-first data handling + DSGVO/GDPR
TRADEMARK.md · THIRD_PARTY_NOTICES.md	Legal + license inventory
docs/LAUNCH.md	Launch sequence & checklist

Try without a key: test-harness mode runs the whole cockpit with no Anthropic key — npm install && npm start (or docker compose up --build), then open http://localhost:4173. To record a demo, see docs/demo/.

License

MIT — Copyright © 2026 Belkis Aslani (BEKO2210). Use it freely, including commercially.

Legal

Trademark & non-endorsement. "Claude," "Claude Code," and related marks are trademarks of Anthropic PBC. AgentForge Command is an independent, unofficial community project — not endorsed by, affiliated with, or officially connected to Anthropic. It is provided as-is for educational and experimental use. See TRADEMARK.md.

Privacy / Datenschutz. AgentForge is local-first and ships zero telemetry. See PRIVACY.md (incl. a DSGVO/GDPR note for the DACH region).

Third-party software. Built on open-source components (all permissive licenses). Inventory + SBOM: THIRD_PARTY_NOTICES.md.

Boundaries. Honest limits and trade-offs: KNOWN_LIMITS.md. Security model + reporting: SECURITY.md · docs/THREAT_MODEL.md.