veritas-kanban: Open Source Project & Work Management

What is veritas-kanban?

Veritas Kanban is a local-first Kanban task board with optional AI agent orchestration, built for developers and small teams who want project truth to stay on their own machine instead of in a hosted service. The board itself is a visual Kanban board, and the agent layers — CLI, MCP, OpenClaw, Squad Chat webhooks, workflows, and governance gates — are optional additions that can be switched on later.

What it is

Veritas Kanban is a TypeScript project, licensed MIT, that combines a visual task board with an orchestration harness for AI agents. It lives in the developer-tools and DevOps tooling ecosystem, with topic tags that name the agent communities it interoperates with: agents, ai-agents, codex, hermes, openclaw, local-first, kanban, and pino logging. The README describes it plainly as a "local-first task management board with optional AI agent orchestration," versioned at 6.2.1 and built for TypeScript 6.0. The registry record shows 831 stars, 99 forks, and 6 open issues.

The concrete problem it solves is the split between a task board and the agents working against it. Rather than hosting project state in a remote SaaS product and wiring an assistant to it afterwards, Veritas Kanban runs the board locally and exposes it to agents through explicit, gated interfaces: an MCP server, CLI access, an OpenClaw gateway or browser relay, and Squad Chat webhooks. Optional workflow gates and governance policies can supervise what an agent is allowed to do against active tasks. The project replaces the hosted, always-online board for the part of its audience that wants task data to remain on local disk.

Key capabilities

Runs a local Kanban board whose UI defaults to http://localhost:3000.
Offers discrete setup paths documented in docs/SETUP-PATHS.md: board-only, CLI, MCP, OpenClaw, and self-hosted.
Provides an MCP server for agent integration, with MCP write access treated as a separately gated capability.
Supplies a health endpoint at http://localhost:3001/api/health so readiness can be verified before an assistant is given access.
Ships a signed and notarized macOS desktop app through Homebrew from the BradGroux/tap tap.
Auto-seeds example tasks on first run; they can be cleared with rm tasks/active/task_example_*.md and the board re-seeded.
Supports optional OpenClaw gateway and browser relay, Squad Chat webhooks for external wake, notification delivery channels, workflow gates, and governance policies.

Who uses it and how

Individual developers on macOS install the packaged app via the Homebrew cask and keep a private board without any hosted dependency.
Small teams run it from source with pnpm dev, then choose one layer at a time, running read and write smoke checks before handing the board to an assistant.
Agent-heavy workflows enable the MCP server, OpenClaw browser relay, or Squad Chat webhooks when an assistant needs to wake on new tasks or report results back.
DevOps and developer-tools practitioners use workflow gates and governance policies to constrain what automated agents may change on the board.
Teams focused on design-thinking processes use the Kanban surface for their working board while keeping agent orchestration as a separate, revocable layer.

Getting started

Install the signed Mac desktop app with brew tap BradGroux/tap followed by brew install --cask veritas-kanban. For a source checkout, clone the repository, run pnpm install, copy server/.env.example to server/.env and set VERITAS_ADMIN_KEY, then start with pnpm dev.

How it compares

The facts provided list no paid products that Veritas Kanban replaces, and no directly similar tools are named in its topics or README. Within this registry it stands alone as a local-first Kanban board with first-class agent orchestration.

When to use it — and when not to

A self-hoster must be willing to run a Node and pnpm toolchain, maintain server/.env, set VERITAS_ADMIN_KEY, and manage ports 3000 and 3001; desktop users also need to follow the ordered Mac upgrade path covering backup, heartbeat pause, app replacement, and version readiness. Not a fit for teams that want a zero-ops hosted service or that will not maintain optional layers, and the README itself warns against enabling OpenClaw, MCP write access, Squad Chat webhooks, notifications, workflow gates, or governance policies on day one unless already known to be needed.

project readme (upstream, from github) — read inline

⚖️ Veritas Kanban

Veritas in actis — Truth in action.

Local-first task management board with optional AI agent orchestration.

Start with a visual Kanban board. Add CLI, MCP, OpenClaw, Squad Chat webhooks, workflows, or governance only when you need that layer.

Veritas Kanban 6.2.0 candidate board-to-task interaction

🎬 Watch the full demo video

⭐ If you find this useful, star the repo — it helps others discover it!

Quickstart · Features · Why VK · All Features · Docs · Troubleshooting · API · Agent Setup · MCP Server · Contributing · Changelog

Created by Brad Groux — CEO of Digital Meld, and host of the Start Small, Think Big podcast · LinkedIn · Twitter · YouTube

⚡ Quickstart

Start with the local board. OpenClaw, MCP, Squad Chat webhooks, notifications, workflows, and governance gates are optional layers you can turn on later. See Setup Paths for the board-only, CLI, MCP, OpenClaw, and self-hosted paths.

Want to take the easy way out? Ask your agent:

Clone and set up veritas-kanban locally using the board-only setup path first. Install dependencies with pnpm, copy server/.env.example to server/.env, and start the dev server. Verify the UI at localhost:3000 and the API health endpoint at localhost:3001/api/health. Do not configure OpenClaw, MCP, Squad Chat webhooks, workflows, or notifications unless I explicitly ask for that layer.

Want to do it yourself? Choose the packaged Mac app or a local source checkout:

For the packaged Mac desktop app:

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

Existing desktop users should follow the routine Mac upgrade path so backup, heartbeat pause, app replacement, launch, and exact-version server readiness happen in the right order.

For local source development:

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

Open http://localhost:3000 for source runs, or install the signed/notarized Mac app with brew tap BradGroux/tap && brew install --cask veritas-kanban. The board auto-seeds with example tasks on first run so you can explore right away.

A working board means the UI loads and http://localhost:3001/api/health returns healthy. Agent-ready and external wake/delivery-ready are separate setup levels; use Setup Paths before adding those layers.

Do not configure these on day one unless you already know you need them:

OpenClaw gateway or browser relay
MCP write access
Squad Chat webhook or external wake behavior
Notification delivery channels
Workflow gates or governance policies

When the board is working, use Setup Paths to choose the next layer and run the read/write smoke checks before handing the board to an assistant.

Want a clean slate? Delete the example tasks: rm tasks/active/task_example_*.md and refresh. Want to re-seed? Run pnpm seed to restore the example tasks (only works when the board is empty).

Note: Never commit .env files. Use .env.example as a template — it contains safe placeholder values and documentation for every variable.

📚 Documentation Map

Setup Paths — start here for board-only, CLI, MCP, OpenClaw, and self-hosted paths without mixing optional layers into first-run setup.
Getting Started Guide — zero ➝ agent-ready in 5 minutes, plus sanity checks and prompt registry tips.
MCP Server Guide — optional MCP setup, 42 tools, architecture, tool catalog, security model, and read/write smoke checks.
Agent Guide and AGENTS.md Template — shared managed-run protocol, external self-reporting template, and unmanaged MCP setup.
Agent Providers — evidence-backed Buzz, Grok Build, Codex, Claude Code, Copilot CLI, Hermes, OpenClaw, and optional model profiles.
v6 Agent Runtime Control Plane — authority, adapter, lifecycle, approval, tool, credential, Buzz, and certification boundaries.
Phase Capability Profiles — versioned execution-phase authority contracts, deterministic intersections, exact-path plan artifacts, and current delivery boundaries.
Phase Transition Journal — durable compare-and-set transitions, approval and override controls, restart recovery, REST, and CLI operations.
Run Access Summary v1 — one redacted, digest-bound view of a run's filesystem, network, tools, integrations, budgets, support, and historical authority.
Knowledge Collections v1 — immutable sources, cited pages, stable identity, bidirectional links, and reversible reviewed ingestion with file/SQLite parity.
OpenAI Codex Integration — local execution, SDK and app-server sessions, cloud delegation, MCP setup, workflows, and telemetry.
Codex Integration SOP & Codex Workflow Examples — operational playbooks for using Codex as a first-class Veritas agent.
API Reference — Auth, endpoints, request/response examples, WebSocket, common workflows.
Identity and RBAC Model — users, workspaces, memberships, roles, agent tokens, permission matrix, migration, and UX flows.
v6 GA Checklist — release gates for harness certification, migration, runtime, desktop, and distribution evidence.
v6 Visual Tour — release-safe views of provider support, Buzz setup, approvals, and run evidence.
v6 Upgrade, Install, Remote, And Admin Guide — fresh install, v5-to-v6 upgrade, harness setup, desktop, backup, and diagnostics paths.
v6 Compatibility And Release Policy — provider support tiers, tested builds, platform combinations, update channels, and rollback limits.
v6 Release Notes — user-facing highlights, stabilization fixes, install/upgrade steps, behavior changes, and known limits.
Desktop Architecture ADR — shell decision, native/server boundaries, connection modes, lifecycle, packaging, and security model.
Post-GA Native Mobile Offline ADR — native mobile authority model, offline queue semantics, conflict handling, and security review.
Post-GA Cloud Sync And Hosted SaaS ADR — optional hosted model, tenant isolation, lifecycle, support, cost, and migration boundaries.
Self-Hosting Guide — production deployment, reverse proxy, auth hardening, Docker, and backups.
Agent Task Workflow SOP — lifecycle, API/CLI snippets, prompts.
Squad Chat Protocol — agent messaging, system events (spawned/completed/failed), model attribution, and helper scripts.
Buzz Integration — signed Squad Chat bridging, explicit persona/team import, and a separate disabled-by-default buzz-agent profile under the generic ACP provider.
Agent Providers — exact-version Grok Build, GitHub Copilot CLI, Buzz Agent, Claude Code, and Codex runtime setup, safet

Frequently asked questions

Is veritas-kanban free to use?

veritas-kanban is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does veritas-kanban do?

Lightweight orchestration harness built for your AI agents. The unfiltered truth about where your project stands.

What is veritas-kanban written in?

veritas-kanban is primarily written in TypeScript. Its source is publicly available at https://github.com/BradGroux/veritas-kanban, and it has 831 GitHub stars.