Brain/Hand Agent Loop

claude-brain-hand — a fenced Brain/Hand coding loop

A Claude Code plugin for the Brain/Hand pattern: one agent plans and reviews (read-only), another executes one tiny task at a time, and a deterministic loop enforces hard stop conditions — so the agent stays a fenced assistant, never "an unsupervised raccoon with terminal access".

Two independent kinds of guardrail, by design:

• Per-action fences — PreToolUse hooks check every individual tool call before it runs (blast-radius containment) and a permission allow/deny list narrows what's runnable at all.
• Loop governor — after every Hand turn the workflow checks stop conditions and hands back to a human when one trips.

What's in the box

Component	Ships via	Role
agents/brain.md	plugin (auto)	Brain — read-only planner/reviewer. Picks ONE next task; judges the last report. No Edit/Write.
agents/hand.md	plugin (auto)	Hand — executor. Does one task, runs tests/lint, commits on green, reports honestly.
hooks/guard-bash.sh	plugin (auto)	PreToolUse guard: blocks rm -rf, sudo, force-push, history rewrites, pipe-to-shell, fence escapes.
hooks/guard-write.sh	plugin (auto)	PreToolUse guard: blocks writes outside the project folder and to secret-like files.
project-template/workflows/brain-hand-loop.js	manual	The controlled loop with the hard stop conditions.
project-template/hooks/changed-lines.sh	manual	Single source of truth for the "diff too large" governor (counts hand-written lines, excludes lockfiles).
project-template/settings.json	manual	Recommended permission allow/deny list.

Why the split?

Claude Code plugins can ship agents and hooks, but cannot ship workflows or a permissions list — those are project-scoped by design. So the plugin auto-installs the reusable agents + safety fence, and the three project-scoped pieces live in project-template/ for you to drop into your repo's .claude/.

Install

1. The plugin (agents + guard hooks)

/plugin marketplace add sunfmin/claude-brain-hand
/plugin install claude-brain-hand@sunfmin-brain-hand --scope project

Use --scope project so the guard hooks apply only in the repo where you run the loop — not to every session everywhere (they block git push, sudo, etc., which you don't want fenced during normal work).

2. The project-scoped pieces (workflow + governor + permissions)

From the root of the repo you want to run the loop in:

# the workflow + the diff-size governor script
mkdir -p .claude/workflows .claude/hooks
cp "$(claude plugin path claude-brain-hand)"/project-template/workflows/brain-hand-loop.js .claude/workflows/
cp "$(claude plugin path claude-brain-hand)"/project-template/hooks/changed-lines.sh       .claude/hooks/
chmod +x .claude/hooks/changed-lines.sh

Then merge project-template/settings.json into your .claude/settings.json (the permissions.allow / permissions.deny blocks). Tighten allow to exactly your project's test/build/lint commands — the narrower the allowlist, the smaller the attack surface.

Don't have claude plugin path? Just git clone this repo and cp the two files out of project-template/ by hand.

Run

Before the first run the repo must be on a feature branch with a clean git tree, and have real test + lint commands (edit the agents' instructions / the allow list to match your stack).

The loop is a Claude Code Workflow, which spawns multiple agents, so it needs explicit opt-in. Ask Claude Code, in that repo:

run the brain-hand-loop workflow with the goal "add input validation to parseConfig"

or invoke the Workflow tool with { name: "brain-hand-loop", args: "add input validation to parseConfig" }.

The Brain and Hand are ordinary subagents — you can also drive them directly with the Agent tool.

How the safety maps to the pattern

Stop condition	Where it lives
Stop after N loops	MAX_LOOPS (workflow)
Stop if tests fail twice	MAX_TEST_FAILURES (workflow)
Stop if the diff gets too large	MAX_DIFF_LINES (workflow) + changed-lines.sh
Stop if the Hand is unclear	report.unclear → human
No writes outside the project	guard-write.sh
No destructive/privileged commands	guard-bash.sh + deny list
Clean git + small commits + revertable	git; one task = one commit

Hardening further (recommended for real use)

• Run inside a Docker container or a dedicated dev user so even a bypassed guard can't reach your machine. The hooks are a convenience layer, not a security boundary.
• Protect main server-side (branch protection) — the local git push block is only a courtesy.
• Keep the allow list as narrow as your project's real commands.

License

MIT © Felix Sun