VE Harness — walk away, come back to reviewed work

Q: Can I add it to a project that already has a CLAUDE.md?

Yes. When setup finds an existing CLAUDE.md or .claude/ directory it runs in upgrade mode: it reads your files, diffs them against the current templates, tells you what is new, asks which changes you want, and never overwrites anything without confirmation. The same mode is how you pull in later updates.

What's in it

Three layers. Adopt as many as you want. Hover or tap a layer for what it is and what it needs.

Layer 3 · VE Worker

A container that works the board while you're away.

What it does: Clones your repo inside the container, takes the highest-priority ready task off the board, checks it isn't already done, builds it on its own branch and opens a PR for you to review.
Needs: Docker, the board, and a fine-grained GitHub token scoped to the one repo. It runs on your existing Claude subscription.
The brake: A spend cap per batch, set by a flag rather than a prompt. What the container is given is the real boundary: a single-repo GitHub token you scope yourself, a board key (its file is mounted read-only; the key can still write to the board) and your Claude token — never your checkout, SSH keys or cloud CLI credentials.
Read: 03-VE-WORKER.md →

Layer 2 · Vibe Board

The memory that outlives the window.

What it is: An MCP server backed by Firestore: 21 tools for projects, tasks, sessions, handoffs, an activity log, gate telemetry and shared memory.
Needs: A Firebase project — Firestore's free tier covers normal use — plus Node 18+ and the gcloud and Firebase CLIs.
What it adds: A new window reads the last one's handoff and continues. A teammate's agent can search what yours learned.
Read: 02-VIBE-BOARD.md →

Layer 1 · Bootstrap

The foundation, written into your repo while you watch.

What it writes: CLAUDE.md, the rule templates, the hooks with a test suite each, a permission allow-list and deny-list, and the skills.
Needs: Claude Code, git and python3 — the hooks parse their input with it, and fail open without it — plus gitleaks for the secret gate. No cloud project, no container.
On its own: A disciplined single-session setup with process gates.
Read: 01-BOOTSTRAP.md →

The board works without the worker. The hooks work without the board.

Without it, and with it

Nine places a long session goes wrong, and what happens there instead.

When	Without a harness	With VE Harness
Session ends	Context is gone; the next session starts cold.	Handoff notes are on the board; the next window resumes.
Compaction hits	Task state silently drops out.	A hook tells the agent to reopen its board session and pick its tasks back up.
Review	A habit you skip under pressure.	`git commit` is denied until a review ran.
Permissions	Approve this, approve that, all day.	Pre-approved inside the fence, denied outside it.
Secrets	Caught in code review, or not at all.	Scanned before the commit lands.
Protected files	A stale copy silently reverts a shipped fix.	The edit is denied until you explicitly override it.
Team knowledge	Travels by pull request, or by Slack.	Agents share what they learn in real time.
Overnight	The queue sits idle until you're back.	A container worker runs it under a spend cap and opens a PR.
Your process	Lives in your head.	Lives in rules, hooks and modes.

The three things it actually buys you

11 hook test suites — one per hook — run on Ubuntu and macOS on every push.

It runs longer

Everything a session knows evaporates when the window closes. Here it doesn't: plans, decisions, deviations and handoff notes land on the board while the work happens, and two hooks tell the agent to reopen its board session after a restart or a compaction. The hooks remind; the agent acts — reliable, not mechanical. Close the window, open a new one, it reads the handoff and continues.

Check it: 02-VIBE-BOARD.md — 21 board tools, sessions and handoffs included.

It runs safely

Not sandboxed-safe — safe as in the moves that cost you a bad afternoon are the ones the harness makes hard. git commit is denied until a review ran, and the marker is per-session, so one window's review can't authorize another window's commit. Secrets are scanned before the commit lands, and findings are listed without ever printing the value.

Check it: bash doctor.sh — tells you whether the gates in your project are installed, registered and able to fire.

Best practices, without the pain

Everyone knows you should plan before you code, review before you commit, and write down why. Nobody does it consistently at 11pm. A mode system does it instead — plans bind to board tasks, each task names the specialist that owns it once you've built some, and a deviation protocol puts divergence on the record instead of quietly substituting a different approach.

Check it: the badge above, and ls .claude/hooks/test-*.sh for the honest list.

the review gate, denying a commit — illustrative output

$ git commit -m "wire up the thing"

