harness-mini

A minimal outer harness for developers' long coding tasks.

Run a coding agent on a multi-session feature and three failure modes compound:
it drifts off the goal, context explodes as heavy reads crowd out working
memory, and closing the window means session amnesia — decisions and
in-flight plans evaporate. harness-mini keeps that work on-task,
context-light, and resumable with nothing but repo conventions and thin shell
glue: skills, sub-agents, plans, checkpoints, and evals — all committed to git.
It is an outer harness around your coding agent (not a generic agent shell,
not a sandbox platform), and its whole contract is files + shell: any agent
that can read the repo and run commands can drive it.

Core Architecture Contract

The harness is an environment, not a program — no runtime, no daemon, no
package manager, no third-party binary. Five invariants define it:

Under all of it sits the Mini constraint — delete before you add; a new
capability is a doc by default and only becomes shell when it must execute
(docs/principles.md).

Who it's for / not for

How it compares (one glance)

Quick Demo

Placeholder for an asciicast recording. The clip should show, end-to-end:
init.sh grafting the harness into a project, the agent routing a real task
through stage-viewer (intake → prd → issues → implement), a disposable
explorer absorbing a heavy read so the main context stays under the 40% line,
an evaluator grading the slice in a separate window, and a committed
checkpoint that a brand-new session resumes from with zero context loss.

Install

It installs like a skill — tell your agent "install harness-mini here", or run:

git clone https://github.com/harness-mini/harness-mini.git
bash harness-mini/init.sh /path/to/your/project

init.sh is additive (never overwrites your files) and idempotent (safe
to re-run). It behaves asymmetrically:

• New/empty project → generative bootstrap: seeds an intake plan and runs the
  founder funnel (founder-check → to-prd → to-issues).
• Existing project → recon graft: installs additively and seeds a recon plan
  (the explorer maps your codebase into ARCHITECTURE.md); skips the founder
  funnel.

Skills install to .claude/skills/ and agents to .claude/agents/.
harness/manifest.md lists those paths. Any coding agent that can read the
repo and run shell can drive the same files.

So the agent prefers the harness by default (rather than waiting to be told),
init.sh also seeds a short routing gate into each host's always-on file —
CLAUDE.md, .cursor/rules/harness-mini.mdc (Cursor), and the top of
AGENTS.md (Codex). The gate is status-first and path-aware: run
bin/harness.sh status, read its path: line, and open the matching session
skill (session-init for plan work, session-coding for slice work) — see
The session path below. Non-trivial work still routes
through stage-viewer first, and when a harness skill and another tool both
fit, the harness skill wins. Seeding is additive + idempotent — an existing
CLAUDE.md keeps its content, and older gate versions are upgraded in place
(marker-guarded, exactly one gate ever).

How a host picks it up

Same files everywhere. Nothing here is a primary agent; each host reads the
install layout in its own way:

The harness is plain Markdown + shell, so any agent can use it by reading the
files — init.sh seeds the routing gate for each host (and, for Cursor, one
agent-requested rule per skill), and the getting-started guides show the prompt
recipes: docs/cursor-getting-started.md and
docs/codex-getting-started.md. The Cursor
skill mirror is file-level tested and demonstrated end-to-end: a worked
run (examples/cursor-slugify-demo/,
#23) shows Cursor
observably loading the gate and pulling skill rules on demand by description,
with a separate-chat evaluator reproducing the firewall. That's one model
session, not a guarantee for every host — and Cursor still has no 40%-line hook,
so that reminder stays manual there.

Your first task: quick or full?

harness-mini does not force ceremony onto every change. Route first:

The stage-viewer skill makes this call; the templates are its two shapes. New
to the loop? Watch one run end-to-end: docs/walkthrough.md.

The session path

Every session starts from file truth, not memory. bin/harness.sh status
distills the board into machine lines:

$ bin/harness.sh status
active plans:
  demo-auth                stage: implement
     workboard: in_progress · 1/3 pass · current: slice-002 · next: slice-002
path: coding
path_reason: next slice ready
ready: ready — slice-002: write the failing 401 test, then bcrypt verification

The path: line picks the playbook:

• path: init → the session-init skill: plan-layer work only
  (founder funnel, PRD, issues, the JSON twin) — no product code on this path.
• path: coding → the session-coding skill: a mandatory five-step
  Getting Bearings first turn (pwd · status + recent commits + latest
  checkpoint · open the twin and select the next: slice · app baseline green ·
  report the selected slice), then exactly one slice, test-first, verified
  against the twin's steps and routed through evaluate — the builder never
  flips passes (anti-self-praise).

Each plan is a dual file: <NNN-slug>.md (narrative; frontmatter stage:
is the lifecycle authority) + a same-basename .json twin (the machine
workboard: status · current_slice_id · slices[].passes). A
## Session Context Handoff section gives a cold session its three-line
memory. For unattended runs, bin/session.sh forces the matching playbook
into a fresh context (bin/session.sh -- <your-host-cli> …); it is optional
P2 glue, not part of the core.

Versioning & updates

The install is versioned. bin/harness.sh is the front door:

bin/harness.sh version              # installed version (+ latest, best-effort)
bin/harness.sh update               # pull a newer harness into this project
bin/harness.sh doctor               # install health: ok/warn/fail (exit 1 on fail)
bin/harness.sh status               # work state: plans, workboard, session path, resumable
bin/harness.sh report               # aggregate .trace metrics (stages, context, evals)
bin/harness.sh release <x.y.z>      # (source repo) bump + tag + GitHub release

The firewall has teeth: a plan can't reach done without a committed
verdict: pass record in .trace/evals/ — doctor FAILs otherwise. report
turns the runtime traces into a metrics summary (context trend vs the 40% line,
eval pass-rate + rework loops) so the thresholds are tuned by data, not vibes.
Hosts that speak a PostToolUse hook can give the 40% rule teeth with the
opt-in bin/ctx-hook.sh (see docs/smart-dumb.md). Wire it from
.claude/settings.json.

On entering a fresh session the agent runs harness.sh status first (the
routing gate is status-first); when a newer release exists, version, status,
and doctor all surface an update reminder, so you're prompted to update
rather than drifting behind. The check is best-effort and silent offline
(HARNESS_NO_NET); HARNESS_LATEST pins it.

init.sh records the version and a checksum of every harness-owned file in
harness/harness.lock. update is checksum-guarded: files you never touched
are refreshed silently, files you edited are kept (the upstream copy is
written next to them as <file>.new), and brand-new files are added — your
exec-plans, .trace/, and project code are never touched. release stamps
VERSION, rolls CHANGELOG.md, tags v<x.y.z>, and cuts a GitHub release,
gated on green tests + a clean tree (see the release skill).

The one rule: the 40% line

Context occupancy below 40% = smart zone; at/above 40% = dumb zone. Every
agent keeps itself smart by (1) delegating heavy reads to a disposable explorer
(context firewall), (2) checkpointing + resetting at 40%, (3) progressive
disclosure. See docs/smart-dumb.md. Estimate with bin/ctx.sh <used> [window].

What we measured (bench/cib/results/FINDINGS.md).
We built a benchmark (bench/cib/) and ran it live on gpt-4o-mini, haiku-4.5, and
Qwen2.5-7B. Under a controlled design (fixed task, only context fill varied), raw
occupancy showed no 40% "intelligence cliff" — even on the small model from the paper
that motivated the line. What degraded real QA-F1 was interference (competing,
related content), not how full the window was. So 40% is a conservative checkpoint
default, not a law — and the firewall + progressive-disclosure mechanisms earn their
keep by holding competing content out, which is the effect that actually matters.
(Caveat: gradual/modest effect, frontier-model contrast still pending.)

Lifecycle

intake → prd → issues → implement ⇄ evaluate → checkpoint → done
                           ↑___________|   (loop until criteria pass)
       garden ──── runs orthogonally, on triggers ────

Only the main agent advances the stage (via stage-viewer). No worker promotes
its own work to "done" — evaluation happens in a separate context (the
anti-self-praise gate), tiered by risk: L0 self-check · L1 lightweight
reviewer (default) · L2 full Opus evaluator. See the evaluate skill.

Layout

Editing skills? skills/<name>/SKILL.md (and agents/<name>.md) are the
canonical source — edit there. init.sh copies them into a target
project's .claude/skills/ and .claude/agents/. This repo does not commit
that directory.

Sub-agents

Model is a capability tier, not a pinned version. The builder (generator)
auto-upgrades to the highest-available frontier model tier (opus, the top
tier the harness names) when HARNESS_TOP_MODEL is set, falling back to sonnet
otherwise; every other role keeps its static tier. The spawning agent resolves it
at spawn time via bin/model.sh builder and passes the result as the worker's
model override. Set HARNESS_TOP_MODEL=1 to force the upgrade;
HARNESS_MODEL_BUILDER=<alias> pins the builder to an exact model.

Develop

bash tests/run.sh   # 299 assertions, zero dependencies

Pure POSIX shell, no dependencies — tested on macOS bash 3.2 and Linux bash,
and safe to call from zsh. See the compatibility notes in
CONTRIBUTING.md before contributing shell.

References distilled in docs/references/

• Anthropic — Effective harnesses for long-running agents
• Anthropic — Harness design for long-running apps
• Anthropic — Scaling managed agents (decoupling brain/hands/session; stale assumptions)
• OpenAI — Harness engineering (leveraging Codex)
• Anthropic — The Founder's Playbook

Contributing

Issues and PRs welcome — see CONTRIBUTING.md. It's a small,
opinionated harness: most contributions are Markdown (skills, agents, docs) plus
the occasional ~30 lines of test-first shell. Ship thin, keep it smart.

Community

GitHub Discussions —
questions, show-and-tell, and feedback welcome.

Accessibility matters here too — our accessibility statement
covers goals for the CLI's plain-text output and the docs, supported
environments, and how to report barriers.

License

MIT © 2026 harness-mini contributors.