Realm

See your AI agents work. Realm visualizes Claude Code activity in real-time 3D, orchestrates multi-agent tasks, and connects external systems via REST API.

Every tool call animates a character moving through a living workshop. Each session gets its own hexagonal zone. Tasks decompose automatically and route to the right agent. Watch it all unfold in real-time.

What Realm Does

Visualize — Every tool call (read, write, bash, grep) triggers a context-aware animation. Reading files? Walk to the bookshelf. Running tests? The terminal glows. Committing code? Celebrate. Errors? Shake your head.

Orchestrate — Dispatch tasks to multiple Claude Code instances or Claw agents in parallel. An LLM-powered router decomposes natural language into sub-tasks and routes each to the best-fit session automatically.

Connect — External systems (OpenClaw, DingTalk, Feishu, Telegram) push tasks via REST API. Realm routes them, collects results, and fires webhooks when complete.

Requirements

• macOS or Linux (Windows not supported — hooks require bash)
• Node.js 18+
• jq (brew install jq / apt install jq)
• tmux (brew install tmux / apt install tmux)

Quick Start

# 1. Install dependencies
brew install jq tmux

# 2. Configure hooks (once)
npx realm setup

# 3. Start
npx realm

Open http://localhost:4003 and use Claude Code normally. Watch it move through the workshop as it works.

From source:

git clone <this-repo>
cd Realm && npm install && npm run dev

Stations

Features

• Multi-agent zones — Each session gets a hex zone with its own character and workstations
• Real-time 3D animations — Context-aware reactions: celebrates commits, shakes on errors
• Subagent visualization — Mini-characters spawn at the Portal for parallel sub-tasks
• Spatial audio — Synthesized sounds positioned in 3D space (Tone.js, no audio files)
• Activity feed — Live stream of tool calls, responses, and thinking
• Voice input — Speak prompts with real-time transcription (Deepgram API key required)
• Draw mode — Paint hex tiles with colors, 3D stacking, and labels
• Department grouping — Organize zones into departments (Civ-6-style)
• Station panels — Per-workstation history and details
• Attention system — Zones pulse when waiting for input or finishing
• Auto-compact / Auto-continue — Keeps long-running sessions alive
• IM integration — Receive tasks from DingTalk, Feishu, Telegram; send results back

Multi-Agent Orchestration

Dispatch tasks to multiple agents and watch them work in parallel:

1. Click "+ New" (or Alt+N) to create a zone
2. Configure name, directory, agent type, and flags
3. Select a zone (1–6) to target it with prompts
4. Or use POST /dispatch to let the LLM router decide

Each session runs in its own tmux with status tracking (idle / working / offline).

See docs/ORCHESTRATION.md for the full API.

POST /dispatch — External Agent Integration

Realm accepts tasks from external systems and routes them intelligently:

IM Platform → Agent → POST /dispatch (Realm)
                              ↓
                       LLM decomposes task
                              ↓
                   dispatch to matching zones
                              ↓
                  zones work asynchronously
                              ↓
               POST callbackUrl → Agent → IM

Request:

POST /dispatch
{ "message": "...", "callbackUrl": "http://agent/callback", "sessionId": "optional" }

Callback (when all zones complete):

POST callbackUrl
{ "taskGroupId": "abc123", "results": [...], "durationMs": 12000 }

LLM Provider Configuration

Configure in the Settings UI or in ~/.realm/data/settings.json:

{
  "llmProviders": {
    "openrouter": {
      "provider": "custom",
      "apiKey": "sk-or-v1-...",
      "model": "stepfun/step-3.5-flash:free",
      "baseUrl": "https://openrouter.ai/api/v1",
      "maxTokens": 1024
    }
  },
  "defaultProvider": "openrouter"
}

Supported: "anthropic", "openai", "custom" (OpenAI-compatible, e.g. OpenRouter, Ollama).

Keyboard Shortcuts

Draw mode: 1–6 colors · 0 eraser · Q/E brush size · R 3D stack · X clear

CLI

realm [options]
realm setup       # Configure Claude Code hooks
realm uninstall   # Remove hooks (keeps data)
realm doctor      # Diagnose issues

Options:
  --port, -p <port>   Server port (default: 4003)
  --help, -h          Show help
  --version, -v       Show version

Data Directory

Realm stores persistent data in ~/.realm/data/:

Setup Guide

See docs/SETUP.md for detailed installation instructions.

Technical Documentation

See CLAUDE.md for architecture and developer reference.

License

MIT