autorun

Key Features

• Tool calls pass through native safety hooks on Claude Code, Antigravity, Qwen Code, and Codex. Pi and OpenCode use in-process vetoes; ForgeCode receives advisory guidance.
• File policies control whether an agent may create files. Command guards turn rm into trash guidance and git reset --hard into git stash guidance.
• Stop hooks resume incomplete tasks on supported harnesses. Use /ar:tasks pause <reason> to suspend reminders and Stop enforcement without changing task state.
• Planning is optional. For work that needs it, autorun can critique a plan and run separate implementation, evaluation, and verification stages.
• The command and skill bundle includes plan export, task tracking, commit guidance, design principles, and session-history analysis.

Quick Start

# Install the published package with UV. The distribution is `autorun-ai`;
# the command it installs is `autorun`, and the harness commands are `/ar:*`.
uv tool install autorun-ai
autorun --install
# "autorun: command not found"? uv's tool directory (~/.local/bin by default)
# is not on your PATH yet: run `uv tool update-shell`, open a new terminal.

# Verify installation
/ar:st
# Expected: "AutoFile policy: allow-all"

# See every command in your harness's own spelling
/ar:help

Upgrading is the same two commands, which install the newest release. Add [pdf] ('autorun-ai[pdf]') if you installed the PDF backends, or the upgrade removes them:

uv tool install --force autorun-ai && autorun --install

Then restart open agent sessions: each reads its hooks when it starts. With only the Claude Code marketplace install, run claude plugin marketplace update autorun && claude plugin update ar@autorun in a shell instead. Each release's notes give the exact, version-pinned command.

Use as much or as little workflow structure as the task needs: keep the safety hooks in the background, run a task directly, or add planning for larger work.

Optional planning and execution:

/ar:go Build a login form with tests    # Run directly with three-stage verification

/ar:plannew Design a REST API with authentication and tests
/ar:planrefine                          # Critique and improve the plan
/ar:planprocess                         # Execute the plan

File Policy (prevent file clutter):

/ar:f                    # Strict: only modify existing files
/ar:j                    # Justify: require justification for new files
/ar:a                    # Allow: create files freely (default)

Safety:

/ar:sos                  # Emergency stop

Works with Claude Code, Google Antigravity, Qwen Code, Codex CLI, Pi, ForgeCode, and OpenCode. Legacy Gemini CLI support remains explicit opt-in — see Multi-CLI Support.

Examples use Claude/Gemini slash commands. In Codex, use the same command without the leading slash, such as ar:st or ar:ok git push. Every harness that receives your prompt also accepts the other spellings: Command Spellings by Harness.

Self-Improvement (learn from past sessions):

aise skills run corrections --when 30d --limit 50  # Find recurring AI mistakes
aise analyze --when 30d --output /absolute/new/analysis
# Install AI Session Search separately; see https://github.com/ahundt/ai-session-search

Table of Contents

• Key Features
• Quick Start
• UV Installation
  • Multi-CLI Support
• What autorun Does For You
• Why Byobu + tmux Integration
• AutoFile Lifecycle Flow
• How It Works
  • Three-Stage Autorun System
• Tmux Integration
• Development
• Available Commands
  • Command Spellings by Harness
  • AutoFile (File Creation Control)
  • Command Redirecting
  • Autorun Commands (Autonomous Execution)
  • Plan Management Commands
  • Task Lifecycle Tracking
  • Documentation Commands
  • Tmux Automation Commands
  • Usage Examples
• CLI Reference
• Plugin Architecture and Integration Guide
• Tmux Automation Agents
• Project Structure
• Developer Documentation
• Dependencies
• Companion Tools
• Troubleshooting
• Contributing and Sharing
• References
• License

UV Installation (Recommended)

The source marketplace includes autorun and pdf-extractor. The standalone autorun Python distribution embeds only the ar plugin's harness assets; install the pdf-extractor plugin from the Claude marketplace or a source checkout. Its extraction code needs no separate package — see below.

Note: plan-export functionality is now built into the autorun plugin. Use /ar:planexport commands for plan management.

Python package installation

autorun is the only published distribution. Install a release from PyPI:

uv tool install autorun-ai
autorun --install

PDF extraction ships inside it. extract-pdfs is always present, and every extraction backend is optional, so nobody who never opens a PDF downloads one:

uv tool install --force 'autorun-ai[pdf]'
extract-pdfs --list-backends

GitHub installation

Install the current autorun Python distribution directly from its repos