REVIEW GATE — code changes require review before commit. AUTO-RUN the review now:

  1. Invoke the code-reviewer agent (focus: the staged diff).
  2. If the staged diff includes TypeScript/Python/SQL/tests, also invoke test-runner.
  3. If any critical or high findings surface, STOP and surface them to the user for a
     decision. Do NOT commit.
  4. If findings are low/medium or clean, file them to the board, create THIS SESSION'S
     marker, THEN retry the commit.

The marker is namespaced by session_id so one window's review cannot authorize another
window's commit; touching any other path will not satisfy this gate.

Abridged from the hook's real output. The gate denies; it does not grade your review. It looks for a marker the agent sets once it has reviewed, and it fires when a commit touches code — by default TypeScript, JavaScript, Python, SQL, shell and config files outside docs/ and .claude/ — or stages everything at once. A commit of only other files passes, so add your language's extensions to the hook. The reviewer it calls for is one you build with /build-agents.

RIPER-CAT · the mode system

How a task moves through it

Seven steps in order, and two modes you can drop into at any point. The agent opens every reply with the mode it's in, so you can see at a glance whether it is still reading or already writing — and the working modes say what they may not do yet.

[MODE: RESEARCH]

Read first. Understand the problem before proposing anything.

Does: Reads the code and asks questions.
May not: Suggest, plan or write code.
On the record: Anything new it notices is logged to the board as it goes, so a compaction doesn't erase it.

[MODE: INNOVATE]

Options on the table, with the trade-offs of each.

Does: Lays out the approaches, their pros and cons, and the edge cases.
May not: Go into implementation detail or write code.
Optional: Skip it for a task you already understand. It is the only step you can skip.

[MODE: PLAN]

A full spec, and a board task for every line of it.

Does: Names the files and functions, then creates one board task per checklist item — each assigned to the specialist that owns it, once you have specialists.
May not: Write the code.
Then: Goes straight into review, automatically. No plan runs unchecked.

[MODE: REVIEW]

The plan gets checked before anything is built.

Does: Reads the tasks back off the board: is each one clearly scoped, are the dependencies right, is anything missing?
Verdict: Pass or fail, with the findings logged to the board so they outlive the session.

[MODE: EXECUTE]

Build exactly what the plan says.

Does: Implements the plan, handing each task to the specialist it names, where there is one.
May not: Deviate silently.
If it must: The deviation protocol: it flags the change on the board, says what was planned, what it is doing instead and why, then carries on.

[MODE: REVIEW]

A second opinion on the result, once you've built the reviewers.

Does: Calls the code-reviewer and test-runner agents, if you've built them, to look for bugs, security issues and failing tests.
Also covers: Changes made outside the repo. A schema change applied by hand is reviewable output too.
Verdict: Pass or fail, findings on the board.

[MODE: COMMIT]

Only when you say so.

Does: Stages and commits — and any doc or rule the change made wrong ships in the same commit.
May not: Touch the implementation.
Hook-backed: git commit is denied until a review ran in this session.

[MODE: TROUBLESHOOT]

Stop everything and find the root cause.

Does: Pauses whatever mode it was in for a deep diagnosis.
Returns: A list of the issues and a proposed way through them.
Then: Picks the previous mode back up.

[MODE: AI REVIEW]

Bring another model's critique in.

Does: Takes a critique from another AI and agrees, disagrees or improves on it.
Then: Returns to the mode it left.

/go <task> The whole cycle, one command.

It drives research, plan, review, execute and review on its own, moving on each time a review passes. It stops for four things: a review that finds something serious, 500 lines changed, a task that turns out bigger than it looked, or a decision that is yours to make. Run interactively, it never commits — that waits for you.

The modes are a rule the agent follows, not a gate. Two hooks back the flow: the commit is denied until a review ran, and a turn that changed something is stopped once if nothing reached the board.

Memory, in three layers

Your repo already syncs your code. It does not sync what your agents learned while writing it.

Claude Code forgets at three different speeds, so the harness remembers at three. The middle one is the part most setups don't have.

The board outlives the session, a compaction, the machine

Tasks, sessions, handoff notes, and an activity log of decisions and deviations. Closing a task with open children is refused until you say what happens to them — agents kept closing parents and silently orphaning five to nine real subtasks, so the data layer refuses.

Shared memory outlives the developer Most setups lack this

The rules and gotchas any teammate's agent recorded — “X caused Y; do Z instead”, with the files and commits that prove it. Saved in one window, findable from every other window's next search. No commit, no pull, no “did you see my message”. It is searched, not pushed: an agent finds a memory when it looks for one, and the tool descriptions tell it to look at session start.

Auto-memory outlives the conversation

