Installation
Get Agent Cockpit running locally in under 5 minutes. You'll need a working Claude Code or Codex CLI installation — the Cockpit is the UI layer on top.
Prerequisites
Before you start:
- Node 22+ —
node --version should print v22 or above - pnpm 8+ — install via
npm install -g pnpm - Claude Code CLI — installed and authenticated (see below)
- Or: Codex CLI — installed and authenticated (see below)
Install Claude Code
MAC / LINUX# Shell installer
$ curl -fsSL https://claude.ai/install.sh | bash
# Authenticate
$ claude auth login
WINDOWS# PowerShell installer
> irm https://claude.ai/install.ps1 | iex
# Authenticate
> claude auth login
Install Codex optional
ALL OS$ npm install -g @openai/codex
# Set your API key
$ export OPENAI_API_KEY=sk-... # Mac / Linux
> $env:OPENAI_API_KEY = "sk-..." # Windows PowerShell
$ codex --version
NOTE
Agent Cockpit does not manage your API keys. Claude Code and Codex must be authenticated in your shell environment before launching sessions.
Clone and install
BASH# Clone the repository
$ git clone https://github.com/agent-cockpit/agent-cockpit.git
$ cd agent-cockpit
# Install all workspace dependencies
$ pnpm install
Start the development server
You need two terminals — one for the daemon, one for the UI.
TERMINAL 1 — DAEMON# Listens on port 3002 (Claude Code hooks) and 3001 (WebSocket)
$ pnpm --filter @cockpit/daemon dev
TERMINAL 2 — UI# Vite dev server at http://localhost:5173
$ pnpm --filter @cockpit/ui dev
Open http://localhost:5173 in your browser. You'll land on the office map. No agents are running yet — hit + LAUNCH in the top bar to create your first session.
TIP
Press
⌘Kfrom anywhere in the UI to open the command palette. It's the fastest way to launch sessions, jump between agents, and trigger approvals.
Project structure
TREEagent-cockpit/
├── daemon/ # Node.js session manager + WebSocket server
│ ├── src/
│ └── package.json
├── ui/ # React + Vite browser app
│ ├── src/
│ │ ├── components/
│ │ ├── game/ # Canvas game engine
│ │ ├── pages/
│ │ └── store/
│ └── package.json
└── pnpm-workspace.yaml
Configuration
Agent Cockpit uses a .env file in ui/ and an optional daemon config. All settings have sensible defaults.
UI environment variables
Create or edit ui/.env:
ENV# URL of the local daemon. Default: http://localhost:3000
VITE_DAEMON_URL=http://localhost:3000
# WebSocket URL for live session events. Default: ws://localhost:3000
VITE_WS_URL=ws://localhost:3000
Daemon environment variables
Create or edit daemon/.env:
ENV# Port for HTTP + WebSocket. Default: 3000
PORT=3000
# Max concurrent sessions. Default: 20
MAX_SESSIONS=20
# Working directory browsing root (for the BROWSE picker)
BROWSE_ROOT=/Users/you
All config options
| KEY | DEFAULT | DESCRIPTION |
|---|
VITE_DAEMON_URL | http://localhost:3000 | Daemon HTTP base URL used for REST calls |
VITE_WS_URL | ws://localhost:3000 | WebSocket endpoint for event streaming |
PORT | 3000 | Daemon listen port |
MAX_SESSIONS | 20 | Hard cap on simultaneous live sessions |
BROWSE_ROOT | ~ | Root path for the workspace file browser |
Session management
A session is a single running agent process tied to a workspace directory and a provider. You can run many simultaneously.
Launching a session
Click + LAUNCH in the top bar, or press ⌘K and type "launch". The launch modal asks for:
- Provider — CLAUDE or CODEX
- Workspace path — the directory the agent will work in. Use the BROWSE button to navigate your filesystem.
- Pilot — which pixel character represents this session on the map. Pure cosmetic.
Session lifecycle
| STATE | INDICATOR | MEANING |
|---|
active | green LED | Agent process running, accepting tasks |
waiting | amber LED | Agent paused pending approval |
error | red LED | Process crashed or rejected credentials |
ended | grey LED | Task completed or manually terminated |
Terminating a session
Open the session's instrument window and click TERMINATE in the header, or use the right-click context menu on the agent's chip in the top bar. Termination sends a SIGTERM to the agent process and marks the session as ended.
WARNING
Terminating a session that has an active file write in progress may leave files in a partial state. Check the Diff panel before terminating.
Session history
All sessions (live and ended) appear in the Session Archive. Open it via ⌘K → "archive" or the HISTORY button in the top bar. From here you can:
- Filter by provider, status, workspace, or date
- Resume a session if the process is still alive
- View the read-only timeline and diff for ended sessions
- Export session data as JSON (⌘E)
Approval workflow
When an agent wants to run a shell command, write a file, or make a network request, it must ask for permission. Agent Cockpit surfaces these requests as approval cards sorted by risk.
Risk levels
| LEVEL | COLOUR | EXAMPLE OPERATIONS |
|---|
HIGH | ● Red | Shell commands, rm, chmod, network writes, credential access |
MED | ● Amber | File edits, dependency installs, git commits |
LOW | ● Green | Read operations, documentation fetches, local path lookups |
Reviewing an approval
When an agent requests approval, an amber balloon appears above its character on the map. Click the balloon or the session chip in the top bar to open the instrument window, which defaults to the Approvals tab.
Each card shows:
- Risk rail — coloured left column (RED / AMBER / GREEN)
- Tool kind — SHELL, EDIT, READ, FETCH, etc.
- Description — what the agent wants to do, with inline code where relevant
- Diff preview — for EDIT requests, shows the proposed change
Keyboard-first approvals
When the Approvals tab is focused you can act without touching the mouse:
| KEY | ACTION |
|---|
| A | Allow the focused request and advance to next |
| D | Deny the focused request and advance to next |
| E | Open the Edit dialog to modify the request before allowing |
| ↓ / ↑ | Navigate between pending requests |
| AA | Allow all LOW-risk items in the queue at once |
PRO TIP
During a long session, keep the Approvals tab open in a pinned window. The amber glow on the window header pulses when new items land — you'll catch them peripherally without interrupting your focus.
Provider guide
Agent Cockpit supports two providers today. Each has different strengths — you can run both simultaneously in the same session list.
CLAUDE — Claude Code
Anthropic's Claude Code agent. Strong for large, context-heavy tasks: multi-file refactors, understanding legacy codebases, writing architecture docs alongside code, and anything where a long conversation thread helps.
Setup
MAC / LINUX# Shell installer
$ curl -fsSL https://claude.ai/install.sh | bash
# Authenticate (opens browser)
$ claude auth login
# Verify
$ claude --version
WINDOWS# PowerShell installer
> irm https://claude.ai/install.ps1 | iex
# Authenticate (opens browser)
> claude auth login
# Verify
> claude --version
Claude Code sessions show an orange left-edge stripe in every chip and window.
CODEX — OpenAI Codex
OpenAI's Codex agent. Optimised for fast, surgical edits: targeted bug fixes, test generation, docstring writing, and cases where you want a quick patch without a long planning phase.
Setup
BASH# Install Codex CLI
$ npm install -g @openai/codex
# Set your API key
$ export OPENAI_API_KEY=sk-...
# Verify
$ codex --version
Codex sessions show a purple left-edge stripe in every chip and window.
Choosing between providers
| TASK | RECOMMENDED |
|---|
| Large multi-file refactor | CLAUDE |
| Fix a specific failing test | CODEX |
| Write architecture documentation | CLAUDE |
| Generate JSDoc for a module | CODEX |
| Explore and understand a new codebase | CLAUDE |
| Apply a mechanical rename across files | CODEX |
| Debug a complex race condition | CLAUDE |
Keyboard shortcuts
Agent Cockpit is designed to be keyboard-first. Every critical action has a shortcut so you can manage 10+ agents without touching the mouse.
Global
| SHORTCUT | ACTION |
|---|
| ⌘K | Open command palette — jump to any agent, panel, or action |
| Esc | Close top-most overlay. Never closes the map. |
| ⌥1–⌥9 | Focus the nth open instrument window |
| ⌘M | Minimize focused window to taskbar |
| ⌘L | Open Launch Session modal |
| ⌘H | Open Session Archive / History |
| ⌘T | Toggle tacmap radar |
Instrument windows
| SHORTCUT | ACTION |
|---|
| ⌥A | Switch focused window to Approvals tab |
| ⌥C | Switch focused window to Chat tab |
| ⌥T | Switch focused window to Timeline tab |
| ⌥D | Switch focused window to Diff tab |
| Double-click header | Maximize / restore window |
| Drag header | Reposition window |
| Drag bottom-right corner | Resize window |
Approvals tab
| SHORTCUT | ACTION |
|---|
| A | Allow focused request, advance queue |
| D | Deny focused request, advance queue |
| E | Edit request before allowing |
| ↓ / ↑ | Navigate pending requests |
| AA | Allow all LOW-risk items at once |
Game map
| SHORTCUT | ACTION |
|---|
| WASD / arrows | Move player character |
| Shift + move | Sprint |
| E | Interact with nearest agent NPC |
| Esc | Open game menu (when no overlay is open) |
API / Daemon reference
The daemon exposes a REST API for session management and a WebSocket for real-time event streaming. All endpoints are local — nothing leaves your machine.
Base URL
ENVhttp://localhost:3000
REST endpoints
Sessions
| METHOD | PATH | DESCRIPTION |
|---|
GET | /api/sessions | List all sessions (live + history) |
POST | /api/sessions | Launch a new session. Body: {provider, workspacePath} |
DELETE | /api/sessions/:id | Terminate session by ID |
GET | /api/sessions/:id/events | Fetch event log for a session |
Approvals
| METHOD | PATH | DESCRIPTION |
|---|
GET | /api/approvals | List all pending approvals across sessions |
POST | /api/approvals/:id/allow | Allow a pending request |
POST | /api/approvals/:id/deny | Deny a pending request |
POST | /api/approvals/:id/edit | Allow with modified payload. Body: {patch} |
Filesystem browser
| METHOD | PATH | DESCRIPTION |
|---|
GET | /api/browse?path=... | List subdirectories at path. Returns {path, parent, entries} |
WebSocket events
Connect to ws://localhost:3000. The server streams JSON messages:
JSON// Session status update
{ "type": "session_update", "sessionId": "abc123", "status": "active" }
// New approval request
{ "type": "approval_request", "sessionId": "abc123",
"approvalId": "req_456", "risk": "high", "tool": "bash" }
Contributing
Agent Cockpit is MIT-licensed and welcomes contributions. Here's how to get involved without stepping on each other's toes.
Before you start
- Check the open issues — especially ones labelled
good first issue - For significant changes, open an issue first to discuss the approach
- All PRs need passing tests:
pnpm test from the repo root
Development workflow
BASH# Fork and clone
$ git clone https://github.com/YOUR_FORK/agent-cockpit.git
$ cd agent-cockpit && pnpm install
# Create a branch
$ git checkout -b feat/your-feature
# Start dev server
$ pnpm dev
# Run tests (watch mode)
$ pnpm test --watch
Project conventions
- TypeScript everywhere — no
any unless absolutely necessary - Component files < 300 lines — split if larger
- Tailwind + CSS variables — use existing tokens, don't invent new colours
- Radix UI for overlays — dialogs, dropdowns, and tooltips use Radix for accessibility
- Redux Toolkit for state — all async side-effects go in thunks or middleware, not components
- Canvas game engine is isolated — avoid importing game code into UI components
Commit style
BASHfeat(ui): add floating instrument windows
fix(daemon): handle SIGTERM on session terminate
docs: add keyboard shortcuts reference
refactor(game): extract NPC pathfinding into own module
TIP
Phases in commit messages (
Phase 30:) are for internal tracking only. You don't need to use them in your PR.
Opening a PR
- Make sure
pnpm test passes - Add or update tests for new behaviour
- Write a clear PR description: what, why, and any screenshots for UI changes
- Reference any related issues with
Fixes #123
Changelog / Roadmap
What shipped, what's in progress, and what's coming next.
Released
v0.1.0-alphaApril 2026SHIPPED
- RPG office map with pixel-art characters (ninja, astronaut, robot, pirate, alien, ghost, hologram, caveman, monkey, medicine-woman)
- Game engine: tilemap renderer, NPC pathfinding + behavior, camera, collision map
- Daemon WebSocket bridge — real-time session events streamed to UI
- Session launch / terminate with Claude Code and Codex CLI
- Instrument panels: Approvals, Chat, Timeline, Diff, Memory, Artifacts
- Approval risk levels (HIGH / MED / LOW) with keyboard A / D / E shortcuts
- Provider accent colours (Claude orange, Codex purple) on all UI surfaces
- Mini-map radar with live agent positions
- Session archive / history page with search and filters
- Audio system: ambient music, SFX for approvals, footsteps, UI events
In progress
v0.2.0Q2 2026IN PROGRESS
- New map — larger world with biomes, workspace-specific zones, ambient NPCs
- Web UI redesign — floating instrument windows, command palette (⌘K), dense top bar
- Taskbar for minimized agent windows
- Draggable + resizable instrument windows (multi-open)
Planned
v0.3.0Q3 2026PLANNED
- Multi-workspace grouping in session chips
- Session compare — diff two sessions' output side-by-side
- Diff archive and export (
pnpm export-diffs) - Agent-to-agent messaging
v1.0.0TBDFUTURE
- Remote daemon support (SSH tunnel or hosted)
- Team multiplayer map (multiple humans in the same office)
- Plugin API for custom panels and providers
- Gemini CLI and additional provider support