air CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

air is a Claude Code plugin for automated PR code review, with an optional Managed Agent mode for CI automation.

The CLI plugin (plugins/air/) is markdown files and JSON metadata — no build system or dependencies. The Managed Agent (managed/) adds Python scripts for Anthropic's cloud API + a GitHub Actions workflow.

Two CLI commands: /air:review (13-step review pipeline) and /air:learn (wiki cleanup/regeneration). For CI: managed/review.py or the reusable GitHub Action.

Project Structure

plugins/air/
├── agents/              # 6 review specialists + 1 managed-mode coordinator (markdown prompts)
│   ├── code-reviewer.md
│   ├── security-auditor.md
│   ├── simplify.md
│   ├── git-history-reviewer.md
│   ├── ui-copy-reviewer.md    # UI/business-audience copy + static UX/a11y (conditional — UI-touching diffs)
│   ├── review-verifier.md
│   └── coordinator.md         # Managed-mode delegator — fans out specialists via callable_agents (not a reviewer)
├── commands/            # CLI command orchestration
│   ├── review.md              # Main pipeline — the core of the plugin
│   ├── review-self.md         # Self-review flow (--self mode)
│   ├── review-respond.md      # Respond flow (--respond mode)
│   ├── review-solo.md         # Solo flow (--solo mode — one Fable agent, all lenses, gate-capable)
│   └── learn.md               # Wiki maintenance
├── hooks/               # Pre-commit drift-check hook (v1.6.0+)
│   ├── hooks.json             # PreToolUse hook registration
│   ├── pre-commit-drift.py    # Wrapper: narrows to `git commit`, routes custom/built-in
│   └── builtin-checks.sh      # Zero-config auto-detection (version mirror + badge)
├── lib/                 # Shared Python helpers (stdlib-only, called by CLI + managed)
│   ├── meta.py                # /air:learn trigger counter (wiki file or memory-store backend + find-store)
│   ├── wiki_git.py            # Clone + commit-meta-with-retry (legacy wiki backend)
│   ├── pattern_lifecycle.py   # Deterministic author-pattern strengthen/clean/decline/archive ops
│   ├── pr_conversation.py     # Merge GitHub PR comments/reviews into <pr-conversation> agent context
│   ├── agent_loop.py          # Self-hosted Messages-API tool-use loop for headless mode (5m cache default, thinking round-trip)
│   ├── tool_exec.py           # Read-only sandbox for headless agents (path-jailed Read/Grep/Glob + fixed-verb git, shell=False)
│   ├── solo_prompt.py         # THE solo-prompt assembly (CLI --solo runs it; managed setup.py imports it)
│   ├── agent_md.py            # THE agents/*.md frontmatter parser — single source for solo_prompt / setup / headless._persona_model
│   ├── diff_hygiene.py        # THE diff stub-generated/vendored + size-cap pass — single source: managed github_client fetchers re-export it; CLI review.md pipes its diff saves through it
│   ├── wiki_cap.py            # THE deterministic wiki bloat-cap (per-file byte ceilings; managed learn/render + CLI learn all call it)
│   ├── env.py                 # THE tolerant AIR_* env parsing (env_int/float/bool — crash-safe on a typo'd value) + report_env() startup drift report
│   └── verdict.py             # THE review-gating contract (shared: CLI Step 12 runs it via --decide; managed imports it)
└── .claude-plugin/
    └── plugin.json      # Plugin metadata (name, version, author)

.air-checks.sh           # Opt-in per-repo drift checks (consumed by the hook above)

.claude-plugin/
└── marketplace.json     # Marketplace distribution definition

managed/                          # Managed Agent (CI automation)
├── api.py                        # Shared API helpers
├── setup.py                      # Creates/updates agents + environment via API
├── review.py                     # Client-side driver: orchestrates the review run (launches coordinator, posts)
├── headless.py                   # `messages-api` mode driver: self-hosted specialist+verifier loop (full lens set), reuses verdict/prompts/github_client/review helpers
├── github_client.py              # GitHub REST: fetchers, pagination, comment/verdict POSTs
├── verdict.py                    # Thin shim re-exporting plugins/air/lib/verdict.py (the shared gating contract)
├── session_runner.py             # Session lifecycle: run_session, REST drain, billing retry, SIGTERM cleanup
├── prompts.py                    # Prompt builders: PR context block + verifier-task templates
├── learn.py                      # Triggers wiki/store maintenance sessions (single-agent, managed)
├── learn_headless.py             # MA-independent learn: client-side map-reduce store curation (no managed session)
├── memory_store.py               # Per-repo pattern memory store: discovery, reads, sha256-preconditioned writes
├── pattern_writer.py             # Applies pattern_lifecycle ops to the store after each review
├── migrate_wiki_to_store.py      # One-shot wiki → store migration (per-author split, --dry-run)
├── migrate_workspace_stores.py   # One-shot store → store copy across workspaces (sha256-verified)
├── render_store_to_wiki.py       # Deterministic store→wiki mirror render (throttled per-review + on learn)
├── salvage_review.py             # Drain a finished orphaned session and post its review ($0 — e.g. after a job cancel)
├── test-session.py               # Quick 9-test verification script
├── prompts/learn-orchestrator.md # System prompt for cloud learn agent
│                                 # (review orchestrator.md deleted in v1.7.0 — review.py orchestrates client-side)
├── requirements.txt              # Python dependencies
└── README.md

.github/workflows/
├── managed-review.yml            # Reusable GitHub Action (teams reference this)
├── air-review.yml                # Dogfood caller for this repo (PR + workflow_dispatch)
├── release-please.yml            # Automated tag + GitHub Release on version bumps
└── drift-checks.yml              # Runs .air-checks.sh on every PR (closes the local-hook-only gap)