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

t 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.

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.

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.

GitHub: link
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.