anywhere-agents

English · 中文

anywhere-agents

One config for every agent — Claude Code, Codex, and whatever comes next.

Start with effective defaults. Add packs, small bundles of rules, skills, or permissions, as you need them. One AGENTS.md drives every agent in every repo on every machine.

Install  •  Why  •  How it works  •  Pack CLI  •  Docs  •  Fork

[!NOTE] Condensed from daily use. The sanitized public release of the agent config I have run daily since early 2026 across research, paper writing, and dev work (PyOD 3, LaTeX, admin) on macOS, Windows, and Linux. Not a weekend project. Maintained by Yue Zhao — USC CS faculty and author of PyOD (9.8k★ · 38M+ downloads · ~12k citations).

Why You'd Use This

Four problems this fixes:

You use more than one agent. Claude Code at work, Codex on personal projects, Cursor on the side. Without anywhere-agents, three configs to keep in sync. With it, one AGENTS.md drives all three.

You work across many repos. Every new project repeats the same setup ritual: writing-style rules, permission policies, custom skills. Without anywhere-agents, you copy-paste between repos and watch them drift. With it, bootstrap pulls shared defaults and layers repo-local overrides on top.

You want a review loop before you push. anywhere-agents ships /implement-review and its short alias /vet, which hand your staged diff to a second reviewer from another model family. Codex stays the no-argument default; /vet agy selects Gemini through the official Antigravity CLI, with Copilot and headless Claude Code also available. Every automated backend can run tests, experiments, shell commands, and network verification without interactive permission gates. Without it, you wire reviewer CLIs per project. With it, the skill is present the first time you bootstrap.

You want your agents to follow writing conventions automatically. The default agent-style rule pack bans ~45 AI-tell words and formatting patterns; a PreToolUse guard denies any .md / .tex / .rst write that contains one. Without anywhere-agents, the banned words land in your files. With it, the guard blocks the write.

As of v0.7.7: Bare anywhere-agents is the canonical apply command: one verb bootstraps, deploys, applies prompt-policy drift on mutable refs, and regenerates CLAUDE.md. v0.7.x also moved releases to OIDC automatic publishing through gh release create and registered prun in aa-core-skills for parallel delegation fan-out. The agent-pack reference repo is the blueprint for any pack you want to author: your own profile, paper workflow, team conventions, custom skills. The pattern is fork-and-replace. Fork ap, replace its three packs with your content, tag a release, then point pack add at your fork:

anywhere-agents pack add https://github.com/yzhao062/agent-pack --ref v0.1.0

The auth chain handles private repos automatically: SSH agent → gh CLI → GITHUB_TOKEN → anonymous, in that order, with whatever you already have configured. --ref is optional (defaults to main); pin a tag for production.

How It Works

A pack is a small bundle (a rule set, a skill, or a permission policy) that the composer deploys to wherever it needs to land: AGENTS.md, .claude/skills/, .claude/commands/, ~/.claude/hooks/, or ~/.claude/settings.json.

bootstrap installs shipped defaults (agent-style, aa-core-skills, which currently ships six skills: ci-mockup-figure, editable-figure, implement-review, my-router, prun, and readme-polish; completing an editable-figure PPTX deliverable requires desktop PowerPoint on Windows or macOS, and its bundled export script is Windows-only) and assembles project-active selections from rule_packs: in agent-config.yaml, rule_packs: in agent-config.local.yaml, and the AGENT_CONFIG_PACKS env var as a transient name list. Each entry is either a registered name (resolved against bootstrap/packs.yaml) or a direct-URL form with a source: {url, ref} field. v0.5.0's 4-method auth chain fetches both public and private repos with whatever Git authentication you already have configured.

Since v0.6.0, the bundled-default policy table is agent-style (passive) → auto (silent refresh + stderr summary) and aa-core-skills (active) → prompt (apply-by-default + stderr summary). Third-party packs default to prompt. Bare anywhere-agents applies prompt-policy drift on mutable refs inline; the run prints one stderr summary line per affected pack (applied 1 update for <pack> @ <ref>: <old> -> <new>). Per-run skip is available via ANYWHERE_AGENTS_UPDATE=skip (v0.5.0 contract) or the --no-apply-drift CLI flag (the flag wins when both are set). Durable fail-closed: pin update_policy: locked in agent-config.yaml. The anywhere-agents pack add | remove | list CLI writes a user-level manifest at $XDG_CONFIG_HOME/anywhere-agents/config.yaml. Since v0.5.2, pack add is one-shot: it writes the entry, runs the composer, and deploys in a single command.

anywhere-agents is the sync step. Re-run it on any machine or repo, and the same command reproduces the shipped defaults plus the project-level selections, applies any drift, and refreshes generated files.

What This Looks Like

Every Session Opens with a Status Banner

Current and latest versions of Claude Code and Codex (arrows appear only when they differ); auto-update state; active skills (local + pack + shared); hooks (guard.py PreToolUse, session_bootstrap.py SessionStart); any drift flagged by the session check. If anything needs attention, the last line names it with a concrete action (for example, ⚠ actions/checkout@v4 in .github/workflows/validate.yml:17 — bump to v5).

What Appears in Your Repo After Bootstrap

your-project/
├── AGENTS.md              # shared rules synced from upstream
├── AGENTS.local.md        # your per-project overrides (optional)
├── CLAUDE.md              # generated from AGENTS.md for Claude Code
├── agents/codex.md        # generated from AGENTS.md for Codex
├── agent-config.yaml      # (optional) per-project pack selections
├── .claude/
│   ├── commands/          # slash-command pointers for shipped skills
│   └── settings.json      # your project keys merged with shared
├── .agent-config/         # upstream cache (gitignored)
└── skills/                # (optional) repo-local skill overrides

Bootstrap also drops guard.py and session_bootstrap.py into ~/.claude/hooks/, installs statusline.py and agent-quota.py under ~/.claude/, and merges shared keys into ~/.claude/settings.json. The status row and standalone readout cover Claude, Codex, and Agy quota. Everything above comes from one bootstrap run; re-running it keeps these files in sync with upstream.

After bootstrap, every Claude Code session shows recent Claude, Codex, and Agy quota at the bottom of the terminal. The row is compact enough to keep all three visible:

cc 5h82% (3h4m) 7d38% (2d17h) | gpt 7d75% (6d3h) @now | agy 5h100% (4h59m) 7d100% (6d23h) @now

cc is the Claude pool, from statusLine stdin. gpt is Codex, from recent ~/.codex/sessions/**/rollout-*.jsonl records. agy is the Gemini Models quota group returned by agy -p "/usage" --output-format json. Each percentage is quota remaining; the parenthesized value is time until reset, (reset) means the window rolled over and awaits a new reading, and @2m means the disk snapshot is two minutes old. The zero-turn Agy query runs from the home directory in a hidden, bounded background helper at most once per five minutes, so a status render never waits on the network or opens a project-scoped Agy workspace. The lock and failure cooldown prevent duplicate refreshes. To keep the status row compact, it shows only the default Gemini pool. The standalone agent-quota.py shows both Agy pools, including the separate Claude/GPT allowance usable through claude-sonnet-4-6, claude-opus-4-6-thinking, or gpt-oss-120b-medium.

Pick the Reviewer With /vet

Set IMPLEMENT_REVIEW_DEFAULT_CHANNEL=auto in your user-level Claude Code environment when CLI review should be the default. Then the reviewer token is the whole command:

Without the user-level Auto-terminal default, add the channel once: /vet auto agy. The Agy backend authenticates through the installed agy CLI and the Google AI plan attached to it; it does not require a separate Gemini API key. It reviews an isolated export of the staged Git index with accept-edits and unattended tool approval, so it can run real experiments while generated artifacts stay out of the source checkout. It publishes Review-Antigravity.md atomically. Override the model only when needed with ANTIGRAVITY_DISPATCH_MODEL; override effort with ANTIGRAVITY_DISPATCH_EFFORT.

/prun uses a different cost split: every unit runs on Agy, unattended in a scratch directory or throwaway clone with follow-up turns while slower units finish. It spawns no Claude subagents, because those bill the same Claude account the coordinating session runs on. Codex is deliberately excluded from bulk fan-out and reserved for /vet. Agy units use the same Gemini 3.8 Flash High / high default, and the coordinator chooses as many independent units as the task supports rather than imposing a two- or three-worker cap.

One AGENTS.md, Rules for Every Agent

Shared rules plus agent-specific blocks in one file; the generator emits one file per agent.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#fdf5f6', 'primaryBorderColor': '#8b2635', 'primaryTextColor': '#1a1a1a', 'lineColor': '#8b2635'}}}%%
flowchart LR
    A["<b>AGENTS.md</b><br/>shared rules<br/>+ &lt;!-- agent:claude --&gt;<br/>+ &lt;!-- agent:codex --&gt;"] -->|shared + claude blocks| B["<b>CLAUDE.md</b><br/>for Claude Code"]
    A -->|shared + codex blocks| C["<b>agents/codex.md</b><br/>for Codex"]
    A -.->|future: +1 tag| D(["other agent"])