@benlooper/agent-board-tui 1.0.0

package/AGENT_API.md

@@ -0,0 +1,301 @@
+# Agent Board API Reference
+
+Base URL: `http://localhost:31377/api`
+
+This board is the shared workspace between you and the user. Use it to track your work, signal progress, and — critically — ask the user for input when you need it.
+
+---
+
+## Workflow Basics
+
+1. **Claim a card** when you pick up a task — this sets you as the owner and moves it to In Progress.
+2. **Post comments** on the card as you work. This is how the user follows along.
+3. **Ask for input** using the long-poll endpoint whenever you need a decision, approval, or information. The request surfaces in the UI with an audio alert. **Do not proceed past a blocking question — wait for the answer.**
+4. **Check your messages** at the start of each turn — the user may have left you a message via the chat system.
+5. **Update the status** when you finish or hit a wall.
+
+---
+
+## Cards
+
+### List all cards
+```
+GET /cards
+GET /cards?status=<statusId>
+```
+Returns all cards, optionally filtered by status ID. Use `GET /statuses` first to resolve status names to IDs.
+
+### Get a single card (with comments)
+```
+GET /cards/:id
+```
+Returns the card plus its full comment thread.
+
+### Claim a card
+```
+POST /cards/:id/claim
+{
+  "agentId": "implementer-1",
+  "autoAdvance": true
+}
+```
+Sets you as the owner. If `autoAdvance` is true (default) and the card is in "To Do", it automatically moves to "In Progress". **Do this before starting work.**
+
+### What statuses can I move this card to?
+```
+GET /cards/:id/allowed-statuses?agentId=implementer-1
+```
+Returns the list of status objects you are permitted to move this card to from its current status, based on the configured transition rules. If no rules are configured, returns all statuses. **Check this before patching status** to avoid a rejected move.
+
+### Update a card
+```
+PATCH /cards/:id
+{
+  "statusId": "<id>",
+  "agentId": "implementer-1",
+  "title": "...",
+  "description": "...",
+  "type": "task|story|bug",
+  "epicId": "<id or null>",
+  "featureId": "<id or null>"
+}
+```
+All fields are optional. When changing status, include your `agentId` so transition rules are enforced. If a move is not permitted, the server returns an error.
+
+### Create a card
+```
+POST /cards
+{
+  "title": "Fix login bug",
+  "statusId": "<To Do status ID>",
+  "type": "bug",
+  "description": "...",
+  "agentId": "implementer-1",
+  "epicId": "<id>",
+  "featureId": "<id>"
+}
+```
+
+### Delete a card
+```
+DELETE /cards/:id
+```
+
+### Post a comment
+```
+POST /cards/:id/comments
+{
+  "body": "Finished the database migration. Moving to review.",
+  "author": "agent"
+}
+```
+Use comments to narrate your progress. The user reads these.
+
+---
+
+## Requesting User Input ⚠️
+
+**This is the most important endpoint. Use it any time you need a decision, approval, clarification, or information you cannot determine yourself. Do not guess — ask.**
+
+```
+POST /input
+{
+  "cardId": "<your card id>",
+  "questions": [
+    {
+      "id": "q1",
+      "type": "yesno",
+      "prompt": "Should I overwrite the existing config file?"
+    },
+    {
+      "id": "q2",
+      "type": "choice",
+      "prompt": "Which environment should this deploy to?",
+      "options": ["staging", "production"]
+    },
+    {
+      "id": "q3",
+      "type": "text",
+      "prompt": "What should the new API endpoint be named?",
+      "default": "/api/v2/users"
+    }
+  ],
+  "timeoutSecs": 900
+}
+```
+
+**This call blocks.** The HTTP request stays open until the user answers in the UI (or the timeout expires). Your card is automatically moved to "Blocked" while waiting. When the user responds, the call returns:
+
+```json
+{
+  "requestId": "...",
+  "status": "answered",
+  "answers": {
+    "q1": "yes",
+    "q2": "production",
+    "q3": "/api/v2/users"
+  }
+}
+```
+
+On timeout (HTTP 408):
+```json
+{ "requestId": "...", "status": "timed_out", "answers": null }
+```
+
+**Question types:**
+- `text` — free-form string. Supply `default` if there's a sensible fallback.
+- `yesno` — answer will be `"yes"` or `"no"`.
+- `choice` — single-select from `options`. Answer will be one of the option strings.
+
+**When to use it:** Whenever you are blocked on a human decision, need approval before a destructive action, are uncertain about scope or intent, or need credentials/values you don't have. The user gets an audio alert and a prompt in the UI — they expect to be asked.
+
+---
+
+## Agent Chat (Message Queue)
+
+The board has a bidirectional chat system. The user can send you messages between turns and expects you to read them before doing any work. You can also send replies that appear in the user's chat window.
+
+### Fuzzy agent matching
+
+Messages use a fuzzy pattern match — the message's `agentId` is matched as a substring of your agent id. This means a message addressed to `"implementer"` will be picked up by `"implementer-1"`, `"implementer-frontend"`, or `"implementer"` itself.
+
+Always poll using your **full** agent id:
+```
+GET /queue?agentId=implementer-1&status=pending
+```
+
+### Check your messages (do this at the start of each turn)
+```
+GET /queue?agentId=<your-agent-id>&status=pending
+```
+Returns pending messages addressed to you (via fuzzy match), ordered oldest first. Filter for `status=pending` to only get unread messages.
+
+### Reply to a message / send a message
+```
+POST /queue
+{
+  "agentId": "implementer-1",
+  "body": "Done — the migration is complete. No data loss.",
+  "author": "implementer-1"
+}
+```
+Set `author` to your own agent id so the user's chat window shows it as a reply from you. The `agentId` field identifies which conversation thread this belongs to.
+
+### Mark a message as read
+```
+POST /queue/:id/read
+```
+Call this after you have processed a message.
+
+### List all conversations
+```
+GET /queue/conversations
+```
+Returns a summary per agent: `{ agentId, total, unread, lastAt }`.
+
+### QueueMessage shape
+```json
+{
+  "id": "uuid",
+  "agentId": "implementer",
+  "body": "Please prioritize the login bug fix next.",
+  "status": "pending",
+  "author": "user",
+  "createdAt": "2026-03-24T10:00:00.000Z",
+  "readAt": null
+}
+```
+
+**`author` field:** `"user"` means the human sent it. Any other value is the agent id of the sender.
+
+**Recommended per-turn workflow:**
+1. At the start of each turn, call `GET /queue?agentId=<your-id>&status=pending`.
+2. Read the messages and adjust your plan accordingly.
+3. Reply with `POST /queue` (set `author` to your agent id) if a response is warranted.
+4. Call `POST /queue/:id/read` for each message you act on.
+5. Note any changes to your plan in a comment on the relevant card.
+
+---
+
+## Statuses
+
+### List all statuses (ordered by position)
+```
+GET /statuses
+```
+Returns `[{ id, name, color, position }]`. Resolve status names to IDs before using them in card operations.
+
+---
+
+## Epics
+
+### List all epics
+```
+GET /epics
+```
+
+### Create an epic
+```
+POST /epics
+{
+  "title": "Authentication Overhaul",
+  "description": "...",
+  "statusId": "<id>"
+}
+```
+
+### Update an epic
+```
+PATCH /epics/:id
+{ "title": "...", "description": "...", "statusId": "<id>" }
+```
+
+---
+
+## Features
+
+### List all features
+```
+GET /features
+```
+
+### Create a feature
+```
+POST /features
+{
+  "epicId": "<id>",
+  "title": "JWT Token Issuance",
+  "description": "...",
+  "statusId": "<id>"
+}
+```
+
+### Update a feature
+```
+PATCH /features/:id
+{ "title": "...", "description": "...", "statusId": "<id>" }
+```
+
+---
+
+## Transition Rules
+
+Rules control which agents can move cards to which statuses. If no rules exist, all moves are allowed.
+
+### List all rules
+```
+GET /transition-rules
+```
+Returns `[{ id, agentPattern, fromStatusId, toStatusId }]`. `null` means "any".
+
+---
+
+## Tips
+
+- Always claim a card before working on it.
+- Post a comment when you start, when you hit a decision point, and when you finish.
+- Use `GET /cards/:id/allowed-statuses?agentId=<you>` before changing status — it tells you exactly what moves are available to you.
+- When in doubt about anything, use `POST /input`. The user prefers being asked over having you guess.
+- `timeoutSecs` defaults to 900 (15 min). For non-urgent questions you can increase it; for quick confirmations leave it at default.
+- Check `GET /queue?agentId=<you>&status=pending` at the start of each turn before doing any other work.

