@cardor/agent-harness-kit

A provider-agnostic scaffolding kit for running structured multi-agent workflows in your codebase.

Instead of letting AI agents roam freely through your project with no memory, no coordination, and no audit trail, agent-harness-kit gives them a shared structure: a task backlog, a defined workflow, a persistent log of every action taken, and a health gate that must be green before any work begins.

You stay in control. The agents stay on track.

Visit the website to view a full explanation, examples, and other tools!

npx ahk init

Table of Contents

• @cardor/agent-harness-kit
  • Table of Contents
  • Why this exists
  • How it works
  • Features
  • Requirements
  • Installation
  • Commands
    • ahk init
    • ahk build
    • ahk dashboard
    • ahk status
    • ahk health
    • ahk sync
    • ahk serve
    • ahk task add
    • ahk task list
    • ahk task done <id|slug>
    • ahk reset
    • ahk migrate
    • ahk export
  • Files created by ahk init
    • What each file does
  • Tasks schema
  • What you can customize
    • agent-harness-kit.config.ts
    • health.sh
    • Agent definition files
    • .harness/feature_list.json
  • MCP tools (for agents)
  • Agent roles
    • MCP tool permissions by role
  • What to commit
  • Runtime compatibility
  • Contributing & local development
    • Testing the local build in another project
  • Roadmap

Why this exists

If you don't know what is Agent Harness, you can check this blog post: Introducing Agent Harness.

Most AI coding tools give you a single agent with a chat window. That works for small tasks. It breaks down when:

• You want multiple specialized agents working in sequence (plan → explore → build → review)
• You need to track what changed, what was tried, and what was blocked — across sessions
• You switch between AI providers (Claude Code today, OpenCode tomorrow) and don't want to re-setup everything
• You want a health check that agents must pass before touching code

agent-harness-kit solves all of this with a thin layer of scaffolding and a local MCP server that any MCP-compatible AI tool can connect to.

How it works

ahk init
  └── creates config, agent definitions, task backlog, health check

AI tool opens your project
  └── reads .claude/mcp.json, opencode.json, or .codex/config.toml
  └── spawns: npx ahk serve (stdio MCP server)

Agent starts working
  └── tasks.get()         → picks a task from the backlog
  └── tasks.claim(id)     → atomically claims it (no double-work)
  └── actions.start()     → registers its action
  └── actions.write()     → logs sections: result, files, blockers…
  └── actions.complete()  → closes the action

Lead → Explorer → Builder → Reviewer
  └── each role has its own agent definition with clear responsibilities
  └── the harness DB records the full history

Everything is stored locally in a SQLite database (.harness/harness.db). No cloud, no external services, no API keys required beyond what your AI tool already uses.

Features

• Provider-agnostic — works with Claude Code, OpenCode, Codex CLI, or any MCP-compatible AI tool. Switch providers without losing your task history or reconfiguring your workflow.
• Structured 5-agent workflow — Lead, Explorer, Consultant, Builder, and Reviewer each have defined responsibilities and can only act within their role.
• Atomic task claiming — agents use tasks.claim() which uses a SQLite transaction to prevent two agents from picking up the same task at the same time.
• Full audit trail — every action, file touched, tool used, and section written is stored in SQLite and queryable.
• Health gate — agents must run health.sh and get a green exit before starting or closing any task. You define what "healthy" means.
• Markdown fallback — current.md is always regenerated so agents can understand the session state even without the MCP server.
• Docs search — agents can call docs.search(query) to find relevant content in your project's docs folder before writing code.
• Multi-database support — SQLite by default (zero native deps, uses node:sqlite on Node ≥ 22 or bun:sqlite on Bun). Switch to PostgreSQL or MySQL with a single config line — same schema, same MCP tools, same workflow.
• Incremental scaffold — ahk init and ahk build never overwrite files you've customized. Agent definitions you've edited are preserved.
• Global installation — ahk init can scaffold the harness into your home directory (~/.claude or ~/.config/opencode) to share it across all projects.
• Input validation — CLI prompts validate all inputs (name length, path format, task title, etc.) and retry with the error message instead of silently accepting bad values.

Requirements

• Node.js ≥ 22.5 or Bun (any recent version)
• npm ≥ 9

Installation

# Install in your project as a dev dependency
npm install --save-dev @cardor/agent-harness-kit

# Or globally
npm install -g @cardor/agent-harness-kit

Then run the interactive setup inside your project:

npx ahk init
# or, if installed globally:
ahk init

Commands

ahk init

Interactive scaffold. Asks for your project name, description, AI provider, docs path, task adapter, and an optional first task. Creates all harness files in the current directory.

ahk init

# Skip prompts with flags
ahk init --name "my-app" --provider claude-code --docs ./docs --tasks local
ahk init --name "my-app" --provider codex-cli   --docs ./docs --tasks local

