harness-async

harness-async is the home of ha (harness-agent), an agent-first CLI and local web dashboard for async human-agent collaboration.

ha is built around a few core ideas:

• Agent-first CLI usage. The main caller is an agent, not a human typing commands by hand all day.
• Layered collaboration. Tasks are marked as L1, L2, or L3 based on how much human involvement they require.
• DAG orchestration. Tasks can depend on each other and unlock downstream work automatically.
• Dual storage. ha supports both project-local state and global state.
• Auditability. Tasks, events, runs, and dashboard views make the workflow inspectable.

What works today

The repository already contains a working implementation, not just design docs.

• CLI commands for init, doctor, task, schedule, daemon, run, and hook
• Markdown task storage with frontmatter, index.json, and append-only events.ndjson
• DAG dependency handling and task state transitions
• Local daemon support for launchd and Docker
• Dashboard backend and frontend
• Claude and Codex adapter integration
• Test coverage across CLI, core logic, dashboard, and end-to-end flows
• npm packaging and publish-ready build output

Repository layout

.
├── AGENTS.md
├── README.md
├── docs/
│   ├── 01-architecture.md
│   ├── 02-mvp.md
│   └── 03-roadmap.md
├── specs/
│   ├── AGENTS.md
│   └── active/
│       ├── phase0-scaffold-plan.md
│       ├── phase1-mvp-plan.md
│       └── phase2-agent-integration-plan.md
├── src/
│   ├── adapters/
│   ├── cli/
│   ├── core/
│   ├── dashboard/
│   ├── daemon.ts
│   └── types/
├── tests/
│   ├── cli/
│   ├── core/
│   ├── dashboard/
│   ├── e2e/
│   └── types/
├── scripts/
├── package.json
├── tsconfig.json
├── tsconfig.build.json
└── Dockerfile

Directory responsibilities:

• docs/: stable project-level design documents
• specs/: execution plans and acceptance criteria by phase
• src/cli/: CLI entrypoint, command registration, and terminal output helpers
• src/core/: task storage, DAG logic, scheduling, daemon, run management, and workflow logic
• src/adapters/: agent adapter interfaces and Claude/Codex implementations
• src/dashboard/: local HTTP server, websocket layer, and dashboard UI
• src/types/: shared types and schemas
• tests/: regression and end-to-end coverage
• scripts/: helper scripts for local verification
• dist/: build artifacts, generated only
• .ha/: local project state managed by the CLI, not hand-edited

Getting started

Requirements:

• Node.js >= 20
• npm >= 10

Local development setup:

npm install
npm run build
npm link
ha --help

A typical local smoke flow:

ha init
ha doctor
ha task create "Implement auth module" --level L1
ha task list
ha task graph
ha daemon start

Install from npm

The published package name is harness-async. The installed command is ha.

Global install:

npm install -g harness-async
ha init
ha doctor

Run without a global install:

npx -y -p harness-async ha init
npx -y -p harness-async ha doctor

Development commands

npm run build
npm test
npm run test:e2e
npm pack --dry-run

Publishing

Before publishing, verify the package locally:

npm run build
npm test
npm pack --dry-run

Publish to npm:

npm publish --registry=https://registry.npmjs.org/

If your npm account requires publish-time 2FA, complete that setup in npm account settings before publishing.

Reading order

If you are new to the repository, read in this order:

1. README.md
2. docs/01-architecture.md
3. docs/02-mvp.md
4. docs/03-roadmap.md
5. The relevant file under specs/active/
6. The implementation and tests for the area you are changing

Notes

• docs/ holds stable architectural intent.
• specs/active/ holds execution plans.
• Code changes should stay consistent with both. If they diverge, fix the mismatch explicitly rather than silently drifting further.