claude-harness

The Claude Code setup I run every day, mirrored public. Incident-born guard hooks, a model-routing policy that is enforced rather than suggested, a dozen small zero-dependency tools, and a nightly self-reflection loop that promotes observations into rules only when the evidence earns it.

This is not a starter kit designed in an afternoon. It grew rule by rule out of real incidents over six months of daily use, and most of it exists because something broke first. The private repo that backs it also holds the agent's memory; that stays on the machine. Everything here was swept file by file before publishing (see Security).

Contents

• Why it exists
• How it fits together
• Guards
• Model routing and delegation
• Tools
• Scheduled jobs
• Subagents
• The meditation ladder
• Layout
• Stealing pieces
• What is templated, what is not here
• Security
• Contributing, license, support

Why it exists

Three examples of what "incident-born" means:

• hooks/process-kill-guard.cjs exists because a subagent cleaned up its test window with Stop-Process -Name notepad and killed a real Notepad session with about 40 tabs of unsaved work. Name-based process kills are now blocked at the tool layer. PID-based kills still work.
• hooks/agent-model-guard.cjs exists because one workflow spawned 110 agents on the most expensive model through inherited defaults and burned a full five-hour usage window. Every agent spawn now requires an explicit model, and the expensive tier is capped per session.
• git-hooks/pre-commit runs hooks/secret-guard.cjs over every staged file in every repo on the machine, whatever the language, because keys were once found sitting in plaintext on disk.
• The four-round fix session of 2026-09-03 is written up in docs/postmortem-2026-09-03-declick-launch.md: what a file-scoped fix workflow, a capped advisor, an over-tight edit budget and a missing git guard cost on one launch day, and what each became.
• hooks/git-tree-guard.cjs exists because a reviewer in a 17-agent fix workflow ran git stash to watch a test fail without its fix, the pop conflicted on a sibling's edit, and a 25-file fix pass sat silently reverted under six agents still working. Stash, path checkouts, restore, hard reset and clean are now denied in shell calls; baselines come from copies (git show HEAD:<path> into a scratch dir). workflows/fix-findings.js says the same thing in every prompt it sends.

The design stance behind all of it: a rule written in prose is a hope. A rule that matters gets a hook, the hook gets a probe that makes it fail on purpose, and the probe runs on a schedule. A guard that has never been observed failing has been installed, not verified.

How it fits together

flowchart LR
    subgraph session["Claude Code session"]
        S[SessionStart] --> P[UserPromptSubmit]
        P --> T{Tool call}
        T -->|PreToolUse| G[Guards]
        G -->|allow| X[Tool runs]
        G -->|deny + reason| P
        X -->|PostToolUse| A[Advisory hooks]
        A --> P
        P -->|Stop| L[Telemetry]
    end
    C[CLAUDE.md<br/>global agreement] -.loaded.-> S
    SOUL[SOUL.md<br/>identity] -.read first.-> S
    L --> M[Nightly meditation]
    M -->|observation → fact → rule → trait| C
    M --> SOUL
    X -->|git commit| H[pre-commit chain<br/>secret scan, doc gates, lint]

Two layers do the work. Hooks sit on Claude Code's lifecycle events and either deny a call with a reason the model can act on, or inject context the model would otherwise forget. The ladder runs once a night, reads the telemetry and the day's work, and decides whether anything earned promotion into a standing rule. Everything else in the repo is tooling in service of those two.

Guards

Every guard is a single file, no dependencies, wired in settings.json. Each carries an override marker so a deliberate exception is one comment away and gets logged, rather than a reason to switch the guard off.

hooks/tests/ holds the probes. hooks/adapters/ wires the same files into Codex and Antigravity so there is one guard suite, not three copies (docs/harness-parity.md). Mechanism and incident history for each guard: docs/harness-guards.md.

Model routing and delegation

The global agreement routes work by cost and the hooks enforce it.