Run this once per project. If the project is already initialized, the command prints an 'already initialized' message with suggested next-step commands (ahk build, ahk build --sync, ahk reset, ahk serve) and exits without overwriting anything.

The config file extension is chosen automatically: .ts if a tsconfig.json is present, .mjs for ESM-only projects ("type": "module" in package.json), or .mjs otherwise.

ahk build

Regenerates AGENTS.md and provider-specific files from your agent-harness-kit.config.ts. Use this after changing config values.

ahk build
ahk build --watch    # watch mode: rebuilds automatically on config changes
ahk build --sync     # sync tools: frontmatter in agent files to match current permission constants (claude-code only; no-op for opencode/codex-cli)

ahk dashboard

Opens a local web dashboard to visualize everything stored in the harness database — tasks, agent actions, file operations, tool usage, and live timelines. Updates in real time via WebSocket as agents work.

ahk dashboard                  # opens http://localhost:4242 in your browser
ahk dashboard --port 8080      # custom port
ahk dashboard --no-open        # start server without opening browser

If the requested port (default 4242) is already in use, ahk dashboard automatically tries up to 10 sequential ports (e.g. 4242 → 4243 → … → 4251). The actual port opened is printed to the console. If all 10 ports are exhausted, the command exits with a clear error message showing which port range was attempted.

The dashboard includes:

ahk status

Shows the current task table and any active agent actions in the terminal.

ahk status
ahk status --json    # machine-readable output

ahk health

Runs health.sh and reports the result. Exit 0 = healthy, exit 1 = something is wrong.

ahk health

ahk sync

Syncs .harness/feature_list.json ↔ SQLite. Tasks already in the DB are skipped by slug. Use this to seed the backlog from the JSON file without duplicating existing tasks.

ahk sync                         # both directions (default)
ahk sync --direction in          # JSON → SQLite only
ahk sync --direction out         # SQLite → JSON only
ahk sync --dry-run               # preview changes without applying them
ahk sync --dry-run --direction in

ahk serve

Starts the MCP server on stdio. You never need to call this manually. After ahk init, the generated .claude/mcp.json (Claude Code) or opencode.json (OpenCode) tells the AI tool to spawn it automatically when you open the project.

ahk serve
ahk serve --port 3456    # store a port hint in config (stdio transport only)

ahk task add

Interactively adds a new task to the backlog (SQLite + feature_list.json).

ahk task add

ahk task list

Lists all tasks. Optionally filter by status.

ahk task list
ahk task list --status pending
ahk task list --status in_progress
ahk task list --status done
ahk task list --status blocked
ahk task list --json             # machine-readable output

ahk task done <id|slug>

Marks a task as done. Runs the health check first if health is required — if it fails, the task is not closed.

ahk task done 3
ahk task done add-auth-flow

ahk reset

Clears harness data interactively. Only SQLite databases are managed by this command — remote Postgres/MySQL databases are intentionally skipped.

ahk reset                          # interactive — asks before deleting each item
ahk reset --force                  # skip all confirmation prompts
ahk reset --provider claude-code   # also delete agent files for this provider
ahk reset --provider opencode
ahk reset --provider codex-cli

What it can reset:

• The SQLite .db file (plus WAL and SHM files if present)
• .harness/feature_list.json
• Agent definition files in .claude/agents/, .opencode/agents/, or .codex/agents/

After a reset, run ahk init to scaffold a fresh harness.

ahk migrate

Migrates provider-specific files from one AI provider to another. Useful when switching from Claude Code to OpenCode or vice versa.

ahk migrate --to opencode
ahk migrate --to claude-code
ahk migrate --to codex-cli

ahk export

Exports the full database as JSON or SQL. Useful for backups, external reporting, or migrating data.

ahk export --json                        # JSON to stdout
ahk export --json --output snapshot.json # JSON to file
ahk export --sql                         # SQL dump to stdout
ahk export --sql --output dump.sql       # SQL dump to file

Files created by ahk init

Claude Code (provider: 'claude-code'):

your-project/
├── agent-harness-kit.config.{ts|mjs|cjs}
├── AGENTS.md
├── CLAUDE.md
├── health.sh
├── .harness/
│   ├── harness.db                 ← gitignored
│   ├── current.md                 ← gitignored
│   └── feature_list.json
└── .claude/
    ├── agents/
    │   ├── lead.md
    │   ├── explorer.md
    │   ├── builder.md
    │   └── reviewer.md
    ├── mcp.json                   ← MCP server registration
    └── settings.json              ← sets `agent: "lead"` as the default session agent

OpenCode (provider: 'opencode'):

