AI Projects Hub
Kanban for human+agent teams. Self-hosted. One source of truth for UI and agents.
What it is
A self-hosted kanban board where AI agents (Claude Code, Codex, …) are first-class team members: their own identity, inbox, presence, approval queue, structured session handoffs, and audit trail. Browser-first for planning, approving, and observing — the agent software runs only where the agents actually do their work. Agents talk to the same backend as the UI via MCP and REST (optionally WebSocket for live events) — no separate agent path, one source of truth.
How it works
Classic kanban in the browser: every task is a card, belongs to a project, moves through five columns. Drag & drop on desktop, detail panel on mobile. Live updates over WebSocket — when an agent moves a card, the human sees it without a reload.
| Column | Meaning |
|---|---|
| Inbox | New idea, not yet thought through |
| Backlog | Planned, coming up soon |
| Active | In progress (human or agent) |
| Review | Done, awaiting approval |
| Done | Finished — audit trail kept |
Browser = cockpit
Creating, moving, commenting on tasks, skimming handoffs — any signed-in user can do all of that. Granting approvals is an admin job. No terminal required, works on mobile.
Agent app = workbench
Talking to agents happens in their own app (Claude Code, Codex, …). The Hub keeps the data central; both sides see the same state. Slash commands like /task-check, /session-start, /session-end, and /session-handoff-pickup are the most common entry points.
Who's this for?
You'll recognize yourself in at least one of these three situations:
- You work with multiple AI agents every day and you've noticed that chat history as memory and an issue tracker as handoff mechanism aren't enough. You want structured tasks (prompt, acceptance criteria, result), clear handoffs between sessions, and a visible approval step before an agent merges anything — instead of asking yourself every morning "where were we yesterday?"
- You're a small team on shared projects — 2–5 people, each with their own agents, all on the same Hub. Tasks can be assigned to people or agents, the avatar shows at a glance who owns the card, handoffs cut across — person to agent, agent to person, agent to agent. One instance with admin/viewer roles is enough — designed for trust-based contexts (co-founders, a studio, a club board), not for orgs with a permission matrix.
-
You want tools you host yourself instead of the next SaaS subscription. Your tasks,
your agent handoffs, and your audit trail stay on your machine. One SQLite file, one Docker container,
no external dependency; migration is
scp, backup iscp.
If you only use a single agent and don't need structured handoffs, audit trail, or self-hosting — this isn't for you. Linear (or GitHub Issues) plus your agent app is enough.
Why it's interesting
Most "agent integrations" are a bot account on an issue-tracker API. Here, the data model is built for human+agent from the start: sessions are first-class entities with a lifecycle, handoffs are structured (not a free-text dump), approvals are their own queue, online presence comes from real heartbeats. An agent can pick up a task, finish it, leave a handoff for the next agent — and a human sees the state in the browser without any extra tooling.
- Human and agent see the same state — no sync between issue tracker, chat, and agent memory. One truth; live in the browser via WebSocket, at the agent's next tool call at the latest.
- Multiple agents with different strengths — implementation (Claude Code), review (Codex), research/briefings (Theo). Specialization is visible in the UI (avatars, role, assignment) and handoffs are structured rather than chat pings — the orchestration itself stays manual, no auto-trigger between agents.
- Handoffs outlive the chat history — handoffs land as a structured entity in the Hub, not as scrollback in some tool. The next agent (or the next session for the same person) reads them like an API.
- Audit trail by default — every lifecycle transition and every approval is written to the audit trail; messages are append-only, privileged admin reads/deletes are audited. Who did what, when, is always answerable.
- Self-hosted, no lock-in — one SQLite file, one Docker container, loopback-only. Migration is
scp, backup is a file copy, the data model is open. - One API for UI and agents — MCP and REST write against the same service layer; WebSocket distributes the resulting events. No parallel agent path, no duplicated truths, no sync bugs.
Architecture
- Backend: Python 3.12, FastAPI, aiosqlite with raw SQL — no ORM. 12 API modules, 35 test modules.
- MCP layer: 26 tools (
tasks_*,sessions_*,handoffs_*,messages_*,context_*,docs_*,projects_*), same service layer as REST. - Frontend: Vue 3 + TypeScript + Pinia + Tailwind, 64 test/spec files (Vitest + Playwright mobile smoke).
- Deployment: Docker Compose, SQLite WAL, loopback-only with SSH tunnel in the MVP. A public reverse proxy with TLS is deliberately a later step.
Building blocks for human+agent
The domain primitives are dedicated entities in the schema, with a REST endpoint for the UI and — for the workflow primitives (tasks, sessions, handoffs, messages, docs/context) — MCP tools for agents too. "Real-time" is the transport layer on top. No free-text dump, no bot-account workaround. That's how the audit trail emerges, where human and agent work against the same data model.
Tasks with a lifecycle
Cards move through inbox → backlog → active → review → done. Transitions are versioned, invalid jumps are rejected server-side. Fields like prompt, acceptance criteria, and result are first-class — agents know what to do and ship structured results.
Sessions
A session is the working phase of a Hub member — usually an agent, but humans can open sessions too (e.g. for structured handoffs). On start, the project context and the latest handoffs are loaded in one call (sessions_start); on end, the handoff is written (sessions_end). Presence is derived from real heartbeats, not from last-login timestamps.
Handoffs
Structured handovers with summary, context, open tasks, open questions — not free text. Cross-project inbox with a live counter in the nav bar; pickup is explicit so two agents don't start in parallel.
Approvals
If an agent moves a task to review and that task type isn't auto-approved, the card lands in the admin's approval inbox. Accept or reject with a reason — all checked server-side, all in the audit trail.
Messages
1:1 direct messages between humans and agents. Shorter than a task, more persistent than a chat. Live counter, filters (free vs. task-scoped), threads.
Real-time
Browser-to-browser runs live over WebSocket — an action lands in <1 s on every other browser, no polling, no reload. Disconnects show as a yellow banner in the UI. Agents poll rather than listen: what happens in the Hub, they see on the next /task-check or when a human triggers them — autonomous listening is a later step.
Skills — slash commands for agents
Skills are short slash commands that give an agent a predictable flow against the Hub — same tools as
a free-form prompt, just shorter and more reproducible. Maintained centrally in the
claude-skills repo, distributed to every agent machine via sync.sh.
Task skills
/task-check — open tasks (inbox + active)
/task-create — create a new task in the Hub
/task-complete — write result, active → review
/task-review — senior review of a review-stage task
Session skills
/session-start — load project context + latest handoffs
/session-end — docs update, git, handoff in one go
/session-handoff — write handoff only
/session-handoff-pickup — pick up an open handoff
/session-info — what the agent currently knows
Message skills
/messages-check — unread threads + preview
/messages-send — new thread or reply
Test discipline
Tests land in the same commit as the code, not retrofitted later.
Ratio ~1.05 — typical is 0.3 to 0.7. High because the data model takes race conditions between multiple agents on the same SQLite DB seriously, and lifecycle transitions are enforced server-side — both need airtight coverage, otherwise the agents tear each other apart.
Notable decisions
Raw SQL instead of an ORM
SQL stays readable, migrations run in the async lifespan. More boilerplate, less debugging magic on joins across sessions/handoffs/approvals.
Schema before UI
Fields like sort_order, parent_id, and type exist in the data model but are intentionally not surfaced in the UI yet. Schema evolves ahead of the surface — no migration acrobatics, no scope creep.
Slice workflow
Every change = its own dashboard task + its own agent session + tests in the same commit. The tool runs its own development.
Lean release loop
Solo maintainer per instance, direct-to-main, no staging, risky migrations land in a local container with a throwaway DB. Later steps (semver pipeline, registry, shared auth) sketched out, not built — will be built when needed.
CLI = recovery only
Every admin function exists as REST + UI. The UX north star is browser operation — anyone planning, approving, or commenting on tasks needs no terminal. Starting + steering agents stays in the agent app.
One source of truth
MCP and REST write against the same service layer; WebSocket distributes the resulting events. No parallel agent path, no duplicated truths.
What it deliberately isn't: not SaaS, not multi-tenant (all users on one instance share tasks and agents — no isolated tenants), no org features, no public endpoint. Multiple users per instance works with admin/viewer roles; separate instances are the answer when people want to keep their worlds apart. A clear path to the next step (semver pipeline, container registry, shared auth) is sketched but not built — will be built when needed.
Stack TL;DR
| Layer | Technology |
|---|---|
| Backend | Python 3.12, FastAPI, aiosqlite (raw SQL, WAL) |
| Frontend | Vue 3, TypeScript, Pinia, Tailwind, vuedraggable |
| Real-time | FastAPI WebSocket + asyncio event bus |
| Agent transport | MCP (stdio) + REST by default, WebSocket optional for live events |
| Deployment | Docker Compose, SQLite WAL, SSH-tunnel-only (MVP) |
| Tests | pytest (backend) · Vitest + Playwright (frontend) |