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 or opencode.json
  └── 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, or any MCP-compatible AI tool. Switch providers without losing your task history or reconfiguring your workflow.
• Structured 4-agent workflow — Lead, Explorer, 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, whether to install globally, docs path, task adapter, and an optional first task. Creates all harness files in the current directory (or home directory if global).

ahk init

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

Run this once per project. Safe to re-run — it will not overwrite files you've customized.

Global installation — if you answer yes to "Install globally?", files go to ~/.claude (Claude Code) or ~/.config/opencode (OpenCode). This lets you share one harness config across all your projects.

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

The dashboard includes:

| View | What it shows | |------|--------------| | Overview | Status counts, active tasks with acceptance progress, recent agent activity | | Tasks | Full task list, filterable by status, with acceptance progress bars | | Task detail | Acceptance criteria, action timeline per agent, files touched, tools used | | Agents | Per-role breakdown: actions, tasks worked, files touched, completion rate | | Tools | Top tools bar chart + full log of recent tool calls with args and results | | Files | Most-touched files with operation breakdown + recent file operation log |

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 i