# Agent Task Board

**Project site:** https://lucasaraujonrt.github.io/agent-task-board/
A local task backlog with a JSON CLI and stdio MCP interface, extracted from the mini-Linear built for Inker. Agents can create, find and update tasks without navigating a web UI. SQLite is the source of truth; FTS5 powers text search and an event table records changes.

## Capabilities

- Create tasks with a stable idempotency key to avoid duplicates after retries.
- Search titles and descriptions with SQLite FTS5.
- List by project or status and read a task's full history.
- Update title, description, priority or status.
- Run locally with one SQLite file and no cloud service.

## Quick start

Requires Bun 1.2 or newer. Install dependencies with `bun install` for the MCP server; the core CLI only uses Bun's built-in SQLite.

```sh
export AGENT_TASK_DB=./tasks.db
bun run src/cli.ts add "Review webhook retries" "Check duplicate events" api issue-123
bun run src/cli.ts search webhook
bun run src/cli.ts list todo api
bun run src/cli.ts show 1
bun run src/cli.ts status 1 in_progress
bun run src/cli.ts stats
```

Every command emits JSON. The MCP server is `bun run src/mcp.ts` and exposes `task_add`, `task_search`, `task_list`, `task_get`, `task_update` and `task_stats`.

Example MCP client entry:

```json
{
  "mcpServers": {
    "agent-tasks": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/agent-task-board/src/mcp.ts"],
      "env": { "AGENT_TASK_DB": "/absolute/path/to/tasks.db" }
    }
  }
}
```

## Data contract

Statuses: `backlog`, `todo`, `in_progress`, `in_review`, `done`, `cancelled`. Priority is an integer 0–4, where 0 is highest. `project` is a free-form namespace, default `default`. `idempotencyKey` is unique for task creation; the same key and same task fields return the existing task.

The MCP server runs on stdio and has access to the configured database file. Protect that file and only attach the server to agents that should read or write this backlog. This first release has no multi-user authorization or hosted HTTP endpoint.

See [architecture](docs/architecture.md) for storage and failure behavior.

## Verification

`bun test` uses an in-memory SQLite database. Tests cover creation, search, updates, audit history, status validation and idempotency conflicts. No external service is needed.

## Origin and scope

Inker's internal board also contains finance, marketing, vault and reporting integrations. This repository keeps the reusable agent task core and includes none of those modules or their data.