yzhao062/anywhere-agents

[!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, a skill that hands your staged diff to a second reviewer (Codex, GitHub Copilot, headless Claude Code, or whichever you configure), converges on feedback, and revises. Without it, you wire reviewer APIs 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 five skills: ci-mockup-figure, implement-review, my-router, prun, and readme-polish) 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/, statusline.py into ~/.claude/statusline.py (Claude Max + Codex 5h / weekly quota readout in the Claude Code status row), and merges shared keys into ~/.claude/settings.json. Everything above comes from one bootstrap run; re-running it keeps these files in sync with upstream.

After bootstrap, every Claude Code session shows your live Claude Max + Codex quota at the bottom of the terminal — no API key, no polling, no extra setup:

🤖 Opus 4.8 · 5h 78% (3h 4m) · 7d 51% (15h 4m)  |  Codex 5h 89% (3h 25m) · 7d 90% (4d 23h)

The Claude side reads from the statusLine stdin (Claude Code v2.1.80+ injects rate_limits for Pro/Max subscribers). The Codex side tails the most recent ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl. Windows that already reset are flagged (stale); missing data renders as —.

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"])

Add a new agent tomorrow and only the tag name changes. scripts/generate_agent_configs.py runs every bootstrap; the shared content stays in lock-step across agents because it lives in one source file.

Writing That Does Not Read Like an AI

Default AI output leans on a small set of filler words and em-dash rhythm. The agent-style rule pack is a ban list plus formatting rules; the PreToolUse guard enforces the ban at write-time on .md / .tex / .rst / .txt files.

The guard denies the Write / Edit tool call outright when the outgoing content contains a banned word. The agent sees the deny message with the hit list and revises before any file changes.

git push Is Never a Silent Action

[guard.py] ⛔ STOP! HAMMER TIME!

  command:   git push --force origin main
  category:  destructive push

This is destructive. Are you sure? (y/N)

The guard covers git push, git commit, git merge, git rebase, git reset --hard, gh pr merge, gh pr create, and related destructive commands. Read-only operations (status, diff, log) pass silently, so the common workflow stays fast.

Install

[!TIP] The simplest install is to tell your AI agent: "Install anywhere-agents in this project." It will pick the right command from PyPI or npm.

Recommended:

# One-time per machine:
pipx install anywhere-agents     # or: uv tool install anywhere-agents

# Per-project (run in any repo):
anywhere-agents                          # bootstrap shared config + hooks + settings
anywhere-agents pack add <pack-repo-url>  # add a pack (one-shot: fetch, install, deploy)

Choosing an install path:

All paths run bootstrap. For pack add | remove | verify | list | update, install the Python CLI via pipx install anywhere-agents. The npm package is bootstrap-only; if you need pack commands, install the Python CLI separately on the same machine.

Why pipx and not plain pip install? anywhere-agents is a CLI tool with its own dependencies. Plain pip install either lands in the active venv (per-project, not per-machine) or hits PEP 668 / externally-managed-environment errors on modern Ubuntu / Debian / Homebrew Python. pipx gives each CLI tool its own isolated venv and exposes the binary on PATH globally; it is clean to upgrade, clean to remove, and avoids dependency conflicts. It is the PyPA-recommended approach for Python CLI applications.

How to Update

For Claude Code, updates are automatic. anywhere-agents installs a SessionStart hook that runs bootstrap every time you open a Claude Code session, so the shared AGENTS.md, skills, and settings stay fresh with no typing.

For Codex or other agents (no SessionStart hook support today), tell the agent in your first message of a session:

read @AGENTS.md to run bootstrap, session checks, and task routing

This triggers the agent to read the bootstrap block in AGENTS.md and execute it. Same effect as the hook, one verbal invocation per session.

To force a refresh mid-session (for example, when the maintainer just pushed a fix you need right now):

# macOS / Linux
bash .agent-config/bootstrap.sh

# Windows (PowerShell)
& .\.agent-config\bootstrap.ps1

To pin to a specific version, fork the repo and check out a tag in your fork, then point consumers at your fork instead of the main branch.

mkdir -p .agent-config
curl -sfL https://raw.githubusercontent.com/yzhao062/anywhere-agents/main/bootstrap/bootstrap.sh -o .agent-config/bootstrap.sh
bash .agent-config/bootstrap.sh

New-Item -ItemType Directory -Force -Path .agent-config | Out-Null
Invoke-WebRequest -UseBasicParsing -Uri https://raw.githubusercontent.com/yzhao062/anywhere-agents/main/bootstrap/bootstrap.ps1 -OutFile .agent-config/bootstrap.ps1
& .\.agent-config\bootstrap.ps1

Source: PyPI · npm · bootstrap scripts

Pack Management CLI

Install the anywhere-agents CLI (via pipx install anywhere-agents) to manage packs without editing per-project YAML.

