create-agent-harness

Cross-platform scaffolder for a multi-agent project harness: Claude (architect) + Gemini (researcher) + Codex (typist), wired with rule files, MCP servers, and a heuristic task router.

Works on macOS, Linux, and Windows. Requires Node ≥ 18.

Use

# from any directory
npx create-agent-harness@latest my-project
cd my-project
# then open CLAUDE.md / lat.md / DESIGN.md and fill in the project-specific blanks

Apply to an existing repo without clobbering its .claude/settings.json:

npx create-agent-harness@latest . --merge

What you get

my-project/
├── CLAUDE.md              # senior-engineer conventions + lane rules
├── lat.md                 # repo map (top-level layout, module ownership)
├── DESIGN.md              # UI/UX system contract
├── .claude/
│   ├── settings.json      # permissions for claude/codex/gemini/gh/git
│   ├── agents/
│   │   ├── architect.md   # Claude
│   │   ├── researcher.md  # Gemini
│   │   └── typist.md      # Codex
│   └── commands/
│       ├── route.md       # /route
│       ├── analyze.md     # /analyze
│       └── design.md      # /design
├── .mcp.json              # filesystem / github / postgres
├── scripts/
│   ├── route.mjs          # picks the right agent
│   ├── invoke-claude.mjs
│   ├── invoke-codex.mjs
│   └── invoke-gemini.mjs
└── docs/HARNESS.md        # how the harness works

Design choices (and what we deliberately left out)

• No third-party orchestrators. Heuristic router in 80 LOC beats a framework that breaks on upgrade. Replace it when you outgrow it.
• No "claude-hud" / "plannotator" / similar tools are auto-installed — they're listed in docs/HARNESS.md as optional pointers because their stability isn't something we can guarantee per platform.
• MCP set is small on purpose: filesystem, github, postgres. Add more in .mcp.json as you need them.

Optional add-ons (opt-in, not bundled)

These third-party tools pair well with the harness. They are not auto-installed because their stability and cross-platform behavior is out of our control. See docs/EXTERNAL_TOOLS_REPORT.md for the full Gemini-generated review with risk ratings.

| Tool | What it adds | When to install | | --------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------ | | claude-hud | terminal HUD: context %, token spend, tool use | always, if you run long agent sessions | | plannotator | visual review of agent-generated plans before execution | when changes have high blast radius | | notebooklm-mcp | MCP server backed by NotebookLM for heavy RAG | when researcher tasks need persistent doc corpus | | andrej-karpathy-skills | Karpathy-flavored CLAUDE.md guardrails | already overlaps with our default CLAUDE.md — borrow snippets only | | myclaude | richer multi-agent workflow templates | when the 3-agent split feels too narrow |

URLs above were resolved by Gemini and spot-verified with gh repo view — all five repos exist, are public, and were active in the last 30 days as of the report date. Re-verify before integration.

CLI flags

| Flag | Meaning | | ---------------- | ---------------------------------------------------------- | | <target-dir> | folder to scaffold into (created if missing) | | --name <name> | project name written into rule files (default: folder name)| | --merge | merge .claude/settings.json with existing instead of overwriting | | --no-install | skip the postinstall hints |

Develop locally

cd tools/agent-harness
node --test tests/smoke.test.mjs    # smoke tests
node bin/create.mjs /tmp/demo --name demo

Maintenance — dhelper ↔ GitHub template sync

This package is authored inside dhelper/tools/agent-harness/ and mirrored to github.com/neohum/create-agent-harness (template repo). To push local changes upstream:

# from dhelper repo root
git subtree push --prefix=tools/agent-harness `
  https://github.com/neohum/create-agent-harness.git main

To pull upstream-only changes back into dhelper:

git subtree pull --prefix=tools/agent-harness `
  https://github.com/neohum/create-agent-harness.git main --squash