0.13.0

Harness

Agent-ready repository harness — a global npm CLI that turns any software repo into a structured workspace for humans and coding agents.

The app is what users touch. The harness is what agents touch.

Install

Install and update with npm, bun, or pnpm. The package is a thin launcher: it downloads/runs the OS-native binary for your platform (not a Node.js CLI).

npm i -g 5harness
# or
bun add -g 5harness
# or
pnpm add -g 5harness

harness --version
npm update -g 5harness    # or bun/pnpm equivalent, or `harness update`

Direct OS installers (no Node required) are a fallback:

Windows (PowerShell):

$version = "0.27.1"
Invoke-WebRequest "https://raw.githubusercontent.com/vantanminh/5harness/v$version/install/windows.ps1" -OutFile install-5harness.ps1
Get-Content .\install-5harness.ps1
powershell -ExecutionPolicy Bypass -File .\install-5harness.ps1

macOS:

VERSION=0.27.1
curl --proto '=https' --tlsv1.2 -fsSL "https://raw.githubusercontent.com/vantanminh/5harness/v${VERSION}/install/macos.sh" -o install-5harness.sh
less install-5harness.sh
bash install-5harness.sh

Linux:

VERSION=0.27.1
curl --proto '=https' --tlsv1.2 -fsSL "https://raw.githubusercontent.com/vantanminh/5harness/v${VERSION}/install/linux.sh" -o install-5harness.sh
less install-5harness.sh
bash install-5harness.sh

Point any native installer at a local build with HARNESS_INSTALL_FROM (directory or binary path). Pin a release with HARNESS_INSTALL_VERSION=<version> and use HARNESS_INSTALL_SKIP_PATH=1 in automation. Prefer npm/bun/pnpm for version management.

Project-local (optional):

npm i -D 5harness
npx harness --help

Releases use npm trusted publishing (OIDC) with provenance when configured. See docs/product/distribution.md.

Quick start

cd /path/to/project
harness init                 # scaffold markdown + register this project
# after git clone of a harnessed repo on another machine:
harness link                 # register path + reindex committed history

harness intake --type spec_slice --summary "Add export API" --lane normal
harness intake update --id IN-001 --stories US-001
harness intake close IN-001
harness story add --id US-001 --title "Export API" --lane normal
harness story update --id US-001 --status implemented --unit 1 --integration 1 --e2e 0 --platform 0
harness decision add --id 0001 --title "Use markdown SoT" --doc docs/decisions/0001.md
harness query matrix
harness search "export"
harness get US-001
harness links US-001
harness doctor
harness next
harness dashboard            # or bare: harness

Features

Project Link (opt-in)

Project Link lets related repositories declare roles, resolve explicitly configured peers, read bounded peer context, and exchange durable reports:

# frontend project
harness project role set frontend --stack supabase
harness project peer add <backend-project-id-or-path> --role backend
harness peer search "auth contract" --role backend
harness report add --to backend --summary "Login response contract mismatch"

# backend project
harness report list --status open
harness report get RP-001
harness report update --id RP-001 --status fixed --resolution "Updated response schema"

Role, stack, and peer ids are Git-backed markers in the managed AGENTS.md block. Peer paths are not committed: both repositories must be registered in the same machine-local ~/.5harness registry (or HARNESS_HOME). Reads are limited to direct configured peers and bounded search / get / context / links results; peer-of-peer traversal and arbitrary paths are rejected.

Reports are target-owned Git-backed entities under docs/reports/. Create and update them only through harness report or its MCP tools, never by hand. Keep payloads sanitized: do not include credentials, tokens, secrets, or unnecessary personal data. Multi-user machines can restrict report targets with HARNESS_PEER_WRITE_ROOTS, an OS-path-delimited list of existing absolute directories. When set, CLI and MCP report creation fail closed for targets outside those canonical roots. doctor reports policy mismatches in addition to unresolved peers and missing peer indexes; status summarizes Project Link state; next surfaces open reports before planned backend work.

MCP authentication

Both harness mcp and the dashboard's /mcp endpoint are OAuth 2.1 protected resources. MCP clients discover the embedded authorization server through RFC 9728, dynamically register as public clients, and use Authorization Code with mandatory PKCE S256. Access tokens are short-lived, opaque, and bound to the canonical MCP resource URI. The server starts unbound: the working directory and --dir do not authorize access to a project. During consent, the operator grants either one healthy linked project or all healthy linked projects.

harness dashboard              # MCP resource: http://127.0.0.1:3927/mcp
harness mcp                    # MCP resource: http://127.0.0.1:3928/mcp
harness dashboard set-password # replace the initial administrator password

A single-project grant always routes tools to the selected project. An all-projects grant requires the target project's durable id on every MCP request:

cd /path/to/project
harness project id             # also stored as harness-project-id in AGENTS.md

