GitHub - thomasrice/arcane-agents: Local-first visual control room for terminal-backed AI coding agents. Manage Claude Code, OpenCode, or any CLI agent as characters on a 2D map with live terminal streaming.

Arcane Agents gives each local agent a place on a shared map and keeps its real terminal one click away. Spawn a team, see who is working or waiting for input, organise agents into control groups, broadcast a command, and jump directly into the terminal that needs you.

Local-first: Arcane Agents has no hosted backend or Arcane account. Worker state lives in SQLite, processes live in a dedicated tmux server, and terminal traffic stays between your browser and your machine.

Quick start · Feature tour · Keyboard controls · Configuration · Development

Why Arcane Agents?

Feature tour

Visual agent control room

• Pixel-art agents inhabit a depth-aware 2D map with animated movement, labels, effects, scenery occlusion, and selectable character packs.
• Select one agent, Shift-click several, or draw a marquee around a group.
• Move selected agents with held W/A/S/D or the arrow keys; the camera follows near the map edge.
• Right-click a destination to send selected agents there, right-drag to pan, and use + / - to zoom.
• Switch agents from the map or roster, jump directly to a known Character by name with G, work through a stable keyboard review queue, cycle idle workers, and jump through populated control groups.
• Resize the map and terminal split by dragging the divider or using keyboard controls.

Real terminals, not simulated chat panels

• Each worker is a tmux window driven through node-pty and streamed over WebSockets.
• The embedded xterm.js terminal supports normal interactive programs, colour, resize, mouse input, and low-latency typing.
• Open the selected worker in an external terminal on supported Linux desktops.
• Browser reconnects do not kill the underlying process; Arcane reconciles persisted worker state with tmux.
• Drag-select terminal text to copy it to the clipboard of the computer viewing Arcane Agents—even when the server runs on another machine.

Fast spawning and project discovery

• Save project + runtime shortcuts as buttons and assign configurable hotkeys.
• Open the / command palette to search shortcuts and every available project/runtime combination.
• Spawn a custom project/runtime pair from the + dialog.
• Batch-spawn a named team from a multiline list; duplicate names are numbered automatically.
• Discover projects from directories, glob patterns, or Git worktrees instead of listing every checkout manually.
• Spawn new workers near a selected group so related agents begin together on the map.

Control groups and team commands

• Assign any selection to groups 1–0, select a group instantly, and cycle populated groups forwards or backwards.
• Open a group page, move through members with J/K or Tab, and focus any member's terminal.
• Send one rally command to every selected agent; $NAME expands to each agent's display name.
• Rename an individual or a whole group, silence background characters, scatter grouped characters, change movement mode, respawn stopped agents, or kill selected workers.

Status, attention, and completion

• Dedicated runtime adapters understand current Claude Code, Codex, OpenCode, and Oh My Pi terminal states, with a generic fallback for other commands.
• Arcane distinguishes active work from an idle prompt, native approvals, questions that need an answer, runtime errors, and stopped processes.
• Claude transcript correlation and live pane signals reduce false working/idle transitions in long-lived sessions.
• Completed but unreviewed agents receive a READY badge, making finished work easy to scan.
• Press Space to start a review session containing every agent currently ready or needing input. The queue keeps handled agents available for backwards navigation, appends newly ready agents, and resets after manual selection, deselection, or Esc.
• Optional character voice lines and sound effects announce arrival, movement, attention, completion, and death.
• Silenced characters remain visible and interactive, including their current work actions, but do not enter attention/completion notification flows or play their automatic attention/completion voice lines.
• Transition history, evaluation facts, flap counts, and exportable status fixtures make incorrect classifications reproducible.

Local state and independent sessions

• SQLite stores workers, positions, names, groups, and state locally.
• Arcane uses its own configurable tmux socket and session, leaving your normal tmux setup untouched.
• Named Arcane sessions provide independent worker databases and tmux parties while sharing one configuration.
• The server can bind to a LAN or private VPN interface for access from another computer; see Network access and security before enabling it.

