Veritas Kanban: a local-first board that agents can also write to

The problem Veritas Kanban picks: a board your agents can actually read

Most task trackers assume a human is the only writer. Agents break that assumption in an awkward way: they need to read what is assigned, claim work, and report back, but they usually do it through a hosted API that the team does not control and cannot inspect offline. Veritas Kanban takes the opposite route. The repository describes it as a "Local-first task management board with optional AI agent orchestration," and the setup instructions keep the board and the agent wiring in separate steps on purpose.

The intended audience is a developer or a small team already running CLI coding agents such as Codex, Claude Code, Copilot CLI or OpenClaw, who wants the board to be the source of truth rather than a chat transcript. The Quickstart makes the layering explicit: OpenClaw, MCP, Squad Chat webhooks, notifications, workflows and governance gates are described as "optional layers you can turn on later," and the README lists them under a blunt warning not to configure them on day one unless you already know you need them.

That is a real design position, not marketing. A pure Kanban board is a solved problem, and the project does not pretend otherwise. What it sells is the boundary between the board and the agents, and the documentation spends most of its length on that boundary.

How the board, the server and the agent control plane fit together

The repository is a pnpm workspace with separate packages for shared code, the server, the web UI, the CLI, the MCP server, and a desktop app. The root package.json declares "private": true and pins the toolchain to Node >=22.22.1 and pnpm >=11.0.0. The dev script runs the server and the web app concurrently, which is why the Quickstart expects two things to come up: the UI on port 3000 and the API on port 3001.

Tasks live on disk. The README gives the example-task cleanup as `rm tasks/active/task_example_*.md`, which tells you the storage format is markdown files under a tasks directory rather than rows in a database you cannot open. The board auto-seeds with example tasks on first run, and `pnpm seed` restores them, with the documented caveat that seeding only works when the board is empty.

The agent side is described in the docs map as a control plane: authority, adapter, lifecycle, approval, tool, credential and certification boundaries. Phase capability profiles are described as versioned execution-phase authority contracts with deterministic intersections, and the phase transition journal as durable compare-and-set transitions with approval and override controls plus restart recovery. In plain terms, the project does not just let an agent move a card. It records which phase the run is in, what that phase is allowed to touch, and what happened when the phase changed. Whether that machinery is proportionate depends on how much you trust the agent writing to your board.

Installing Veritas Kanban and getting a working board

There are two documented install paths. The packaged macOS desktop app comes from a Homebrew tap, and the README notes that existing desktop users should follow the routine Mac upgrade path so backup, heartbeat pause, app replacement, launch and version readiness happen in order.

brew tap BradGroux/tap
brew install --cask veritas-kanban

For source development, clone the repository and install with pnpm. The environment file is copied from the example in the server package, and the README flags the one value you should change.

git clone https://github.com/BradGroux/veritas-kanban.git
cd veritas-kanban
pnpm install
cp server/.env.example server/.env   # Edit to change VERITAS_ADMIN_KEY
pnpm dev

After `pnpm dev`, open http://localhost:3000 for the board. The README defines a working setup as the UI loading and `http://localhost:3001/api/health` returning healthy, so check that endpoint before doing anything else. The .env.example marks VERITAS_ADMIN_KEY as required and suggests generating it with `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`. It also documents VERITAS_JWT_SECRET, warning that if you omit it the server auto-generates one and tokens will not survive restarts, and VERITAS_AUTH_LOCALHOST_BYPASS, which the file says to keep disabled unless you explicitly need it.

There is also a Docker Compose file, but its own header calls it local testing only, binds to 127.0.0.1:3099 and uses a demo admin key that the file states is not a deployment credential. Treat it as a walkthrough, not a deployment recipe.

Where Veritas Kanban is the wrong tool

The honest limitation is that this is a single-operator system with an agent-shaped extension, not a multi-tenant project tracker. The identity documentation describes users, workspaces, memberships, roles and agent tokens, so a permission model exists, but nothing in the repository suggests you should hand this to a fifty-person organisation as its planning system. If your team needs hosted access from anywhere without running a server, this is the wrong choice.

The second constraint is the toolchain. The root package.json requires Node 22.22.1 or newer and pnpm 11 or newer, so a team pinned to an older LTS line cannot build from source without changing its environment. That is a hard gate, not a preference.

The third is operational. The README's own list of things not to configure on day one exists because each layer adds failure modes: webhook delivery, external wake behaviour, notification channels, workflow gates. Turning them all on before the board is stable makes it hard to tell which layer broke. The docs map also points to a troubleshooting file, which is a reasonable signal that first-run problems are expected rather than exceptional.

Finally, the README does not document rollback for the optional layers. There is an upgrade guide for the Mac desktop path, but if you enable MCP write access and want to walk it back, the documentation does not describe a supported reversal procedure.

Veritas Kanban versus a hosted tracker with an API

The natural alternative is a hosted board such as a SaaS Kanban product with a REST API and a webhook surface. The difference is not features, it is where the state lives and who can read it. A hosted tracker keeps tasks in someone else's database, gives you an API token, and expects integrations to be built against that API. Veritas Kanban keeps tasks as markdown files in a directory you own, and the README's cleanup instruction is a plain `rm` command rather than a delete endpoint.

That changes the failure modes. With a hosted tracker, the risk is API rate limits, token rotation and vendor outages. With Veritas Kanban, the risk is your own machine: a corrupted working directory, a lost .env file, or an agent with write access that misreads a task. The project's answer to the last one is the control plane described in its architecture docs, with phase authority contracts and a transition journal. A hosted tracker's answer is usually an audit log you query after the fact.

If your agents already run locally and you want to inspect what they were told to do without a network round trip, the local-first model is the better fit. If your agents run in the cloud and your team is distributed, the file-based model becomes an operational burden you have to solve yourself.

Maintenance, licence and what an upgrade costs

The repository is not archived, and the last push was on 2026-09-10. Releases are frequent and small: v6.2.1 on 2026-09-10, v6.2.0 on 2026-09-08, and v6.1.7 on 2026-09-04. Patch releases three days apart suggest active iteration, and the version badge in the README tracks the current release, so the documentation is kept in step with the code rather than drifting.

For upgrade cost, the documentation is uneven. The Mac desktop path has a documented routine upgrade sequence with explicit ordering: backup, heartbeat pause, app replacement, launch, and server readiness at an exact version. The source path has no equivalent guide, so a source user has to read the changelog and the v6 GA checklist, which the docs map describes as release gates for harness certification, migration, runtime and desktop. That asymmetry matters if you run from source.

The licence is MIT, and the package.json declares it as such. That is permissive: you can use, modify and redistribute the code with the licence and copyright notice preserved. It says nothing about the data you put in the board or about any third-party agent provider you connect, and it is not a substitute for reading the actual licence file before you ship a derivative.

Editorial conclusion

Adopt Veritas Kanban if you want a board you can read and edit as plain files and you plan to let agents touch it deliberately, one layer at a time. Do not adopt it as a hosted multi-team service or if you cannot run Node 22.22.1 and pnpm 11, since the source path enforces both. Before handing the board to an assistant, confirm that http://localhost:3001/api/health returns healthy and run the read/write smoke checks described in docs/SETUP-PATHS.md.

Frequently asked questions

Official sources

1. BradGroux/veritas-kanban on GitHub
2. License: MIT
3. Project website
4. README
5. Releases