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.
 |
 |
| Sentinel specialist drawer | Ledger drawer · spend + forecast |
 |
 |
| Spawn-Builder modal · Alt+N | Mobile · stacked layout |
| 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.jsvianode 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.
- Quickstart
- Mission Control
- Three ways to talk to the swarm
- Auto-enter
- Persistence
- Spawn-Builder
- Architecture
- Optional Rust accelerator
- Quality and security
- License
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
cd gui && npm install && cd ..
node gui/server.js
# open http://localhost:4173/ → Mission ControlOptional — build the Rust accelerator (auto-detected on next launch):
cd tools/forge-pulse
cargo build --releaseOptional — 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.
| 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. |
The mission stream in Atlas's panel shows every specialist's report back to him — colour-coded by kind so you can scan it at a glance.
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 sameworkingreads 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 dispatches a briefing to the entire swarm.
Atlas appends to its own terminal, every specialist transitions through
thinking → working → success → idle and responds with a role-flavoured log
line. Press / to focus, Enter to dispatch, Esc to close any drawer.
„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.
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.
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.
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.
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.
gui/server.js Node HTTP + WebSocket bridge
├── http / → Mission Control (default)
├── http /console → Legacy 4-agent console
├── http /api/agents → PTY config
├── http /api/state → folded .team state
├── http /api/arena → arena server state
├── ws / → PTY bridge (xterm-style terminals)
└── 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 + briefings + spawn rules
├── mascots.js ← 12 SVG mascot templates, 5 evolution levels
├── state.js ← tiny reactive store
├── spawner.js ← Atlas's rule-based spawn engine
├── broadcast.js ← broadcast simulator (state machine per agent)
├── 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)
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 cleanAuto-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.
- Tests —
bash tests/run.shruns 147 checks (87 bash against the coordination scripts + 40 arena unit tests for the cockpit modules + 20 server integration tests that boot the realgui/server.jsover HTTP + WebSocket).cargo test --releaseintools/forge-pulseadds 5 Rust unit tests. - Lint —
bash scripts/team-check.sh(bash -n+shellcheck+ tests) andcargo clippy --release -- -D warningsare both clean. - Concurrency safety — locks are atomic
mkdirdirectories 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.jsonand 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 honourprefers-reduced-motion: reduce.
The original 4-agent coordination kit is preserved unchanged at
/console. The board, role lanes, locks,
green gate, MCP server and team-*.sh scripts in .team/ and
scripts/ work exactly as before — they are the substrate
Mission Control sits on top of.
See gui/README.md for the console's own documentation, and
.team/PROTOCOL.md for the file-based coordination
rules.
MIT — Copyright © 2026 Belkis Aslani (BEKO2210). Use it freely, including commercially.