[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-11253":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":16,"stars30d":17,"stars90d":15,"forks30d":15,"starsTrendScore":15,"compositeScore":18,"rankGlobal":10,"rankLanguage":10,"license":10,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":19,"hasPages":19,"topics":21,"createdAt":10,"pushedAt":10,"updatedAt":25,"readmeContent":26,"aiSummary":27,"trendingCount":15,"starSnapshotCount":15,"syncStatus":28,"lastSyncTime":29,"discoverSource":30},11253,"agent-harness-kit","enmanuelmag\u002Fagent-harness-kit","enmanuelmag","A provider-agnostic scaffolding kit for running structured multi-agent workflows in your codebase.","https:\u002F\u002Fahk.cardor.dev",null,"TypeScript",170,7,68,0,1,28,2.71,false,"main",[22,23,24],"agent","agent-harness","llm","2026-06-12 02:02:30","# @cardor\u002Fagent-harness-kit\n\n**A provider-agnostic scaffolding kit for running structured multi-agent workflows in your codebase.**\n\nInstead 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.\n\nYou stay in control. The agents stay on track.\n\nVisit the [website](https:\u002F\u002Fstack.cardor.dev\u002Fahk) to view a full explanation, examples, and other tools!\n\n\u003Ca href='https:\u002F\u002Fko-fi.com\u002FS6S31ZBGQK' target='_blank'>\u003Cimg height='36' style='border:0px;height:36px;' src='https:\u002F\u002Fstorage.ko-fi.com\u002Fcdn\u002Fkofi6.png?v=6' border='0' alt='Buy Me a Coffee at ko-fi.com' \u002F>\u003C\u002Fa>\n\n```bash\nnpx ahk init\n```\n\n---\n\n## Table of Contents\n\n- [@cardor\u002Fagent-harness-kit](#cardoragent-harness-kit)\n  - [Table of Contents](#table-of-contents)\n  - [Why this exists](#why-this-exists)\n  - [How it works](#how-it-works)\n  - [Features](#features)\n  - [Requirements](#requirements)\n  - [Installation](#installation)\n  - [Commands](#commands)\n    - [`ahk init`](#ahk-init)\n    - [`ahk build`](#ahk-build)\n    - [`ahk dashboard`](#ahk-dashboard)\n    - [`ahk status`](#ahk-status)\n    - [`ahk health`](#ahk-health)\n    - [`ahk sync`](#ahk-sync)\n    - [`ahk serve`](#ahk-serve)\n    - [`ahk task add`](#ahk-task-add)\n    - [`ahk task list`](#ahk-task-list)\n    - [`ahk task done \u003Cid|slug>`](#ahk-task-done-idslug)\n    - [`ahk reset`](#ahk-reset)\n    - [`ahk migrate`](#ahk-migrate)\n    - [`ahk export`](#ahk-export)\n  - [Files created by `ahk init`](#files-created-by-ahk-init)\n    - [What each file does](#what-each-file-does)\n  - [What you can customize](#what-you-can-customize)\n    - [`agent-harness-kit.config.ts`](#agent-harness-kitconfigts)\n    - [`health.sh`](#healthsh)\n    - [Agent definition files (`.claude\u002Fagents\u002F*.md` or `.opencode\u002Fagents\u002F*.md`)](#agent-definition-files-claudeagentsmd-or-opencodeagentsmd)\n    - [`.harness\u002Ffeature_list.json`](#harnessfeature_listjson)\n  - [MCP tools (for agents)](#mcp-tools-for-agents)\n  - [Agent roles](#agent-roles)\n  - [What to commit](#what-to-commit)\n  - [Runtime compatibility](#runtime-compatibility)\n  - [Contributing \\& local development](#contributing--local-development)\n    - [Testing the local build in another project](#testing-the-local-build-in-another-project)\n  - [Roadmap](#roadmap)\n\n---\n\n## Why this exists\n\nIf you don't know what is Agent Harness, you can check this blog post: [Introducing Agent Harness](https:\u002F\u002Faakashgupta.medium.com\u002F2025-was-agents-2026-is-agent-harnesses-heres-why-that-changes-everything-073e9877655e).\n\nMost AI coding tools give you a single agent with a chat window. That works for small tasks. It breaks down when:\n\n- You want multiple specialized agents working in sequence (plan → explore → build → review)\n- You need to track what changed, what was tried, and what was blocked — across sessions\n- You switch between AI providers (Claude Code today, OpenCode tomorrow) and don't want to re-setup everything\n- You want a health check that agents must pass before touching code\n\nagent-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.\n\n---\n\n## How it works\n\n```\nahk init\n  └── creates config, agent definitions, task backlog, health check\n\nAI tool opens your project\n  └── reads .claude\u002Fmcp.json or opencode.json\n  └── spawns: npx ahk serve (stdio MCP server)\n\nAgent starts working\n  └── tasks.get()         → picks a task from the backlog\n  └── tasks.claim(id)     → atomically claims it (no double-work)\n  └── actions.start()     → registers its action\n  └── actions.write()     → logs sections: result, files, blockers…\n  └── actions.complete()  → closes the action\n\nLead → Explorer → Builder → Reviewer\n  └── each role has its own agent definition with clear responsibilities\n  └── the harness DB records the full history\n```\n\nEverything is stored locally in a SQLite database (`.harness\u002Fharness.db`). No cloud, no external services, no API keys required beyond what your AI tool already uses.\n\n---\n\n## Features\n\n- **Provider-agnostic** — works with Claude Code, OpenCode, or any MCP-compatible AI tool. Switch providers without losing your task history or reconfiguring your workflow.\n- **Structured 4-agent workflow** — Lead, Explorer, Builder, and Reviewer each have defined responsibilities and can only act within their role.\n- **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.\n- **Full audit trail** — every action, file touched, tool used, and section written is stored in SQLite and queryable.\n- **Health gate** — agents must run `health.sh` and get a green exit before starting or closing any task. You define what \"healthy\" means.\n- **Markdown fallback** — `current.md` is always regenerated so agents can understand the session state even without the MCP server.\n- **Docs search** — agents can call `docs.search(query)` to find relevant content in your project's docs folder before writing code.\n- **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.\n- **Incremental scaffold** — `ahk init` and `ahk build` never overwrite files you've customized. Agent definitions you've edited are preserved.\n- **Global installation** — `ahk init` can scaffold the harness into your home directory (`~\u002F.claude` or `~\u002F.config\u002Fopencode`) to share it across all projects.\n- **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.\n\n---\n\n## Requirements\n\n- Node.js ≥ 22.5 **or** Bun (any recent version)\n- npm ≥ 9\n\n---\n\n## Installation\n\n```bash\n# Install in your project as a dev dependency\nnpm install --save-dev @cardor\u002Fagent-harness-kit\n\n# Or globally\nnpm install -g @cardor\u002Fagent-harness-kit\n```\n\nThen run the interactive setup inside your project:\n\n```bash\nnpx ahk init\n# or, if installed globally:\nahk init\n```\n\n---\n\n## Commands\n\n### `ahk init`\n\nInteractive 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).\n\n```bash\nahk init\n\n# Skip prompts with flags\nahk init --name \"my-app\" --provider claude-code --docs .\u002Fdocs --tasks local\n```\n\nRun this once per project. Safe to re-run — it will not overwrite files you've customized.\n\n**Global installation** — if you answer yes to \"Install globally?\", files go to `~\u002F.claude` (Claude Code) or `~\u002F.config\u002Fopencode` (OpenCode). This lets you share one harness config across all your projects.\n\n---\n\n### `ahk build`\n\nRegenerates `AGENTS.md` and provider-specific files from your `agent-harness-kit.config.ts`. Use this after changing config values.\n\n```bash\nahk build\nahk build --watch    # watch mode: rebuilds automatically on config changes\n```\n\n---\n\n### `ahk dashboard`\n\nOpens 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.\n\n```bash\nahk dashboard                  # opens http:\u002F\u002Flocalhost:4242 in your browser\nahk dashboard --port 8080      # custom port\nahk dashboard --no-open        # start server without opening browser\n```\n\nThe dashboard includes:\n\n| View | What it shows |\n|------|--------------|\n| **Overview** | Status counts, active tasks with acceptance progress, recent agent activity |\n| **Tasks** | Full task list, filterable by status, with acceptance progress bars |\n| **Task detail** | Acceptance criteria, action timeline per agent, files touched, tools used |\n| **Agents** | Per-role breakdown: actions, tasks worked, files touched, completion rate |\n| **Tools** | Top tools bar chart + full log of recent tool calls with args and results |\n| **Files** | Most-touched files with operation breakdown + recent file operation log |\n\n![Dashboard](.\u002Fassets\u002Fahk-dashboard.png)\n\n\n---\n\n### `ahk status`\n\nShows the current task table and any active agent actions in the terminal.\n\n```bash\nahk status\nahk status --json    # machine-readable output\n```\n\n---\n\n### `ahk health`\n\nRuns `health.sh` and reports the result. Exit 0 = healthy, exit 1 = something is wrong.\n\n```bash\nahk health\n```\n\n---\n\n### `ahk sync`\n\nSyncs `.harness\u002Ffeature_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.\n\n```bash\nahk sync                         # both directions (default)\nahk sync --direction in          # JSON → SQLite only\nahk sync --direction out         # SQLite → JSON only\nahk sync --dry-run               # preview changes without applying them\nahk sync --dry-run --direction in\n```\n\n---\n\n### `ahk serve`\n\nStarts the MCP server on stdio. **You never need to call this manually.** After `ahk init`, the generated `.claude\u002Fmcp.json` (Claude Code) or `opencode.json` (OpenCode) tells the AI tool to spawn it automatically when you open the project.\n\n```bash\nahk serve\nahk serve --port 3456    # store a port hint in config (stdio transport only)\n```\n\n---\n\n### `ahk task add`\n\nInteractively adds a new task to the backlog (SQLite + `feature_list.json`).\n\n```bash\nahk task add\n```\n\n---\n\n### `ahk task list`\n\nLists all tasks. Optionally filter by status.\n\n```bash\nahk task list\nahk task list --status pending\nahk task list --status in_progress\nahk task list --status done\nahk task list --status blocked\nahk task list --json             # machine-readable output\n```\n\n---\n\n### `ahk task done \u003Cid|slug>`\n\nMarks a task as done. Runs the health check first if health is required — if it fails, the task is not closed.\n\n```bash\nahk task done 3\nahk task done add-auth-flow\n```\n\n---\n\n### `ahk reset`\n\nClears harness data interactively. Only SQLite databases are managed by this command — remote Postgres\u002FMySQL databases are intentionally skipped.\n\n```bash\nahk reset                          # interactive — asks before deleting each item\nahk reset --force                  # skip all confirmation prompts\nahk reset --provider claude-code   # also delete agent .md files for this provider\nahk reset --provider opencode\n```\n\nWhat it can reset:\n- The SQLite `.db` file (plus WAL and SHM files if present)\n- `.harness\u002Ffeature_list.json`\n- Agent `.md` files in `.claude\u002Fagents\u002F` or `.opencode\u002Fagents\u002F`\n\nAfter a reset, run `ahk init` to scaffold a fresh harness.\n\n---\n\n### `ahk migrate`\n\nMigrates provider-specific files from one AI provider to another. Useful when switching from Claude Code to OpenCode or vice versa.\n\n```bash\nahk migrate --to opencode\nahk migrate --to claude-code\n```\n\n---\n\n### `ahk export`\n\nExports the full database as JSON or SQL. Useful for backups, external reporting, or migrating data.\n\n```bash\nahk export --json                        # JSON to stdout\nahk export --json --output snapshot.json # JSON to file\nahk export --sql                         # SQL dump to stdout\nahk export --sql --output dump.sql       # SQL dump to file\n```\n\n---\n\n## Files created by `ahk init`\n\n```\nyour-project\u002F\n├── agent-harness-kit.config.ts    ← main config (edit freely)\n├── AGENTS.md                      ← navigation map regenerated from config\n├── health.sh                      ← implement your health checks here\n├── .harness\u002F\n│   ├── harness.db                 ← SQLite source of truth (gitignored)\n│   ├── current.md                 ← auto-generated session snapshot (gitignored)\n│   └── feature_list.json          ← human-editable task backlog (commit this)\n└── .claude\u002F                       ← or .opencode\u002F depending on your provider\n    ├── agents\u002F\n    │   ├── lead.md\n    │   ├── explorer.md\n    │   ├── builder.md\n    │   └── reviewer.md\n    └── mcp.json                   ← tells Claude Code to spawn ahk serve\n```\n\n### What each file does\n\n| File | Purpose | Edit it? |\n|------|---------|----------|\n| `agent-harness-kit.config.ts` | Defines project metadata, provider, storage paths, MCP port | Yes — it's yours |\n| `AGENTS.md` | Navigation map agents read first. Regenerated by `ahk build` | No — changes will be overwritten |\n| `health.sh` | Shell script agents run before starting work. Must exit 0 | **Yes — implement your checks here** |\n| `.harness\u002Ffeature_list.json` | Task backlog in JSON. Humans edit this, `ahk sync` loads it into SQLite | Yes — add tasks here |\n| `.harness\u002Fharness.db` | SQLite database. Source of truth for tasks, actions, sections | No — managed by the harness |\n| `.harness\u002Fcurrent.md` | Auto-generated session snapshot for agents without MCP access | No — regenerated automatically |\n| `.claude\u002Fagents\u002F*.md` | Agent role definitions. Created once, never overwritten | **Yes — customize agent behavior** |\n| `.claude\u002Fmcp.json` | MCP server config. Merged (not overwritten) by `ahk build` | Yes, carefully — don't remove the `agent-harness-kit` entry |\n\n---\n\n## What you can customize\n\n### `agent-harness-kit.config.ts`\n\nEverything in the config file is yours to change:\n\n```ts\nimport { defineHarness } from '@cardor\u002Fagent-harness-kit'\n\nexport default defineHarness({\n  project: {\n    name: 'My App',\n    description: 'What this project does',\n    docsPath: '.\u002Fdocs',           \u002F\u002F where agents search for documentation\n  },\n\n  provider: 'claude-code',        \u002F\u002F 'claude-code' | 'opencode'\n\n  agents: {\n    lead:     { instructionsPath: null },\n    explorer: { instructionsPath: null, allowedPaths: ['.\u002Fdocs', '.\u002Fsrc'] },\n    builder:  { instructionsPath: null, writablePaths: ['.\u002Fsrc', '.\u002Ftests'] },\n    reviewer: { instructionsPath: null },\n    custom:   [],                 \u002F\u002F define extra agents here\n  },\n\n  \u002F\u002F ── Database ──────────────────────────────────────────────────────────────\n  \u002F\u002F SQLite (default — zero native deps, Node 22+ or Bun)\n  database: { type: 'sqlite', path: '.harness\u002Fharness.db' },\n\n  \u002F\u002F PostgreSQL — uncomment to use instead:\n  \u002F\u002F database: { type: 'postgres', connectionString: process.env.DATABASE_URL },\n\n  \u002F\u002F MySQL — uncomment to use instead:\n  \u002F\u002F database: { type: 'mysql', connectionString: process.env.DATABASE_URL },\n\n  storage: {\n    dir:   '.harness',\n    tasks: { adapter: 'local' },  \u002F\u002F 'local' | 'jira' | 'linear' | 'mcp'\n    sections: {\n      toolsUsed:     true,        \u002F\u002F log which tools agents used\n      filesModified: true,        \u002F\u002F log which files were touched\n      result:        true,        \u002F\u002F log action results\n      blockers:      true,        \u002F\u002F log blockers agents hit\n      nextSteps:     false,       \u002F\u002F optional next steps field\n    },\n    markdownFallback: { enabled: true, path: '.harness\u002Fcurrent.md' },\n  },\n\n  health: {\n    scriptPath: '.\u002Fhealth.sh',\n    required:   true,             \u002F\u002F set to false to skip health checks\n  },\n\n  tools: {\n    mcp:     { enabled: true, port: 3742 },\n    scripts: { enabled: true, outputDir: '.\u002F.harness\u002Fscripts' },\n  },\n})\n```\n\n### `health.sh`\n\nThis is the most important file to implement. Agents will not start or close tasks until this script exits 0. Examples:\n\n```bash\n#!\u002Fusr\u002Fbin\u002Fenv bash\n\n# Check the dev server is up\ncurl -sf http:\u002F\u002Flocalhost:3000\u002Fhealth > \u002Fdev\u002Fnull || exit 1\n\n# Run unit tests\nnpm test || exit 1\n\n# Check DB connection\npsql \"$DATABASE_URL\" -c \"SELECT 1\" > \u002Fdev\u002Fnull 2>&1 || exit 1\n\necho \"All checks passed.\"\n```\n\n### Agent definition files (`.claude\u002Fagents\u002F*.md` or `.opencode\u002Fagents\u002F*.md`)\n\nThese are Markdown files with a YAML frontmatter and free-form instructions. They are created once and **never overwritten** by `ahk build` — so any edits you make are permanent.\n\nYou can:\n- Add domain-specific context (e.g. \"this project uses hexagonal architecture\")\n- Restrict what the agent is allowed to do\n- Add project-specific conventions the agent must follow\n- Reference specific files or docs the agent should read first\n\n```markdown\n---\ndescription: Builder agent — implements the plan produced by explorer and lead\n---\n\n# Builder Agent\n\nYou are the builder agent for MyApp. Follow these rules:\n\n- All API endpoints must be defined in `src\u002Froutes\u002F`\n- Never modify `src\u002Fcore\u002F` without lead approval\n- Run `npm test` after every change and fix failures before completing\n- Use the existing error handling pattern from `src\u002Flib\u002Ferrors.ts`\n```\n\n### `.harness\u002Ffeature_list.json`\n\nThe human-editable task backlog. Add tasks here, then run `ahk sync` to load them into SQLite.\n\n```json\n[\n  {\n    \"slug\": \"add-auth-flow\",\n    \"title\": \"Add JWT authentication flow\",\n    \"description\": \"Implement login, refresh token, and logout endpoints\",\n    \"acceptance\": [\n      \"POST \u002Fauth\u002Flogin returns a signed JWT\",\n      \"POST \u002Fauth\u002Frefresh validates and rotates the token\",\n      \"All protected routes return 401 without a valid token\",\n      \"Tests cover happy path and token expiry\"\n    ]\n  }\n]\n```\n\nGood acceptance criteria make the difference — the reviewer agent uses them to decide whether to approve or block a task.\n\n---\n\n## MCP tools (for agents)\n\nThe harness exposes these tools via MCP. Agents use them instead of reading files directly.\n\n| Tool | Parameters | Description |\n|------|-----------|-------------|\n| `tasks.get` | `status?` | List tasks, optionally filtered by `pending \\| in_progress \\| done \\| blocked` |\n| `tasks.claim` | `id, agent` | Atomically claim a pending task. Returns `task_already_claimed` if another agent got it first |\n| `tasks.update` | `id, status` | Change task status |\n| `tasks.add` | `title, slug?, description?, acceptance?` | Create a new task directly from MCP (agents can queue work on the fly) |\n| `tasks.acceptance.update` | `criterionId` | Mark an acceptance criterion as met. Criterion IDs come from `tasks.get` |\n| `actions.start` | `taskId, agent` | Start a new action, returns `actionId` |\n| `actions.write` | `actionId, sectionType, content` | Record a text section: `result \\| tools_used \\| blockers \\| next_steps`. Does **not** populate the Files dashboard — use `actions.record_file` for that |\n| `actions.complete` | `actionId, summary` | Close an action with a one-line summary |\n| `actions.get` | `taskId` | Full action history for a task (all agents, all sections) |\n| `actions.record_file` | `actionId, filePath, operation, notes?` | Register a file touch. The **only** way to populate the Files dashboard. `operation`: `read \\| created \\| modified \\| deleted` |\n| `actions.record_tool` | `actionId, toolName, argsJson?, resultSummary?` | Register a tool call. The **only** way to populate the Tools dashboard |\n| `docs.search` | `query` | Search the `docsPath` folder for content matching the query |\n\n---\n\n## Agent roles\n\n| Role | Responsibility |\n|------|---------------|\n| **lead** | Decomposes the task into a plan, assigns sub-agents. Does not write code or read source files. |\n| **explorer** | Reads and maps the codebase. Never writes files. Records every file read. |\n| **builder** | Implements the plan. Only writes to `writablePaths`. Records every file modified. |\n| **reviewer** | Verifies all acceptance criteria are met. Approves or blocks. Runs health check before approving. |\n\n---\n\n## What to commit\n\n| File | Commit? |\n|------|---------|\n| `agent-harness-kit.config.ts` | Yes |\n| `AGENTS.md` | Yes |\n| `health.sh` | Yes |\n| `.harness\u002Ffeature_list.json` | Yes |\n| `.claude\u002Fagents\u002F*.md` | Yes |\n| `.claude\u002Fmcp.json` \u002F `opencode.json` | Yes |\n| `.harness\u002Fharness.db` | **No** (gitignored) |\n| `.harness\u002Fcurrent.md` | **No** (gitignored) |\n\nThe rule: commit inputs (config, task definitions, agent instructions). Ignore outputs (DB, auto-generated snapshots).\n\n---\n\n## Runtime compatibility\n\n| Runtime | SQLite | PostgreSQL | MySQL |\n|---------|--------|-----------|-------|\n| Node.js ≥ 22 | ✅ uses `node:sqlite` built-in | ✅ via `postgres` package | ✅ via `mysql2` package |\n| Bun (any recent) | ✅ uses `bun:sqlite` built-in | ✅ via `postgres` package | ✅ via `mysql2` package |\n| Node.js \u003C 22 | ❌ `node:sqlite` not available | ✅ | ✅ |\n\nSQLite requires no additional packages. For PostgreSQL install `postgres`, for MySQL install `mysql2`:\n\n```bash\nnpm install postgres    # for PostgreSQL\nnpm install mysql2      # for MySQL\n```\n\n---\n\n## Contributing & local development\n\n```bash\ngit clone \u003Crepo-url>\ncd agent-harness-kit\nnpm install\n\nnpm run build:ui    # build the dashboard SPA (dashboard\u002F → src\u002Fdashboard-dist\u002F)\nnpm run build       # build:ui + tsc + copy-assets\nnpm run dev         # watch mode (CLI TypeScript only)\nnpm test            # run tests\n```\n\n### Testing the local build in another project\n\nUse the helper script to build the package and link it into any local project in one step:\n\n```bash\n# Build + link into a specific project\n.\u002Fscripts\u002Flink-local.sh \u002Fpath\u002Fto\u002Fyour-other-project\n\n# Build + register globally only (then link manually wherever you need)\n.\u002Fscripts\u002Flink-local.sh\n```\n\nWhat the script does:\n\n1. Runs `npm run build` (full build including dashboard assets)\n2. Runs `npm link` to register the package globally on your machine\n3. Runs `npm link @cardor\u002Fagent-harness-kit` inside the target project\n4. Smoke-tests the `ahk` binary with `--version`\n\nAfter linking, `npx ahk` inside the target project will use your local build. To unlink when you're done:\n\n```bash\n# Inside the target project\nnpm unlink @cardor\u002Fagent-harness-kit\n\n# Optionally remove the global registration\nnpm uninstall -g @cardor\u002Fagent-harness-kit\n```\n\n> **Tip:** If you're iterating quickly, run `npm run build` in this repo after each change — the link picks up the new `dist\u002F` immediately without re-running the script.\n\nTo work on the dashboard UI with hot reload:\n\n```bash\n# Terminal 1 — CLI server (no browser open)\ncd your-test-project && ahk dashboard --no-open --port 4242\n\n# Terminal 2 — Vite dev server with HMR\ncd dashboard && npm run dev   # http:\u002F\u002Flocalhost:5173, proxies \u002Fapi and \u002Fws → :4242\n```\n\nCommit messages follow [Conventional Commits](https:\u002F\u002Fwww.conventionalcommits.org\u002F) with a required scope:\n\n```\nfeat(cli): add export command\nfix(db): prevent race condition in claimTask\nchore(ci): update Node version to 22\n```\n\nTypes: `feat fix chore refactor docs test perf style build ci revert`\n\n---\n\n## Roadmap\n\n- ✅ **`ahk dashboard`** — local web UI with real-time WebSocket updates. Shows tasks, action timelines, file activity, tool usage, and per-agent breakdowns.\n- ✅ **`ahk reset`** — interactively clear the SQLite DB, feature list, and agent files to start a project fresh.\n- ✅ **PostgreSQL + MySQL drivers** — remote database support via `postgres` and `mysql2` packages. Configure with `database: { type: 'postgres', connectionString: '...' }`.\n- ✅ **`actions.record_file` + `actions.record_tool`** — dedicated MCP tools for populating the Files and Tools dashboard views.\n- ✅ **`tasks.add` via MCP** — agents can create new tasks on the fly without leaving the conversation.\n- ✅ **Global installation** — `ahk init` can install the harness to your home directory, shared across projects.\n- ✅ **Input validation** — all CLI prompts validate and retry on bad values.\n- **Graphify integration** — connect the harness to Graphify to visualize agent workflows, task dependencies, and action timelines as interactive graphs.\n- **Open Telemetry integration** — emit OpenTelemetry spans for all agent actions, file operations, and tool calls.\n- **Jira task adapter** — pull tasks directly from Jira instead of maintaining `feature_list.json` manually.\n- **Linear task adapter** — same as Jira, for Linear.\n- **GitHub Issues adapter** — same, for GitHub Issues.\n- **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.\n","agent-harness-kit 是一个与提供商无关的脚手架工具包，用于在代码库中运行结构化的多代理工作流。它提供了一个任务积压列表、定义的工作流程、每个操作的持久日志以及开始任何工作前必须通过的健康检查门，确保AI代理在执行任务时有记忆、协调和审计追踪。该工具包适合需要多个专业代理按顺序协作完成复杂任务，并且要求对整个过程有详细记录和控制的场景。使用TypeScript编写，提供了丰富的命令行工具来初始化、构建、同步及监控项目状态。",2,"2026-06-11 03:31:34","CREATED_QUERY"]