https://github.com/yzhao062/anywhere-agents
One config to rule all your AI agents: portable (every project, every session), effective (curated writing, routing, skills), and safer (destructive-command guard).
https://github.com/yzhao062/anywhere-agents
agent-config agent-skills agents-md ai-agents ai-safety claude-code code-review codex dual-agent-review git-safety npm opinionated portable-config pypi safety-hooks shared-configuration skill-dispatch skill-router
Last synced: 17 days ago
JSON representation
One config to rule all your AI agents: portable (every project, every session), effective (curated writing, routing, skills), and safer (destructive-command guard).
- Host: GitHub
- URL: https://github.com/yzhao062/anywhere-agents
- Owner: yzhao062
- License: apache-2.0
- Created: 2026-04-16T17:44:59.000Z (27 days ago)
- Default Branch: main
- Last Pushed: 2026-04-23T06:22:54.000Z (21 days ago)
- Last Synced: 2026-04-23T10:35:05.029Z (21 days ago)
- Topics: agent-config, agent-skills, agents-md, ai-agents, ai-safety, claude-code, code-review, codex, dual-agent-review, git-safety, npm, opinionated, portable-config, pypi, safety-hooks, shared-configuration, skill-dispatch, skill-router
- Language: Python
- Homepage: https://anywhere-agents.readthedocs.io
- Size: 1.37 MB
- Stars: 141
- Watchers: 1
- Forks: 14
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
**English · [中文](README.zh-CN.md)**
# 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.
[](https://pypi.org/project/anywhere-agents/)
[](https://www.npmjs.com/package/anywhere-agents)
[](https://anywhere-agents.readthedocs.io/)
[](LICENSE)
[](https://github.com/yzhao062/anywhere-agents/actions/workflows/validate.yml)
[](https://github.com/yzhao062/anywhere-agents)
[Install](#install) •
[Why](#why-youd-use-this) •
[How it works](#how-it-works) •
[Pack CLI](#pack-management-cli) •
[Docs](https://anywhere-agents.readthedocs.io) •
[Fork](#fork-and-customize)
> [!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](https://yzhao062.github.io) — USC CS faculty and author of [PyOD](https://github.com/yzhao062/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, Copilot, 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.
**Coming next.** Private-source packs are the v0.5.0 milestone: your own skills or team conventions shipped as first-class packs, with version locks and authentication for fetches against private repos. Today you can fork and extend packs manually; private-source authoring ships next.
## 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`.
In v0.4.0, `bootstrap` installs the shipped defaults (`agent-style`, `aa-core-skills`) and any project-level selections from `agent-config.yaml` or `agent-config.local.yaml` when those files use the legacy `rule_packs:` key. It also accepts `AGENT_CONFIG_PACKS` as a transient name list.
The `anywhere-agents pack add | remove | list` CLI writes `packs:` to user-level config today; `bootstrap` starts consuming that user-level file, and the project-level `packs:` key, in v0.4.x. Private-source packs land in v0.5.0.
`bootstrap` is the sync step. Re-run it on any machine or repo, and `bootstrap` reproduces the shipped defaults plus the bootstrap-active project-level selections.
## 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 + 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
```text
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/` 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.
### One `AGENTS.md`, Rules for Every Agent
Shared rules plus agent-specific blocks in one file; the generator emits one file per agent.
```mermaid
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#fdf5f6', 'primaryBorderColor': '#8b2635', 'primaryTextColor': '#1a1a1a', 'lineColor': '#8b2635'}}}%%
flowchart LR
A["AGENTS.md
shared rules
+ <!-- agent:claude -->
+ <!-- agent:codex -->"] -->|shared + claude blocks| B["CLAUDE.md
for Claude Code"]
A -->|shared + codex blocks| C["agents/codex.md
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.
Without anywhere-agents
With anywhere-agents
> We delve into a pivotal realm — a multifaceted endeavor that underscores a paramount facet of outlier detection, paving the way for groundbreaking advances that will reimagine the trailblazing work of our predecessors.
32 words. Twelve banned-word or close-variant hits. Em-dash as casual punctuation. Every clause adds filler.
> We examine outlier detection along three dimensions: coverage, interpretability, and scale. Each matters; none alone is sufficient. Prior work has addressed one or two in isolation; this work integrates all three.
31 words. Zero banned words. Semicolons and colons instead of em-dashes. One idea per sentence.
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
```text
[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.
```bash
# Python (zero-install with pipx)
pipx run anywhere-agents
# Node.js (zero-install with Node 14+)
npx anywhere-agents
```
### 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):
```bash
# 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.
Raw Shell (No Package Manager Required)
macOS / Linux:
```bash
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
```
Windows (PowerShell):
```powershell
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](https://pypi.org/project/anywhere-agents/) · [npm](https://www.npmjs.com/package/anywhere-agents) · [bootstrap scripts](https://github.com/yzhao062/anywhere-agents/tree/main/bootstrap)
## Pack Management CLI
Install the `anywhere-agents` CLI (via `pipx install anywhere-agents` or `pip install`) to manage packs without editing per-project YAML.
```bash
anywhere-agents pack list
anywhere-agents pack add aa-core-skills --ref v0.4.0
anywhere-agents pack remove aa-core-skills
anywhere-agents uninstall --all # clean everything from the current project
```
The CLI writes to `$XDG_CONFIG_HOME/anywhere-agents/config.yaml` (POSIX) or `%APPDATA%\anywhere-agents\config.yaml` (Windows).
**v0.4.0 boundary.** For pack selections that must affect `bootstrap` today, use the legacy `rule_packs:` key in `agent-config.yaml` or `agent-config.local.yaml`, or pass names through `AGENT_CONFIG_PACKS`. The `anywhere-agents pack` CLI writes user-level `packs:` config now; bootstrap starts reading that user-level file and the project-level `packs:` key in v0.4.x.
For the legacy rule-pack composition contract that still backs project-level `rule_packs:` in v0.4.0, including cache, offline behavior, and failure modes, see [`docs/rule-pack-composition.md`](docs/rule-pack-composition.md).
## What's Next
`v0.4.0` ships the pack runtime (state files, cross-platform locks, recoverable transactions) and the pack CLI. `v0.4.x` wires the composer to acquire those locks and to reconcile installed packs against the manifest on every session start. `v0.5.0` adds private-source packs: fetch packs from private repos with the standard Git authentication you already have configured (SSH key, `gh auth login`, or `GITHUB_TOKEN`). Shipped-status details live in the [changelog](CHANGELOG.md).
Want to author your own pack? See [`yzhao062/agent-pack`](https://github.com/yzhao062/agent-pack), a public reference repo that declares three packs (two passive, one active) using the v2 manifest schema. Fork it, replace the content with your own profile and skills, tag a release, then follow its Consumer Setup split: copy passive bodies or register pack names in a controlled bootstrap manifest for v0.4.0; use `anywhere-agents pack add --ref ` once v0.5.0 remote fetch lands.
## Deeper Docs
Full reference lives at **[anywhere-agents.readthedocs.io](https://anywhere-agents.readthedocs.io)**:
- Per-skill deep documentation (`implement-review`, `my-router`, `ci-mockup-figure`, `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//`, `skills/my-router/references/routing-table.md`.
3. **Point consumers at your fork.** Pass your upstream as the bootstrap argv on first install:
```bash
# Bash (macOS / Linux / Git Bash)
curl -sfL https://raw.githubusercontent.com///main/bootstrap/bootstrap.sh -o .agent-config/bootstrap.sh
bash .agent-config/bootstrap.sh /
```
```powershell
# PowerShell (Windows)
Invoke-WebRequest -UseBasicParsing -Uri https://raw.githubusercontent.com///main/bootstrap/bootstrap.ps1 -OutFile .agent-config/bootstrap.ps1
& .\.agent-config\bootstrap.ps1 /
```
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:**
```bash
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.
What Is Opinionated and Why
| Opinion | Why |
|---------|-----|
| **Safety-first by default** | `git commit` / `push` always confirm. Destructive Git/GitHub (ask) and compound-command shapes (deny) have no bypass; writing-style and banner gates have an `AGENT_CONFIG_GATES=off` escape hatch for false positives. |
| **Dual-agent review is default** | Claude Code implements; Codex reviews. Either solo still works; the second opinion is where the value is. Includes an optional Phase 0 plan-review for complex work where the shape precedes the code. |
| **Strong writing style** | ~45 banned words (enforced by PreToolUse hook on `.md` / `.tex` / `.rst` / `.txt` writes), no em-dashes as casual punctuation, no bullet-conversion of prose, no summary sentence at the end of every paragraph. Sound like you, not a chatbot. |
| **Session checks report, not fix** | Flags outdated Actions versions, wrong Codex config, model preferences — agents never silently change anything without telling you. |
Disagree with any of this? Fork it and edit.
Repo Layout
```text
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
│ ├── compose_packs.py # v0.4.0 composer: reads manifest, dispatches passive + active kinds
│ ├── compose_rule_packs.py # legacy v0.3 rule-pack composer (kept for BC)
│ ├── packs/ # v0.4.0 primitives: config, state, locks, transaction, kind 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
│ └── 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
```
Related Projects
**Same family.** `anywhere-agents` ships alongside two companion public repos:
- [`agent-style`](https://github.com/yzhao062/agent-style): the writing-rule pack composed into every consumer's `AGENTS.md` by default. 21 rules (12 classic + 9 LLM-observed) with BAD -> GOOD examples per rule.
- [`agent-pack`](https://github.com/yzhao062/agent-pack): public reference example for third-party pack authors. Declares 3 packs (passive profile, passive paper-workflow, active academic skills) in the v2 manifest format. Fork as a starting point for your own pack repo.
**Different approaches.** If you want a general-purpose multi-agent sync tool or a broader skill catalog, these take different routes:
- [iannuttall/dotagents](https://github.com/iannuttall/dotagents) — central location for hooks, commands, skills, AGENTS/CLAUDE.md files
- [microsoft/agentrc](https://github.com/microsoft/agentrc) — repo-ready-for-AI tooling
- [agentfiles on PyPI](https://pypi.org/project/agentfiles/) — CLI that syncs configurations across multiple agents
`anywhere-agents` is intentionally narrower: a published, maintained, opinionated configuration, not a tool that manages configurations. Fork it if you like the setup; use one of the tools above if you want a universal manager.
What This Is Not
- Not a general-purpose framework or plugin host. The `anywhere-agents` CLI is narrow: it bootstraps a project (zero-install via `pipx run` / `npx`) and manages user-level pack selections (`pack add | remove | list | uninstall`). Nothing more.
- Not a universal multi-agent sync tool. Claude Code + Codex is the supported set. Other agents (Cursor, Aider, Gemini CLI) may work via the `AGENTS.md` convention but are not tested here.
- Not a marketplace or registry. One curated configuration, two first-party packs (`agent-style`, `aa-core-skills`), one maintainer. Third-party packs from arbitrary sources land in v0.5.0.
Limitations and Caveats
- Requires `git` everywhere. Requires Python (stdlib only) for settings merge; bootstrap continues without merge if Python is unavailable.
- Guard hook deploys to `~/.claude/hooks/guard.py` and modifies `~/.claude/settings.json`. To opt out of user-level modifications, remove the user-level section from `bootstrap/bootstrap.sh` / `bootstrap/bootstrap.ps1` in your fork.
- `AGENT_CONFIG_GATES=off` in the `env` block of `~/.claude/settings.json` disables only the writing-style and banner gates. Destructive Git/GitHub and compound-command guards stay active.
Maintenance and Support
- **Maintained:** the author's daily-use workflow. Changes land when the author needs them.
- **Not maintained:** feature requests that do not match the author's work. Users should fork.
- **Best-effort:** bug reports, PRs for clear fixes, documentation improvements.
See [CONTRIBUTING.md](CONTRIBUTING.md) for how to propose changes.
## License
Apache 2.0. See [LICENSE](LICENSE).