Menu
akurai-tasks
publicLatest change 6ff494d6bf89c9e17b4480876ff52570fe9f8f91 - Add all-projects Tasks board and DSH framing by Ólafur Búi Ólafsson
# AkurAI-Tasks
AkurAI-Framework-based task and Kanban service for work spanning multiple projects and
repositories. One Rust process exposes the same command core through CLI, authenticated REST,
MCP over stdio/HTTP, and a no-build web application.
The vertical slice is deployed through AkurAI Build, but it is not yet the authoritative
replacement for legacy task sources. Remaining authorization, recovery, immutable-artifact,
lossless-import, and cutover gates live in AkurAI Notes note 139 (`AkurAI-Tasks — PLAN`).
## What works
- multiple projects, each scoped to zero or more `owner/repository` identifiers;
- project task IDs (`PROJECT-1`, `PROJECT-2`, …) and nine-state Kanban boards;
- revision-checked adjacent transitions, blocking, dependencies, Ready frontier, claims,
evidence, comments, durable handoffs, and append-only audit events;
- actor-scoped idempotency for every mutation;
- one embedded AkurAI-Framework BTree commit for projection, event, and idempotency result;
- CLI, authenticated REST, a 25-tool MCP 2025-11-25 surface, and responsive web UI;
- bearer authentication and same-origin enforcement for REST and Streamable HTTP MCP.
## Build and check
Run on Titan from the repository root:
```sh
./scripts/check.sh
```
The gate runs the Rust workspace tests, builds the binary, creates a real temporary
multi-repository project and task through the CLI, reads its board, and exercises MCP over
stdio. The API tests cover authenticated reads/mutations and same-origin rejection.
## Run locally
Keep the token in the process environment or AkurAI PassVault-backed deployment environment;
never commit it:
```sh
export AKURAI_TASKS_TOKEN='replace-with-a-local-token'
export AKURAI_TASKS_ACTOR='local-operator'
cargo run -p akurai-tasks -- \
--db data/tasks.db \
serve --host 127.0.0.1 --port 8090 --frontend frontend
```
Open <http://127.0.0.1:8090>. Enter the same token in the in-app session dialog. The browser
keeps it in `sessionStorage`, so it is removed when the tab session ends.
For a separate public origin, set `AKURAI_TASKS_ALLOWED_ORIGIN` to the exact origin. Same-origin
browser requests work without that override.
## CLI
Install or refresh the Titan-local release binary through the maintained suite:
```sh
akurai-data-cli install
akurai-data-cli status
akurai-tasks help
```
This installs a local operator/development CLI only. It does not deploy AkurAI-Tasks or make
the service a production source of truth.
Global flags may appear before or after the command:
```sh
export AKURAI_TASKS_DB=data/tasks.db
export AKURAI_TASKS_ACTOR=olafur
cargo run -p akurai-tasks -- \
--idempotency project-akurai \
project create AKURAI "AkurAI services" olibuijr/AkurAI-Tasks,olibuijr/AkurAI-Framework
cargo run -p akurai-tasks -- \
--idempotency task-command-core \
item create AKURAI "Finish command core" \
--repo olibuijr/AkurAI-Tasks --priority high
cargo run -p akurai-tasks -- project update AKURAI olibuijr/AkurAI-Tasks,olibuijr/AkurAI-Framework
cargo run -p akurai-tasks -- item set-repo AKURAI-1 olibuijr/AkurAI-Tasks
cargo run -p akurai-tasks -- board AKURAI
cargo run -p akurai-tasks -- frontier AKURAI
```
### Repository binding
A work item's `repo` must name a repository the project registers. When a project registers
exactly one repository the item repo is auto-filled; when it registers several an explicit
`--repo` is required, and an unregistered or missing repo is rejected. Use `project update KEY
REPOS` to register repositories on an existing project and `item set-repo ID REPO` to move an
existing item onto one. The MCP equivalents are `project_update` and `work_set_repo`.
Run `akurai-tasks help` for transition, claim, dependency, comment, evidence, block, and handoff
commands. Supply explicit idempotency keys for automation; the CLI generates one only for
interactive calls.
## REST
All `/api/*` routes except `/api/health` and `/api/ready` require:
```text
Authorization: Bearer <token>
X-AkurAI-Actor: <stable principal>
Idempotency-Key: <required on mutations>
```
Primary resources:
```text
GET /api/projects
GET /api/board
GET /api/frontier
POST /api/projects
POST /api/projects/{key}/repos
POST /api/projects/{key}/archive
POST /api/projects/{key}/unarchive
POST /api/projects/{key}/delete
POST /api/projects/{key}/purge
GET /api/projects/{project}/board
GET /api/projects/{project}/frontier
POST /api/items
GET /api/items/{id}
POST /api/items/{id}/repo
POST /api/items/{id}/transition
POST /api/items/{id}/claim
POST /api/items/{id}/dependency
POST /api/items/{id}/comment
POST /api/items/{id}/evidence
POST /api/items/{id}/handoff
POST /api/items/{id}/accept-handoff
POST /api/items/{id}/block
```
## MCP
Stdio mode never opens a second production database in the intended deployment topology; run it
against a local database only during development:
```sh
cargo run -p akurai-tasks -- --db data/tasks.db --actor agent-id mcp
```
The serving process exposes the same JSON-RPC dispatcher at authenticated `POST /mcp`. The
31-tool catalog covers projects (create, update, archive, unarchive, delete, purge), repository
binding, work create/list/get/query, transitions, claims and lease renewal/release, comments,
evidence, dependencies, handoffs, blocking, boards, Ready frontier, imports, audit events, and
`system_doctor`. It also exposes `tasks://projects` and the `next-task` prompt. `project_delete`
removes an empty project only; `project_purge` deletes a project with all its work items and
history; `project_archive`/`project_unarchive` toggle the reversible `archived` flag.
Run a local catalog check without touching production data:
```sh
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' |
akurai-tasks --db /tmp/akurai-tasks-catalog.db --actor local-catalog mcp
```
## Architecture and boundaries
- Framework checkout: `/home/olafurbui/Projects/AkurAI-Framework` on Titan.
- Hindsight remains authoritative for conversational memory.
- AkurAI Notes notebook **AkurAI-Tasks** (ID 34) remains the architecture/operations record.
- AkurAI PassVault folder **AkurAI-Tasks** (ID 5) is the only approved credential store.
- ACP connects editors to agents; AkurAI-Tasks is the MCP tool server, not an ACP task store.
- Agents operate persistent Tasks, Notes, Memory, PassVault, and Build state through configured MCP tools only. CLI examples in this README are local development examples with disposable state.
See AkurAI Notes note 139 (`AkurAI-Tasks — PLAN`) for production hardening, lossless import,
backup/restore, source fencing, deployment, and cutover acceptance gates.