Getting started
Install
npm install -g @wranglebot/cli
Requires Node.js 20 or newer (engines field in package.json). Two binaries
are installed:
wranglebot— the supervisor CLI (bin/wranglebot.mjs).wranglebot-hook— the Claude Code PreToolUse hook entry point (bin/wranglebot-hook.mjs). See Hooks.
The run command
wranglebot run <claude-code|codex> [PROMPT...] [--workdir DIR] [--scope PATH]...
That is the entire CLI surface (arg parsing lives in parseArgs in
src/daemon/cli.ts):
- The only subcommand is
run. Anything else is rejected with exit1. - The agent is positional and must be exactly
claude-codeorcodex. - The prompt is every positional argument joined with single spaces.
--workdir DIR— project root handed to the guardrails; defaults to the current working directory. Also thecwdfor the spawned agent and the flush directory for.curtoutput.--scope PATH— repeatable. Each value is handed toscope-guardas an additional allowed write root outside the workdir (allowedPathsinsrc/daemon/registry.ts).- Any other
--flagis an unknown-flag error (exit1).
Semantics:
- workdir: the containment root.
scope-guarddenies file writes that resolve outside it (unless covered by a--scoperoot), andast-gateuses it for destructive-deletion path checks. - scope: escape hatches for directories the agent may legitimately write
outside the workdir (e.g. a sibling checkout). An exact
--scopeentry also overrides the default denied patterns (.git/,.github/workflows/,.claude/settings.json).
Worked example
wranglebot run claude-code "fix the failing tests" \
--workdir /path/to/repo \
--scope ../shared-lib
What happens:
parseArgsvalidates the command, agent, and flags. On failure it printswranglebot: <error>plus the usage line to stderr and exits1.- A session id (UUID) is generated and the guardrails load
(
loadGuardrailsinsrc/daemon/registry.ts, order:ast-gate,loop-breaker,scope-guard). stderr:wranglebot session <uuid> agent=claude-code guardrails=[ast-gate, loop-breaker, scope-guard] - The Claude Code CLI is spawned as
claude -p "fix the failing tests" --output-format stream-json --verbosewithcwdset to the workdir (src/daemon/claude-stream.ts). - Every
tool_useblock in the stream-json becomes anAgentEventand runs through the guardrails. Each verdict is printed to stderr:wranglebot: Edit -> deny (scope-guard: ... is outside workdir ...) - On the first
denyverdict the agent process is killed. On a clean finish the agent's own exit code is returned. - Before exiting, all buffered records are flushed to
/path/to/repo/.wranglebot/<session>.curtand stderr printswranglebot: curt written: <file>.
Codex
wranglebot run codex "refactor the parser" --workdir /path/to/repo
Same pipeline; the agent is spawned as codex exec --json <prompt> (override
the binary path with the CODEX_PATH environment variable) and its JSONL
events are parsed by the Codex observer.
Hook mode (no wrapper process)
Instead of wrapping the whole run, you can attach wranglebot as a native Claude Code PreToolUse hook so edit-tool calls are gated inline:
{
"hooks": {
"PreToolUse": [{ "hooks": [{ "type": "command", "command": "wranglebot-hook" }] }]
}
}
See Hooks.
Related
- Guardrails — what each guardrail checks.
- Exit codes — full code reference.