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: