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

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? Get up and running in under 5 minutes:

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 — that's it. The board auto-seeds with example tasks on first run so you can explore right away.

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.

• 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, 36 tools, architecture, tool catalog, security model, and read/write smoke checks.
• OpenAI Codex Integration Roadmap — optional local execution, SDK sessions, cloud delegation, MCP setup, workflows, telemetry, and release QA.
• Veritas Cutover Operating Guide — authority model, HermesAgent roster, QA evidence gate, and GitHub-backed task templates.
• 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.
• 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.
• Sprint Planning SOP — epic → sprint → task breakdown.
• Multi-Agent Orchestration — PM + worker handoffs.
• Cross-Model Code Review — enforce Claude ↔ GPT reviews.
• Agent Governance SOPs — Policy engine, drift detection, decision audit, output evaluation, user feedback.
• Operational SOPs — Broadcasts, delegation, deliverables, prompt registry, squad chat, system health.
• Best Practices & Tips + Tricks — patterns, shortcuts, integrations.
• Real-World Examples — copy/pasteable agent recipes.
• Troubleshooting — deeper diagnostics when things wobble.

1. Run locally first. Keep your board and agents on your own machine until you fully understand the behavior. Never expose an unauthenticated instance to the internet. Veritas Kanban includes built-in API rate limiting, but if you deploy publicly, still add a reverse proxy (nginx, Caddy, Cloudflare) with edge-level rate limiting in front of it.

2. Never trigger agents from uncontrolled inputs. Don't let inbound emails, webhooks from third parties, or public form submissions automatically spawn agent work. An attacker who can craft an input can control your agent.

3. Principle of least privilege. Give agents the minimum permissions they need. Use the agent role (not admin) for API keys. Restrict file system access. Don't run agents as root.

4. Review before merge. Agents can write code — that doesn't mean the code is correct or safe. Always review agent-generated code before merging to production branches. Use the built-in code review workflow.

5. Set boundaries on destructive actions. Agents should not have unsupervised access to rm, git push --force, database drops, or production deployments. Require human approval for irreversible operations.

6. Monitor and audit. Use time tracking and activity logs to understand what agents are doing. Review agent-completed tasks. Check git diffs before pushing.

7. Rotate credentials regularly. If an agent has access to API keys, tokens, or secrets, rotate them on a schedule. Don't embed real credentials in task descriptions or prompts.

8. Isolate environments. Run agents in containers, VMs, or sandboxed environments when possible. Keep agent workspaces separate from sensitive data.

The bottom line: Agentic AI is transformational, but it amplifies both your capabilities and your mistakes. Plan accordingly, start small, and add autonomy gradually as you build confidence in your guardrails.

Policy Engine — Define what agents can and can't do. Configurable tool/action policies with allow, deny, and require-approval guard rules. Every policy decision is logged. Decision Audit Trail — Log agent decisions with confidence scores, supporting evidence, and stated assumptions. Record outcomes afterward to see whether assumptions held. Behavioral Drift Detection — Set metric baselines and thresholds; get alerted when an agent's behavior deviates. User Feedback Loop — Collect feedback on agent outputs with sentiment tagging and category analytics. Output Evaluation — Score agent outputs against weighted criteria profiles (regex, keyword, numeric range, custom expressions).

Spawn autonomous coding agents on tasks when you choose to connect an agent runner. Track them in real-time with the multi-agent dashboard — status indicators, expandable agent cards, model attribution. Squad Chat gives agents a shared local communication channel with system lifecycle events (spawned, completed, failed). Assign multiple agents per task, set permission levels (Intern/Specialist/Lead), and let them coordinate.

Veritas now documents the GitHub-backed operating model for Codex and HermesAgent work. The new cutover guide names Veritas as the source of truth, routes HermesAgent/Hermes Gateway as the control plane for agent execution, keeps Mission Control focused on display/control, and makes GitHub Issues/PRs/reviews/CI the implementation record. It also adds the active Hermes roster, required QA evidence gates, and copy/paste task templates for product specs, research/revenue intake, and approval-gated client workflows.

Codex can run as a first-class Veritas agent through local codex exec, SDK-backed sessions, GitHub-native @codex delegation, workflow-engine steps, review actions, Settings health checks, and MCP access to the board. The docs include a roadmap, SOP, workflow examples, and an AGENTS template so Codex work can be started, tracked, reviewed, and released through the same Veritas lifecycle as other agents.

Draggable & Resizable Widget Grid — Rearrange and resize dashboard widgets via drag-and-drop. Layouts persist across sessions. Add widgets from the library or remove ones you don't need. Global System Health Bar — Persistent header status bar with five health levels (stable → alert) across three signal categories: system resources, agent availability, and operation success rate.

