Skip to content

ahundt/ar

v1.0.0rc5Apache-2.0

Lifecycle safety hooks and reusable automation skills for AI coding assistants

autorun

An AI coding agent left alone stops mid-task, calls a first draft done, and runs commands such as rm -rf or git reset --hard. autorun adds hooks that send it back to work and block those commands. It supports Claude Code, Codex, Qwen Code, Pi, Prime Agent, ForgeCode, OpenCode, Antigravity and the legacy Gemini CLI.

Install

uv tool install autorun-ai   # installs the `autorun` command
autorun --install            # adds hooks, commands and skills to every agent it finds
autorun --status             # checks each install and runs the hook command once

Then start a new agent session and type /ar:help (ar:help in Codex) to see the command list. autorun --install-dry-run previews the writes. autorun --uninstall removes what autorun installed, including the autorun-ai tool, and stops its background daemon; it keeps ~/.autorun (session state, task history and logs).

Other routes:

uv tool install 'git+https://github.com/ahundt/autorun.git#subdirectory=plugins/autorun'   # from GitHub
claude plugin marketplace add https://github.com/ahundt/autorun.git                     # Claude Code only
claude plugin install ar@autorun
uv tool install 'autorun-ai[pdf]'    # adds the PDF backends for `extract-pdfs`

The pdf-extractor agent plugin's extraction code ships in this package, behind the pdf extra.

What each agent gets

If the daemon is busy, unreachable, misses a deadline or cannot evaluate state, overload_policy=critical-guards (default) allows ordinary commands and non-shell tools with a notice and runs the built-in destructive-command guards locally for shell tools. No session state is read: /ar:no rules, /ar:ok grants, the file policy, and task and plan gating are not checked until autorun answers again. A guarded command stays blocked even with a grant. A cheap screen lets ordinary commands such as git status proceed even with no check budget. If the full check fails or is late, only a command that names a guarded command as a whole word, or uses shell syntax that can spell one indirectly, is denied with wait-and-retry guidance. Do not restart the daemon under load.

The overload_policy key in ~/.autorun/autorun.config.json accepts critical-guards, block (deny every tool-gate call) and allow (allow every call without local guards); AUTORUN_OVERLOAD_POLICY overrides the file. Unknown values use critical-guards and appear in autorun --status. If the Python package cannot be imported, the stdlib hook still denies tool calls with repair guidance because it has no guard code. Stop and other non-gate events keep their existing behavior.

AgentSafety hookKeeps working past StopCommands and skills
Claude Codenative hooksyesnative
Codexnative hooksyesCodex plugin and skills
Qwen Codenative hooksyesnative extension
Antigravitynative hooksthe events Antigravity offersnative extension
OpenCodein-process tool vetoyes on 0.6.0+, through session.idle; older clients only show the reason. Its todo list is mirrored into task statuscommand files and skills
Piin-process tool vetoagent_settled continuation and task toolsone local package containing the extension and skills
Prime Agentthe Pi extension below 0.10.0; none on 0.10+as Pi below 0.10.0; no on 0.10+below 0.10.0, one local package containing the extension and skills; on 0.10+, guidance and skills
ForgeCodeadvice onlynocommand files and skills
Legacy Gemini CLInative hooksyesnative extension

autorun's messages use each agent's spelling: /ar: in Claude, Gemini CLI, Qwen Code and Antigravity, /ar in Pi, ar: in Codex, and /ar- in ForgeCode and OpenCode.

Documentation: https://github.com/ahundt/autorun. Development setup and tests: AGENTS.md. Licensed under Apache 2.0; see LICENSE.