Claude Code's own per-project memory. /review-memory audits it for stale, duplicated and mis-filed entries, and files what it finds as board tasks.

Gate telemetry · /self-improve

It learns from what keeps going wrong

A one-off is never a rule. A pattern has to come back before the harness proposes one.

Most setups get better when someone remembers to write the lesson down. This one keeps a record of what its own gates did, and turns the repeats into guardrails — with you approving anything that changes CLAUDE.md or a rule file.

01 · Record

The gates keep their own log

Installed in full, five of the six deny gates — all but the todo block — write a line each time they fire: which gate, which session, and the file where there is one. Two optional recorders cover what the gates can't see — files a shell command changed, as git sees them, and which rule files actually loaded, and why.

02 · Share

One picture for the whole team

The log is local and gitignored. With the board, an optional hook lands every machine's log in one shared store. A row it can't upload is set aside whole, never truncated, and a run that fails is recorded as failed instead of looking quiet.

03 · Find what recurs

Root causes, not symptoms

/self-improve reads the review findings on the board, the worker's batch outcomes and the telemetry, and groups them by root cause. Seen once, it becomes a note or a task. Seen twice, in separate sessions, batches or findings, it becomes a candidate.

04 · Propose

The bigger the change, the more it asks

Guardrails are tiered by blast radius. The worker's own lessons file is updated directly. A change to an agent is proposed as a board task, though a one-line addition may be applied and flagged. A change to CLAUDE.md or a rule is filed as a board task that waits for your approval. These are the skill's instructions, not a gate.

What a line holds. A timestamp, the gate, the event and the session, plus the file where there is one: repo-relative inside the project, the full path for a protected file outside it. The recorders add your git email, or user@host if git has none, and the shared store stamps that and the log's own path on every row. For a shell command it records the shape — heredoc, sed, redirect — never the text, because commands can carry secrets. No secret values, no file contents. VE_GATE_TELEMETRY=off turns it off.

A deny is not a catch. Before it counts one, the skill is told to check whether the gate changed what the agent did. A gate that cost a round-trip and changed nothing is a finding about the gate, not about the code.

You run it. /self-improve does not fire on its own: run it after a handful of worker batches, or when the same finding keeps coming back. The worker's own lessons file is the one exception to the one-off rule: a single batch is enough for an entry there, and what it adds reaches you in the batch's PR like any other change.

The config audits itself too. Eight /review-* skills check your agents, skills, rules, docs, memory, board and .claude/ security, and file what they find on the board rather than in prose you'll scroll past.

What ships

The inventory, by the numbers.

11

Hooks

Six deny — review, first-edit facts, protected files, secrets, stop-compliance, ephemeral todos. Two remind the agent to reopen its board session after a restart or compaction. Three record gate telemetry.

11

Hook test suites

One for every hook, run in CI on Ubuntu and macOS on every push. A green badge means the suites passed on clean machines — not that your project's hooks are installed. That's what doctor.sh is for.

15

Skills

Bootstrap, go, plan, review, close, build-agents, the eight review audits, and self-improve — plus a shared reference folder they all cite.

21

Board tools

Projects, tasks, sessions, handoffs, activity, gate telemetry, and real-time shared memory.

6

Rule templates

The mode system, code quality, documentation, git workflow, board protocol — and multi-window coordination, for running several sessions on one checkout. It says which of its clauses a hook backs and which are convention.

0

Agent files

Deliberate. /build-agents surveys your repo, proposes the few specialists it actually deserves, interviews you, and writes them. A catalogue would look more generous and be worth less. On the production codebase this came out of, the same setup drives 40+ specialists — none ship here: they're worth something precisely because they're about that codebase.

Setup is one interactive protocol, run once per project: about 15–20 minutes and roughly six questions.

Why we built it

“The harness is set up to approve the AI to do everything it needs to do, so it shouldn't be asking for permissions — we already guardrail what it can't do. That's why I can run so many windows.

I kick one off and it churns on its own with minimal input from me. A new agent picks up right where the last one left off. And when the model does the work, it compares it against what the specialists suggest — and it'll concede that it got it wrong.”

— Hunter, who built it

Known limits

These are decisions, not bugs. You should know the reasoning before you hit the edge.

The hooks fail open. Every hook exits 0 when its dependencies are missing or its input is malformed — a harness that wedges your editor because Python moved is one you delete by Wednesday. The consequence is real: these gates are enforced discipline, not a security boundary. They make the wrong move take deliberate effort. They do not make it impossible.

