New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Runaway Guard

by RyanAlberts in RyanAlberts/best-of-Agent-Harnesses

Runaway guard: a hook that stops a live Claude Code or Codex session when the agent loops on the same tool call, keeps failing, or exceeds a dollar cap.

MITAuto-check passedAgent Workflows

Install Runaway Guard

skills CLI
$ npx skills add RyanAlberts/best-of-Agent-Harnesses --skill runaway-guard -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install RyanAlberts/best-of-Agent-Harnesses runaway-guard --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/RyanAlberts/best-of-Agent-Harnesses.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/runaway-guard .claude/skills/runaway-guard && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
runaway-guard
GitHub stars
1.1k
Token cost
~2.6k tokens
SKILL.md length
1,414 words
Files
11 (incl. scripts, references)
Repo updated
First seen
Licence
MIT

At a glance

Runaway guard: a hook that stops a live Claude Code or Codex session when the agent loops on the same tool call, keeps failing, or exceeds a dollar cap.

  • Works in 6 steps: Explain the three trip wires and their… → Ask for three choices: the dollar cap,… → Show the dry run with the user's choices → …
  • The user wants a spending cap
  • SKILL.md covers When to use, When not to use, Steps and When the guard stops a call, plus 3 more sections
  • Runs Python scripts from its folder; calls python3 and claude

What it does

Runaway Guard is an agent skill from RyanAlberts/best-of-Agent-Harnesses. Runaway guard: a hook that stops a live Claude Code or Codex session when the agent loops on the same tool call, keeps failing, or exceeds a dollar cap. Use when the user wants a spending cap, budget limit, or cost ceiling for interactive agent sessions (the built-in --max-budget-usd works only in print mode); wants to halt an agent that repeats the same command, is stuck in a loop, or runs up a bill unattended overnight; wants a circuit breaker for several failed tool calls in a row; or asks how much the current…

Its SKILL.md is about 2.6k tokens, which your agent loads only when the skill is triggered. The skill folder holds 12 other files, including scripts and reference files (for example `README.md`, `references/harness-hooks.md` and `references/how-it-decides.md`). Compatibility notes: Python 3.9+ on macOS or Linux, and Claude Code or Codex with hooks enabled. Makes no network calls.

It sits in Agent Workflows, covering Autonomous loops. The repository describes itself as: 🏆 Ranked list of 167 AI agent harnesses, plus templates, playbooks, MCP, and learning resources. Rescored weekly. The licence is MIT.

When your agent uses it

  • The user wants a spending cap
  • Cost ceiling for interactive agent sessions (the built-in --max-budget-usd works only in print mode)
  • Wants to halt an agent that repeats the same command
  • Is stuck in a loop

Example prompts

  • “/runaway-guard”

Requirements

  • Python 3
  • Compatibility (from SKILL.md): Python 3.9+ on macOS or Linux, and Claude Code or Codex with hooks enabled. Makes no network calls.

Workflow steps

