a5c-ai/kanban: The Kanban Board That Treats Git Like a Database
Each card action becomes an append-only operation file. The board is rebuilt from Git history, so humans, terminals, web UI, and agents all share one deterministic source of truth.
- a5c-ai/kanban turns Git into the board's database by storing every action as a small op file and rebuilding state from the log.
- Append-only writes shrink merge pain because collaborators usually touch separate files instead of one mutable board document.
- The SDK is the real product surface, and the web app, TUI, and VS Code extension are just different windows onto the same engine.
- The .a5c layer makes the repo agent-friendly by design, so humans and AI can act through the same history.
The board is not the database
The smartest thing in a5c-ai/kanban is not the UI. It is the refusal to store the board as a mutable board. Every move, rename, and edit becomes a small operation file under .kanban/ops/, and the current state is reconstructed from that log whenever the app needs it.
That flips project management on its head. Git is not just syncing the board. Git is the board's transaction log, merge layer, and audit trail. Once that clicks, the repo stops looking like a productivity tool and starts looking like coordination infrastructure.
That design matters because project work is now shared by people and agents. When truth lives in append-only files, different actors can work in parallel without negotiating over one giant mutable JSON blob. The system can rebuild the same board every time because order is explicit, not implied.
How one card move becomes a file
The command layer in packages/sdk/src/commands.ts does the writing. It validates the action, calculates placement using gap-based positions, and appends a JSON op with a 16-digit sequence prefix. The prefix gives the log a stable order, even when several contributors land changes at once.
.kanban/ops/0000000000000001-7c2a.json
type: createCard
cardId: card_42
listId: backlog
title: Ship conflict-aware rebuild
.kanban/ops/0000000000000002-91df.json
type: moveCard
cardId: card_42
from: backlog
to: doingOn the way back up, the reducer reads the entire op log and reconstructs normalized state. Workspaces, boards, lists, and cards are derived from history, which is why the same repo can render cleanly in a browser, a terminal, or inside VS Code without a separate sync service.
Why merge conflicts get smaller instead of worse
Most board apps make everyone fight over one shared file or one shared record. This repo spreads that risk across many tiny files. Two people can create two cards without touching the same bytes, and Git does what Git is good at. The conflict detector only has to step in when two ops target the same entity or field.
| System | Source of truth | Merge behavior | Agent posture | What it optimizes |
|---|---|---|---|---|
| Trello, Jira, Linear | Central database | Hidden synchronization around shared state | Human-first | Polished workflows and permissions |
| vibe-kanban | Git worktrees per agent | Isolation first, then code merges | Agent-forward | Parallel coding without overwrite risk |
| OpenClaw, KANBAII, KaibanJS | Framework state and task layer | Depends on the framework | Orchestration-first | Visibility and control of agent work |
| a5c-ai/kanban | Append-only op files in Git | Small files merge cleanly, reducer rebuilds state | Human and agent share the same log | Deterministic project truth |
Project management tools like Jira, Linear, and Notion were designed for human-to-human coordination. They assume a person reads the ticket, understands the context, and writes the code. That assumption is breaking down fast.
That is the market this repo is aimed at. If agents are reading tickets and writing code, the project record has to behave like code too. The cleaner the log, the less the board depends on tribal memory.
One engine, three surfaces
The SDK is the center of gravity. The web app, TUI, VS Code extension, and demo app are front doors, not separate products. They all call the same commands and lean on the same Git adapter, which wraps the Git CLI instead of hiding it behind a new database.
The monorepo layout keeps that separation clean. TypeScript, pnpm workspaces, tsc -b, and Node's native test runner all point in the same direction: standard tools, explicit boundaries, no framework tax. A card moved in the terminal shows up the same way in the browser because the repo, not the UI, owns the truth.
The AI layer is not an add-on
The .a5c directory is the tell. It contains Markdown and JavaScript functions that read like playbooks for work, not just docs for humans. The project is built so an agent can inspect the same repo state, act on the same log, and leave behind the same audit trail.
This is where the idea behind vibe-kanban comes in: stop treating AI agents like chatbots you talk to. Start treating them like asynchronous workers you manage.
That line could sit under this repo too. The point is not that the board is AI-themed. It is that the coordination layer is legible to AI because it is already legible to Git.
What it replaces, and what it is not
This repo is not trying to win on polish against Trello, Jira, or Linear. It is trying to make the data model honest. If the board is a repo, then offline use, mergeability, and machine readability stop being features and become defaults.
It also is not just a clone of newer agent boards. Tools like vibe-kanban, OpenClaw Kanban, and KANBAII focus on orchestrating agent work. a5c-ai/kanban goes deeper and changes where state lives. That is a harder problem, but it is the one that lets every interface share one source of truth. In other words, this is a coordination system that happens to look like a Kanban board, not a Kanban board that happens to talk to Git.
