agent-harness-kit

@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
  • MCP command per package manager
  • Commands
    • ahk init
    • ahk build
    • ahk models
    • ahk dashboard
    • ahk status
    • ahk health
    • ahk doctor
    • 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.{json|ts|mjs|cjs}
    • health.sh
    • Agent definition files
  • 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
  • Security Policy
  • 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, .codex/config.toml, or .grok/config.toml
  └── spawns: ahk serve (stdio MCP server)
      via your package manager (npx/pnpm exec/yarn run/bunx) when the
      package is a local dependency, or the bare binary when it isn't

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 → Consultant → 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, Grok Build, or any MCP-compatible AI tool. Switch providers without losing your task history or reconfiguring your workflow.

Note: "Grok Build" here refers to xAI's official Grok Build CLI (provider: 'grok-cli') — it is unrelated to the unofficial, community-maintained grok-cli/grok-dev npm packages.

• 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.
• Docs search — agents can call docs.search(query) to find relevant content in your project's docs folder before writing code.
• Specification discovery — ahk-use-cases, ahk-feature, and ahk-fix turn product requests, Jira ideas, and defects into reviewable drafts in docs/specs/. ahk-use-case-tech creates a linked technical draft only after an approved use case, feature, or fix; MCP can search, read, edit, relate, validate, and approve the documents.
• Multi-database support — SQLite by default (uses better-sqlite3 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.
• 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 (recommended)
npm install --save-dev @cardor/agent-harness-kit

Then run the interactive setup inside your project:

npx ahk init

The config file format depends on whether the package is installed locally. ahk init checks that first, before anything else:

Local install	Generated config	Why
Not installed (global-only CLI)	agent-harness-kit.config.json	Your project cannot resolve @cardor/agent-harness-kit, so a TypeScript config's import type would red-underline in your editor and fail tsc --noEmit on a package that isn't there. JSON has no imports and no types — nothing to resolve, zero editor errors.
Installed (npm install --save-dev @cardor/agent-harness-kit)	.ts, .mjs or .cjs	The package resolves, so you get the full typed config with editor autocompletion. Which of the three is picked is unchanged: .ts when a tsconfig.json is present, otherwise .mjs/.cjs based on package.json type.

The trade-off is autocompletion: a JSON config has no type information behind it, so your editor cannot suggest fields. Installing the package locally and switching to a .ts config gets that back. There is no $schema key in the generated JSON — no JSON Schema for HarnessConfig is published yet, and pointing at a URL that doesn't resolve would only swap a type error for a fetch error.

Existing projects are never converted. If a config of any extension already exists, it keeps working and keeps its format — installing or removing the package locally will not silently rewrite it. loadConfig() reads all five formats, and ahk init stops when it finds any of them.

A local install is still recommended even though it is no longer required: it pins the CLI version so behavior stays reproducible across your team and CI instead of drifting with whatever is installed globally on each machine. A global-only install is fully supported — ahk does not print a local-install warning, and the command runs and exits normally either way.

This check also works with Yarn Berry (PnP) projects, which never create a node_modules folder — ahk detects .pnp.cjs/.pnp.loader.mjs and falls back to checking that the package is declared in package.json instead of requiring a node_modules entry.

MCP command per package manager

ahk init and ahk build detect which package manager your project uses and generate the MCP server launch command (.mcp.json, opencode.json, .codex/config.toml, or .grok/config.toml) accordingly, instead of hardcoding npx:

Detection order: the packageManager field in your package.json (e.g. "packageManager": "pnpm@8.15.0") takes priority when present; otherwise ahk falls back to lockfile heuristics; if nothing is detected, it defaults to npm.