Docs

Supervise Claude Code + Codex

01Quick start

WrangleBot wraps your coding agent: it streams the run, gates tools, kills loops, and records everything.

npm install -g @wranglebot/cli

# supervise a Claude Code run
wranglebot run claude-code "fix the failing tests" \
  --workdir /path/to/repo --scope src --scope tests

# supervise a Codex run
wranglebot run codex "refactor the parser" --workdir /path/to/repo

Requires Node ≥ 20. Or run from source: clone the repo, npm install --legacy-peer-deps, then node bin/wranglebot.mjs.

02CLI reference

usage: wranglebot run <claude-code|codex> [PROMPT...] [--workdir DIR] [--scope PATH]...
ArgMeaning
agentclaude-code or codex — the supervised agent kind
PROMPTthe task prompt, passed through to the agent
--workdirproject directory the agent works in (default: cwd)
--scopepath scope the agent may write; repeatable

Exit codes: 0 agent finished clean · 1 setup/supervision error · 2 agent denied (loop-breaker kill or guardrail deny).

03Guardrails

GuardrailWhat it does
ast-gateTree-sitter parse of Edit/Write content (TS + Python). Denies child_process/subprocess; warns on destructive deletes outside the workdir, Python eval/exec, network egress. Parse errors fail open.
scope-guardReal path containment (resolve + relative, Windows-safe). Denies writes outside the workdir/scope and to CI/config surfaces; warns on package-manifest writes.
loop-breakerDeterministic kill signals: identical (tool, input) fingerprint ≥3 warn / ≥5 deny; byte-identical shell output ≥3 turns; same test-failure hash ≥4 deny. All thresholds configurable.

04Claude Code hook mode

Run WrangleBot as a native PreToolUse hook instead of a wrapper process:

{
  "hooks": {
    "PreToolUse": [{ "hooks": [{ "type": "command", "command": "wranglebot-hook" }] }]
  }
}

Deny/rewrite decisions ride hookSpecificOutput.permissionDecision and updatedInput. Warn surfaces as an approval prompt (ask). Edit, Write, and MultiEdit are gated.

05.curt sessions

Every supervised event is recorded and flushed to <workdir>/.wranglebot/*.curt on exit. WrangleBot is the first consumer of the .curt format — agent run records you can diff, audit, and replay.

06Development

npm install --legacy-peer-deps
npm test        # vitest
npm run lint    # tsc --noEmit
Home