# Preferred all-projects request selector:
X-Harness-Project: <project-id>
# Compatibility selector: append ?project=<project-id> to the MCP resource URI

Missing, conflicting, unknown, unlinked, or unavailable project ids fail closed. Agents must not infer authorization from cwd. See the project-binding specification and security model.

After binding the calling project, MCP tool discovery dynamically exposes peer read and report tools only when that project has configured peers. In an all-projects grant, X-Harness-Project still selects the calling project; a peer id never substitutes for that OAuth binding. Cross-project operational-entity mutation is restricted to sanitized reports owned by the configured target project; explicit peer-management commands may also attempt reverse configuration markers.

Plain HTTP is accepted only on loopback. A non-loopback bind requires an HTTPS reverse proxy and its canonical URL, for example harness mcp --host 0.0.0.0 --public-url https://mcp.example.com.

Product pivot: decision 0011.

Optional cloud sync

Harness Cloud synchronizes durable markdown across devices and exposes a hosted MCP so a web AI (ChatGPT and others) can read a designated project's harness and write an implementation brief.

harness login                 # default https://5harness.knotree.com
harness sync push             # once: store passphrase, then auto-sync on durable edits
harness sync status
harness plan get <token>      # load a brief created by a web AI

harness login prints a short-lived device code and verification URL. Approve the code in the browser; the CLI polls the Worker with PKCE and does not need a loopback callback listener. After the first successful push, later durable CLI mutations auto-sync as GitHub-like commits (id, time, author, client, changed paths). Override the server with --server or HARNESS_CLOUD_URL. Check an existing session with harness login --status.

The CLI still encrypts a restore snapshot with PBKDF2 + AES-256-GCM. A user-scoped harness catalog is stored so hosted MCP can read entities without source code. Connect a web AI to https://5harness.knotree.com/mcp with the same account, ask it to research a project, then have it call harness_plan_create. It should return:

please implement plan from harness --<token>

A coding agent loads the full plan and prompt with harness plan get <token>. Configure and deploy using docs/product/cloud-sync.md, firebase/README.md, and web/README.md.

Agent rules (summary)

1. First commands: harness doctor --json, harness next --json. Then the harness block in AGENTS.md or .agents/skills/harness/SKILL.md. Do not dump the whole docs tree.
2. Mutate only via tools: harness intake / story / decision / backlog / report — never hand-edit operational entity markdown.
3. Hard-fail (decision 0017): if harness CLI or MCP fails for a required step → HARD STOP. Recover with doctor / link / reindex, then retry. Do not bypass with hand-edits.
4. Prefer queries: search, get, links, query matrix|stats, next with --json.
5. Commit after each completed slice. Do not push unless asked.

Full contract: AGENTS.md · docs/CONTEXT_RULES.md.

Security

• Report vulnerabilities privately — SECURITY.md
• Trust model (verify commands, MCP local-only, registry paths, secrets, provenance for consumers): docs/SECURITY.md

harness story verify runs the project-authored verify command from story markdown (intentional local proof, like CI scripts).

Changelog

Notable changes: CHANGELOG.md (Keep a Changelog + semver).

Draft assist from durable history:

harness export changelog [--since 2026-07-01]

Current status

Local development

npm install
npm run build
npm test
npm --prefix firebase/functions install
npm run cloud:build
npm run cloud:test
npm --prefix web install
npm run web:build
npm run web:test
npm run pack:check          # tarball + version sync
# full gate:
npm run release:check
node dist/cli.js --help
# or: npm run harness -- --help

CI / CD

• Cloud surfaces: Firebase Auth/Firestore rules + Cloudflare Worker/Pages checks on changes under firebase/ or web/
• CI (push/PR): release:check on ubuntu / windows / macos × Node 22 + 24
• Auto-release (push to main): bump, tag, OIDC npm publish --provenance, GitHub Release + SBOM (skip with [skip release])
• Manual: Actions → Release, or matching v* tag

Details: docs/product/distribution.md.

Read first (agents & contributors)

1. AGENTS.md — identity, mutation rules, hard-fail
2. docs/product/overview.md — product contract
3. docs/HARNESS.md — collaboration loop
4. docs/FEATURE_INTAKE.md — lanes before code
5. docs/ARCHITECTURE.md — stack and layering
6. docs/decisions/ — locked choices
7. docs/product/roadmap.md — implementation tracking

Update notices

The CLI may print a one-line notice on stderr when a newer npm version exists. Successful checks are cached for one hour under ~/.5harness/; transient npm errors retry after five minutes. Disable with HARNESS_NO_UPDATE_CHECK=1 (also auto-disabled when CI=true).

harness update    # reinstall latest with detected package manager
harness upgrade   # refresh harness block in project AGENTS.md

License

MIT — see LICENSE.

Acknowledgments

Thanks to the authors of repository-harness for ideas we studied while designing this product.