DEV Community

Enmanuel Magallanes Pinargote
Enmanuel Magallanes Pinargote

Posted on

I got tired of AI agents roaming my codebase — so I built a harness layer

#agents #ai #opensource #tooling

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode
  • 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
Enter fullscreen mode Exit fullscreen mode

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."
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

ahk export --json dumps the full history.

Provider-agnostic

Works with Claude Code today. Moving to OpenCode? One command:

ahk migrate --to opencode
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)