your-project/
├── agent-harness-kit.config.{ts|mjs|cjs}
├── AGENTS.md
├── health.sh
├── opencode.json                  ← MCP server + default_agent + compaction config
├── .harness/
└── .opencode/
    └── agents/
        ├── lead.md
        ├── explorer.md
        ├── builder.md
        └── reviewer.md

Codex CLI (provider: 'codex-cli'):

your-project/
├── agent-harness-kit.config.{ts|mjs|cjs}
├── AGENTS.md
├── health.sh
├── .harness/
└── .codex/
    ├── config.toml                ← MCP server registration
    └── agents/
        ├── lead.toml
        ├── explorer.toml
        ├── builder.toml
        ├── reviewer.toml
        └── default.toml           ← overrides Codex's built-in default agent → routes to lead

What each file does

Tasks schema

The tasks table includes an updated_at timestamp column, set on creation and automatically updated on every status change. On first run after upgrading from an older version, existing rows are backfilled with COALESCE(completed_at, started_at, created_at). Tasks returned by tasks.get are ordered by status priority (pending → in_progress → blocked → done) then by updated_at descending.

What you can customize

agent-harness-kit.config.ts

Everything in the config file is yours to change:

import { defineHarness } from '@cardor/agent-harness-kit'

export default defineHarness({
  project: {
    name: 'My App',
    description: 'What this project does',
    docsPath: './docs', // where agents search for documentation
  },

  provider: 'claude-code', // 'claude-code' | 'opencode' | 'codex-cli'

  agents: {
    lead: { instructionsPath: null },
    explorer: { instructionsPath: null, allowedPaths: ['./docs', './src'] },
    builder: { instructionsPath: null, writablePaths: ['./src', './tests'] },
    reviewer: { instructionsPath: null },
    custom: [], // define extra agents here
  },

  // ── Database ──────────────────────────────────────────────────────────────
  // SQLite (default — zero native deps, Node 22+ or Bun)
  database: { type: 'sqlite', path: '.harness/harness.db' },

  // PostgreSQL — uncomment to use instead:
  // database: { type: 'postgres', connectionString: process.env.DATABASE_URL },

  // MySQL — uncomment to use instead:
  // database: { type: 'mysql', connectionString: process.env.DATABASE_URL },

  storage: {
    dir: '.harness',
    tasks: { adapter: 'local' }, // 'local' | 'jira' | 'linear' | 'mcp'
    sections: {
      toolsUsed: true, // log which tools agents used
      filesModified: true, // log which files were touched
      result: true, // log action results
      blockers: true, // log blockers agents hit
      nextSteps: false, // optional next steps field
    },
    markdownFallback: { enabled: true, path: '.harness/current.md' },
  },

  health: {
    scriptPath: './health.sh',
    required: true, // set to false to skip health checks
  },

  tools: {
    mcp: { enabled: true, port: 3742 },
    scripts: { enabled: true, outputDir: './.harness/scripts' },
  },
})

health.sh

This is the most important file to implement. Agents will not start or close tasks until this script exits 0. Examples:

#!/usr/bin/env bash

# Check the dev server is up
curl -sf http://localhost:3000/health > /dev/null || exit 1

# Run unit tests
npm test || exit 1

# Check DB connection
psql "$DATABASE_URL" -c "SELECT 1" > /dev/null 2>&1 || exit 1

echo "All checks passed."

Agent definition files

Created once and never overwritten by ahk build — your edits are permanent.

