WrangleBot
WrangleBot is a deterministic supervisor for coding agents (Claude Code, Codex).
It sits between your agent and its tools and makes thrashing expensive:
dangerous constructs get gated before they execute, runaway loops get killed by
deterministic signals, and every decision lands in a .curt record.
The package is @wranglebot/cli (npm), a TypeScript CLI requiring Node.js 20+.
Licensed under BUSL-1.1 — free for personal and noncommercial use, converts
to MIT on 2030-10-16, commercial use requires a written license from the
licensor. It is not MIT-licensed today.
The three pillars
- Guardrails — pre-execution inspection of every tool call the agent
attempts. The
ast-gateparses the content of file edits with tree-sitter and denies dangerous constructs; thescope-guardconfines file writes to the session workdir; theloop-breakercounts repeated calls and failures. - Loop-breaking — deterministic kill signals. When the agent repeats the identical call too many times, or keeps producing the same failure, it is killed instead of allowed to burn more tokens.
.curtrecords — every supervised event and its verdict is serialized to a.curtfile under.wranglebot/in the workdir when the session ends. WrangleBot is the first consumer of the .curt format.
The exit-code contract
| Code | Meaning |
|---|---|
0 | Agent finished clean; no deny verdict was issued. |
1 | Setup or supervision error: bad CLI arguments, missing prompt, agent failed to spawn or exited non-zero. |
2 | The agent was denied — killed by a loop-breaker signal or blocked by a guardrail deny. |
Details and the full failure taxonomy: Exit codes.
Supervisors supervise
WrangleBot does not run your agent better — it watches. Tool calls flow through
a supervision pipeline (src/daemon/), each guardrail returns a verdict
(allow, warn, deny, rewrite; see src/types.ts), and the first deny or
rewrite wins. A deny in wrapper mode kills the agent process immediately and
the run exits 2. There is no LLM in the loop: every decision is derived
mechanically from the event stream.
Where to go next
- Getting started — install and run your first supervised session.
- Guardrails — the complete guardrail reference.
- CLI reference — every flag and subcommand.