Version-controlled prompt templates with variable extraction, full version history with rollback, usage tracking, and preview rendering with sample variable injection. Manage your prompt library the same way you manage code.

Define multi-step agent pipelines as version-controlled YAML. Sequential steps, parallel fan-out/fan-in, loop iteration over collections, gate approvals with human-in-the-loop, and retry routing. Think GitHub Actions — but for AI agents. Live execution view with step-by-step progress. Monitoring dashboard with success rates, active runs, and per-workflow health metrics.

Not just cards on a board. Tasks have dependency graphs with cycle detection, crash-recovery checkpointing (auto-sanitizes secrets), observational memory with importance scoring, time tracking, and full activity logs. Enforcement gates (review gates, delegation enforcement, auto-telemetry) add production guardrails — all optional, all toggleable.

Isolated worktrees per task — no branch switching, no conflicts. Built-in code review with unified diff viewer and inline comments. Approval workflows (approve, request changes, reject). Visual merge conflict resolution. Create GitHub PRs directly from the task detail panel. Bidirectional GitHub Issues sync with label mapping.

Tasks are markdown files. Settings are JSON. Workflows are YAML. No database, no Redis, and no Docker required for local use. Clone, pnpm install, pnpm dev — done. Everything is grep-friendly, version-controllable, and human-readable. Back up your entire board with git push.

• MCP Server — 36 tools across 8 categories via Model Context Protocol
• CLI — vk begin <id> / vk done <id> "summary" replaces 6 API calls with 2 commands
• REST API — Full lifecycle management. If it can make HTTP calls, it can drive the board.

📋 Full feature reference with every config option: docs/FEATURES.md

Most agentic AI tools fall into one of two camps: orchestration frameworks that are powerful but invisible (CrewAI, AutoGen, LangGraph) — or project boards that look nice but have zero agent awareness (Jira, Linear, Notion).

Veritas Kanban is neither. It's the visual command center for agentic work — where you can see what your agents are doing, what they've done, and what they're about to do, with full audit trails and production guardrails.

The bottom line: Orchestration frameworks give you agent execution without visibility. Project boards give you visibility without agent execution. Veritas Kanban gives you both — plus the guardrails, telemetry, and audit trails that production agentic work demands.

Built and battle-tested with OpenClaw, with docs for Codex and HermesAgent/Hermes Gateway workflows. OpenClaw is optional. VK works with any platform that can make HTTP calls.

  Any AI Agent / CLI / MCP Client
           │
           ▼
┌──────────────────────────────┐
│      REST API + WebSocket    │
│    http://localhost:3001     │
│                              │
│  ┌───────┐  ┌───────────┐    │
│  │ Tasks │  │ Workflows │    │
│  │  API  │  │   Engine  │    │
│  └───┬───┘  └─────┬─────┘    │
│      │            │          │
│      ▼            ▼          │
│   Markdown    YAML Workflows │
│    Files       + Run State   │
└──────────────────────────────┘
           │
           ▼
   React 19 + Vite Frontend
   http://localhost:3000

The board is the source of truth. Agents interact via the REST API — create tasks, start workflows, update status, track time, submit completions. Workflows orchestrate multi-step agent pipelines with loops, gates, and parallel execution. The frontend reflects everything in real time over WebSocket. No vendor lock-in: if it can make HTTP calls, it can drive the board.

