The problem
Every time I open Claude Code or any MCP-compatible AI tool, the same thing happens: the agent starts working, does something, and I have no idea what it changed, what it tried, or why it got stuck. Across sessions, it's even worse — the agent has no memory of what was already attempted.
If you want multiple agents working in parallel or in sequence, good luck coordinating them without race conditions, double work, or conflicting changes.
I wanted something I could actually trust to run on my codebase.
What I built
agent-harness-kit (ahk) is a scaffolding layer for structured multi-agent workflows. One command drops it into any project:
npx ahk init
It creates a local MCP server (runs on stdio, no ports needed), a SQLite database, a task backlog, a health gate, and four agent definition files.
Website
How it works
The 4-agent workflow
Lead → Explorer → Builder → Reviewer
Lead decomposes the task into a plan. Never reads source files.
Explorer maps the codebase. Never writes files.
Builder implements. Only writes to writablePaths you define.
Reviewer checks acceptance criteria. Runs health check before approving.
Each role has its own Markdown file you can customize. They're created once and never overwritten.
Atomic task claiming
tasks.claim(id, agent) // SQLite transaction — no double-work possible
Two agents can't grab the same task. The second one gets task_already_claimed and moves on.
Health gate
Before any agent starts or closes a task, it runs your health.sh:
#!/usr/bin/env bash
npm test || exit 1
curl -sf http://localhost:3000/health > /dev/null || exit 1
echo "All checks passed."
If it exits with anything other than 0, the task stays open. You define what "healthy" means for your project.
Full audit trail
Every action is recorded:
actions.start(taskId, agent) // start
actions.write(actionId, 'files_modified', 'src/auth.ts, src/routes/login.ts')
actions.write(actionId, 'result', '...')
actions.complete(actionId, 'summary') // close
ahk export --json dumps the full history, or visualize it in a dashboard
The dashboard
ahk ships with a local dashboard. Five views, all reading from .harness/harness.db:
Overview — task counts by status (pending / in progress / done / blocked), total actions run, files touched, unique tools used, active tasks with acceptance criteria progress bars, live activity timeline.
Tasks — full table with status filter buttons. Shows assigned agent, acceptance criteria progress bar per task, created date. Click any row for the full task detail.
Agents — per-role breakdown. For each agent: total actions, completion rate (progress bar), tasks worked, files touched, blocked count.
Tools — horizontal bar chart of most-used tools across all sessions, plus a full call log showing tool name, agent, task slug, args preview, result summary, and timestamp.
Files — most-touched files with read / created / modified / deleted counts, plus a recent operations table with operation type badge, file path, agent, task, and notes.
Provider-agnostic
Works with Claude Code today. Moving to OpenCode? One command:
ahk migrate --to opencode
Your task history, agent definitions, and config stay intact.
No cloud, no native deps
Everything lives in .harness/harness.db (SQLite, gitignored). Uses node:sqlite built-in — no node-gyp, no native compilation.
Requirements: Node ≥ 22 or Bun.
Get started
npx ahk init
Interactive setup. Asks for your project name, AI provider, docs path, and an optional first task. Creates everything in under a minute.
Website https://ahk.cardor.dev
GitHub: https://github.com/enmanuelmag/agent-harness-kit
npm: @cardor/agent-harness-kit
I'd love feedback on the health gate design and the atomic claiming approach — those were the trickiest parts to get right.