6 steps, taken from the first numbered list in SKILL.md.

  1. Explain the three trip wires and their defaults in plain words
  2. Ask for three choices: the dollar cap, the harness (Claude Code or Codex), and the scope (user
  3. Show the dry run with the user's choices
  4. Install only on a clear yes: run the same command with --write added. Done when the output
  5. Relay the notes printed under "Notes", in particular
  6. Offer status

What it can do on your machine

Read from SKILL.md and the folder at commit 4fa20bc. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 6 files in scripts/ (Python), which the agent can run.

    Shell commands in SKILL.md call:

    • python3
    • claude

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

  • Compatibility

    Python 3.9+ on macOS or Linux, and Claude Code or Codex with hooks enabled. Makes no network calls.

    From compatibility in the SKILL.md frontmatter.

Context cost

Runaway Guard loads about 2.6k tokens when it runs, and up to ~7.1k if it reads all its reference files. Until then it costs about 178 tokens; SKILL.md has 1,414 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~178
When it runs · the whole SKILL.md, loaded when a task matches
~2.6k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~7.1k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from RyanAlberts/best-of-Agent-Harnesses at commit 4fa20bc, republished under its MIT licence (© RyanAlberts). 1,414 words, ~2,569 tokens.

Download SKILL.mdSave it as .claude/skills/runaway-guard/SKILL.md (or your agent's skills folder). This skill also uses 10 other files; get the full folder from GitHub.
name
runaway-guard
description
Runaway guard: a hook that stops a live Claude Code or Codex session when the agent loops on the same tool call, keeps failing, or exceeds a dollar cap. Use when the user wants a spending cap, budget limit, or cost ceiling for interactive agent sessions (the built-in --max-budget-usd works only in print mode); wants to halt an agent that repeats the same command, is stuck in a loop, or runs up a bill unattended overnight; wants a circuit breaker for several failed tool calls in a row; or asks how much the current session has spent against its cap, why a call was blocked, or how to raise or reset the cap. Runs locally: reads the session transcripts before each tool call and sends nothing.
compatibility
Python 3.9+ on macOS or Linux, and Claude Code or Codex with hooks enabled. Makes no network calls.
license
MIT
metadata.author
Ryan Alberts
metadata.version
1.0.0
metadata.source
https://github.com/RyanAlberts/best-of-Agent-Harnesses

Runaway guard

An agent left alone can repeat a failing command, retry broken calls, or keep spending long after the work stopped paying off, and Claude Code's --max-budget-usd cap works only in print mode. This skill installs a hook (a command the harness runs before every tool call) that steps in at three trip wires: the same call a third time with nothing changed, five failed calls in a row, and a dollar cap. The hook reads the session's transcript files on this machine, keeps only counts and hashes, and sends nothing anywhere.

When to use

  • The user wants a spend cap, budget, or cost ceiling for interactive Claude Code or Codex sessions.
  • The user wants an agent stopped when it loops on one command or keeps failing, for example before leaving it unattended.
  • The user asks how much the current session has spent against its cap, why the guard blocked a call, or how to raise the cap or start the count over.
  • The user wants to remove the guard.

When not to use

  • Finding where past tokens and money went: use session-waste-report.
  • Testing whether permission rules and hooks stop dangerous commands: use guardrail-tester.
  • Turning a rule from AGENTS.md or CLAUDE.md into a hook: use rules-to-guards.
  • A one-off print-mode run (claude -p): its own --max-budget-usd and --max-turns flags cap it.
  • Gemini CLI, Cursor, and OpenCode: the guard does not install there. Gemini CLI and OpenCode already detect loops; references/harness-hooks.md says what each lacks.

Steps

<skill-dir> means the folder that holds this SKILL.md (Claude Code shows it as the skill's base directory). Run every command through python3 exactly as written, with the path in double quotes: skill folders can sit under paths with spaces.

  1. Explain the three trip wires and their defaults in plain words:

    • Loop: the same tool call with the same input, a third time with nothing changed in between, is blocked. Reads and searches in between change nothing; an edit, another command, or a new user prompt does. Re-running tests after an edit never trips it, and neither do deliberate waits or starting subagents.
    • Failures: after 5 failed tool calls in a row, Claude Code asks the user before the next call runs. Codex hooks cannot ask, so there the call is blocked with a message telling the agent to ask the user.
    • Spend: the running cost of the session and its subagents at API list prices. A warning at 80% of the cap; at the cap every tool call is blocked (in Claude Code the turn ends) until the user raises the cap or starts the count over. A model missing from the price table is priced like the most expensive known model of its family, so the cap still holds.

    Done when the user has heard all three wires and the $10 default cap.

  2. Ask for three choices: the dollar cap, the harness (Claude Code or Codex), and the scope (user: every session of this user; project: only sessions in the current project). Say that on a subscription plan the dollar figure measures usage at API prices, not the bill. Done when you have all three answers, or the user accepted the defaults: Claude Code, user scope, $10.

  3. Show the dry run with the user's choices:

    bash
    python3 "<skill-dir>/scripts/install.py" --harness claude-code --scope user --cap 10

    It prints the headline, the settings file it would change, the diff, and notes, and writes nothing. Add --project <folder> for project scope when the agent's working folder is not the project. Done when the user has seen the headline and the diff and has said yes or no.

  4. Install only on a clear yes: run the same command with --write added. Done when the output starts with the headline and says "Done". Exit code 2 means a settings file could not be read as JSON, has an unexpected shape, or could not be written; nothing was changed. Quote the message, and leave the file for the user to fix.

  5. Relay the notes printed under "Notes", in particular:

    • Claude Code normally applies hook changes to sessions already running. A session the guard already counts is blocked at its next tool call once it is over the cap; a session it sees for the first time after spending more than the cap is counted from that point.
    • Codex runs the hook only after the user trusts it in /hooks.
    • Before the user moves, updates, or removes this skill, they run --uninstall, then install again from the new place: the hook entry points at this folder.

    Done when every note is passed on.

  6. Offer status:

    bash
    python3 "<skill-dir>/scripts/status.py"

    Done when the user has the headline, or declined.

To remove the guard, run python3 "<skill-dir>/scripts/install.py" --uninstall, show the diff, and add --write on a clear yes. With no --harness, --scope, or --settings, it checks all four places the guard can be (Claude Code and Codex, user and project) and names each file it changes. It removes only the guard's own entries, and puts a file back exactly as it was when nothing else changed it.

Show full SKILL.md (578 more words)Show less

When the guard stops a call

A blocked call comes back as a tool error that starts with "Runaway guard". Stop and pass the message to the user in your own words, naming the trip wire.

  • Spend stop: every tool call is blocked, status.py included, and in Claude Code the turn ends. Answer in text only. Give the user the two ways on that the message names, for them to use in their own terminal: the setting that holds the cap (the file, or the RUNAWAY_GUARD_CAP_USD variable), and the status.py ... --reset command. To see the counts, they run python3 "<skill-dir>/scripts/status.py" there too. The cap is theirs to lift.
  • Loop: change the approach rather than the wording of the same call.
  • Failure question: the user answers it in the permission prompt; continue with what they allow.

Read the results

install.py:

  • Headline: the limits the hook will enforce after the change, from --cap, the guard's settings files, and any RUNAWAY_GUARD_* variable set in the shell.
  • Diff: the one PreToolUse entry added or removed; the hooks already there stay unchanged.
  • Notes: steps the user still takes, and settings that change the picture, such as disableAllHooks.
  • --json for an install: headline, action, settings_path, config_path, command, cap_usd, limits, changed, written, other_hooks, notes. For --uninstall: headline, action, hook_entries_removed, changed, written, notes, and targets (each file checked, with removed and restored_exactly).

status.py (defaults to the session the guard checked most recently; --session takes an id or its first characters, --list shows every session):

  • Headline: the session's first 8 characters, dollars since the start or the last reset, the cap, and how many times the guard stepped in.
  • Table: each wire's limit, its current value, and how often it fired.
  • Latest events: time, wire, tool name, detail. Warnings appear here too.
  • Estimate line: the part of the dollar figure priced by estimate, for models missing from the price table, and which models they are.
  • --json: session, spent_usd, total_usd, cap_usd, limits, trips, recent_trips, failure_streak, transcripts, estimated_usd, estimated_tokens, estimated_models, resets, errors_logged.

references/how-it-decides.md has every rule, threshold, setting, and safeguard, with calibration on real sessions; references/harness-hooks.md has what each harness's hooks allow, with sources.

Report to the user

After an install or a dry run:

  1. The headline, verbatim, in bold.
  2. What changes: the settings file and the one entry, and the cap file when --cap was given.
  3. The notes, as a short list.
  4. One line: how to check status, and how to remove the guard.

For status:

  1. The headline, verbatim, in bold.
  2. The table.
  3. When a wire has fired: the latest events and the next step. For a spend stop, the raise or reset command from the block message, for the user to run in their own terminal.

Files

  • scripts/guard.py: the hook. Reads the hook input on stdin and prints a decision. Always exits 0, and lets the call through on any internal error, logging it to errors.log in the state folder.
  • scripts/install.py: prints the settings change and applies it with --write; --uninstall removes only the guard's entries. Flags: --harness, --scope, --project, --cap, --settings, --json, --out.
  • scripts/status.py: spend and trip counts per session; --list, --session, --reset, --json, --out.
  • scripts/transcripts.py, scripts/pricing.py, scripts/safe.py: the shared transcript reader, price table, and text cleaner that puts session ids, tool names, and model ids in the report inside inline code, copied from this repository's shared code.
  • references/how-it-decides.md: the trip wires, thresholds, settings, safeguards, and speed.
  • references/harness-hooks.md: hook support in Claude Code, Codex, Gemini CLI, Cursor, and OpenCode.

© RyanAlberts, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 10 other files (scripts, references) in skills/runaway-guard of RyanAlberts/best-of-Agent-Harnesses.

  • SKILL.md
  • LICENSE.txt
  • README.md
  • references/harness-hooks.md
  • references/how-it-decides.md
  • scripts/guard.py
  • scripts/install.py
  • scripts/pricing.py
  • scripts/safe.py
  • scripts/status.py
  • scripts/transcripts.py

Open the folder on GitHubat commit 4fa20bc

Compare with similar skills

Runaway Guard next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Runaway Guard compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Runaway Guard this skillRyanAlberts/best-of-Agent-Harnesses1.1k—~2.6kAutomated safety check: PassMIT
Show Me Your Work Decision Logcursor/plugins11k8 repos~1.6kAutomated safety check: PassNone
Autoresearch Iteration Loopuditgoenka/autoresearch6.5k1 repos~2kAutomated safety check: PassMIT
Install Loop Engineeringcobusgreyling/loop-engineering11k1 repos~648Automated safety check: PassMIT
LoopyForward-Future/loopy3.2k—~3.9kAutomated safety check: PassMIT
AI Performance Improvement Plantanweai/pua20k2 repos~6.9kAutomated safety check: PassMIT

Similar skills

  • Show Me Your Work Decision Log

    cursor/plugins

    Official

    Keeps a TSV decision log for long or unattended agent runs, one row per decision with what, why, evidence and result, so a reviewer can check the work later.

    11k GitHub starsUsed in 8 repos~1.6k tokens
    Agent WorkflowsAuto-check passed

  • Autoresearch Iteration Loop

    uditgoenka/autoresearch

    Runs an autonomous modify, verify, keep-or-discard loop against any metric, with subcommands for planning, debugging, fixing, security audits, shipping and more.

    6.5k GitHub starsUsed in 1 repo~2k tokens
    Agent WorkflowsAuto-check passed

  • Install Loop Engineering

    cobusgreyling/loop-engineering

    Installs Loop Engineering into a project through the single @cobusgreyling/loop CLI, scaffolding a report-only loop and a readiness score.

    11k GitHub starsUsed in 1 repo~648 tokens
    Agent WorkflowsAuto-check passed

  • Loopy

    Forward-Future/loopy

    Discover, find, compare, audit, repair, adapt, craft, run, debrief, save, and prepare repeatable AI-agent loops for publication.

    3.2k GitHub stars~3.9k tokensUpdated 1 mo ago
    Agent WorkflowsAuto-check passed

  • AI Performance Improvement Plan

    tanweai/pua

    Pushes an agent to exhaust every option, investigate before asking and take initiative beyond the literal request, instead of giving up or waiting passively.

    20k GitHub starsUsed in 2 repos~6.9k tokens
    Agent WorkflowsAuto-check passed

  • LoopX Self Repair

    loopx-project/loopx

    Diagnoses surprising LoopX behavior, such as stale recommendations or tiny progress, assigns it to the responsible layer and repairs it at the lowest durable level.

    6.2k GitHub stars~2.2k tokensUpdated today
    Agent WorkflowsAuto-check passed

More from RyanAlberts/best-of-Agent-Harnesses

All 9 skills in this repo

  • Agents Md Checker

    RyanAlberts/best-of-Agent-Harnesses

    Checks which instruction files (AGENTS.md, CLAUDE.md, GEMINI.md, Cursor rules, Copilot instructions) each coding agent loads from a repo, what gets cut or skipped, and whether the commands those…

    1.1k GitHub stars~3.1k tokensUpdated 2 days ago
    Auto-check passed

  • Claim Check

    RyanAlberts/best-of-Agent-Harnesses

    Claim checker that audits a coding agent's statements that tests pass or a build is clean against its own session transcripts: whether a matching run happened before the claim, whether it passed…

    1.1k GitHub stars~2.4k tokensUpdated 2 days ago
    Auto-check passed

  • Guardrail Tester

    RyanAlberts/best-of-Agent-Harnesses

    Guardrail tester that checks whether the permission rules and PreToolUse hooks already set up in Claude Code, Codex, Gemini CLI, OpenCode, or Cursor stop a battery of dangerous commands, including…

    1.1k GitHub stars~2.9k tokensUpdated 2 days ago
    Auto-check passed

  • Harness Test Drive

    RyanAlberts/best-of-Agent-Harnesses

    Test-drives coding agents (Claude Code, Codex, Gemini CLI) on tasks mined from the user's own git history: each agent gets a past commit message in a fresh copy of the repo, and the repo's own tests…

    1.1k GitHub stars~2.9k tokensUpdated 2 days ago
    Auto-check passed

  • Regression Finder

    RyanAlberts/best-of-Agent-Harnesses

    Regression check for coding agents: shows how the agent behaved before and after each harness update, model switch, or week in the user's own Claude Code or Codex history, and finds the point where…

    1.1k GitHub stars~3k tokensUpdated 2 days ago
    Auto-check passed

  • Rules To Guards

    RyanAlberts/best-of-Agent-Harnesses

    Rule enforcer that finds which written rules in AGENTS.md, CLAUDE.md, and GEMINI.md a coding agent keeps breaking, counts every violation in recent Claude Code, Codex, Gemini CLI, and OpenCode…

    1.1k GitHub stars~2.7k tokensUpdated 2 days ago
    Auto-check: notes

Categories

Questions about Runaway Guard

What does Runaway Guard do?

Runaway guard: a hook that stops a live Claude Code or Codex session when the agent loops on the same tool call, keeps failing, or exceeds a dollar cap. Runaway Guard is an agent skill from RyanAlberts/best-of-Agent-Harnesses. Runaway guard: a hook that stops a live Claude Code or Codex session when the agent loops on the same tool call, keeps failing, or exceeds a dollar cap.

When should I use Runaway Guard?

Runaway Guard fits situations like: the user wants a spending cap; cost ceiling for interactive agent sessions (the built-in --max-budget-usd works only in print mode); wants to halt an agent that repeats the same command; is stuck in a loop.

How do I install Runaway Guard in Claude Code?

Run `npx skills add RyanAlberts/best-of-Agent-Harnesses --skill runaway-guard -a claude-code`. Or copy the skill folder (skills/runaway-guard in RyanAlberts/best-of-Agent-Harnesses) into .claude/skills/runaway-guard in your project. Claude Code loads it when a task matches its description.

How do I install Runaway Guard in Codex?

Run `npx skills add RyanAlberts/best-of-Agent-Harnesses --skill runaway-guard -a codex`. Or copy the skill folder (skills/runaway-guard in RyanAlberts/best-of-Agent-Harnesses) into .agents/skills/runaway-guard in your project. Codex loads it when a task matches its description.

Can I use Runaway Guard in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add RyanAlberts/best-of-Agent-Harnesses --skill runaway-guard -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/runaway-guard, .gemini/skills/runaway-guard, .github/skills/runaway-guard and .opencode/skills/runaway-guard in your project.

What does Runaway Guard need to run?

Going by SKILL.md and its folder, Runaway Guard needs Python for the scripts in its folder and the command-line tools its instructions call (python3 and claude). Our summary lists: Python 3. Compatibility (from SKILL.md): Python 3.9+ on macOS or Linux, and Claude Code or Codex with hooks enabled. Makes no network calls..

Does Runaway Guard access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Runaway Guard safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Runaway Guard use?

Runaway Guard is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Runaway Guard use?

About 2.6k tokens (SKILL.md is roughly 10k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 4.5k tokens, read only when the agent opens those files.

What are the alternatives to Runaway Guard?

Skills that share tags, products or a category with Runaway Guard: Show Me Your Work Decision Log (cursor/plugins, 11k stars), Autoresearch Iteration Loop (uditgoenka/autoresearch, 6.5k stars), Install Loop Engineering (cobusgreyling/loop-engineering, 11k stars) and Loopy (Forward-Future/loopy, 3.2k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Runaway Guard?

RyanAlberts (a GitHub user) maintains it in RyanAlberts/best-of-Agent-Harnesses, which has 1,133 GitHub stars. The repository was last updated on October 9, 2026.

Source: RyanAlberts/best-of-Agent-Harnesses on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.