veritas-kanban/                  ← pnpm monorepo
│
├── web/                         ← React 19 + Vite frontend
│   └── src/
│       ├── components/          ← UI components (Shadcn + custom)
│       ├── hooks/               ← React Query hooks, WebSocket
│       └── lib/                 ← Utilities, API client
│
├── server/                      ← Express + WebSocket API
│   └── src/
│       ├── routes/              ← REST endpoints (/api/v1/*)
│       ├── services/            ← Business logic
│       └── middleware/          ← Auth, rate limiting, security
│
├── shared/                      ← TypeScript types & contracts
│   └── src/types/               ← Shared between web & server
│
├── cli/                         ← `vk` CLI tool
├── mcp/                         ← MCP server for AI assistants
├── docs/                        ← Sprint & audit documentation
│
├── tasks/                       ← Task storage (Markdown files)
│   ├── active/                  ← Current tasks (.gitignored)
│   ├── archive/                 ← Archived tasks (.gitignored)
│   └── examples/                ← Seed tasks for first-run
│
└── .veritas-kanban/             ← Runtime config & data
    ├── config.json
    ├── workflows/               ← YAML workflow definitions
    ├── workflow-runs/           ← Run state & step outputs
    ├── tool-policies/           ← Role-based tool restrictions
    ├── worktrees/
    ├── logs/
    └── agent-requests/

Data flow: Web ↔ REST API / WebSocket ↔ Server ↔ Markdown/YAML files on disk

All API endpoints support versioned paths. The current (and default) version is v1.

Every response includes an X-API-Version: v1 header. Clients may optionally request a specific version:

curl -H "X-API-Version: v1" http://localhost:3001/api/tasks

• Non-breaking changes (new fields, new endpoints) are added to the current version.
• Breaking changes will introduce a new version (v2). The previous version remains available during a deprecation period.
• The unversioned /api/... alias always points to the latest stable version.

📖 Comprehensive CLI guide: docs/CLI-GUIDE.md — installation, every command, scripting examples, and tips.

Manage your entire task lifecycle with two commands.

# Install globally
pnpm --filter @veritas-kanban/shared build
pnpm --filter @veritas-kanban/cli build
cd cli
npm link

For read/write auth checks, use the smoke tests in the CLI Guide.

vk setup                         # Guided environment check + sample task
vk setup --skip-task             # Check only, no sample task
vk setup --json                  # Machine-readable output

Validates Node version, server health, API auth, and optionally creates a welcome task to get you started.

The vk begin and vk done commands replace multi-step API workflows with single commands. Inspired by Boris Cherny's (Claude Code creator) philosophy: "automate everything you do twice."

Before (6 separate curl calls):

curl -X PATCH http://localhost:3001/api/tasks/<id> -H "Content-Type: application/json" -d '{"status":"in-progress"}'
curl -X POST http://localhost:3001/api/tasks/<id>/time/start
curl -X POST http://localhost:3001/api/agent/status -H "Content-Type: application/json" -d '{"status":"working","taskId":"<id>","taskTitle":"Title"}'
# ... work happens ...
curl -X POST http://localhost:3001/api/tasks/<id>/time/stop
curl -X PATCH http://localhost:3001/api/tasks/<id> -H "Content-Type: application/json" -d '{"status":"done"}'
curl -X POST http://localhost:3001/api/tasks/<id>/comments -H "Content-Type: application/json" -d '{"author":"agent","text":"summary"}'

After (2 commands):

vk begin <id>                    # → in-progress + timer + agent working
vk done <id> "Added OAuth"       # → timer stop + done + comment + agent idle

vk list                          # List all tasks
vk list --status in-progress     # Filter by status
vk show <id>                     # Task details
vk create "Title" --type code    # Create task
vk update <id> --status review   # Update task

vk time start <id>               # Start time tracker
vk time stop <id>                # Stop time tracker
vk time entry <id> 3600 "desc"   # Add manual entry (seconds)
vk time show <id>                # Display time summary

vk comment <id> "Fixed the bug"           # Add comment
vk comment <id> "Done" --author Veritas    # With author

vk agent status                  # Show current agent status
vk agent working <id>            # Set to working (auto-fetches title)
vk agent idle                    # Set to idle
vk agent sub-agent 3             # Set sub-agent mode with count

vk project list                  # List all projects
vk project create "my-app" --color "#7c3aed" --description "Main app"

vk github sync                   # Trigger manual sync
vk github status                 # Show sync status
vk github config                 # View/update configuration
vk github mappings               # List issue↔task mappings

vk agents:pending                # List pending agent requests
vk agents:status <id>            # Check if agent running
vk agents:complete <id> -s       # Mark agent complete

vk summary                       # Project stats
vk summary standup               # Daily standup summary
vk notify:pending                # Check notifications

All commands support --json for scripting and machine consumption.

Veritas Kanban works with any agentic platform that can make HTTP calls. The REST API covers the full task lifecycle — create, update, track time, complete. No agent runner is required for board-only use.

Built and tested with OpenClaw (formerly Clawdbot/Moltbot), which provides native orchestration via sessions_spawn. OpenClaw is optional. Use it when you want VK to hand work to OpenClaw or wake OpenClaw from Squad Chat events.

VK also documents the Codex and Hermes operating model:

• Veritas is the source of truth for tasks, status, audit trail, release readiness, and GitHub-linked implementation history.
• HermesAgent/Hermes Gateway is the active control plane for the named Hermes roster and execution routing.
• Mission Control is display/control only in the cutover model, while GitHub Issues, PRs, review comments, and CI remain the durable delivery record.
• OpenAI Codex can be a first-class agent through local CLI runs, SDK sessions, Codex Cloud delegation, workflow steps, review actions, and MCP access.

1. Start Agent — Click "Start Agent" in the UI on a code task (or hit the API directly)
2. Request Created — Server writes to .veritas-kanban/agent-requests/
3. Agent Picks Up — Your agent reads the request and begins work
4. Work Happens — Agent updates task status, tracks time, commits code
5. Completion — Agent calls the completion endpoint with results
6. Task Updates — Status moves to Review; notifications are sent only when configured

💡 Using the CLI? Skip the curl commands — vk begin <id> and vk done <id> "summary" handle the full lifecycle in one shot. See the CLI Guide for details.

# Create a task
curl -X POST http://localhost:3001/api/tasks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $YOUR_KEY" \
  -d '{"title": "Implement feature X", "type": "code", "status": "in-progress"}'

# Start time tracking
curl -X POST http://localhost:3001/api/tasks/<id>/time/start \
  -H "X-API-Key: $YOUR_KEY"

# Mark complete
curl -X POST http://localhost:3001/api/agents/<id>/complete \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $YOUR_KEY" \
  -d '{"success": true, "summary": "What was done"}'

# Trigger a manual sync
curl -X POST http://localhost:3001/api/github/sync \
  -H "X-API-Key: $YOUR_KEY"

# Check sync status
curl http://localhost:3001/api/github/sync/status \
  -H "X-API-Key: $YOUR_KEY"

Issues with the kanban label are imported as tasks. Status changes push back (done → close, reopen on todo/in-progress/blocked). Labels like priority:high and type:story map to task fields. Configure in .veritas-kanban/integrations.json.

# Check for pending agent requests
vk agents:pending

# OpenClaw sub-agents use sessions_spawn to execute work,
# then call the completion endpoint automatically.

• Follow the Codex Integration SOP when Codex should implement, review, or delegate Veritas tasks.
• Use the Veritas Cutover Operating Guide when routing work through the HermesAgent roster, enforcing QA evidence, or creating GitHub-backed task templates.
• Configure Codex MCP access with the MCP Server Guide so Codex reads and updates Veritas through typed tools instead of one-off HTTP calls.

Optional. The MCP server exposes 36 tools across 8 categories (tasks, agents, automation, notifications, summaries, sprints, comments, projects) via Model Context Protocol. Skip this for board-only use.

→ Full MCP documentation — architecture, quickstart, tool catalog with examples, security model, read/write smoke checks, and troubleshooting.

Quick config (Claude Desktop / Cursor / OpenClaw):

{
  "mcpServers": {
    "veritas-kanban": {
      "command": "node",
      "args": ["/path/to/veritas-kanban/mcp/dist/index.js"],
      "env": {
        "VK_API_URL": "http://localhost:3001",
        "VK_API_KEY": "your-agent-api-key"
      }
    }
  }
}

VK_API_KEY is required for write tools unless localhost auth bypass grants an agent or admin role. Prefer an agent role key over the admin key.

After adding the config, restart your MCP client. For OpenClaw:

openclaw gateway restart

Verify discovery with openclaw mcp list. See Troubleshooting if the server doesn't appear.

Troubleshooting MCP connection issues:

• Always restart the MCP client after MCP config changes — MCP servers are discovered at startup
• Verify tools are available: Run openclaw mcp list to confirm 36 Veritas Kanban tools appear
• When reporting issues, provide:
  • OpenClaw version (openclaw --version)
  • VK version and health (curl http://localhost:3001/api/health)
  • MCP logs (~/.openclaw/logs/mcp.log on macOS/Linux)
  • API accessibility test (curl -H "X-API-Key: your-key" http://localhost:3001/api/tasks)

See full MCP troubleshooting guide for details.

Tasks are markdown files with YAML frontmatter:

---
id: 'task_20260126_abc123'
title: 'Implement feature X'
type: 'code'
status: 'in-progress'
priority: 'high'
project: 'rubicon'
git:
  repo: 'my-project'
  branch: 'feature/task_abc123'
  baseBranch: 'main'
---

## Description

Task details here...

pnpm dev        # Start dev servers (web + API concurrently)
pnpm build      # Production build
pnpm typecheck  # TypeScript strict check
pnpm lint       # ESLint
pnpm lint:budget # ESLint with current warning budget
pnpm test       # Unit tests (Vitest)
pnpm test:e2e   # E2E tests (Playwright)
pnpm test:load:smoke # k6 API smoke test
pnpm validate:release # Release readiness checks

Click to expand screenshots

Board Overview

Task Management

Task Extras

Metrics & Dashboard

Settings

Menus & Activity

Current planning lives in GitHub, not in a stale README checklist:

• Open issues
• v5.0 roadmap issues
• Release history

Use issues for current work and the changelog for shipped work.

All support and feature requests go through GitHub:

• 🐛 Bug reports — Open an issue
• 💡 Feature requests — Open an issue
• ❓ Questions & discussion — GitHub Discussions

Note: Support is not provided via email or social media. GitHub is the single source of truth for all project communication.

Special thanks to Peter Steinberger and OpenClaw (formerly Clawdbot/Moltbot) — the platform that inspired this project and made autonomous agent orchestration feel like magic.

MIT © 2026 Digital Meld