The permission fence guards against accidents, not adversaries. The deny list stops the commands you'd regret. It does not enumerate every spelling of them, and an agent that wants to route around a pattern can. If a branch is production, put a real boundary on the server side as well.

Setup is an interview, not an install. Fifteen to twenty minutes and roughly six questions. It writes rules, hooks and permissions into your repo — we'd rather you watched that happen than had it done to you.

Layer 2 needs a Firebase project. Persistent, real-time, cross-machine state has to live somewhere, and Firestore's free tier covers normal use. Won't run a cloud dependency? Take Layer 1 alone — you just lose continuity between sessions.

Claude Code needs a paid plan. Your existing Pro/Max subscription, or API billing. The CLI is a free download; using it isn't. VE Harness adds no model cost of its own, and the worker runs on the same subscription.

In the worker, the spend cap is mechanical and the deny list is a speed bump. A text-matching filter is not a boundary — credential scoping is the real control. A prompt instruction is advice and a flag is a gate, and we'd rather you knew which was which before you left it running overnight.

The changelog retracts our own advice when we were wrong. The correction goes in the log next to the original claim rather than quietly replacing it. Read the retractions — they're the most useful part.

Questions, answered straight

Including the ones where the answer is “not yet”.

What does “reviewed” actually mean?

That a review ran before the commit, not that it was a good one. The gate looks for a marker the agent sets after reviewing, and each marker is good for one commit in one session. It does not read the review. The reviewer is an agent you build with /build-agents; until you have one, the agent is reviewing its own work.

What languages does it cover?

Most of it works the same in any language: the rules, the board, the modes, shared memory, and the secret gate, which scans whatever you stage. Two gates look at file types. The review gate and the first-edit fact gate share one list of what counts as code: TypeScript, JavaScript, Python, SQL, shell, .conf, YAML, TOML, Astro, Dockerfiles and package.json. In a Go, Rust, Ruby, Java, PHP, C#, Swift or Kotlin project, a commit that names its files is not gated, and neither gate tells you so, until you add your extensions. The fact gate reads them from FACT_GATE_CODE_RE; the review gate's list is one line in the hook. A wholesale git add -A is treated as code in any language. The worker's prompt asks for a type-check before each commit; change that line to your project's own check.

Does it work with Cursor, Codex or other coding agents?

No. It is built on Claude Code's own machinery: hooks, skills, permission rules and MCP servers. A worker batch can optionally be reviewed by a second model, but the harness itself runs in Claude Code.

Can I add it to a project that already has a CLAUDE.md?

Yes. When setup finds an existing CLAUDE.md or .claude/ directory it runs in upgrade mode: it reads your files, diffs them against the current templates, tells you what is new, asks which changes you want, and never overwrites anything without confirmation. The same mode is how you pull in later updates.

Will it use more of my Claude plan?

It bills nothing and makes no model calls of its own; the hooks are shell scripts. The process it enforces does more work than a bare session, though: a review before a commit and a specialist working in its own context are both model calls on your plan. The worker is the one place with a hard limit, a spend cap per batch set by a flag.

Does it run on Windows?

It is not tested there. CI runs the hook suites on Ubuntu and macOS. The hooks are bash scripts that need Python 3, so on Windows they need a bash shell such as WSL or Git Bash.

What we built, and what we built on

Built here: the board and its 21 tools, real-time shared memory, the per-session review gate, the stop hook, the container worker, doctor.sh, a test suite for every hook, and the rule for running several windows on one checkout.

Where someone had already solved the problem, it borrows — and says whose work it was, and what went on top:

RIPER-5 by robotlovehuman — the five original modes, the mode prefix on every reply, and what each mode may and may not do. We added COMMIT, AI REVIEW and TROUBLESHOOT, the automatic step from plan into review, the one-command /go cycle, plans bound to board tasks, per-mode delegation, the deviation protocol, and a hook behind the commit.

affaan-m/ECC and zunoworks/gateguard — the fact-gate and protected-files patterns. Both are rewritten here to this kit's hook conventions; the protected-files gate is widened from linter configs to allowlists, ignore files and the hook scripts themselves, with a per-session override.

gitleaks — the scanner behind the secret gate. The gate around it is ours: it also scans what a one-line add-and-commit is about to stage, and lists a finding without printing the value.

taylorwilsdon/google_workspace_mcp — upstream of the Workspace companion, ve-gws.

Full credits in the README →

Stop babysitting it.

Everything is in the README — the gates, the limits, and what we got wrong on the way.

Read the README on GitHub → Join the Discord →

Free. No pitch. Just builders.