{
  "markdown": "# autorun\n\n[![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)\n[![License](https://img.shields.io/badge/license-Apache%20v2-green.svg)](LICENSE)\n\n## Key Features\n\n- Tool calls pass through native safety hooks on Claude Code, Antigravity, Qwen\n  Code, and Codex. Pi and OpenCode use in-process vetoes; ForgeCode receives\n  advisory guidance.\n- File policies control whether an agent may create files. Command guards turn\n  `rm` into `trash` guidance and `git reset --hard` into `git stash` guidance.\n- Stop hooks resume incomplete tasks on supported harnesses. Use\n  `/ar:tasks pause <reason>` to suspend reminders and Stop enforcement without\n  changing task state.\n- Planning is optional. For work that needs it, autorun can critique a plan and\n  run separate implementation, evaluation, and verification stages.\n- The command and skill bundle includes plan export, task tracking, commit\n  guidance, design principles, and session-history analysis.\n\n![autorun Architecture](autorun-architecture.svg)\n\n## Quick Start\n\n```bash\n# Install the published package with UV. The distribution is `autorun-ai`;\n# the command it installs is `autorun`, and the harness commands are `/ar:*`.\nuv tool install autorun-ai\nautorun --install\n\n# Verify installation\n/ar:st\n# Expected: \"AutoFile policy: allow-all\"\n\n# See every command in your harness's own spelling\n/ar:help\n```\n\nUse as much or as little workflow structure as the task needs: keep the safety\nhooks in the background, run a task directly, or add planning for larger work.\n\n**Optional planning and execution:**\n\n```bash\n/ar:go Build a login form with tests    # Run directly with three-stage verification\n\n/ar:plannew Design a REST API with authentication and tests\n/ar:planrefine                          # Critique and improve the plan\n/ar:planprocess                         # Execute the plan\n```\n\n**File Policy** (prevent file clutter):\n\n```bash\n/ar:f                    # Strict: only modify existing files\n/ar:j                    # Justify: require justification for new files\n/ar:a                    # Allow: create files freely (default)\n```\n\n**Safety**:\n\n```bash\n/ar:sos                  # Emergency stop\n```\n\n> 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](#multi-cli-support).\n\n> 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](#command-spellings-by-harness).\n\n**Self-Improvement** (learn from past sessions):\n\n```bash\naise skills run corrections --when 30d --limit 50  # Find recurring AI mistakes\naise analyze --when 30d --output /absolute/new/analysis\n# Install AI Session Search separately; see https://github.com/ahundt/ai-session-search\n```\n\n## Table of Contents\n\n- [Key Features](#key-features)\n- [Quick Start](#quick-start)\n- [UV Installation](#uv-installation-recommended)\n  - [Multi-CLI Support](#multi-cli-support)\n- [What autorun Does For You](#what-autorun-does-for-you)\n- [Why Byobu + tmux Integration](#why-byobu--tmux-integration)\n- [AutoFile Lifecycle Flow](#autofile-lifecycle-flow)\n- [How It Works](#how-it-works)\n  - [Three-Stage Autorun System](#three-stage-autorun-system)\n- [Tmux Integration](#tmux-integration)\n- [Development](#development)\n- [Available Commands](#available-commands)\n  - [Command Spellings by Harness](#command-spellings-by-harness)\n  - [AutoFile (File Creation Control)](#autofile-file-creation-control)\n  - [Command Redirecting](#command-redirecting)\n  - [Autorun Commands (Autonomous Execution)](#autorun-commands-autonomous-execution)\n  - [Plan Management Commands](#plan-management-commands)\n  - [Task Lifecycle Tracking](#task-lifecycle-tracking)\n  - [Documentation Commands](#documentation-commands)\n  - [Tmux Automation Commands](#tmux-automation-commands)\n  - [Usage Examples](#usage-examples)\n- [CLI Reference](#cli-reference)\n- [Plugin Architecture and Integration Guide](#plugin-architecture-and-integration-guide)\n- [Tmux Automation Agents](#tmux-automation-agents)\n- [Project Structure](#project-structure)\n- [Developer Documentation](#developer-documentation)\n- [Dependencies](#dependencies)\n- [Companion Tools](#companion-tools)\n- [Troubleshooting](#troubleshooting)\n- [Contributing and Sharing](#contributing-and-sharing)\n- [References](#references)\n- [License](#license)\n\n## UV Installation (Recommended)\n\nThe source marketplace includes **autorun** and **pdf-extractor**. The standalone\nautorun Python distribution embeds only the `ar` plugin's harness assets;\ninstall the pdf-extractor plugin from the Claude marketplace or a source\ncheckout. Its extraction code needs no separate package — see below.\n\n> **Note:** plan-export functionality is now built into the autorun plugin. Use `/ar:planexport` commands for plan management.\n\n### Python package installation\n\n`autorun` is the only published distribution. Install a release from PyPI:\n\n```bash\nuv tool install autorun-ai\nautorun --install\n```\n\nPDF extraction ships inside it. `extract-pdfs` is always present, and every\nextraction backend is optional, so nobody who never opens a PDF downloads one:\n\n```bash\nuv tool install --force 'autorun-ai[pdf]'\nextract-pdfs --list-backends\n```\n\n### GitHub installation\n\nInstall the current autorun Python distribution directly from its repository\nsubdirectory:\n\n```bash\n# Install the CLI and complete embedded plugin\nuv tool install 'git+https://github.com/ahundt/autorun.git#subdirectory=plugins/autorun'\n\n# Register plugins with Claude Code\nautorun --install\n```\n\nClaude Code can alternatively use the repository marketplace directly:\n\n```bash\nclaude plugin marketplace add https://github.com/ahundt/autorun.git\nclaude plugin install ar@autorun\n```\n\n### Local Installation\n\nInstall from a local clone:\n\n```bash\n# Clone repository\ngit clone https://github.com/ahundt/autorun.git\ncd autorun\n\n# Install the autorun tool\nuv tool install --editable plugins/autorun\n\n# Register plugins with Claude Code\nautorun --install\n```\n\n> **Note:** `autorun --install` publishes native assets from the installed\n> distribution. `autorun --install --install-dry-run` previews the same walk.\n\n### Development Installation\n\nFor contributors and developers:\n\n```bash\n# Clone repository\ngit clone https://github.com/ahundt/autorun.git\ncd autorun\n\n# Option 1: UV (recommended; faster dependency management)\nuv run --project plugins/autorun python -m autorun --install --force\n\n# Option 2: pip fallback (if UV is unavailable)\npython -m pip install -e plugins/autorun && autorun --install --force\n\n# REQUIRED: Install as UV tool for global CLI availability\n# This makes 'autorun' and 'autorun-install' globally available\ncd plugins/autorun && uv tool install --force --editable .\n\n# Verify installation\nautorun --status  # Verifies UV tool installation works\n```\n\n**Install UV (if needed):**\n```bash\n# macOS/Linux:\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Homebrew:\nbrew install uv\n\n# Windows:\npowershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n```\n\n### Verification\n\nAfter installation, verify plugins are registered:\n\n```bash\n# Check installed plugins\nclaude plugin marketplace list\n\n# See all available commands\n/help\n\n# Test autorun\n/ar:st\n# Expected: \"AutoFile policy: allow-all\"\n```\n\n### Multi-CLI Support\n\n**autorun defaults to Claude Code, Google Antigravity, Qwen Code, Codex CLI, Pi, Prime Agent, ForgeCode, and OpenCode**, providing shared safety features, command handlers, and autonomous execution capabilities across maintained harnesses. Legacy Gemini CLI support remains available only through explicit `--gemini` selection.\n\n#### Codex CLI Support\n\nAutorun installs Codex hooks at `~/.codex/hooks.json` by default and exposes its skill bundle as a local Codex plugin through `~/.agents/plugins/marketplace.json` with source `~/plugins/autorun`. After install, run `/hooks` inside Codex if prompted so Codex trusts the hook hashes. Codex task progress maps to the native `update_plan` checklist tool, search/file-discovery guidance uses shell `rg -n` and `rg --files`, and file edits use `apply_patch`.\n\nCodex loads matching hooks from every active source, including user config and plugin bundles. Autorun therefore makes the hook source explicit during installation:\n\n```bash\nautorun --install --codex --codex-hook-source user    # default: ~/.codex/hooks.json only\nautorun --install --codex --codex-hook-source plugin  # ar@personal bundled hooks only\nautorun --install --codex --codex-hook-source both    # install both sources intentionally\nautorun --install --codex --codex-hook-source none    # remove autorun Codex hooks, keep skills/guidance\nautorun --install --codex --codex-plugin-marketplace github\n                                                        # install plugin from ahundt/autorun as ar@autorun\n```\n\n`AUTORUN_CODEX_HOOK_SOURCE` can set the same mode for unattended reinstalls. Reinstalls refresh the selected Codex plugin (`ar@personal` or `ar@autorun`) so changing modes clears stale hook files from previous cache versions instead of leaving duplicate PreToolUse/PostToolUse hooks behind.\n\n`ar@personal` is the local development plugin identity: `ar` is the plugin name, the same one every harness registers, and `personal` is the generated local marketplace name in `~/.agents/plugins/marketplace.json`. For repo-backed Codex installs, the repository ships `.agents/plugins/marketplace.json` with marketplace name `autorun` and display name `Autorun`; use `--codex-plugin-marketplace github` to add `ahundt/autorun` through `codex plugin marketplace add` and install `ar@autorun`. An install made before the plugin was renamed removes its own `autorun` entry, so the marketplace lists one entry per product.\n\nCodex may intercept unknown slash commands before hooks see them, so use `ar:*` or `ar <command>` forms in Codex, such as `ar:st` or `ar:ok git push`. Autorun skills use Codex's native skill surfaces: run `/skills`, mention the skill as `$mermaid-diagrams`, or select the installed `@autorun` plugin. Codex does not turn arbitrary skills into slash commands such as `/mermaid`.\n\n#### Choosing where skills are installed\n\nAn install writes several harnesses at once, and each one should end up with a\nskill by exactly one route. `--skill-placement` decides that route:\n\n```bash\nautorun --install                                     # auto (default)\nautorun --install --skill-placement native            # never use ~/.agents/skills\nautorun --install --skill-placement both              # shared AND native where supported\nautorun --install --skill-placement native --skill-placement codex=both\n```\n\n| Mode | Effect |\n|---|---|\n| `auto` | One route per harness: the shared `~/.agents/skills` root for harnesses whose docs describe reading it (Codex, legacy Gemini, Qwen Code, Pi, Prime Agent, ForgeCode, and OpenCode), otherwise that harness's native plugin/extension skills directory. |\n| `native` | Native route only. Nothing is written to the shared root. |\n| `both` | Shared **and** native where the harness reads both. The only mode that can list one skill twice, after which the two copies can drift apart. |\n\nA bare mode applies to every selected harness; `HARNESS=MODE` overrides one, and\nthe flag repeats. Valid harness names are `antigravity`, `claude`, `codex`,\n`forgecode`, `gemini`, `opencode`, `pi`, `prime`, and `qwen`. An unknown harness\nor mode is rejected at parse time with the list of valid names.\n\n`AUTORUN_SKILL_PLACEMENT` accepts the same grammar, space- or comma-separated\n(`AUTORUN_SKILL_PLACEMENT=\"native codex=both\"`), and the `skill_placement`\nconfig key accepts either a mode string or a mapping of harness to mode with an\noptional `default` key. Precedence is flag > environment > config > `auto`. A\nbad value in the environment or config is ignored rather than aborting the\ninstall; a bad flag value fails immediately.\n\nRun `autorun --install-dry-run` to print the resolved mode, where it came from,\nand the exact directories each harness would receive, before anything is written.\n\n#### Sharing skills with Claude Code\n\nCodex, OpenCode, Pi, Prime Agent, ForgeCode, Qwen Code, and legacy Gemini CLI all scan `~/.agents/skills/`, the cross-tool shared location. Claude Code does not — it reads `~/.claude/skills/` only. A skill authored in the shared directory is therefore invisible to Claude Code until it is bridged:\n\n```bash\nautorun --install --claude --claude-agents-skills link  # symlink shared skills into ~/.claude/skills\nautorun --install --claude --claude-agents-skills copy  # copy instead (Windows without Developer Mode)\nautorun --install --claude --claude-agents-skills none  # default: leave ~/.claude/skills untouched\n```\n\n`AUTORUN_CLAUDE_AGENTS_SKILLS` sets the same mode for unattended installs; the flag wins over the environment variable.\n\nThe default is `none` so no install silently rewrites your skills directory. Skills a plugin already provides are skipped, because Claude Code deduplicates by resolved path rather than by name — a plugin copy and a shared copy are different paths, so both would appear in the skill listing. Existing directories are never replaced.\n\nIndividual skill directories are linked rather than the whole `skills/` folder: Claude Code stops loading user skills entirely when that directory is itself a symlink ([anthropics/claude-code#38051](https://github.com/anthropics/claude-code/issues/38051)), so autorun refuses that layout with an explanation instead of writing something that would never load. Discovery is top level only ([#18192](https://github.com/anthropics/claude-code/issues/18192)), so links are flat. Restart Claude Code after bridging for new skills to appear.\n\n`autorun --uninstall` removes only the links it created; a real directory that happens to share a name, and links pointing anywhere else, are left alone.\n\nThe shared location is configurable through `shared_agents_dir` and `shared_agents_skills_subdir` in `CONFIG`, which install and uninstall both read.\n\n#### Bundled skill examples\n\nAn install selects skills from the chosen `plugins/*/skills/` trees and uses the\nharness's native skill picker or mention syntax. The table lists common examples. In Codex, use `/skills` or `$skill-name`; do not\nassume a skill is an `/ar:*` command. The read-only\n`autorun --capability-snapshot` output is the machine-readable inventory.\n\n| Skill | Purpose |\n|-------|---------|\n| `cache` | Configure cache-miss and compaction protection |\n| `ai-skill-builder` | Create and review portable Agent Skills |\n| `cli-demo-recorder` | Record reproducible CLI and TUI demos |\n| `mermaid-diagrams` | Render Mermaid diagrams |\n| `parallel-subagent` | Investigate ambiguous failures with parallel approaches |\n| `pdf-extractor` | Extract text and structured data from PDFs with backend fallback |\n| `tmux-automation` | Automate isolated terminal and harness tests |\n\nClaude, Gemini, Qwen, and Antigravity discover the skill through their native\nper-plugin installation. Codex receives the union of selected plugin skills in\n`~/.agents/skills/`, so `$pdf-extractor` works independently of the autorun\nplugin cache. Pi consumes the shared installation through `/skill:<name>` and\ncan also use `~/.pi/agent/skills/` when `--skill-placement native` is selected.\nForgeCode and OpenCode use their model-facing skill tools; neither exposes an\nautorun-writable native skill directory, so `native` installs no skills for\nthose two harnesses while `auto` and `both` use the shared route.\n\nFor hook schema details, see [docs/codex-cli-hooks-api.md](docs/codex-cli-hooks-api.md).\n\n#### Legacy Gemini CLI Requirements (Explicit Opt-In)\n\n**Version**: Gemini CLI v0.28.0 or later (hooks require explicit enablement)\n\n**Required Settings**: Edit `~/.gemini/settings.json` and add:\n\n```json\n{\n  \"tools\": {\n    \"enableHooks\": true,\n    \"enableMessageBusIntegration\": true\n  }\n}\n```\n\n**Update Gemini CLI**:\n\n```bash\n# Using Bun\nbun install -g @google/gemini-cli@latest\n\n# Or using npm\nnpm install -g @google/gemini-cli@latest\n\n# Verify version\ngemini --version  # Should show 0.28.0 or later\n```\n\nFor troubleshooting, see [TROUBLESHOOTING.md](plugins/autorun/TROUBLESHOOTING.md).\n\n#### Legacy Gemini CLI Installation\n\n```bash\n# Clone and install\ngit clone https://github.com/ahundt/autorun.git && cd autorun\n\n# Option 1: UV (recommended)\nuv run --project plugins/autorun autorun --install --gemini --force\nuv run --project plugins/autorun autorun --restart-daemon\n\n# Option 2: pip fallback\npython -m pip install -e plugins/autorun && \\\nautorun --install --gemini --force && \\\nautorun --restart-daemon\n\n# Verify installation\ngemini extensions list\nautorun --status --gemini\n# Should show: ar@1.0.0rc1\n\n# Test in Gemini CLI\ngemini\n/ar:st\n# Expected: \"AutoFile policy: allow-all\"\n```\n\n#### Pi support\n\nPi loads autorun from `~/.pi/agent/extensions/ar/`. The TypeScript adapter sends\n`tool_call`, prompt, result, session, and `agent_settled` events to the same\nPython daemon used by the other harnesses. A denied tool returns Pi's native\n`{ block: true, reason }` result. When autorun rejects the settle boundary, the\nadapter sends a hidden `autorun-continuation` custom message that starts the\nnext turn without attributing extension text to the user. Pi also receives\nsequential `TaskCreate`, `TaskUpdate`, `TaskList`, and `TaskGet` tools backed by\nthe same Python task lifecycle and session state as other harnesses.\n\n```bash\nautorun --install --pi --force\npi\n/ar st\n```\n\nPi also accepts `ar:st`, `ar-st`, and `/ar:st`. Skills use Pi's native\n`/skill:<name>` command and the shared `~/.agents/skills/` installation.\nDevelopment tests must redirect `HOME`, `PI_CODING_AGENT_DIR`, `AUTORUN_HOME`,\nand `AUTORUN_TEST_STATE_DIR` before importing or installing autorun.\n\nThe gate covers model tool calls only. Two Pi paths run without it: a `!`\nshell line you type yourself is not a tool call, and a Pi process started with\n`--no-extensions` never loads the adapter. `pi-subagents` passes\n`--no-extensions` to a child `pi` when the agent definition declares its own\n`extensions:` list (or a capability ceiling denies extensions), so add\n`~/.pi/agent/extensions/ar/index.ts` (`~/.prime/agent/extensions/ar/index.ts`\nunder Prime Agent) to that list to keep the guard in the child. Agents without\nan `extensions:` key inherit it automatically.\n\nPi task tools use the same Python-owned lifecycle as Claude: `TaskCreate`,\n`TaskList`, and `TaskGet` provide create/read operations; `TaskUpdate` accepts\none `taskId` or an atomic `taskUpdates` array, including `addBlockedBy` and\n`addBlocks`; `status=\"deleted\"` is the delete operation.\n\n#### Qwen Code Support\n\nQwen Code uses a Gemini-derived extension surface (`qwen extensions install`, `qwen extensions list`, and extension hooks). Autorun reuses the Gemini extension template but rewrites installed Qwen hook commands to `--cli qwen`, so Qwen sessions get Qwen-specific detection and response handling while commands and skills stay single-owned.\n\n```bash\nbrew install qwen-code\nautorun --install --qwen --force\nqwen extensions list\n```\n\nFor Z.AI GLM-5.2 through Qwen Code, use Qwen's OpenAI-compatible auth path\nand the Z.AI coding-plan endpoint:\n\n```bash\nOPENAI_BASE_URL=\"https://api.z.ai/api/coding/paas/v4\" \\\nOPENAI_API_KEY=\"$Z_AI_AUTH_TOKEN\" \\\nOPENAI_MODEL=\"${Z_AI_MODEL:-glm-5.2}\" \\\nqwen --auth-type openai --model \"${Z_AI_MODEL:-glm-5.2}\"\n```\n\nThe local Claude aliases can keep using `ANTHROPIC_AUTH_TOKEN` and\n`Z_AI_BASE_URL=https://api.z.ai/api/anthropic`; Qwen's verified GLM-5.2 route\nmaps the same `Z_AI_AUTH_TOKEN` secret to `OPENAI_API_KEY` instead.\n\n#### Multi-Model Workflows\n\nUse autorun's safety features across supported CLIs:\n\n```bash\n# Claude Code creates implementation\nclaude\n/ar:go \"Implement user authentication system\"\n\n# Gemini CLI reviews with vision capabilities\ngemini\n\"Review the authentication code and analyze this architecture diagram\"\n# Attach: architecture.png\n\n# All sessions use autorun safety:\n# - File policies enforce consistently\n# - Command blocking prevents dangerous operations\n# - Sessions are isolated (no state leakage)\n```\n\n#### Gemini-Specific Features\n\n**Vision + Safety**: Analyze images/diagrams with autorun safety guards active:\n\n```bash\ngemini -i screenshot.png -c \"Convert this UI mockup to React components\"\n```\n\nAutorun ensures generated code respects file policies (`/ar:f` for strict mode) and blocks dangerous operations.\n\n**Cross-Model Code Review**: Use Gemini to review Claude's work with safety features active:\n\n```bash\n# After Claude creates code\ngemini -c \"Review src/auth.py for security issues and suggest improvements\"\n# File policies and command redirecting stay active during review\n```\n\n#### Installation Notes\n\n1. **Single install command**: `autorun --install` detects supported CLIs and installs for whichever are present\n2. **Same handlers**: Autorun and pdf-extractor commands use the same backing behavior across supported CLIs\n3. **Isolated sessions**: Supported CLI sessions don't interfere with each other\n4. **Shared safety**: File policies, command redirecting, and hooks work consistently across supported CLIs\n\nFor more details, see [GEMINI.md](GEMINI.md) for Gemini-specific usage patterns.\n\n## What autorun Does For You\n\n| Problem | autorun Solution |\n|---------|-----------------|\n| Claude stops mid-task, requiring manual \"continue\" | **Automatic continuation** — hooks detect incomplete work and re-inject the task |\n| AI claims \"done\" with partial implementation | **Implement, evaluate, verify** before session ends. Reduces premature exits |\n| AI creates dozens of experimental files | **File policy control** — strict search (`/ar:f`), justified creation (`/ar:j`), or allow all (`/ar:a`) |\n| Dangerous commands run without warning | **Command redirecting** — blocks `rm`, `git reset --hard`, etc. and suggests safer alternatives |\n| Terminal crash loses all progress | **Session persistence** — [tmux](https://github.com/tmux/tmux)/[byobu](https://www.byobu.org/) keeps sessions alive across crashes, reboots, and network drops |\n| Must be at workstation to monitor AI | **Work from anywhere** — access sessions remotely via SSH/[Mosh](https://mosh.org/) from any device |\n\n### Testing\n\n```bash\n# Quick core tests\nuv run --project plugins/autorun pytest plugins/autorun/tests/test_unit_simple.py -v\n\n# Full suite with coverage\nuv run --project plugins/autorun pytest plugins/autorun/tests/ --cov=plugins/autorun/src/autorun --cov-report=term-missing\n```\n\n**Integration test**: Create a byobu session (`byobu-new-session autorun-work`), run `/ar:go <task>`, close terminal, reattach (`byobu-attach autorun-work`) — AI work should continue from where it left off.\n\n## Why Byobu + tmux Integration\n\n**autorun is designed for use with [byobu](https://www.byobu.org/)** (tmux wrapper) for session persistence, remote access, and multi-pane monitoring:\n\n1. **Survive failures**: Sessions persist through crashes, reboots, and network drops — SSH back and resume exactly where you left off\n2. **Work from anywhere**: Access sessions from any device via SSH/Mosh (see [References](#references) for client recommendations)\n3. **Multi-pane monitoring**: Split terminal into panes for AI output, error logs, file system monitoring, and command history simultaneously\n\n## AUTOFILE LIFECYCLE FLOW\n\n```mermaid\ngraph TD\n    A[User sets AutoFile policy] --> B{Policy Level}\n    B -->|Level 3<br/>allow-all| C[All file creation allowed]\n    B -->|Level 2<br/>justify-create| D[Require justification check]\n    B -->|Level 1<br/>strict-search| E[Block all new files]\n\n    C --> F[PreToolUse Hook]\n    D --> G{Justification found?}\n    E --> H{File exists?}\n\n    G -->|Yes| F\n    G -->|No| I[Block file creation]\n    H -->|Yes| F\n    H -->|No| I\n\n    F --> J{Tool is Write?}\n    J -->|No| K[Allow tool execution]\n    J -->|Yes| L{File already exists?}\n    L -->|Yes| K\n    L -->|No| M[Allow new file creation]\n```\n\n**Policy Level 1: Strict Search** (`/afs`)\n- Blocks all new file creation via PreToolWrite hooks\n- Forces AI to modify existing files after platform-native search (`Glob`/`Grep` on Claude, `glob`/`grep_search` on Gemini, `rg --files`/`rg -n` on Codex)\n- Ideal for refactoring established codebases\n- Prevents pollution with experimental files\n\n**Policy Level 2: Justify Create** (`/afj`)\n- Requires `<AUTOFILE_JUSTIFICATION>` tag in AI reasoning\n- Hook scans transcript for proper justification before allowing new files\n- Balances innovation with organization\n- Records why each file was created in reasoning\n\n**Policy Level 3: Allow All** (`/afa`)\n- No restrictions on file creation (default for new projects)\n- Full creative freedom for initial development\n- Best for prototyping and new project setup\n- All tools pass through without intervention\n\n## How It Works\n\n### Three-Stage Autorun System\n\n```mermaid\ngraph TD\n    A[\"/ar:go task description\"] --> B[Stage 1: Initial Implementation]\n    B --> C{AUTORUN_INITIAL_TASKS_COMPLETED?}\n    C -->|No| D[Continue working]\n    D --> B\n    C -->|Yes| E[Stage 2: Critical Evaluation]\n    E --> F{CRITICALLY_EVALUATING_PREVIOUS_WORK_AND_CONTINUING_TASKS_AS_NEEDED?}\n    F -->|No| G[Continue evaluation]\n    G --> E\n    F -->|Yes| H[Stage 3: Final Verification]\n    H --> I{AUTORUN_ALL_TASKS_COMPLETED_AND_VERIFIED_SUCCESSFULLY?}\n    I -->|No| J[Continue verification]\n    J --> H\n    I -->|Yes| K[Task Complete: Session Ends]\n```\n\n**Stage 1: Initial implementation.** Claude works on the task and outputs `AUTORUN_INITIAL_TASKS_COMPLETED` when done.\n\n**Stage 2: Critical evaluation.** Claude evaluates the work, identifies gaps, and outputs `CRITICALLY_EVALUATING_PREVIOUS_WORK_AND_CONTINUING_TASKS_AS_NEEDED` when satisfied.\n\n**Stage 3: Final verification.** Claude checks the requirements and outputs `AUTORUN_ALL_TASKS_COMPLETED_AND_VERIFIED_SUCCESSFULLY` to finish.\n\n**Emergency Stop**: At any point, `/ar:sos` outputs `AUTORUN_STATE_PRESERVATION_EMERGENCY_STOP` and immediately halts.\n\n**Hook mechanism**: User sends `/ar:go <task>` → UserPromptSubmit hook activates stage tracking → AI works autonomously → system validates completion markers at each stage boundary (implement, evaluate, verify) → session ends only after all stages complete.\n\n### Safety Mechanisms\n- **Maximum recheck limit**: Prevents infinite loops (default: 3 attempts per stage)\n- **Emergency stop**: `/ar:sos` immediately terminates any runaway process\n- **Plan acceptance**: Plans can auto-trigger autorun via \"PLAN ACCEPTED\" marker\n- **State validation**: Ensures session integrity throughout process\n\n### Verification Example\n\n**Before autorun**: Claude stops after implementing basic login form\n**With autorun (implement, evaluate, verify)**:\n1. Stage 1: \"Login form implemented!\" → `AUTORUN_INITIAL_TASKS_COMPLETED`\n2. Stage 2: \"Critically evaluated; added error handling; tests missing\" → continues working → `CRITICALLY_EVALUATING_PREVIOUS_WORK_AND_CONTINUING_TASKS_AS_NEEDED`\n3. Stage 3: \"Verified: Form works, tests pass, error handling complete\" → `AUTORUN_ALL_TASKS_COMPLETED_AND_VERIFIED_SUCCESSFULLY` → Session ends\n\n## Tmux Integration\n\nFor crash-safe sessions that survive disconnections, use [byobu](https://www.byobu.org/) (recommended tmux wrapper). Install: `brew install byobu` (macOS), `sudo apt install byobu` (Linux).\n\n```bash\n# Create session, start autonomous work, detach\nbyobu-new-session autorun-work\n/ar:go Build a complete web application with authentication\n# Detach: Ctrl+A, D (or close terminal)\n\n# Reattach from anywhere (SSH/Mosh)\nbyobu-attach autorun-work\n```\n\n**Why byobu over raw tmux?** Simpler keybindings, status bar, session persistence out of the box:\n- **F3/F4** — switch between tabs (windows)\n- **Ctrl+A, D** — detach (session keeps running)\n- **`byobu-attach autorun-work`** — reattach from any terminal/device\n- **F1** — help with all shortcuts\n\nMore: [byobu docs](https://www.byobu.org/documentation), [Mosh](https://mosh.org/) for mobile connections, [SSH/Mosh clients](#references) by platform.\n\n## Development\n\n1. **Edit source**: `plugins/autorun/src/autorun/` in the git repository (NOT the plugin cache at `~/.claude/plugins/cache/`)\n2. **Run tests**: `uv run --project plugins/autorun pytest plugins/autorun/tests/ -v`\n3. **Reinstall after changes**: See [Development Installation](#development-installation-contributors)\n4. **Update plugin**: `/plugin update ar@autorun`\n\n## Advanced Setup (Optional)\n\n### Development Installation (Contributors)\n\nFor contributing to autorun development:\n\n```bash\n# Clone repository\ngit clone https://github.com/ahundt/autorun.git\ncd autorun\n\n# Install plugin + UV tool + restart daemon (one-liner)\n(uv run --project plugins/autorun python -m autorun --install --force && \\\n  cd plugins/autorun && \\\n  uv tool install --force --editable . && \\\n  cd ../.. && \\\n  autorun --restart-daemon) 2>&1 | tee \"install-$(date +%Y%m%d-%H%M%S).log\"\n```\n\n**Contributor Workflow:**\n1. **Make changes**: Edit code in your local clone\n2. **Test locally**: Use the installed development version to test your changes\n3. **Run tests**: `uv run --project plugins/autorun pytest plugins/autorun/tests/` to ensure nothing breaks\n4. **Submit PR**: Create a pull request with your improvements\n\n**AI Safety with Git:**\n- **Undo last commit**: `git reset --soft HEAD~1` undoes commit, keeps changes staged\n- **Stash changes**: `git stash` temporarily shelves changes, `git stash pop` restores\n- **Restore a file**: `git restore filename` reverts specific file to last commit\n- **Change visibility**: `git diff` shows exactly what was modified before committing\n\n### Manual Installation (if plugin system fails)\n\n```bash\n# Option 1: UV (recommended)\nuv run --project plugins/autorun python -m autorun --install --force\n\n# Option 2: pip fallback (if UV not available)\npython3 -m venv .venv\nsource .venv/bin/activate\npython -m pip install -e plugins/autorun\npython -m autorun --install --force\n```\n\n## Available Commands\n\n- **Project/Repo name**: `autorun`\n- **Marketplace name**: `autorun` (used for `/plugin install ar@autorun`)\n- **Command prefix**: `ar` (short forms like `/ar:st` for speed, long forms like `/ar:status` for discoverability)\n- **Live list**: `/ar:help` prints every command with its description, `/ar:help <command>` prints one command's arguments, and typing `ar` alone opens the same list\n\n### Command Spellings by Harness\n\nThe grammar is `ar:<command> [arguments]` everywhere. Harnesses differ only in\nwhich spellings they hand to autorun.\n\n| You type | Claude Code, Antigravity, Qwen Code | Pi, Prime Agent | Codex CLI | ForgeCode, OpenCode |\n|---|---|---|---|---|\n| `/ar:st` | runs, and appears in the slash menu | runs | never arrives | never arrives |\n| `ar:st`, `ar st`, `ar-st` | runs | runs | runs | never arrives |\n| `/ar-st` | never arrives — the harness answers with its own unknown-command message | runs | never arrives | runs, for the installed files named below |\n| `ar:task-status`, `ar:task-ignore`, under any prefix above | runs as `ar:task status` and `ar:task ignore` | same | same | never arrives |\n\n\"Never arrives\" means the harness itself keeps the text: Codex holds its own\nslash menu closed, Claude Code and Qwen Code consume an unknown slash command\nin their own slash processors and print their own feedback (\"Unknown skill\"\non Claude, \"Unknown command\" on Qwen — verified in both harnesses' source, so\nyou always see an immediate error rather than a silent drop), and ForgeCode\nsends autorun no hook events. ForgeCode's installed guards are\nadvice to the agent. OpenCode does not expose prompt or Stop hooks, but its\nin-process JavaScript bridge sends tool calls to autorun, vetoes denied\ncommands, and mirrors OpenCode's native todo list (`todo.updated`) into\nautorun's task status. On both harnesses the installed files `ar-go`, `ar-st`, `ar-allow`,\n`ar-find`, `ar-commit`, and `ar-ph` are the command surface.\n\nAutorun prints the local spelling everywhere: `/ar:` on Claude Code and the\nGemini family, `/ar ` on Pi, `ar:` on Codex, and `/ar-` on ForgeCode and OpenCode. `/ar:help`\nopens with the rule for the harness you are on.\n\n| Short | Long | Legacy | Description |\n|-------|------|--------|-------------|\n| - | `/ar:help` | - | List every command and what it does, in this harness's spelling |\n| `/ar:a` | `/ar:allow` | `/afa` | Allow all file creation (Level 3) |\n| `/ar:j` | `/ar:justify` | `/afj` | Require justification for new files (Level 2) |\n| `/ar:f` | `/ar:find` | `/afs` | Find existing files only; no creation (Level 1) |\n| `/ar:st` | `/ar:status` | `/afst` | Show current policy status |\n| `/ar:go` | `/ar:run` | `/autorun` | Start autonomous task execution |\n| `/ar:gp` | `/ar:proc` | `/autoproc` | Procedural autonomous workflow |\n| `/ar:task` | `/ar:tasks` | - | Show task status or dispatch pause, resume, ignore, prompts, and recovery |\n| `/ar:gc` | `/ar:commit` | - | Display Git Commit Requirements (17-step process) |\n| `/ar:ph` | `/ar:philosophy` | - | Display Universal System Design Philosophy (17 principles) |\n| `/ar:pn` | `/ar:plannew` | - | Create new structured plan |\n| `/ar:x` | `/ar:stop` | `/autostop` | Graceful stop |\n| `/ar:sos` | `/ar:estop` | `/estop` | Emergency stop |\n| `/ar:pr` | `/ar:planrefine` | - | Refine and improve existing plan |\n| `/ar:pu` | `/ar:planupdate` | - | Update plan with new information |\n| `/ar:pp` | `/ar:planprocess` | - | Execute plan with development process |\n| `/ar:tm` | `/ar:tmux` | - | Tmux session management |\n| `/ar:tt` | `/ar:ttest` | - | Tmux test workflow |\n| `/ar:tabs` | - | - | Discover and manage Claude sessions across tmux |\n| `/ar:no <p>` | - | - | Block command pattern in session |\n| `/ar:ok <p> [N\\|5m\\|perm]` | - | - | Allow pattern — `3` uses, `5m` duration, or `perm` (rest of session); default 1 use then auto-revokes |\n| `/ar:clear` | - | - | Clear all session blocks and allows |\n| `/ar:globalno <p>` | - | - | Block command pattern globally (persists across sessions) |\n| `/ar:globalok <p> [N\\|5m\\|perm]` | - | - | Allow pattern globally — `3` uses, `5m` duration, or `perm` (until cleared); default 1 use then auto-revokes |\n| `/ar:blocks` | - | - | Show active session-level blocks and allows |\n| `/ar:globalstatus` | - | - | Show global blocks and allows |\n| `/ar:globalclear` | - | - | Clear all global blocks and allows |\n| `/ar:reload` | - | - | Reload integration rules from config files |\n| `/ar:restart-daemon` | - | - | Restart the daemon for the current autorun install/source tree |\n| `/ar:task` | `/ar:tasks` | - | Show pause, prompting, recovery, and tracked-task status |\n| `/ar:task pause [N] [duration] [reason]` | - | - | Bare pause defaults to five minutes; reason-only pauses until AI recovery; explicit scopes may be combined |\n| `/ar:task resume` | - | - | Resume task enforcement explicitly |\n| `/ar:task ignore <id> [reason]` | - | - | Mark one task ignored so it no longer blocks Stop |\n| `/ar:task prompts on\\|off\\|<N>\\|initial N\\|subsequent N\\|scope all/user/subagent` | - | - | Configure task-staleness prompting |\n| `/ar:task recovery on\\|off\\|min <N>` | - | - | Configure repeated-Stop stale-task recovery |\n| `/ar:cache` | - | - | Cache-miss / compaction protection gate (off by default) — show status |\n| `/ar:cache on [5m\\|1h\\|perm]` | - | - | Enable the gate (optionally for a window) |\n| `/ar:cache off [5m\\|1h\\|perm]` | - | - | Disable the gate (optionally temporarily, prior state restores) |\n| `/ar:cache set ratio\\|read\\|age\\|full <v>` | - | - | Configure threshold axes (tokens `50k\\|.5M`, `85%`, durations `5m\\|2h30m\\|2d`) |\n| `/ar:cache ok [5m\\|N\\|perm]` | - | - | Override the gate — same grammar as `/ar:ok` |\n| `/ar:cache no` | - | - | Cancel outstanding overrides |\n| `/ar:cache global <subcmd>` | - | - | Same operations at the global (cross-session) scope |\n| `/ar:pe` | `/ar:planexport` | - | Show plan export status (effective state and which layer set it) |\n| `/ar:pe on\\|off` | `/ar:planexport on\\|off` | - | Pin plan export for the current project (pin beats the global default) |\n| `/ar:pe globalon\\|globaloff` | `/ar:planexport globalon\\|globaloff` | - | Set the global default for every project |\n| `/ar:pe dir <path>` | `/ar:planexport dir <path>` | - | Set the export directory (template variables allowed) |\n| `/ar:pe pattern <template>` | `/ar:planexport pattern <template>` | - | Set the filename pattern |\n| `/ar:pe <component> [on\\|off\\|dir <path>]` | `/ar:planexport <component> […]` | - | Per-component switch and destination. Components are `accepted` and `rejected`; a bare name toggles it. A component writes only when both plan export and that component are on |\n| `/ar:pe reset` | `/ar:planexport reset` | - | Restore defaults (also clears project pins) |\n| `/ar:tabw` | - | - | Cross-window session actions |\n| `/ar:gemini` | - | - | Gemini CLI reference guide |\n| `/ar:test` | - | - | Test command guidelines |\n| `/ar:marketplace-test` | - | - | Run marketplace tests |\n\n### AutoFile (File Creation Control)\n\nThree-tier policy system enforced via PreToolUse hooks:\n- **Level 3** `/ar:a` — Allow all (default). Best for new projects\n- **Level 2** `/ar:j` — Require `<AUTOFILE_JUSTIFICATION>` tag. For established codebases\n- **Level 1** `/ar:f` — Block all new files, force search-and-modify. For refactoring\n\n### Command Redirecting\n\n**General-purpose command redirecting with actionable suggestions** — When a dangerous command is blocked, autorun doesn't just say \"no\" — it suggests a safer alternative (e.g., `rm` → `trash`, `git reset --hard` → `git stash`). This is one of autorun's most important safety features. Block commands per-session or globally.\n\n**Session Commands:**\n- **/ar:no \\<pattern> [description]** - Block pattern in this session\n- **/ar:ok \\<pattern> [N|5m|permanent]** - Allow pattern — `3` uses, `5m` duration, or `permanent` (rest of session); default 1 use then auto-revokes\n- **/ar:clear** - Clear all session blocks and allows\n- **/ar:blocks** - Show active session-level pattern blocks and allows\n- **/ar:status** - Show AutoFile policy, session and global blocks/allows\n\n**Global Commands:**\n- **/ar:globalno \\<pattern> [description]** - Block pattern globally (all sessions)\n- **/ar:globalok \\<pattern> [N|5m|permanent]** - Allow pattern globally — `3` uses, `5m` duration, or `permanent` (until cleared); default 1 use then auto-revokes\n- **/ar:globalstatus** - Show global blocks\n- **/ar:globalclear** - Clear all global pattern blocks and allows\n\n**Developer/Admin Commands:**\n- **/ar:reload** - Force-reload all integration rules from config files\n- **/ar:restart-daemon** - Restart the daemon for the current autorun install/source tree\n- **autorun --restart-all-daemons** - Risky recovery command for stale or mixed-version daemons; can interrupt active autorun-backed sessions in other installs\n- **autorun --state-status** - Report the configured state backend, whether a conversion to the row-based store has run, and how many fields it moved\n- **autorun --state-migrate** - Convert existing JSON state while the scoped daemon is stopped; required before selecting SQLite when legacy state exists\n- **autorun --state-rollback** - Export state from the row-based store back to `daemon_state.json`, so `state_backend` can be set to `json` again without losing anything written since the conversion\n- **autorun --state-maintenance** - Report SQLite database, WAL, and reclaimable bytes without deleting state\n\n**Pattern Type Prefixes:**\n- **regex:\\<pattern>** - Use regular expression matching\n- **glob:\\<pattern>** - Use glob pattern matching\n- **/\\<pattern>/** - Auto-detects regex when pattern contains metacharacters\n- *(default)* - Literal substring matching\n\n**Examples:**\n```bash\n# Basic blocking (uses DEFAULT_INTEGRATIONS for suggestions)\n/ar:no rm\n\n# Custom description for specific guidance\n/ar:no \"exec(\" unsafe exec function: use alternatives\n\n# Regex pattern matching for flexible patterns\n/ar:no regex:eval\\( dangerous eval usage: blocked for security\n\n# Glob pattern matching for wildcards\n/ar:no glob:*.tmp temporary files are not allowed in this session\n\n# Global blocking with custom description\n/ar:globalno \"git reset --hard\" PERMANENTLY DESTRUCTIVE: use git restore instead\n\n# Auto-detect regex when pattern contains metacharacters\n/ar:no /eval\\(.*assert/ matches eval( or assert(\n```\n\n**Pattern Type Examples:**\n\n| Type | Prefix | Description | Example Pattern | Matches |\n|------|--------|-------------|---------------|--------|\n| Literal | *(none)* | Substring/part matching (default) | `rm` | `rm file.txt` |\n| Regex | `regex:` | Regular expression | `regex:eval\\(` | `code(eval(x))` |\n| Glob | `glob:` | Glob pattern matching | `glob:*.tmp` | `file.tmp` |\n| Auto | `/.../` | Auto-detects regex | `/eval\\(./` | `eval(...` |\n\n**Default integrations (48 entries):**\n- `rm` → Suggests 'trash' CLI (safe file deletion with recovery)\n- `rm -rf` → Dangerous, suggests trash CLI alternatives\n- `git reset --hard` → CRITICAL: Permanently discards uncommitted changes, suggests safer git alternatives\n- `git checkout .` → DANGEROUS: Discards ALL uncommitted changes, suggests git stash\n- `git checkout --` → CAUTION: Discards unstaged changes to specific file, suggests git stash push\n- `git checkout` → CAUTION: Discards unstaged changes (modern syntax without --), suggests git restore\n- `git stash drop` → CAUTION: Permanently deletes stashed changes, suggests git stash pop\n- `git clean -f` → DANGEROUS: Permanently deletes untracked files, suggests git clean -n dry-run first\n- `git reset HEAD~` → CAUTION: Undoes commits, suggests backup branch or git revert\n- `dd if=` → Disk write warning, suggests backup tools\n- `mkfs` → Filesystem warning, suggests backup first\n- `fdisk` → Partition warning, suggests GUI alternatives\n- `sed` → Suggests {edit} AI tool instead of bash sed for file modifications\n- `awk` → Suggests Python or {read} AI tool instead of awk for text processing\n- `grep` → Suggests platform-native search instead (Claude `Grep`, Gemini `grep_search`, Codex `rg -n`; blocked when not in a pipe)\n- `find` → Suggests platform-native file discovery instead (Claude `Glob`, Gemini `glob`, Codex `rg --files`; blocked when not in a pipe)\n- `cat` → Suggests {read} AI tool instead (blocked when not in a pipe)\n- `head` → Suggests {read} AI tool with limit parameter (blocked when not in a pipe)\n- `tail` → Suggests {read} AI tool with offset parameter (blocked when not in a pipe)\n- `echo >` → Suggests {write} AI tool instead of echo redirection\n- `git` → Warning only (action: warn): reminds to check CLAUDE.md git commit requirements\n\n**Installing trash CLI:**\n- macOS: `brew install trash`\n- Linux: `go install github.com/andraschume/trash-cli@latest`\n- Restores files from: `trash-restore` or system trash\n\n**Priority (evaluated top-to-bottom, first match wins):**\n1. **Session/global allows** — `/ar:ok` and `/ar:globalok` (TIER 1, short-circuits all blocks)\n2. **Session blocks** — `/ar:no` (TIER 2, deny wins over warn)\n3. **Global blocks** — `/ar:globalno` (TIER 2)\n4. **User integration files** — `~/.claude/hookify.*.local.md` (TIER 2)\n5. **Default integrations** — built-in safety guards in `config.py` (TIER 2)\n\n**Backward Compatibility:**\nAll existing patterns without type prefixes default to literal matching. Existing blocks continue to work as before.\n\n### Autorun Commands (Autonomous Execution)\n\nStart a task and walk away. Autorun keeps the supported agent working through implement, evaluate, and verify so you don't have to type \"continue\" repeatedly:\n\n- **/ar:go** or **/ar:run** \\<prompt> - Start autonomous workflow with extended work sessions\n  - Reduces manual \"continue\" prompts significantly\n  - Requires implement, evaluate, and verify stages to reduce premature exits\n  - Takes task description as argument (required)\n\n- **/ar:gp** or **/ar:proc** \\<prompt> - Procedural autonomous workflow\n  - Uses Sequential Improvement Methodology\n  - Includes wait process and best practices generation\n\n- **/ar:task pause** \\[N\\] \\[duration\\] \\[reason\\] - Pause task enforcement while talking with the AI\n  - Bare pause defaults to five minutes; reason-only pause has no time limit and supplies periodic AI recovery guidance\n  - Explicit count and duration may be combined and remain authoritative when followed by a reason\n  - Keeps PreToolUse safety hooks and tracked task state unchanged\n  - Use `/ar:task resume`, `/ar:go`, or `/ar:proc` to resume explicitly\n\n- **/ar:x** or **/ar:stop** - Stop gracefully after current task completion\n  - Allows AI to finish current work before stopping\n  - Cleans up processes and state files properly\n\n- **/ar:sos** or **/ar:estop** - Emergency stop — immediately halt any runaway process\n  - Stops all processes immediately without waiting\n  - Use for critical situations or when something goes wrong\n\n### Plan Management Commands\n\nStructured planning for complex development tasks — reduces mistakes and ensures nothing is missed.\n\n| Short | Long | Description |\n|-------|------|-------------|\n| `/ar:pn` | `/ar:plannew` | Create a new structured plan |\n| `/ar:pr` | `/ar:planrefine` | Refine and improve an existing plan |\n| `/ar:pu` | `/ar:planupdate` | Update plan with new information |\n| `/ar:pp` | `/ar:planprocess` | Execute plan with development process |\n\n- **/ar:pn** or **/ar:plannew** - Create a new development plan\n  - Generates structured plan with checkboxes and dependencies\n  - Includes task breakdown and verification criteria\n\n- **/ar:pr** or **/ar:planrefine** - Refine an existing plan\n  - Critically evaluates and improves plan quality\n  - Identifies gaps and adds missing steps\n\n- **/ar:pu** or **/ar:planupdate** - Update plan with new context\n  - Incorporates new requirements or changes\n  - Maintains plan consistency\n\n- **/ar:pp** or **/ar:planprocess** - Execute development process\n  - Follows the plan with Sequential Improvement Methodology\n  - Auto-triggers autorun when plan is approved (\"PLAN ACCEPTED\" marker)\n\n### Task Lifecycle Tracking\n\nTask tracking keeps outstanding work visible and can prevent an early exit while\nreal tasks remain. Need room to discuss before continuing? Run\n`/ar:tasks pause <reason>` to pause task reminders and task-based Stop enforcement\nwithout changing task status. AI recovery or `/ar:tasks resume` turns enforcement\nback on; a bare pause lasts five minutes by default. Command-safety rules remain\nactive throughout.\n\n**Task commands:**\n\n- **/ar:task** or **/ar:tasks** — Show task and enforcement status\n- **/ar:task pause** \\[N\\] \\[duration\\] \\[reason\\] — Bare pause defaults to five minutes; reason-only pause continues until AI recovery\n- **/ar:task resume** — Resume task enforcement\n- **/ar:task ignore** \\<id> \\[reason\\] — Mark one task ignored\n\n**CLI:**\n\n```bash\nautorun task status                  # Show task status for session\nautorun task status --verbose        # Detailed task information\nautorun task export tasks.json       # Export task history to JSON\nautorun task clear                   # Clear task data\nautorun task gc --dry-run            # Preview cleanup of old data\nautorun task gc --no-confirm         # Clean up old task data without prompt\n```\n\n**Key features:** Stop hook enforcement, bounded consecutive-Stop handling, SessionStart resume detection, plan context injection, blockedBy/blocks dependency ordering, escape hatch, full audit trail.\n\n#### Task Staleness Reminders (v0.9) and Stale-Task Escape Hatch (v0.10.2)\n\nInjects a reminder after 25 tool calls in a fresh agent session, then every 50\ncalls after the first checkpoint or any native task/plan update. Every genuine\nTaskCreate/TaskUpdate/TodoWrite, Codex `update_plan`, or equivalent native plan\nupdate resets the active 50-call counter. Primary agents and subagents have\nindependent counters; the default scope is `all`.\n\nThe defaults come from `task_staleness_initial_threshold` (25),\n`task_staleness_subsequent_threshold` (50), and\n`task_staleness_agent_scope` (`all`) in `CONFIG`. Resume and compaction preserve\nthe current phase; a fresh startup or clear begins a new initial phase.\n\n- **/ar:task prompts** — Show prompting status\n- **/ar:task prompts on/off** — Enable or disable reminders only; legacy `/ar:task on/off` remains equivalent and does not disable task-based Stop enforcement\n- **/ar:task prompts \\<N>** — Set both intervals to N (legacy fixed cadence)\n- **/ar:task prompts initial \\<N>** — Set the initial interval for this session\n- **/ar:task prompts subsequent \\<N>** — Set the later interval for this session\n- **/ar:task prompts scope all\\|user\\|subagent** — Select which agent kinds receive reminders\n- **/ar:task recovery** — Show stale-task recovery status\n- **/ar:task recovery on/off** — Enable or disable recovery\n- **/ar:task recovery min \\<N>** — Set the consecutive identical-Stop threshold for this session\n\n**Stale-task escape hatch:** When the same set of task IDs blocks Stop N times in a row with no non-task tool call between them, the stop injection gains an escape hatch instructing the AI to emit `AUTORUN_TASKS_CLEAR_STALE_TASK(<id>)` for any task that Claude's Task DB no longer knows about. A PostToolUse hook detects the marker and marks the task `ignored` (non-blocking), allowing the stop. For a real task that needs discussion, use `/ar:tasks pause <reason>` instead. Disable stale recovery with `/ar:tasks stale off`.\n\n**Bounded consecutive Stops:** Autorun blocks the first `stop_block_max_count`\nStop callbacks when real tasks remain. The next Stop may end that interaction,\nbut it does not complete, ignore, delete, or pause any task. Completed tool\nactivity, a new user prompt, or SessionStart begins a fresh sequence, so task\nenforcement resumes automatically.\n\n**Settings** (`~/.autorun/task-lifecycle.config.json`):\n- `enabled`: Enable/disable task lifecycle tracking (default: true)\n- `max_resume_tasks`: Max tasks shown in resume/stop prompt (default: 20)\n- `stop_block_max_count`: Consecutive blocked Stops before one interaction may end with its tasks retained (default: 3)\n- `task_ttl_days`: Auto-prune completed tasks after N days (default: 30)\n- `debug_logging`: Enable audit logging (default: false)\n- `ghost_clear_enabled`: Enable stale-task escape hatch (default: true)\n- `ghost_clear_min_consecutive_blocks`: Consecutive identical stop blocks before escape hatch appears (default: 2)\n- `ghost_clear_hash_length`: Hex chars in task-id-set digest (default: 12)\n\n**Storage:**\n- **State**: `~/.claude/sessions/daemon_state.json` (single JSON file via filelock+JSON backend)\n- **Logs**: `~/.autorun/task-tracking/{session_id}/audit.log` (per-session)\n- **Config**: `~/.autorun/task-lifecycle.config.json`\n\n### Documentation Commands\n\nThese ship as Agent Skills, so Codex, Qwen, ForgeCode, and OpenCode load them\ntoo, not only Claude Code. The commands below are unchanged.\n\n#### Commit Command\n\n- **/ar:gc** or **/ar:commit** — Display Git Commit Requirements (17-step process)\n  - **Before committing:** Always review requirements before making git commits\n  - **PR review:** Verify commit messages follow guidelines\n  - **Training:** Learn commit message best practices\n\n**Key requirements:**\n1. **Concrete & Actionable** - Use specific, measurable descriptions\n2. **Subject Line Format** - Follow `<files>:` or `type(scope):` convention\n3. **Security Check** - Explicitly check for secrets before committing\n\n#### Philosophy Command\n\n- **/ar:ph** or **/ar:philosophy** — Display Universal System Design Philosophy\n  - Core principles for building systems that \"just work\"\n  - Use during planning, code review, and architecture decisions\n\n**When to use `/ar:philosophy`:**\n- **Before planning:** Apply principles when designing new features\n- **During code review:** Verify implementations follow guidelines\n- **Architecture decisions:** Reference technical and communication principles\n\n**Key principles:**\n- **Automatic and Correct** - Make things \"just work\" without user intervention\n- **Concrete Communication** - Specific, actionable messages with exact error codes, file paths, and test commands\n- **One Problem, One Solution** - Avoid over-engineering; the simplest correct solution wins\n- **Solve Problems FOR Users** - Don't just report issues, fix them automatically\n\n### Tmux Automation Commands\n\n- **/ar:tm** or **/ar:tmux** - Session lifecycle management (create, list, cleanup)\n- **/ar:tt** or **/ar:ttest**: CLI and plugin testing in isolated sessions\n- **/ar:tabs** - Discover and manage Claude sessions running across tmux windows\n- **/ar:tabw** - Execute actions on Claude sessions across tmux windows (DANGEROUS: sends keystrokes to other sessions)\n  - Scans all tmux panes for Claude Code sessions using pattern matching\n  - Displays organized table with session letter (A, B, C), directory, purpose, and status\n  - Supports batch actions: `all:continue`, `awaiting:continue`, `A:git status, B:pwd`\n  - Interactive workflow with user approval before executing commands\n\n#### Session Status Types\n\nWhen `/ar:tabs` discovers sessions, it displays these status indicators:\n\n| Status | Description | Action |\n|--------|-------------|--------|\n| `awaiting input` | Claude waiting for user prompt | Can send commands |\n| `working` | Claude actively generating | Use `:escape` to stop |\n| `plan approval` | Awaiting plan approval | Respond with approval |\n| `tool permission` | Awaiting tool permission | Use `:y` or `:n` |\n| `idle` | Session inactive, no Claude | Safe to send commands |\n| `error` | Error state detected | Investigate before acting |\n\n**See also**:\n- `/ar:tmux` or `/ar:tm` - Create and manage isolated tmux sessions\n- `/ar:ttest` or `/ar:tt` - Automated CLI testing in isolated sessions\n- `tmux-session-automation.md` agent: advanced session lifecycle automation\n\n### Usage Examples\n\n```bash\n# Start autonomous work on a large project\n/ar:go Build complete REST API with authentication, testing, and documentation\n\n# Enable strict file control for security-sensitive work\n/ar:j\n/ar:go Implement OAuth2 authentication system\n\n# Check current file creation policy\n/ar:st\n# Output includes: \"AutoFile policy: justify-create\"\n\n# Protect existing codebase during refactoring (find existing files, don't create new ones)\n/ar:f\n/ar:go Refactor authentication module to use new database schema\n\n# Stop gracefully when task is complete\n/ar:x\n\n# Emergency stop if something goes wrong\n/ar:sos\n\n# Tmux session management\n/ar:tm create my-project\n/ar:tm list\n/ar:tm cleanup\n\n# Discover and manage Claude sessions across tmux windows\n/ar:tabs\n# Shows table of sessions (A, B, C...) with status\n# Then respond with selections like: \"A, B:git status, all:continue\"\n\n# Continue all sessions awaiting input\n/ar:tabs awaiting:continue\n\n# Run different commands on specific sessions\n/ar:tabs A:git status, B:pwd, C:ls -la\n\n# Emergency stop all active sessions\n/ar:tabs all:escape\n\n# Check status of all sessions\n/ar:tabs all:pwd\n```\n\n### Legacy Commands (Backward Compatible)\n\nAll legacy commands continue to work: `/afa`, `/afj`, `/afs`, `/afst`, `/autorun`, `/autoproc`, `/autostop`, `/estop`\n\n## CLI Reference\n\nThe `autorun` CLI command is available after installation for managing plugins, file policies, and task lifecycle outside of supported AI sessions.\n\n**Installation:**\n\n```bash\nautorun --install                    # Register plugins/hooks for installed supported CLIs\nautorun --install autorun            # Register only autorun plugin\nautorun --install --claude           # Register for Claude Code only\nautorun --install --gemini           # Explicitly register the legacy Gemini CLI\nautorun --install --qwen             # Register for Qwen Code only\nautorun --install --pi               # Register for Pi only\nautorun --install --prime            # Register for Prime Agent only (Pi variant)\nautorun --install --codex            # Register for Codex CLI only\nautorun --install --codex --codex-hook-source plugin\n                                      # Package Codex hooks in ar@personal instead of ~/.codex/hooks.json\nautorun --install --codex --codex-plugin-marketplace github\n                                      # Install Codex plugin from ahundt/autorun as ar@autorun\nautorun --install --codex --codex-plugin-marketplace personal\n                                      # Install local development plugin as ar@personal\nautorun --install-dry-run --codex     # Preview all writes without changing user config\nautorun --install --custom-harness 'lab=qwen:qwen-lab:/path/to/config::Qwen Lab'\n                                      # Install a flavored custom harness; option is repeatable\nautorun --install --force            # Force reinstall (development)\nautorun --install --tool             # Also run uv tool install for global CLI\nautorun --uninstall                  # Uninstall plugins and UV tools\n```\n\n**Information:**\n\n```bash\nautorun --status                     # Show maintained-harness installation status\nautorun --status --gemini            # Also inspect retired Gemini CLI compatibility\nautorun --status --custom-harness 'lab=codex:codex-lab:/path/to/config::Codex Lab'\n                                      # Include a custom target in normal status output\nautorun --version                    # Show version\nautorun --help                       # Full help with all options\nautorun --capability-snapshot FILE   # Write platforms, commands, skills, and hooks as JSON\nstatusline-command | autorun --cache-snapshot\n                                      # Persist opt-in Claude cache telemetry from stdin\n```\n\nCustom harness specs use\n`name=flavor:binary:config_dir[::display]`. Supported flavors are `claude`,\n`gemini`, `qwen`, `antigravity`, `agy` (an alias for `antigravity`), and\n`codex`. The `claude` flavor installs the portable markdown commands +\nAGENTS.md bundle (no hooks) — the right shape for Claude-compatible harnesses\nsuch as OpenCode. Persistent targets belong in `CONFIG[\"custom_harnesses\"]`\nusing the same spec grammar; a `--custom-harness` flag overrides a config\nentry with the same name, and several entries may share one flavor with\ndifferent config dirs (for example `codex-home=codex:codex:~/.codex-home` and\n`codex-work=codex:codex:~/.codex-work`).\n\nEach built-in harness's config root is also relocatable:\n`CONFIG[\"harness_config_dirs\"]` (for example `{\"codex\": \"~/.codex-work\"}`)\nwins over the harness's own environment variable (`CLAUDE_CONFIG_DIR`,\n`CODEX_HOME`, `QWEN_HOME`, `FORGE_CONFIG`), which wins over the default. The\ndesktop apps need no separate configuration: the merged ChatGPT/Codex desktop\napp (bundle `com.openai.codex`) shares `~/.codex` with Codex CLI, and Claude\nDesktop's local Code sessions share `~/.claude` with Claude Code.\nThe optional display name follows the unambiguous `::` separator, so a\n`config_dir` may itself contain `:` characters.\n\nAccepted option values: `--codex-hook-source: user|plugin|both|none`;\n`--codex-plugin-marketplace: personal|github`;\n`--claude-agents-skills: link|copy|none`;\n`--skill-placement: auto|native|both` or `HARNESS=auto|native|both`, repeatable.\n\n**Maintenance:**\n\n```bash\nautorun --restart-daemon             # Restart the autorun daemon\nautorun --restart-all-daemons         # Risky: stop matching daemons across installs\nautorun --state-status                # Which state backend, and any conversion\nautorun --state-migrate               # Convert JSON while scoped daemon is stopped\nautorun --state-rollback              # Export the row store back to JSON\nautorun --state-maintenance           # Report database/WAL/reclaimable bytes\nautorun --update                     # Check for and install updates\nautorun --update-method uv           # Force method (auto|claude|gemini|plugin|uv|pip)\nautorun --no-bootstrap               # Disable automatic bootstrap in hooks\nautorun --enable-bootstrap           # Re-enable automatic bo",
  "bytes": 60000,
  "sha": "38ee8d3072753535a79f9d4c7c6b7440933f3eef3019fbe6ff7680f6d8a889ff",
  "repo_slug": "ahundt/autorun",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_ahundt_autorun_b9084e25/readme"
}