More screenshots

Quick start

Requirements

• Node.js 20 or newer and npm
• tmux
• At least one terminal runtime command, such as claude, codex, opencode, omp, or bash
• Optional: git for project/worktree discovery and xdg-terminal-exec for the Linux external-terminal button

Install

npm install -g arcane-agents
arcane-agents setup
arcane-agents

arcane-agents setup checks for tmux, offers the appropriate installation command after confirmation, creates a starter configuration when needed, and runs the built-in doctor checks.

Open http://127.0.0.1:7600.

Edit the generated configuration at any time:

arcane-agents config edit

Useful maintenance commands:

npm install -g arcane-agents@latest  # upgrade
npm uninstall -g arcane-agents       # uninstall

Platform notes

If installing tmux manually:

# Debian / Ubuntu / WSL2
sudo apt install tmux

# macOS with Homebrew
brew install tmux

How it works

flowchart LR
    B[React control room] <-->|HTTP + WebSocket| S[Arcane server]
    S <-->|PTY stream| P[node-pty]
    P <-->|attach + input| T[Dedicated tmux server]
    T --> C[Claude Code]
    T --> X[Codex / OpenCode / OMP]
    T --> R[Shells and custom runtimes]
    S <--> D[(Local SQLite state)]

The browser owns the visual control room and terminal viewer. The server owns orchestration, persistence, tmux reconciliation, process inspection, and status decisions. The agents themselves remain ordinary terminal programs.

Everyday workflow

1. Add projects, runtimes, and favourite launch shortcuts to the YAML configuration.
2. Spawn an agent from the bottom bar, command palette, custom dialog, or batch-spawn flow.
3. Select its character to attach the live terminal; press Enter to focus terminal input.
4. Leave terminal focus with the configured chord (default Ctrl+Alt+]) and move around the roster or map.
5. Group related agents with Ctrl+1–0, then select the group with 1–0 and broadcast a rally command.
6. Watch status nameplates and the roster. Open agents marked READY to review completed work.

Keyboard controls

Press ? in Arcane Agents for the live shortcut reference. The panel is generated from the same registry that handles the keys, so the displayed controls stay in sync with the application.

Selection and groups

The first Space snapshots every agent currently ready for review or needing input; the first Shift+Space starts from the end of that snapshot. Acknowledging an agent does not remove it from the session, and newly ready agents are appended. Manual selection, deselection, or Esc ends the session, so the next Space gesture builds a fresh queue.

Movement and layout

Agent actions and overlays

Configuration

Configuration is loaded at server startup in this order:

1. Built-in defaults
2. ~/.config/arcane-agents/config.yaml
3. ~/.config/arcane-agents/config.local.yaml

The local override is useful for machine-specific paths or commands you do not want in a shared dotfiles repository. Restart the server after changing configuration.

arcane-agents config path  # print config and local override paths
arcane-agents config show  # print the primary YAML file
arcane-agents config edit  # open the primary file in $VISUAL or $EDITOR
arcane-agents doctor       # check the local environment

Generic example

projects:
  app:
    path: ~/code/my-app
    shortName: app
    label: Example App
  docs:
    path: ~/code/product-docs
    shortName: docs
    label: Product Docs

runtimes:
  claude:
    command: ["claude"]
    label: Claude Code
  codex:
    command: ["codex"]
    label: Codex
  opencode:
    command: ["opencode"]
    label: OpenCode
  omp:
    command: ["omp"]
    label: Oh My Pi
  shell:
    command: ["bash"]
    label: Shell

shortcuts:
  - label: App Claude
    project: app
    runtime: claude
    hotkeys: ["Ctrl+1"]
    avatar: elder-wizard
  - label: App Codex
    project: app
    runtime: codex
    hotkeys: ["Ctrl+2"]
  - label: Docs Shell
    project: docs
    runtime: shell
    hotkeys: ["Ctrl+3"]

A complete starter file is available at config.example.yaml.

projects:
  app:
    path: ~/code/my-app
    shortName: app
    label: Example App