anywhere-agents                              # canonical apply: bootstrap + deploy + drift + generator
anywhere-agents pack list
anywhere-agents pack add https://github.com/yzhao062/agent-pack --ref v0.1.0
anywhere-agents pack list --drift             # read-only audit against pack-lock.json
anywhere-agents pack remove profile
anywhere-agents uninstall --all               # clean everything from the current project

pack add <url> reads the remote pack.yaml and writes one user-level row per declared pack (e.g., agent-pack expands to profile, paper-workflow, acad-skills). --ref is optional and defaults to main; pin a tag for production. The CLI writes to $XDG_CONFIG_HOME/anywhere-agents/config.yaml (POSIX) or %APPDATA%\anywhere-agents\config.yaml (Windows).

Audit Pack Deployment

Since v0.5.2, pack add is one-shot: it writes user-level config rows and runs the composer to deploy into the current project in a single command. Use pack verify to audit existing state without writing:

anywhere-agents pack verify              # read-only audit (user, project, lock)

To reconcile drift, run bare anywhere-agents — the canonical apply path applies prompt-policy drift on mutable refs and prints one stderr summary line per affected pack. Per-run skip: ANYWHERE_AGENTS_UPDATE=skip env var or --no-apply-drift CLI flag.

Legacy aliases (still supported through all v0.x). The v0.5.x commands anywhere-agents pack verify --fix [--yes] and anywhere-agents pack update [<name>] continue to work and execute the canonical apply path; each prints a one-line stderr notice pointing at anywhere-agents. CI scripts that use these forms keep working without changes. Removal is allowed only at v1.0 with explicit CI-migration guidance.

Migrating from a project that bootstrapped from agent-config? Run bare anywhere-agents (or bash .agent-config/bootstrap.sh directly). The CLI auto-detects the legacy yzhao062/agent-config upstream from .agent-config/upstream or the cached .git/config, deletes the legacy cache, and bootstraps from anywhere-agents. The detection lives in both the Python CLI and the raw shell scripts, so any entry path triggers the migration once.

Then bring back the User Profile, paper workflow, and 4 academic-writing skills (bibref-filler, bibref-verify, dual-pass-workflow, figure-prompt-builder) that previously lived in agent-config by adding agent-pack:

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

This expands to three user-level rows (profile, paper-workflow, acad-skills) and deploys all three in a single command.

For projects that prefer to declare packs in agent-config.yaml instead of using pack add:

rule_packs:
  - name: profile
    source: {url: https://github.com/yzhao062/agent-pack, ref: v0.1.0}
  - name: paper-workflow
    source: {url: https://github.com/yzhao062/agent-pack, ref: v0.1.0}
  - name: acad-skills
    source: {url: https://github.com/yzhao062/agent-pack, ref: v0.1.0}

Bare anywhere-agents applies them and prints a stderr summary line per affected pack.

For the rule-pack composition contract that backs project-level rule_packs:, including cache, offline behavior, and failure modes, see docs/rule-pack-composition.md.

What's Next

v0.5.0 shipped direct-URL pack fetch with the 4-method auth chain (SSH agent, gh CLI token, GITHUB_TOKEN, anonymous fallback), the trust-model shift to prompt as default update_policy, and the pack update + pack list --drift CLI commands. v0.5.2 ships end-to-end pack management: pack add is one-shot install (writes user-level rows, runs composer, deploys), and the AC→AA migration is automatic. v0.6.0 collapses the day-to-day update flow into a single verb: bare anywhere-agents is the canonical apply path; pack verify --fix and pack update survive as compatibility aliases through all v0.x; prompt-policy drift on mutable refs applies inline by default with stderr summary lines and per-run skip via ANYWHERE_AGENTS_UPDATE=skip or --no-apply-drift. update_policy: auto on active entries is rejected at parse with an actionable error. v0.7.x moves publishing to OIDC Trusted Publishing: gh release create <tag> triggers publish.yml, which builds and publishes to PyPI and npm; manual twine upload / npm publish is fallback only. v0.7.7 registers prun in aa-core-skills: Opus coordinates parallel Codex and Sonnet worker units, workers never commit or push, code-writing units run in a throwaway clone, and Opus plus the user remain the integration gate. Shipped-status details live in the changelog.

The agent-pack reference repo is the canonical blueprint for any pack you author: profile, paper workflow conventions, team conventions, custom skills, anything you want to share across projects. The v2 manifest schema lives there in working form. Fork ap, replace its three packs (profile, paper-workflow, acad-skills) with your content, tag a release, then anywhere-agents pack add https://github.com/<you>/<your-pack> --ref <tag>. Since v0.5.2, this is one-shot: the CLI writes user-level config rows and runs the composer to deploy in a single command.

Deeper Docs

Full reference lives at anywhere-agents.readthedocs.io:

• Per-skill deep documentation (implement-review, my-router, ci-mockup-figure, prun, readme-polish)
• AGENTS.md section-by-section reference
• Customization guide (fork, override, extend)
• FAQ, troubleshooting, platform notes (Windows, macOS, Linux)

Fork and Customize

Want to diverge — change writing defaults, add skills, swap the reviewer? Standard Git, no special tooling.

1. Fork yzhao062/anywhere-agents to your GitHub account.

2. Edit: AGENTS.md, skills/<your-skill>/, skills/my-router/references/routing-table.md.

3. Point consumers at your fork. Pass your upstream as the bootstrap argv on first install:

   # Bash (macOS / Linux / Git Bash)
   curl -sfL https://raw.githubusercontent.com/<your-user>/<your-repo>/main/bootstrap/bootstrap.sh -o .agent-config/bootstrap.sh
   bash .agent-config/bootstrap.sh <your-user>/<your-repo>
   

   # PowerShell (Windows)
   Invoke-WebRequest -UseBasicParsing -Uri https://raw.githubusercontent.com/<your-user>/<your-repo>/main/bootstrap/bootstrap.ps1 -OutFile .agent-config/bootstrap.ps1
   & .\.agent-config\bootstrap.ps1 <your-user>/<your-repo>
   

   Whichever value you pass (argv or AGENT_CONFIG_UPSTREAM env var) is persisted to .agent-config/upstream on that run, so later session-hook invocations pick it up automatically; you only pass it once per consumer project. Setting the env var on a later run updates the persisted value, so the env var can both seed and change the long-term upstream.

4. Pull upstream updates when you want them:

   git remote add upstream https://github.com/yzhao062/anywhere-agents.git
   git fetch upstream
   git merge upstream/main   # resolve conflicts as usual
   

Git is the subscription engine. Cherry-pick what you want, skip what you do not.

anywhere-agents/
├── AGENTS.md                      # central source: tagged rule file (curated defaults)
├── CLAUDE.md                      # generated from AGENTS.md (Claude Code)
├── agents/
│   └── codex.md                   # generated from AGENTS.md (Codex)
├── bootstrap/
│   ├── bootstrap.sh               # idempotent sync for macOS/Linux
│   ├── bootstrap.ps1              # idempotent sync for Windows
│   └── packs.yaml                 # v2 unified manifest: passive + active packs (agent-style, aa-core-skills)
├── scripts/
│   ├── guard.py                   # PreToolUse hook: 4 gate families (dest-git/gh ask; compound cd / writing-style / banner deny)
│   ├── generate_agent_configs.py  # tag-based generator (AGENTS.md -> CLAUDE.md + codex.md)
│   ├── session_bootstrap.py       # SessionStart hook: runs bootstrap automatically
│   ├── statusline.py              # statusLine renderer: Claude Max + Codex 5h / weekly quota
│   ├── compose_packs.py           # v2 composer: bundled packs, direct URLs, drift prompt, locks, state
│   ├── compose_rule_packs.py      # legacy v0.3 rule-pack composer (kept for BC)
│   ├── packs/                     # pack modules: auth, config, source fetch, state, locks, transaction, handlers
│   ├── pre-push-smoke.sh          # pre-push real-agent smoke (validates current checkout)
│   └── remote-smoke.sh            # post-publish real-agent smoke (validates published install)
├── skills/
│   ├── ci-mockup-figure/          # HTML mockups + TikZ/skia-canvas for figures
│   ├── implement-review/          # dual-agent review loop with Phase 0 plan-review (signature skill)
│   ├── my-router/                 # context-aware skill dispatcher
│   ├── prun/                      # parallel delegation fan-out across Codex/Sonnet workers
│   └── readme-polish/             # audit + rewrite GitHub READMEs with modern patterns
├── packages/
│   ├── pypi/                      # anywhere-agents PyPI CLI (pipx run anywhere-agents)
│   └── npm/                       # anywhere-agents npm CLI (npx anywhere-agents)
├── .claude/
│   ├── commands/                  # pointer files so Claude Code discovers the skills
│   └── settings.json              # project-level permissions
├── user/
│   └── settings.json              # user-level permissions, PreToolUse + SessionStart hooks, CLAUDE_CODE_EFFORT_LEVEL=max
├── docs/                          # Read the Docs source + README hero assets
├── tests/                         # bootstrap / guard / generator / session-bootstrap tests (Ubuntu + Windows + macOS CI, Python 3.9-3.13)
├── .github/workflows/             # validate, real-agent-smoke, package-smoke CI
├── .githooks/
│   └── pre-push                   # opt-in pre-push smoke (enable via `git config core.hooksPath .githooks`)
├── CHANGELOG.md
├── CONTRIBUTING.md
├── RELEASING.md
├── LICENSE
├── mkdocs.yml                     # Read the Docs config
└── .readthedocs.yaml

License

Apache 2.0. See LICENSE.