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

## 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**](https://www.npmjs.com/package/@cardor/agent-harness-kit) (`ahk`) is a scaffolding layer for structured multi-agent workflows. One command drops it into any project:

```bash
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](https://ahk.cardor.dev)

## How it works

### The 4-agent workflow

```plaintext
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

```ts
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`:

```bash
#!/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:

```ts
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.

![](https://cdn.hashnode.com/uploads/covers/65a66e2284f4ade3e636a395/a02490df-dcce-4314-bead-33d98376dac0.png align="center")

![](https://cdn.hashnode.com/uploads/covers/65a66e2284f4ade3e636a395/1b74a19a-c611-4f8b-81d0-e5553d9ee141.png align="center")

## Provider-agnostic

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

```bash
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

```bash
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 [link](https://ahk.cardor.dev)

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