CLAUDE.md · diff
git:20260726.54871d7 to git:20260727.6e613ca
7 added, 4 removed. Audit B to B.
# autorun Marketplace - Claude Code
## Critical Runtime Isolation
- Tests must set both `AUTORUN_HOME` and `AUTORUN_TEST_STATE_DIR` before any
autorun import; they must never touch the live daemon socket, PID, locks, logs,
or user session history.
- Daemon hook paths must use `EventContext.state_get/state_set/state_update`;
wrap legacy direct persistence with `state_synchronize` so concurrent threads,
processes, sessions, and harnesses cannot observe stale state.
- Never hide persistent-state I/O or lock failures by raising hook timeouts, and
never weaken concurrency, protocol, or isolation assertions to pass tests.
- Before committing, read `plugins/autorun/commands/commit.md`; use a concrete
`<files>:` subject for few/grouped files or `type(scope):` for many files.
Cover previous behavior, exact changes, rationale, files, and verification.
- Full invariants, regression checks, and recovery guidance:
[`plugins/autorun/docs/RUNTIME_STATE_ISOLATION.md`](plugins/autorun/docs/RUNTIME_STATE_ISOLATION.md).
UV workspace containing 2 Claude Code plugins: **autorun**, **pdf-extractor**.
**For Gemini CLI:** See [GEMINI.md](GEMINI.md) for Gemini-specific installation and configuration.
## Installation (Claude Code)
### From GitHub (Production - Recommended)
```bash
# Install directly via Claude Code plugin system
claude plugin install https://github.com/ahundt/autorun.git
# Verify
claude plugin list # Should show: ar, pdf-extractor
```
### From Local Clone (Development)
```bash
git clone https://github.com/ahundt/autorun.git && cd autorun
# Option 1: UV (recommended - faster, better dependency management)
uv run python -m plugins.autorun.src.autorun.install --install --force
# Option 2: pip fallback (if UV not available)
pip install -e . && python -m plugins.autorun.src.autorun.install --install --force
# REQUIRED: Install as UV tool for global CLI availability
# This makes the 'autorun' and 'autorun-install' commands globally available
# which are needed for proper daemon operation and session management
cd plugins/autorun && uv tool install --force --editable .
# Verify installation
claude plugin list # Should show: ar, pdf-extractor
autorun --status # Verifies UV tool installation works
```
**Install UV (if needed):**
```bash
# macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
# Homebrew:
brew install uv
# Windows:
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```
### Test Installation
```bash
# In Claude Code session:
/ar:st # Expected: "AutoFile policy: allow-all"
```
## Quick Start
```bash
/ar:go <task> # Start autonomous execution with three-stage verification
/ar:sos # Emergency stop
/ar:st # Show current status
```
## Plugins Overview
| Plugin | Prefix | Purpose |
|--------|--------|---------|
| **autorun** | `/ar:` | Autonomous execution, file policies, safety guards, plan export |
| **pdf-extractor** | `/pdf-extractor:` | Extract text from PDFs (9 backends, GPU support) |
---
## autorun Plugin (v0.12.0)
### Three-Stage Verification System
Ensures thorough task completion through mandatory stages:
| Stage | Purpose | Completion Marker |
|-------|---------|-------------------|
| **Stage 1** | Initial implementation | `AUTORUN_INITIAL_TASKS_COMPLETED` |
| **Stage 2** | Critical evaluation - identify gaps, fix issues | `CRITICALLY_EVALUATING_PREVIOUS_WORK_AND_CONTINUING_TASKS_AS_NEEDED` |
| **Stage 3** | Final verification - all requirements met | `AUTORUN_ALL_TASKS_COMPLETED_AND_VERIFIED_SUCCESSFULLY` |
**Concrete Example:**
```
User: /ar:go Add login form with validation and tests
Stage 1: Implements login form → outputs AUTORUN_INITIAL_TASKS_COMPLETED
Stage 2: Reviews work, finds missing error handling, adds it → CRITICALLY_EVALUATING_PREVIOUS_WORK_AND_CONTINUING_TASKS_AS_NEEDED
Stage 3: Verifies form works, tests pass, error handling complete → AUTORUN_ALL_TASKS_COMPLETED_AND_VERIFIED_SUCCESSFULLY → Session ends
```
Without three-stage: Claude might stop after Stage 1 with incomplete work.
### All Commands
**AutoFile Policy** (controls file creation via PreToolUse hooks):
| Short | Long | Legacy | Description |
|-------|------|--------|-------------|
| `/ar:a` | `/ar:allow` | `/afa` | Allow all file creation |
| `/ar:j` | `/ar:justify` | `/afj` | Require `<AUTOFILE_JUSTIFICATION>` for new files |
| `/ar:f` | `/ar:find` | `/afs` | Modify existing files only (strictest) |
| `/ar:st` | `/ar:status` | `/afst` | Show current policy |
**Autorun Control**:
| Short | Long | Legacy | Description |
|-------|------|--------|-------------|
| `/ar:go <task>` | `/ar:run` | `/autorun` | Start autonomous execution |
| `/ar:gp <task>` | `/ar:proc` | `/autoproc` | Procedural mode with Wait Process |
+ | `/ar:task` | `/ar:tasks` | - | Show task status or dispatch pause, resume, ignore, prompts, and recovery |
| `/ar:x` | `/ar:stop` | `/autostop` | Graceful stop |
| `/ar:sos` | `/ar:estop` | `/estop` | Emergency stop |
**Plan Management**:
| Short | Long | Description |
|-------|------|-------------|
| `/ar:pn` | `/ar:plannew` | Create structured plan |
| `/ar:pr` | `/ar:planrefine` | Critique and improve plan |
| `/ar:pu` | `/ar:planupdate` | Update plan with new info |
| `/ar:pp` | `/ar:planprocess` | Execute plan with methodology |
**Documentation**:
| Short | Long | Description |
|-------|------|-------------|
| `/ar:gc` | `/ar:commit` | Git commit requirements (17 steps) |
| `/ar:ph` | `/ar:philosophy` | System design philosophy (17 principles) |
**Safety Guards** (v0.6.0+) - Blocks dangerous commands and suggests safe alternatives:
Built-in protections for: `rm` → `trash`, `git reset --hard` → `git stash`, `git clean -f` → `git clean -n`, etc.
| Command | Description |
|---------|-------------|
| `/ar:no <pattern>` | Block command pattern in this session |
| `/ar:ok <pattern> [N\|5m\|perm]` | Allow pattern — `3` uses, `5m` duration, or `perm` (rest of session); default 1 use then auto-revokes |
| `/ar:clear` | Clear all session blocks and allows |
| `/ar:blocks` | Show active session-level blocks and allows |
| `/ar:globalno <pattern>` | Block command pattern globally (persists across sessions) |
| `/ar:globalok <pattern> [N\|5m\|perm]` | Allow pattern globally — `3` uses, `5m` duration, or `perm` (until cleared); default 1 use then auto-revokes |
| `/ar:globalstatus` | Show global blocks and allows |
| `/ar:globalclear` | Clear all global blocks and allows |
See `plugins/autorun/src/autorun/config.py:175` for the DEFAULT_INTEGRATIONS list.
**Hook Error Prevention**: See `plugins/autorun/CLAUDE.md` "Hook Error Prevention" section. Key rule: NEVER add deprecated fields to `[tool.uv]` in pyproject.toml — UV stderr warnings silently disable ALL hooks.
**Tmux/Session Tools**:
| Short | Long | Description |
|-------|------|-------------|
| `/ar:tm` | `/ar:tmux` | Tmux session management |
| `/ar:tt` | `/ar:ttest` | CLI testing in isolated sessions |
| `/ar:tabs` | - | Discover Claude sessions across tmux windows |
**Plan Export** — Auto-exports plans to `notes/` on ExitPlanMode, recovers unexported plans on SessionStart:
| Short | Long | Description |
|-------|------|-------------|
| `/ar:pe` | `/ar:planexport` | Show plan export status |
| `/ar:pe-on` | `/ar:planexport-enable` | Enable auto-export |
| `/ar:pe-off` | `/ar:planexport-disable` | Disable auto-export |
| `/ar:pe-cfg` | `/ar:planexport-configure` | Interactive configuration |
| `/ar:pe-dir` | `/ar:planexport-dir` | Set output directory |
| `/ar:pe-fmt` | `/ar:planexport-pattern` | Set filename pattern |
| `/ar:pe-reset` | `/ar:planexport-reset` | Reset to defaults |
| `/ar:pe-rej` | `/ar:planexport-rejected` | Toggle rejected plan export |
| `/ar:pe-rdir` | `/ar:planexport-rejected-dir` | Set rejected plan output directory |
**Task Tracking** (v0.9+):
| Command | Description |
|---------|-------------|
- | `/ar:tasks` | Toggle task staleness reminders on/off or set threshold |
- | `/ar:tasks stale on\|off\|min <N>` | Enable/disable stale-task escape hatch or set consecutive-block threshold (v0.10.2) |
- | `/ar:task-status` | Show task lifecycle status and incomplete tasks |
- | `/ar:task-ignore <id>` | Mark task as ignored (user override to unblock stop) |
+ | `/ar:task`, `/ar:tasks` | Show task, pause, prompting, and recovery status |
+ | `/ar:task pause [N] [duration] [reason]` | Pause task enforcement; count and duration may be combined |
+ | `/ar:task resume` | Resume task enforcement |
+ | `/ar:task ignore <id> [reason]` | Mark one task ignored |
+ | `/ar:task prompts on\|off\|<N>` | Configure task-staleness prompting |
+ | `/ar:task recovery on\|off\|min <N>` | Configure repeated-Stop stale-task recovery |
**Cache-Miss / Compaction Protection** (off by default):
| Command | Description |
|---------|-------------|
| `/ar:cache` | Show status (enabled/disabled, thresholds, active overrides). |
| `/ar:cache on [5m\|1h\|perm]` | Enable the gate (optionally for a window). |
| `/ar:cache off [5m\|1h\|perm]` | Disable the gate. |
| `/ar:cache set ratio\|read\|age\|full <value>` | Configure threshold axes. Tokens `50k \| .5M`, percents `85%`, durations `5m \| 2h30m`. |
| `/ar:cache ok [5m\|N\|perm]` | Override the gate (same grammar as `/ar:ok`). |
| `/ar:cache no` | Cancel outstanding overrides. |
Feature lives in `plugins/autorun/src/autorun/cache_guard.py`. Reuses `ScopedAllow`, `parse_scope_args`, `session_state`, `check_blocked_commands`, `detect_cli_type`.
**Developer/Admin**:
| Command | Description |
|---------|-------------|
| `/ar:reload` | Force-reload all integration rules from config files |
| `/ar:restart-daemon` | Restart the daemon for the current autorun install/source tree |
| `autorun --restart-all-daemons` | Risky recovery command for stale or mixed-version daemons; can interrupt active autorun-backed sessions in other installs |
| `/ar:marketplace-test` | Run tests across installed marketplace plugins |
| `/ar:test` | Test command guidelines |
| `/ar:gemini` | Gemini CLI reference guide |
| `/ar:tabw` | Cross-window session actions |
### Key Files
| File | Purpose |
|------|---------|
| `plugins/autorun/src/autorun/config.py` | Single source of truth for CONFIG (stages, policies, templates) |
| `plugins/autorun/src/autorun/main.py` | Hook handler and CLI entry point |
| `plugins/autorun/src/autorun/plugins.py` | Command handlers and dispatch logic |
| `plugins/autorun/src/autorun/plan_export.py` | Plan export logic, PlanExport class, daemon handlers |
| `plugins/autorun/src/autorun/integrations.py` | Unified command integrations (superset of hookify) |
| `plugins/autorun/src/autorun/task_lifecycle.py` | Task lifecycle tracking and stop-hook enforcement |
| `plugins/autorun/src/autorun/session_manager.py` | filelock+JSON session state backend |
| `plugins/autorun/src/autorun/client.py` | Hook response output and CLI detection |
| `plugins/autorun/scripts/plan_export_config.py` | Plan export configuration CLI |
| `plugins/autorun/.claude-plugin/plugin.json` | Plugin manifest |
---
## pdf-extractor Plugin (v0.12.0)
Extract text from PDFs with 9 backends (markitdown, pdfplumber, docling, marker, etc.).
### Commands
| Command | Description |
|---------|-------------|
| `/pdf-extractor:extract <file>` | Extract PDF to markdown |
### CLI Usage
```bash
extract-pdfs document.pdf # Single file
extract-pdfs ./pdfs/ ./output/ # Batch extraction
extract-pdfs --list-backends # Show available backends
extract-pdfs doc.pdf --backends marker # Use specific backend (GPU OCR)
```
### Key Files
| File | Purpose |
|------|---------|
| `plugins/pdf-extractor/src/pdf_extraction/backends.py` | 9 extraction backends |
| `plugins/pdf-extractor/src/pdf_extraction/cli.py` | CLI entry point |
| `plugins/pdf-extractor/CLAUDE.md` | Full documentation |
---
## Architecture
```
autorun/ # Git repository root
├── plugins/
│ ├── autorun/ # Main plugin
│ │ ├── src/autorun/ # Python source
│ │ ├── commands/ # Slash commands
│ │ ├── agents/ # Tmux automation agents
│ │ ├── skills/ # Claude Code skills
│ │ └── hooks/ # Event hooks
│ └── pdf-extractor/ # PDF extraction plugin
├── src/autorun_marketplace/ # Marketplace registration
├── pyproject.toml # UV workspace config
└── README.md # Full documentation
```
## Testing
```bash
# Quick tests (from repo root)
uv run pytest plugins/autorun/tests/test_unit_simple.py -v
# Full suite with coverage
uv run pytest plugins/autorun/tests/ --cov=plugins/autorun/src/autorun --cov-report=term-missing
```
## Integration References
- **Claude Code Plugins**: [docs.claude.com/en/docs/claude-code/plugins](https://docs.claude.com/en/docs/claude-code/plugins)
- **Plugin Reference**: [docs.claude.com/en/docs/claude-code/plugins-reference](https://docs.claude.com/en/docs/claude-code/plugins-reference)
- **Slash Commands**: [docs.claude.com/en/docs/claude-code/slash-commands](https://docs.claude.com/en/docs/claude-code/slash-commands)
- **Hooks**: [docs.claude.com/en/docs/claude-code/hooks](https://docs.claude.com/en/docs/claude-code/hooks)
- **Agent SDK**: [docs.claude.com/en/api/agent-sdk/overview](https://docs.claude.com/en/api/agent-sdk/overview)
- **Byobu/Tmux**: [byobu.org](https://www.byobu.org/) - Terminal multiplexer for crash-safe sessions
- **Mosh**: [mosh.org](https://mosh.org/) - Mobile shell for unreliable connections
## Full Documentation
See `README.md` for complete details:
- Installation options: "Quick Start" and "UV Installation" sections
- Three-stage verification internals: "Three-Stage Autorun System" section
- Safety guards with defaults: the command-blocking sections
- Tmux/byobu integration: "Tmux Integration" section
- Plugin architecture: "Plugin Architecture and Integration Guide" section
- Troubleshooting: "Troubleshooting" section