runtimes:
  pipeline:
    command: ["bin/run-pipeline"]
    label: Pipeline
    freshnessWindowMs: 60000

shortcuts:
  - label: Tests
    project: app
    runtime: shell
    command: ["npm", "test", "--", "--watch"]
    hotkeys: ["Ctrl+T"]
    avatar: elder-wizard

keybindings:
  leaveTerminalFocus: ["Ctrl+Alt+]"]

discovery:
  - name: code-projects
    type: directories
    path: ~/code
    match: ".git"
    exclude: ["node_modules", ".cache", "dist"]
    maxDepth: 2
  - name: app-worktrees
    type: worktrees
    path: ~/code/my-app
  - name: playgrounds
    type: glob
    path: ~/code/playground/*

status:
  extraInteractiveCommands:
    - my-custom-editor

status:
  rules:
    - id: polling-worker-waiting
      match:
        runtimeId: shell
        command: '^python3$'
        lastLine: '^No work for [^;]+; checking again in [0-9]+s\.$'
      set:
        status: idle

backend:
  tmux:
    socketName: arcane-agents
    sessionName: arcane-agents
    pollIntervalMs: 2500

audio:
  enableSound: true

avatars:
  disabled:
    - gothic-witch

server:
  host: 127.0.0.1
  port: 7600

Named sessions

Named sessions run independent Arcane instances with separate SQLite databases and tmux sessions while sharing projects, runtimes, shortcuts, and other configuration.

arcane-agents start                         # default session
arcane-agents start --session side-project  # named session
arcane-agents start -s experiments
arcane-agents sessions list
arcane-agents sessions delete side-project

The default database lives at ~/.local/state/arcane-agents/arcane-agents.db. Named databases live under ~/.local/state/arcane-agents/sessions/<name>/arcane-agents.db.

Network access and security

To bind the built app to every network interface:

ARCANE_AGENTS_API_HOST=0.0.0.0 npm run start

For development access from another machine:

npm run dev -- --host
npm run dev -- --host --allow-host your-private-hostname

You can also bind Vite to a specific private interface with npm run dev -- --host 192.168.1.42.

Development

git clone https://github.com/thomasrice/arcane-agents.git
cd arcane-agents
npm install
npm run cli -- setup
npm run dev

Development URLs:

• Vite app: http://127.0.0.1:7600
• Express API: http://127.0.0.1:7601

Quality and build commands:

npm run typecheck
npm run lint
npm run test:ci
npm run build
npm start

The production app defaults to http://127.0.0.1:7600. Health endpoints are available at /api/health on the relevant server port.

Status debugging

Set ARCANE_AGENTS_STATUS_TRACE=transitions to log status changes or ARCANE_AGENTS_STATUS_TRACE=verbose to log every evaluation.

ARCANE_AGENTS_STATUS_TRACE=transitions npm run dev:server

Debug endpoints:

• GET /api/status-debug — all workers, including transition flap counts
• GET /api/workers/:workerId/status-debug — recent evaluations and decision facts
• GET /api/workers/:workerId/status-history — status transition history
• GET /api/workers/:workerId/status-fixture — export the current or a recent transition as a reproducible integration-test fixture

Project layout

src/
  client/   React UI, map runtime, render layers, xterm terminal
  server/   API, orchestration, tmux, persistence, status monitor
  shared/   Shared types and configuration models
assets/     Maps, character sprites, and optional voice lines

Custom avatars

Avatar packs are directory-driven under assets/characters/<avatar-type>/. The required sprite files are documented in assets/characters/README.md; a compliant folder becomes available automatically.

Optional voice clips live in assets/characters/<avatar-type>/voice-lines/. Fixed events use arrive.mp3, attention.mp3, complete.mp3, and death.mp3; random variants match move*.mp3 and selected*.mp3.

Demo

Watch the original demo on YouTube →

Stack

TypeScript · React · Vite · Express · WebSockets · xterm.js · node-pty · tmux · SQLite

License

Arcane Agents is available under the MIT License.