ai-agent-board 0.2.0 → 0.2.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +210 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,210 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# ai-agent-board
|
|
4
|
+
|
|
5
|
+
**A visual dashboard for managing autonomous AI coding agents.**
|
|
6
|
+
|
|
7
|
+
Kanban board • Real-time logs • Diff review • One-click PRs
|
|
8
|
+
|
|
9
|
+
[](https://www.npmjs.com/package/ai-agent-board)
|
|
10
|
+
[](https://opensource.org/licenses/MIT)
|
|
11
|
+
[](https://nodejs.org)
|
|
12
|
+
[]()
|
|
13
|
+
|
|
14
|
+
</div>
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## What is agent-board?
|
|
19
|
+
|
|
20
|
+
`agent-board` is a local web dashboard that lets you **create tasks**, **assign them to AI coding agents**, and **monitor everything** from a Kanban-style interface — real-time execution logs, code diffs, and automatic PR creation on GitHub.
|
|
21
|
+
|
|
22
|
+
It works with the coding CLIs you already have installed:
|
|
23
|
+
|
|
24
|
+
| Agent | CLI Command | Status |
|
|
25
|
+
|-------|-------------|--------|
|
|
26
|
+
| **Claude Code** | `claude` | Supported |
|
|
27
|
+
| **Codex** | `codex` | Supported |
|
|
28
|
+
| **Copilot** | `copilot` | Supported |
|
|
29
|
+
| **Gemini** | `gemini` | Supported |
|
|
30
|
+
|
|
31
|
+
## Quick Start
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
npx ai-agent-board
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
That's it. The dashboard opens automatically in your browser. No configuration files, no Docker, no database setup.
|
|
38
|
+
|
|
39
|
+
> **Requirements:** Node.js >= 18. At least one supported AI coding CLI installed and authenticated.
|
|
40
|
+
|
|
41
|
+
### CLI Options
|
|
42
|
+
|
|
43
|
+
```
|
|
44
|
+
npx ai-agent-board [options]
|
|
45
|
+
|
|
46
|
+
--port <number> Server port (default: auto-detect)
|
|
47
|
+
--no-open Don't open browser automatically
|
|
48
|
+
--clear-cache Delete cached binary and re-download
|
|
49
|
+
--version, -v Show version
|
|
50
|
+
--help, -h Show help
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Features
|
|
54
|
+
|
|
55
|
+
### Kanban Board
|
|
56
|
+
|
|
57
|
+
Manage tasks across stages: **To Do** → **In Progress** → **In Review** → **Done**. Each task card shows its current status, assigned agent, and progress at a glance.
|
|
58
|
+
|
|
59
|
+
### Two-Agent Workflow
|
|
60
|
+
|
|
61
|
+
Tasks go through a structured pipeline:
|
|
62
|
+
|
|
63
|
+
```
|
|
64
|
+
You describe a task PM Agent generates You review & edit Dev Agent writes
|
|
65
|
+
in natural language ───▶ a detailed spec ───▶ the spec ───▶ the code
|
|
66
|
+
│
|
|
67
|
+
▼
|
|
68
|
+
Review diff & merge
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
1. **Create task** — describe what you need in plain language
|
|
72
|
+
2. **PM Agent** — generates a detailed technical specification
|
|
73
|
+
3. **Review spec** — edit, regenerate, or approve
|
|
74
|
+
4. **Dev Agent** — implements the approved specification
|
|
75
|
+
5. **Review & merge** — inspect the diff, then create a PR
|
|
76
|
+
|
|
77
|
+
### Real-time Execution Logs
|
|
78
|
+
|
|
79
|
+
Watch your AI agent work in real-time via Server-Sent Events (SSE). Every step, every file change, streamed directly to your browser.
|
|
80
|
+
|
|
81
|
+
### Diff Viewer
|
|
82
|
+
|
|
83
|
+
Review all code changes before they go anywhere. Inline diff viewer shows exactly what the agent modified, added, or removed.
|
|
84
|
+
|
|
85
|
+
### GitHub Integration
|
|
86
|
+
|
|
87
|
+
Create Pull Requests directly from the dashboard. Review PR comments, request changes, and track merge status — all without leaving the board.
|
|
88
|
+
|
|
89
|
+
### Dark Mode
|
|
90
|
+
|
|
91
|
+
Full light and dark theme support. Automatically follows your system preference.
|
|
92
|
+
|
|
93
|
+
## How It Works
|
|
94
|
+
|
|
95
|
+
`agent-board` runs a lightweight local server that:
|
|
96
|
+
|
|
97
|
+
1. **Detects** which AI coding CLIs you have installed (Claude Code, Codex, Copilot, Gemini)
|
|
98
|
+
2. **Orchestrates** task execution by invoking the CLI agents in sandboxed worktrees
|
|
99
|
+
3. **Streams** real-time output to the browser via SSE
|
|
100
|
+
4. **Manages** code changes with git worktrees — your main branch stays untouched
|
|
101
|
+
5. **Creates** Pull Requests via the GitHub API when you approve changes
|
|
102
|
+
|
|
103
|
+
All data is stored in a local SQLite database. Nothing leaves your machine except the API calls your AI coding CLIs already make and the GitHub API calls for PR creation.
|
|
104
|
+
|
|
105
|
+
## Task Lifecycle
|
|
106
|
+
|
|
107
|
+
| Status | Description | Board Column |
|
|
108
|
+
|--------|-------------|:------------:|
|
|
109
|
+
| `draft` | Task created, awaiting spec generation | To Do |
|
|
110
|
+
| `refining` | PM Agent generating specification | To Do |
|
|
111
|
+
| `pending_approval` | Spec ready for your review | To Do |
|
|
112
|
+
| `approved` | Spec approved, Dev Agent starting | In Progress |
|
|
113
|
+
| `coding` | Dev Agent working | In Progress |
|
|
114
|
+
| `awaiting_review` | Changes ready for your review | In Review |
|
|
115
|
+
| `pr_created` | Pull Request created on GitHub | In Review |
|
|
116
|
+
| `done` | PR merged | Done |
|
|
117
|
+
| `failed` | Error during execution | — |
|
|
118
|
+
|
|
119
|
+
## Architecture
|
|
120
|
+
|
|
121
|
+
```
|
|
122
|
+
┌─────────────────────────────────────────────────────┐
|
|
123
|
+
│ ai-agent-board │
|
|
124
|
+
│ │
|
|
125
|
+
│ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ │
|
|
126
|
+
│ │ Dashboard │ │ Server │ │ Shared │ │
|
|
127
|
+
│ │ React SPA │◄─┤ Express API │ │ Types & │ │
|
|
128
|
+
│ │ Vite 7 │ │ Bun runtime │ │ Schemas │ │
|
|
129
|
+
│ │ TanStack │ │ SQLite │ │ Zod │ │
|
|
130
|
+
│ │ Tailwind 4 │ │ SSE │ │ │ │
|
|
131
|
+
│ └──────────────┘ └──────┬───────┘ └────────────┘ │
|
|
132
|
+
│ │ │
|
|
133
|
+
│ ┌──────┴───────┐ │
|
|
134
|
+
│ │ CLI Runner │ │
|
|
135
|
+
│ │ Orchestrator│ │
|
|
136
|
+
│ └──────┬───────┘ │
|
|
137
|
+
│ │ │
|
|
138
|
+
│ ┌────────────┼────────────┐ │
|
|
139
|
+
│ ▼ ▼ ▼ │
|
|
140
|
+
│ claude codex gemini ... │
|
|
141
|
+
└─────────────────────────────────────────────────────┘
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
### Tech Stack
|
|
145
|
+
|
|
146
|
+
| Layer | Technologies |
|
|
147
|
+
|-------|-------------|
|
|
148
|
+
| **Frontend** | React 19, Vite 7, TypeScript, Tailwind CSS 4, shadcn/ui, TanStack Router & Query, Zustand |
|
|
149
|
+
| **Backend** | Express, Bun, TypeScript, sql.js (SQLite via WASM), SSE |
|
|
150
|
+
| **Shared** | Zod schemas, TypeScript types, npm workspaces |
|
|
151
|
+
| **CLI** | Lightweight npx wrapper, platform-specific binary distribution |
|
|
152
|
+
|
|
153
|
+
### Key Design Decisions
|
|
154
|
+
|
|
155
|
+
- **SSE over WebSockets** — unidirectional streaming is sufficient for logs; simpler, works with any proxy/CDN, and browsers auto-reconnect
|
|
156
|
+
- **SQLite (WASM)** — zero-config embedded database, no external server needed, cross-platform via WebAssembly
|
|
157
|
+
- **Git worktrees** — agent works in isolated worktrees so your main branch is never at risk
|
|
158
|
+
- **npx distribution** — single command to run, binary auto-downloaded and cached per platform
|
|
159
|
+
|
|
160
|
+
## Development
|
|
161
|
+
|
|
162
|
+
```bash
|
|
163
|
+
# Clone and install
|
|
164
|
+
git clone https://github.com/ezeoli88/dash-agent.git
|
|
165
|
+
cd dash-agent
|
|
166
|
+
npm install
|
|
167
|
+
|
|
168
|
+
# Run in development mode (server + dashboard)
|
|
169
|
+
npm run dev
|
|
170
|
+
|
|
171
|
+
# Build all packages
|
|
172
|
+
npm run build
|
|
173
|
+
|
|
174
|
+
# Build specific packages
|
|
175
|
+
npm run build:shared
|
|
176
|
+
npm run build:server
|
|
177
|
+
npm run build:dashboard
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
The dashboard runs on **port 3003** (Vite dev server) and the server on **port 3000** (Bun). Vite proxies `/api` requests to the server automatically.
|
|
181
|
+
|
|
182
|
+
### Environment Variables
|
|
183
|
+
|
|
184
|
+
Create `packages/server/.env`:
|
|
185
|
+
|
|
186
|
+
```env
|
|
187
|
+
# Required: for AI agent capabilities
|
|
188
|
+
OPENAI_API_KEY=sk-...
|
|
189
|
+
|
|
190
|
+
# Optional: for GitHub PR creation
|
|
191
|
+
GITHUB_TOKEN=ghp_...
|
|
192
|
+
|
|
193
|
+
# Optional: server configuration
|
|
194
|
+
PORT=3000
|
|
195
|
+
DATABASE_PATH=./data/dash-agent.db
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
## Contributing
|
|
199
|
+
|
|
200
|
+
Contributions are welcome. Please open an issue first to discuss what you'd like to change.
|
|
201
|
+
|
|
202
|
+
1. Fork the repository
|
|
203
|
+
2. Create your branch (`git checkout -b feature/my-feature`)
|
|
204
|
+
3. Commit your changes (`git commit -m 'Add my feature'`)
|
|
205
|
+
4. Push to the branch (`git push origin feature/my-feature`)
|
|
206
|
+
5. Open a Pull Request
|
|
207
|
+
|
|
208
|
+
## License
|
|
209
|
+
|
|
210
|
+
[MIT](LICENSE) © [Ezequiel Olivera](https://github.com/ezeoli88)
|