flowchart TD
    F[Fable<br/>decisions, review, synthesis] --> O[Opus<br/>planning, orchestration, hard debugging]
    O --> S[Sonnet<br/>implementation, exploration]
    S --> H[Haiku<br/>lookups, mechanical edits]
    S -. advisor .-> O
    O -. advisor .-> F

• Downward only. A spawn that crosses a missing edge is denied. A fork inherits its caller's model, so it counts as a peer edge from any subagent.
• Upward is consultation, not delegation. A worker that hits an architecture choice, a security boundary, or a second failed fix spawns agents/advisor.md. The guard ignores any model it asks for and places it one rung up. Guidance comes back; ownership stays with the caller.
• The economics are measured, not assumed. A subagent costs roughly 60k input tokens before its first tool call, then 2-4k per call. Under ten calls or eighty edited lines, doing it inline is cheaper on any model. The numbers and the method are in tools/tokflow/AUDIT-2026-09-02.md.
• Lean agent types by default. haiku-scout, sonnet-implementer and opus-owner carry restricted tool sets and cost about a third of a general-purpose spawn.

Tools

Zero-dependency, one directory each, each with its own README.

Scheduled jobs

Subagents

The meditation ladder

The part people ask about most. A scheduled session runs every morning, reflects on recent work, and appends dated observations. Ideas climb a ladder:

observation  →  fact (memory)  →  rule (CLAUDE.md)  →  trait (SOUL.md)

Each rung has explicit graduation gates. A rule needs three or more signals across two or more distinct sessions, with signals older than thirty days counting half. Every promotion cites the dated evidence that earned it. The ladder runs both ways: one contradiction is recorded, two demote. Failure lessons are written as evidence ("when X broke, Y fixed it"), not commands, so a hostile input cannot become a standing rule in one session.

The design goal is that refusing a promotion is the normal outcome. A gate that has never once refused anything is not a gate. The gates, the demotion path and the write rails for SOUL.md are in meditations/MEDITATIONS.md.

Layout

Stealing pieces

Do not clone this expecting a turnkey install. Paths are Windows and specific to one machine. The useful move is taking one piece at a time.

One guard. Copy the file, then register it. A PreToolUse hook that prints a deny reason to stderr and exits 2 blocks the call and hands the model the reason:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|PowerShell",
        "hooks": [
          { "type": "command", "command": "node \"C:/path/to/hooks/process-kill-guard.cjs\"" }
        ]
      }
    ]
  }
}

The pre-commit chain. Point git at the directory once and every repo on the machine gets the secret scan:

git config --global core.hooksPath /path/to/git-hooks

The ladder. meditations/MEDITATIONS.md is self-contained. Start with an empty CANDIDATES.md, run the nightly prompt in scripts/meditation/, and refuse the first few promotions on purpose to see the gates work.

docs/reddit-claude-setup-share.md walks the whole setup with a "steal this pattern" line per item.

What is templated, what is not here

SOUL.md and everything under meditations/ are structural templates in this mirror. The real files accumulate personal and business context that stays private. The mechanism, the gates and the write rails are here unchanged.

Not in the mirror:

• projects/, the agent's memory store.
• skills/, personal skill definitions, some of them voice and identity material.
• The profile block of the private CLAUDE.md (memory wiring, project map, a remote devbox) and the autoMode trust-boundary block of settings.json. Both map my machines and business context.
• .secrets.env and anything else untracked.
• The scheduled jobs that drive product repos and the autonomous company that runs on top of this harness. Different repos, private.

Security

The private repo never contained credentials. Before each sync this mirror is swept file by file for key shapes, bearer tokens, credentialed URLs, key=value secrets, emails and phone numbers, and the sweep prints the file count beside its verdict so a clean result on zero files cannot pass as clean. The last sync scanned 156 files; the only hits were fake keys inside tools/deskclaw/tests/, which exist to prove the redaction works.

If you find something that should not be here, see SECURITY.md.

Contributing, license, support

Issues and pull requests are welcome, especially incident reports of the form "this guard let X through" with a probe that reproduces it. See CONTRIBUTING.md. Changes to the mirror are listed in CHANGELOG.md.

MIT. If these tools save you time: