How It Works • Features • Getting Started • Environment Variables • Tests • Contributing
A drag-and-drop Kanban board that delegates coding tasks to AI agents — GitHub Copilot, Claude Code, OpenAI Codex, or OpenCode. Drop a task into "In Progress," pick an agent, and it will plan, execute, and complete the work, streaming live progress back to the board.
- Create a task in the Backlog column
- Drag it to In Progress — the agent panel opens automatically
- Configure the run — set the repo path, branch name, agent type, and whether to use a git worktree
- Click Start Agent — the selected agent begins working, streaming progress in real-time
- Review the results — commands executed, files modified, output produced
- Merge or create a PR — merge the branch to main locally, or create a PR if the repo has a GitHub remote
The server uses a provider pattern (via @codewithdan/agent-sdk-core) to support multiple AI coding agents behind a common interface:
AgentProvider— creates sessions, reports availabilityAgentSession— runs a task, emits events, supports abortAgentManager— orchestrates sessions with timeouts, event caching, and graceful cleanup
Each task can specify which agent to use. Available agents are auto-detected at startup by checking for installed CLIs. Four providers are supported: Copilot, Claude Code, Codex, and OpenCode. Events from all providers are normalized into a common AgentEvent format and streamed to the UI via WebSocket.
For projects needing multiple parallel changes, Task Groups let you define a batch of related tasks in a single form:
- Click New Group (or press
G) to open the group creation dialog - Set group-level config: title, repo path, base branch, priority
- Add child tasks (2–20), each with its own title, description, agent type, and worktree toggle
- Set parallelism with a slider (1 to N) — controls how many agents run concurrently
- Click Create & Run to launch immediately, or Create Group to add to backlog
Groups appear as a single card on the board showing aggregate progress. Click to expand the Group Panel with per-child status, retry buttons for failures, and drill-through to individual agent panels. Groups auto-advance to "review" when all children complete successfully.
- Kanban board with Backlog, In Progress, Review, Done columns
- Multi-agent support — choose GitHub Copilot, Claude Code, OpenAI Codex, or OpenCode per task
- Auto-detection of available agents at startup
- Drag-and-drop task management with transition validation
- Real-time agent activity streaming via WebSocket
- Terminal-style event viewer (xterm.js) with ANSI color support
- Agent panel with event coalescing (thinking, commands, output)
- Git worktree isolation per task (optional)
- Local merge or PR — merge worktree branch to main locally, or create a PR if a GitHub remote exists (auto-detected)
- Worktree auto-cleanup after merge, PR creation, or archival
- Dual database backends — SQLite (zero-config default) or PostgreSQL
- Task templates for reusable task configurations
- Task Groups — define multiple related tasks in one form, launch with configurable parallelism (slider 1..N), monitor aggregate progress
- Auto-run option to start agent immediately on task creation
- Priority levels (critical, high, medium, low) with emoji indicators and color-coded borders
- Filter and sort tasks by agent type, status, and priority
- API key authentication (optional — set
API_KEYenv var) - Task archiving
- Dark/light theme toggle
- Task search and filtering
- Keyboard shortcuts (N: new task, G: new group, Esc: close panels)
- Node.js 22+
- npm 10+
- At least one agent CLI authenticated on your machine:
- GitHub Copilot: CLI installed and authenticated
- Claude Code: CLI installed and authenticated
- OpenAI Codex: CLI installed and authenticated
- OpenCode: CLI installed and authenticated
Works on Linux, macOS, and Windows.
git clone https://github.com/DanWahlin/ai-agent-board.git
cd ai-agent-board
npm install
# Start both server and client together
npm run dev
# Or run them separately:
# Terminal 1 — API server (port 8080)
npm run dev:server
# Terminal 2 — Vite dev server (port 8081)
npm run dev:clientOpen http://localhost:8081.
By default the app uses SQLite — zero configuration required.
For PostgreSQL, start the database container and set DATABASE_URL:
docker compose up -d
# Set the connection string in packages/server/.env
DATABASE_URL=postgresql://agentboard:your_password@localhost:5433/agentboardnpm run build:server
npm run build:client| Variable | Default | Description |
|---|---|---|
API_KEY |
(unset) | Bearer token for API + WebSocket auth; unset = open access |
VITE_API_KEY |
(unset) | Client-side API key (must match API_KEY) |
PORT |
8080 |
Server port |
DATABASE_URL |
(unset) | PostgreSQL connection string; when unset, uses SQLite |
DB_PATH |
./data/agentboard.db |
SQLite database file path |
COPILOT_MODEL |
claude-opus-4-20250514 |
Model for Copilot SDK sessions |
CLAUDE_MODEL |
claude-opus-4-20250514 |
Model for Claude Code sessions |
CODEX_MODEL |
gpt-5.2-codex |
Model for OpenAI Codex sessions |
COPILOT_DENIED_TOOLS |
(unset) | Comma-separated tool names to deny in Copilot sessions |
ALLOWED_REPO_ROOTS |
$HOME,/tmp |
Allowed repo root paths (comma-separated) |
ALLOWED_ORIGINS |
http://localhost:8081,http://localhost:4175,http://localhost:4176 |
CORS origins |
AGENT_TIMEOUT_MS |
600000 |
Max agent execution time (ms) |
API_URL |
http://localhost:8080 |
Vite proxy target |
PROJECTS_DIR |
~/projects |
Host projects path |
ai-agent-board/
├── packages/
│ ├── client/ # React frontend
│ │ └── src/
│ │ ├── components/ # Board, Column, TaskCard, TaskGroupCard, GroupPanel, AgentPanel, TerminalView, ParallelismSlider, FilterChips, dialogs
│ │ ├── hooks/ # useTasks, useTaskGroups, useTheme, useDebounce, useKeyboardShortcuts
│ │ └── lib/ # API client, WebSocket, agent-config, priority-config, utilities
│ ├── server/ # Express backend
│ │ └── src/
│ │ ├── middleware/ # Bearer token auth
│ │ ├── routes/ # REST API split: tasks, agent, git (merge/PR/worktree), templates, groups
│ │ ├── services/ # Agent session orchestration via agent-sdk-core
│ │ ├── repositories/ # SQLite + PostgreSQL data access (tasks + templates + groups)
│ │ ├── db.ts # Database init + migrations
│ │ └── websocket.ts # Real-time event broadcast
│ └── e2e/ # Playwright end-to-end tests
└── shared/ # Shared types (Task, TaskGroup, TaskTemplate, AgentEvent, etc.) + validation
# Run all E2E tests (requires client + server running)
npm test
# Run directly
cd packages/e2e && npx playwright test --reporter=list7 test files covering 81 tests:
| File | Tests | Coverage |
|---|---|---|
board.spec.ts |
14 | Task CRUD, drag & drop, theme, priority, sorting, filters, retry |
api-improvements.spec.ts |
20 | Auto-run, batch create, status endpoint, WebSocket events, follow-up messages |
agent-selector.spec.ts |
7 | Agent selection UI, badges, worktree dialog |
groups.spec.ts |
28 | Group CRUD, validation, archive, edge cases (E3/E12), UI |
git-operations.spec.ts |
8 | Local merge, conflict handling, PR creation, worktree cleanup |
group-integration.spec.ts |
2 | Full agent execution with real agents, stop & cleanup |
agent-sdk.spec.ts |
2 | Real Copilot SDK execution (skipped without test repo) |
| Layer | Technology |
|---|---|
| Frontend | React 19, Vite, Tailwind CSS 4, Framer Motion |
| Drag & Drop | @dnd-kit |
| Backend | Express, better-sqlite3 / PostgreSQL, ws (WebSocket) |
| AI Agents | @codewithdan/agent-sdk-core (wraps @github/copilot-sdk, @anthropic-ai/claude-agent-sdk, @openai/codex-sdk, @opencode-ai/sdk) |
| Terminal UI | @xterm/xterm |
| Monorepo | npm workspaces |
| Dev Environment | Direct install (Linux, macOS, Windows) |
See CONTRIBUTING.md.