package/README.md

@@ -0,0 +1,107 @@
+# agent-board-tui
+
+A terminal UI fork of [agent-board](https://github.com/benlooper/agent-board). Replaces the React/Vite web frontend with a keyboard-driven terminal interface built with [Ink](https://github.com/vadimdemedes/ink).
+
+Everything else is unchanged — same Elysia API, same SQLite database, same agent integration.
+
+---
+
+## Setup
+
+```bash
+bun install
+bun run dev        # starts server + TUI together
+```
+
+Or run them independently:
+
+```bash
+bun run server     # API only — keeps running between TUI sessions
+bun run tui        # TUI only — connects to a running server
+```
+
+The database is created automatically at `server/data/agent-board.db` on first run.
+
+- **API** — `http://localhost:31377`
+- **Swagger** — `http://localhost:31377/docs`
+
+---
+
+## Navigation
+
+| Key | Action |
+|-----|--------|
+| `b` / `c` / `a` | Switch to Board / Chat / Admin view |
+| `Ctrl+A` | Jump to Admin from anywhere |
+| `h` / `l` | Move between columns (board) or tabs (admin) |
+| `j` / `k` | Move up / down |
+| `Enter` | Open card / confirm |
+| `Esc` | Go back |
+| `i` | Answer a pending agent input request |
+| `?` | Help overlay |
+| `Ctrl+R` | Restart TUI (server keeps running) |
+| `Ctrl+C` | Quit |
+
+---
+
+## Themes
+
+Admin → Theme tab. Four presets: **Default**, **Dracula**, **Nord**, **Gruvbox**. Persists to `~/.config/agent-board/settings.json`.
+
+---
+
+## Integrating agents
+
+Same as the original. Include `AGENT_API.md` in any agent's system prompt:
+
+```
+You have access to a task board at http://localhost:31377.
+See the API reference below for how to use it.
+
+<agent_api>
+[contents of AGENT_API.md]
+</agent_api>
+```
+
+For Claude Code agents, `.claude/commands/` has slash command skills:
+
+```
+/board-create-card      /board-update-card      /board-complete-card
+/board-block-card       /board-request-input    /board-add-comment
+/board-list-cards       /board-get-card         /board-create-epic
+/board-create-feature   /board-check-messages   /board-send-message
+```
+
+---
+
+## Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Runtime | Bun |
+| API | Elysia + Eden Treaty |
+| Database | SQLite (Drizzle ORM) |
+| Terminal UI | React 18 + [Ink](https://github.com/vadimdemedes/ink) |
+| Server state | TanStack Query v5 |
+| UI state | Zustand |
+| Real-time | Native WebSocket |
+
+---
+
+## Project structure
+
+```
+agent-board-tui/
+├── server/          # Elysia API (unchanged from original)
+├── tui/             # Ink terminal UI (replaces client/)
+│   └── src/
+│       ├── views/   # Board, CardDetail, Chat, Admin
+│       ├── components/
+│       ├── hooks/   # useWebSocket, useDimensions, useTheme
+│       ├── store/   # Zustand
+│       └── api/     # Eden Treaty client
+├── scripts/
+│   ├── dev.ts       # Starts server + TUI (restart-aware)
+│   └── tui.ts       # TUI-only launcher
+└── AGENT_API.md     # HTTP reference for agents
+```

package/commands/kanban.md

@@ -0,0 +1,48 @@
+Enter orchestrator mode for the agent-board kanban system.
+
+$ARGUMENTS is an optional initial directive describing the work to accomplish.
+If not provided, ask the user what they want to accomplish before proceeding.
+
+## Step 1: Ensure the server is running
+
+Check if the board server is up:
+
+    curl -s --max-time 2 http://localhost:31377/api/cards
+
+If that fails, start it:
+
+    agent-board-tui
+
+Then poll every 2s (up to 15s) until the health check passes.
+
+## Step 2: API Reference
+
+You now have the full agent-board API reference. Internalize it — all board
+operations go through these endpoints.
+
+{{AGENT_API}}
+
+## Step 3: Assume orchestrator role
+
+Your agent ID for this session is `orchestrator`.
+
+As orchestrator:
+- Assign stable IDs to sub-agents before spawning (e.g. `implementer-1`, `reviewer-1`)
+- Create an epic for the overall goal, features for major workstreams, cards for agent tasks
+- Assign cards to agents by setting `agentId` — do not claim cards yourself
+- Spawn sub-agents via the Agent tool, passing their card ID and agent ID in the prompt
+- Monitor progress by reading card comments (`GET /cards/:id`)
+- Check `GET /queue/conversations` for unread agent messages; route or forward as needed
+- Use `POST /input` (with your own cardId) for decisions that require the user
+
+## Step 4: Accept the directive
+
+Use $ARGUMENTS as the directive, or ask the user now if none was provided.
+
+## Step 5: Structure the work and begin orchestrating
+
+1. `POST /epics` — create an epic for the overall goal
+2. `POST /features` — one per major workstream
+3. `POST /cards` — one per sub-agent task; set `agentId` and `epicId`/`featureId`
+4. Spawn sub-agents via the Agent tool; each gets their card ID, agent ID, and enough context
+5. Monitor the board and handle input requests as they arrive

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@benlooper/agent-board-tui",
+  "version": "1.0.0",
+  "bin": {
+    "agent-board-tui": "scripts/cli.ts"
+  },
+  "files": [
+    "scripts/",
+    "commands/",
+    "AGENT_API.md"
+  ],
+  "scripts": {
+    "dev": "bun scripts/dev.ts",
+    "server": "bun run --filter server dev",
+    "tui": "bun scripts/tui.ts",
+    "build": "bun run --filter '*' build",
+    "install:all": "bun install",
+    "setup": "bun scripts/setup.ts"
+  },
+  "devDependencies": {
+    "concurrently": "^8.2.2"
+  }
+}

package/scripts/cli.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env bun
+/// <reference types="bun-types" />
+
+const [subcommand] = process.argv.slice(2);
+
+switch (subcommand) {
+  case "setup":
+    await import("./setup.ts");
+    break;
+  default:
+    console.error(
+      `Usage: agent-board-tui <command>\n\nCommands:\n  setup    Install the /kanban slash command to ~/.claude/commands/`
+    );
+    process.exit(subcommand ? 1 : 0);
+}

package/scripts/dev.ts

@@ -0,0 +1,49 @@
+import { spawn } from "child_process";
+import { openSync } from "fs";
+import { join } from "path";
+
+const isWindows = process.platform === "win32";
+const bunCmd = isWindows ? "bun.exe" : "bun";
+const RESTART_CODE = 75;
+
+// Redirect server output to a log file so it doesn't pollute the TUI terminal
+const logPath = join(import.meta.dir, "../server.log");
+const logFd = openSync(logPath, "w");
+
+const server = spawn(bunCmd, ["run", "--filter", "server", "dev"], {
+  stdio: ["ignore", logFd, logFd],
+});
+
+server.on("error", (err) => {
+  console.error("[dev] failed to start server:", err.message);
+  process.exit(1);
+});
+
+process.on("SIGINT", () => {
+  server.kill();
+});
+
+function launchTui() {
+  // TUI runs in foreground — must inherit stdin so Ink gets a real TTY
+  const tui = spawn(bunCmd, ["run", "dev"], {
+    cwd: new URL("../tui", import.meta.url).pathname,
+    stdio: "inherit",
+  });
+
+  tui.on("error", (err) => {
+    console.error("[dev] failed to start tui:", err.message);
+    server.kill();
+    process.exit(1);
+  });
+
+  tui.on("exit", (code) => {
+    if (code === RESTART_CODE) {
+      launchTui(); // restart TUI, keep server running
+    } else {
+      server.kill();
+      process.exit(code ?? 0);
+    }
+  });
+}
+
+launchTui();

package/scripts/setup.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env bun
+/// <reference types="bun-types" />
+/**
+ * setup.ts
+ *
+ * Installs the /kanban global slash command to ~/.claude/commands/kanban.md.
+ * Replaces {{AGENT_API}} in commands/kanban.md with the contents of AGENT_API.md.
+ *
+ * Usage:
+ *   bun scripts/setup.ts
+ *
+ * Idempotent — re-running overwrites with the latest content.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from "fs";
+import { join, dirname } from "path";
+import { homedir } from "os";
+
+const root = join(dirname(import.meta.path), "..");
+
+const templatePath = join(root, "commands", "kanban.md");
+const apiMdPath = join(root, "AGENT_API.md");
+
+const template = readFileSync(templatePath, "utf8");
+const apiContent = readFileSync(apiMdPath, "utf8").trimEnd();
+
+const output = template.replace("{{AGENT_API}}", apiContent);
+
+const destDir = join(homedir(), ".claude", "commands");
+mkdirSync(destDir, { recursive: true });
+
+const destPath = join(destDir, "kanban.md");
+writeFileSync(destPath, output, "utf8");
+
+console.log(`✓ Installed /kanban to ${destPath}`);

package/scripts/tui.ts

@@ -0,0 +1,29 @@
+import { spawn } from "child_process";
+
+const isWindows = process.platform === "win32";
+const bunCmd = isWindows ? "bun.exe" : "bun";
+const RESTART_CODE = 75;
+
+function launchTui() {
+  const tui = spawn(bunCmd, ["run", "dev"], {
+    cwd: new URL("../tui", import.meta.url).pathname,
+    stdio: "inherit",
+  });
+
+  tui.on("error", (err) => {
+    console.error("[tui] failed to start:", err.message);
+    process.exit(1);
+  });
+
+  tui.on("exit", (code) => {
+    if (code === RESTART_CODE) {
+      launchTui();
+    } else {
+      process.exit(code ?? 0);
+    }
+  });
+
+  process.on("SIGINT", () => tui.kill());
+}
+
+launchTui();