A visual kanban board for orchestrating multiple Claude Code agents
Spawn, monitor, and interact with AI coding assistants from a single web UI. Manage your autonomous development team through tmux sessions with real-time state tracking and intelligent auto-discovery.

• ✨ Features
• 🚀 Quick Start
• 📱 Remote Access
• 🎯 Usage Guide
• 🏗️ Architecture
• ⚙️ Configuration
• 🔧 Development
• 🐛 Troubleshooting
• 📚 API Reference

• 🚀 Agent Spawning — Create new Claude Code agents with custom prompts and project paths
• 📊 Kanban Board — Visual organization across Running, Idle, and Completed columns
• 🔄 Real-time State Detection — Automatic state tracking via intelligent terminal output parsing
• 🔍 Auto-Discovery — Automatically detects existing Claude tmux sessions and adds them to the board
• 💬 Interactive Messaging — Send follow-up messages and files to running agents
• 📁 Smart Project Management — Save frequently-used projects as tabs for quick access

• 🎨 ANSI Color Support — Full 16/256/24-bit color rendering in terminal output
• 📤 File Uploads — Drag-and-drop or click to send files to agents
• 🔄 Re-spawn — Restart completed agents with new prompts in the same project
• 🔗 Direct Attachment — Copy tmux attach commands for terminal access
• 🌐 Mobile-Friendly — Access and manage agents from your phone via Tailscale
• 🧠 AI-Generated Labels — Automatic label generation using Claude Haiku for better organization
• 📦 Persistent Registry — Agent state persists across server restarts

• N — Open spawn modal
• Enter — Send message (in prompt field)
• Shift+Enter — New line (in prompt field)

You'll need the following installed on your system:

• Node.js v18 or higher
• tmux for session management
• Claude CLI (claude command in PATH)

# Install dependencies via Homebrew
brew install node tmux

# Install Claude Code CLI globally
npm install -g @anthropic-ai/claude-code

node --version    # Should be v18+
tmux -V           # Should show tmux version
claude --version  # Should show Claude CLI version

# Clone the repository
git clone <repo-url>
cd agent-viewer

# Install dependencies
npm install

# Start the server
npm start

Open http://localhost:4200 in your browser.

Access Agent Viewer from any device on your network using Tailscale.

1. Install on your Mac

   brew install tailscale
   # Or download from https://tailscale.com/download

2. Install on your phone

   • iOS App Store
   • Android Google Play

3. Sign in with the same account on both devices

# Start the server (binds to 0.0.0.0 by default)
npm start

Get your Tailscale IP:

tailscale ip

Then visit on your phone:

http://<tailscale-ip>:4200

With MagicDNS (if enabled):

http://<machine-name>:4200

1. Click [+ SPAWN] or press N
2. Enter the project path (or browse with 📁)
3. Write your initial prompt
4. Click SPAWN

The agent launches in a new tmux session and appears on the board.

• Click + to save the current project as a tab
• Click a tab to filter by that project
• When a tab is selected, spawn modal auto-fills that project path

Click the 📁 button in the spawn modal to visually browse your filesystem and select project directories.

Agent Viewer automatically discovers existing tmux sessions running Claude Code and adds them to the board. No manual registration needed!

Agent Viewer is a minimal, framework-free application with a clean two-file architecture:

agent-viewer/
├── server.js              # Express backend (tmux integration, SSE broadcasting)
├── public/
│   ├── index.html         # Frontend (HTML/CSS/JS in one file)
│   ├── prompt-key-utils.js
│   └── expanded-card-utils.js
├── .agent-registry.json   # Persistent agent state
└── .project-tabs.json     # Saved project tabs

Core Systems:

• Agent Registry — In-memory state + JSON persistence
• State Detection — Polls tmux output every 3s to classify agent states
• Tmux Integration — Spawns sessions, captures output, sends input
• Auto-Discovery — Scans tmux sessions and detects Claude processes
• LLM Label Generation — Async Claude Haiku calls for smart labeling
• SSE Broadcasting — Real-time state updates to all clients

State Detection Logic:

Agents are classified by pattern-matching terminal output:

• Running — "esc to interrupt" prompt visible
• Idle — Empty prompt or permission requests
• Completed — Session exited or specific completion signals

• Vanilla JavaScript — No frameworks, no build step
• SSE-Driven Updates — Real-time state synchronization
• ANSI Converter — Full 16/256/24-bit color support
• Drag-and-Drop — For card reordering and file uploads
• Terminal Aesthetic — Dark, modern UI inspired by CLI tools

Custom port:

PORT=3000 npm start

Localhost only:

HOST=127.0.0.1 npm start

Multiple settings:

HOST=0.0.0.0 PORT=8080 POLL_INTERVAL=5000 npm start

agent-viewer/
├── server.js              # Main backend (Express + tmux integration)
├── public/
│   ├── index.html         # Complete frontend app
│   ├── prompt-key-utils.js       # Keyboard handling utilities
│   └── expanded-card-utils.js    # Card state management
├── test/
│   └── ansi-test.html     # ANSI color rendering tests
├── docs/
│   └── architecture.html  # Visual architecture diagram
├── .agent-registry.json   # Auto-generated agent state
├── .project-tabs.json     # Auto-generated saved tabs
├── CLAUDE.md             # Claude Code integration guide
└── package.json

This project runs directly with Node.js:

• No transpilation
• No bundling
• No compilation

Just edit and refresh!

• Shell escaping — Single quotes: message.replace(/'/g, "'\\''")
• Async commands — All external commands use exec() with timeouts (never execSync())
• Session naming — Format: agent-{label} (lowercase, hyphenated)
• Manual parsing — Multipart file uploads parsed without libraries
• Interactive handling — waitForClaudeReady() auto-dismisses Claude startup prompts

Problem: Agent doesn't appear on the board after clicking SPAWN

Solutions:

• Verify claude is in your PATH: which claude
• Check tmux is installed: tmux -V
• Ensure project path exists and is accessible
• Check server logs for errors

Problem: Terminal output is blank or not updating

Solutions:

• Wait 3 seconds for next state detection cycle
• Check if tmux session exists: tmux ls
• Try clicking VIEW OUTPUT instead of EXPAND
• Verify agent is actually running: tmux attach -t agent-<label>

Problem: Existing Claude tmux sessions not appearing

Solutions:

• Ensure tmux session contains a Claude process
• Restart the server to trigger fresh discovery
• Check .agent-registry.json for corrupted data

Problem: Tailscale IP not accessible

Solutions:

• Verify server started with HOST=0.0.0.0
• Check Tailscale is running on both devices: tailscale status
• Use IP address instead of MagicDNS name
• Ensure no firewall blocking port 4200

Enable verbose logging:

DEBUG=* npm start

View tmux sessions:

tmux ls

Attach to agent directly:

tmux attach -t agent-<label>

Spawn Agent:

curl -X POST http://localhost:4200/api/agents \
  -H "Content-Type: application/json" \
  -d '{
    "projectPath": "/path/to/project",
    "prompt": "Implement user authentication"
  }'

Send Message:

curl -X POST http://localhost:4200/api/agents/my-agent/send \
  -H "Content-Type: application/json" \
  -d '{"message": "Add unit tests"}'

Upload File:

curl -X POST http://localhost:4200/api/agents/my-agent/upload \
  -F "files=@./config.json"

See repository for license information.

Contributions are welcome! This is a minimal project by design:

• Keep it simple
• No frameworks or build tools
• Maintain the single-file frontend approach

Built with:

• Express — Web framework
• tmux — Terminal multiplexer
• Claude Code — AI coding assistant

Made with ❤️ for developers managing multiple AI agents