Claude Code (.claude/agents/*.md) and OpenCode (.opencode/agents/*.md) use Markdown with YAML frontmatter:

---
name: builder
description: Builder agent — implements the plan produced by explorer and lead
tools:
  read: true
  write: true
  edit: true
  bash: true
permissionMode: acceptEdits
---

# Builder Agent

You are the builder agent for MyApp. Follow these rules:

- All API endpoints must be defined in `src/routes/`
- Never modify `src/core/` without lead approval
- Run `npm test` after every change and fix failures before completing
- Use the existing error handling pattern from `src/lib/errors.ts`

Codex CLI (.codex/agents/*.toml) uses TOML format:

name = "builder"
sandbox_mode = "workspace-write"

description = """
Builder agent — implements the plan produced by explorer and lead.
"""

developer_instructions = """
# Builder Agent

You are the builder agent for MyApp. Follow these rules:

- All API endpoints must be defined in `src/routes/`
- Never modify `src/core/` without lead approval
- Run `npm test` after every change and fix failures before completing
"""

The sandbox_mode field controls Codex's filesystem permissions per agent: "read-only" for lead, explorer, and reviewer; "workspace-write" for builder. The permissionMode field in Claude Code agent files enforces the same constraints at the session level (plan for read-only roles, acceptEdits for builder).

.harness/feature_list.json

The human-editable task backlog. Add tasks here, then run ahk sync to load them into SQLite.

[
  {
    "slug": "add-auth-flow",
    "title": "Add JWT authentication flow",
    "description": "Implement login, refresh token, and logout endpoints",
    "acceptance": [
      "POST /auth/login returns a signed JWT",
      "POST /auth/refresh validates and rotates the token",
      "All protected routes return 401 without a valid token",
      "Tests cover happy path and token expiry"
    ]
  }
]

Good acceptance criteria make the difference — the reviewer agent uses them to decide whether to approve or block a task.

MCP tools (for agents)

The harness exposes these tools via MCP. Agents use them instead of reading files directly.

Agent roles

MCP tool permissions by role

Each agent role has a scoped set of MCP tools enforced through the agent definition files.

explorer is read-only for task state — can query but cannot mutate status or mark criteria.
reviewer is the only role that can mark acceptance criteria as met (tasks.acceptance.update).
lead and builder have identical access, both excluding tasks.acceptance.update.
consultant is advisory-only — reads code, writes to harness, and can call deps tools. Never modifies the codebase.

permissions.check compares each .claude/agents/*.md tool list against the canonical constants in the package. Returns { in_sync: bool, agents: { lead, explorer, consultant, builder, reviewer } } with per-agent missing and extra arrays. Run ahk build --sync to fix any drift.

What to commit

The rule: commit inputs (config, task definitions, agent instructions). Ignore outputs (DB, auto-generated snapshots).

Runtime compatibility

SQLite requires no additional packages. For PostgreSQL install postgres, for MySQL install mysql2:

npm install postgres    # for PostgreSQL
npm install mysql2      # for MySQL

Contributing & local development

git clone <repo-url>
cd agent-harness-kit
npm install

npm run build:ui    # build the dashboard SPA (dashboard/ → src/dashboard-dist/)
npm run build       # build:ui + tsc + copy-assets
npm run dev         # watch mode (CLI TypeScript only)
npm test            # run tests

Testing the local build in another project

Use the helper script to build the package and link it into any local project in one step:

# Build + link into a specific project
./scripts/link-local.sh /path/to/your-other-project

# Build + register globally only (then link manually wherever you need)
./scripts/link-local.sh

What the script does:

1. Runs npm run build (full build including dashboard assets)
2. Runs npm link to register the package globally on your machine
3. Runs npm link @cardor/agent-harness-kit inside the target project
4. Smoke-tests the ahk binary with --version

After linking, npx ahk inside the target project will use your local build. To unlink when you're done:

# Inside the target project
npm unlink @cardor/agent-harness-kit

# Optionally remove the global registration
npm uninstall -g @cardor/agent-harness-kit

Tip: If you're iterating quickly, run npm run build in this repo after each change — the link picks up the new dist/ immediately without re-running the script.

To work on the dashboard UI with hot reload:

# Terminal 1 — CLI server (no browser open)
cd your-test-project && ahk dashboard --no-open --port 4242

# Terminal 2 — Vite dev server with HMR
cd dashboard && npm run dev   # http://localhost:5173, proxies /api and /ws → :4242

Commit messages follow Conventional Commits with a required scope:

feat(cli): add export command
fix(db): prevent race condition in claimTask
chore(ci): update Node version to 22

Types: feat fix chore refactor docs test perf style build ci revert

Roadmap

• ✅ ahk dashboard — local web UI with real-time WebSocket updates. Shows tasks, action timelines, file activity, tool usage, and per-agent breakdowns.
• ✅ ahk reset — interactively clear the SQLite DB, feature list, and agent files to start a project fresh.
• ✅ PostgreSQL + MySQL drivers — remote database support via postgres and mysql2 packages. Configure with database: { type: 'postgres', connectionString: '...' }.
• ✅ actions.record_file + actions.record_tool — dedicated MCP tools for populating the Files and Tools dashboard views.
• ✅ tasks.add via MCP — agents can create new tasks on the fly without leaving the conversation.
• ✅ Global installation — ahk init can install the harness to your home directory, shared across projects.
• ✅ Input validation — all CLI prompts validate and retry on bad values.
• ✅ Codex CLI provider — full support for OpenAI Codex CLI. Generates .codex/agents/*.toml files with proper sandbox_mode per role and merges .codex/config.toml for MCP registration. Overrides the built-in default agent so the harness lead runs by default.
• Graphify integration — connect the harness to Graphify to visualize agent workflows, task dependencies, and action timelines as interactive graphs.
• Open Telemetry integration — emit OpenTelemetry spans for all agent actions, file operations, and tool calls.
• Jira task adapter — pull tasks directly from Jira instead of maintaining feature_list.json manually.
• Linear task adapter — same as Jira, for Linear.
• GitHub Issues adapter — same, for GitHub Issues.
• Remote MCP adapter — connect to a hosted MCP server instead of a local SQLite file. Enables shared task state across machines and team members without syncing a DB file.