dotagents

Like dotfiles, but for AI coding agents: a portable, token-budgeted ~/.agents configuration that works across agent runners (Claude Code, Antigravity, Copilot, Codex, pi, ...). dotagents is the mechanism — install a neutral base, then layer in opt-in overlays that carry your standards (repo structure, CI/release discipline, whatever workflows you want) — so you record them once instead of restating them every session.

Design

• Core + load-on-demand routing. AGENTS.md is the only always-loaded file: a handful of always-on rules plus a routing table. Task-specific detail lives in flows/ and kb/ files that an agent reads only when the task matches. You pay for what you use.
• A neutral base + opt-in overlays. init lays down a minimal, opinion-free base overlay (just the AGENTS.md scaffolding + design-log convention). Everything opinionated — workflows, language kb/ files, repo templates, tools — lives in composable overlays you layer in explicitly (dotagents overlays add <name>), each contributing its own routing lines, rules, skills, and commands. Additive-only: overlays never overwrite something you've already customized.
• Overlays carry the opinions, not the tool. dotagents is the mechanism (install, compose, discover); what your agents should do is an overlay concern. The example overlays in this repo are a starting point — a planning/execution/review workflow set, language conventions, a release helper — but they're payloads riding on dotagents, swappable for your own. See the docs for what each ships.

Layout

The config is a base overlay plus opt-in overlays; the dotagents CLI applies them. Everything else is repo infrastructure.

The example overlays — the flows workflow set, per-language kb/ + templates, references, release, private-sync, net, recovery, tools — live on a separate overlays branch, not in main's tree: they are swappable payloads, not part of the tool. dotagents overlays add <name> resolves them from there (or from any --repo). See the docs for what each ships.

Named-agent directives aren't a shipped overlay — a named agent (Claude, Antigravity, …) just reads its own ~/.agents/<agent>.md on top of the shared AGENTS.md, which the base overlay's routing already states. This config's own design log lives privately under its untracked .agents/dotagents/ (DECISIONS.md + one file per decision) — like every project, .agents/ is never tracked or pushed.

Each overlay's <name>/overlay.toml carries a name/description/requires/routing manifest read by the dotagents overlays subcommand, which manages overlays by name (add/remove/list/sync) — see Managing overlays below.

Install

pip install dotagents-cli   # gives you `import dotagents` and the `dotagents` command

Or skip pip entirely with the self-contained downloadable .pyz (see below).

dotagents init lays down the neutral base config.

init writes the .agents/ scaffolding — the AGENTS.md managed block, the per-agent <CLAUDE|ANTIGRAVITY|...>.md → @AGENTS.md pattern, the design-log convention — and wires each supporting agent's hooks so dotagents context reaches it automatically at session start (--no-hooks opts out) — but imposes no opinions (those come from overlays add). Its AGENTS.md/CLAUDE.md are a marker-delimited managed block, so re-running init never clobbers what you've added around it. Scope: project by default (<cwd>/.agents), or the user store with -g/--global (~/.agents).

dotagents init                          # project: <cwd>/.agents
dotagents init -g                       # user store: ~/.agents
dotagents init --bin-dir ~/.local/bin   # also write a `dotagents` command on PATH
dotagents init --dry-run                # show what would happen
dotagents init --force                  # replace AGENTS.md/CLAUDE.md wholesale (backed up)

--from <path-or-uri> selects the base source for a pip install-only environment (a git checkout dir, file:, http(s):, zip:, sftp:, or s3: URI via pip install "dotagents-cli[uri]"); init's base ships inside the package, so it needs no --from.

Overlays beyond the base are managed by name with dotagents overlays add <name> — it installs into <scope>/.agents/overlays/<name>/ (discoverable) and publishes the overlay's skills into the shared skills dir. See below.

Managing overlays

dotagents overlays manages opt-in overlays by name, resolving each name against repos in order — the first that offers the name wins. A repo is always a collection of overlays: a directory (each subdirectory an overlay, e.g. a checkout of the overlays branch) or a JSON/TOML/YAML registry file mapping names to sources. It lives at a local path, an http(s):// URL (a registry file, fetched), or inside a git repository named <repo>[@<branch|tag|commit>][#<path>], where the path picks the directory or registry file in the checkout (no path: the checkout root). A source names one overlay: a local directory, or a git spec whose path is the overlay's root directory (no path: the repository root is the overlay); a relative path is relative to the registry file, and inside a git checkout stays in the same repository at the same ref. Name repos with --repo, $AGENTS_OVERLAYS_REPO_<KEY> / $AGENTS_OVERLAYS_REPO, or a dotagents.{json,toml,yaml} in the project or user store. Installed overlays are discovered by their presence under <scope>/.agents/overlays/.

dotagents overlays add python engineering  # install into the scope, publish skills, merge D59 rules/routing
dotagents overlays list                    # installed (discovered) + available (from source)
dotagents overlays sync 'py*'              # refresh installed overlays matching a glob, resync their skills
dotagents overlays remove python           # delete the overlay dir + unpublish its skills

Scope is project by default (<project>/.agents/, when run inside one) or user with -g/--global (~/.agents/, the configurable store). Each overlay installs as a directory (kept, discoverable), its routing/rules merge additively into AGENTS.md's managed block, and its skills/<name>/ are symlinked (or --copy'd, for Windows / no-symlink) into the shared <scope>/.agents/skills/ so every agent sees the same skills. add/sync are additive and never clobber a file you hand-edited inside an installed overlay. Removing an overlay deletes only its dir and unpublishes only the skills it published; its lines in AGENTS.md's managed block are not auto-pruned (a warning points at the manual edit, or re-run install).

Overlay setup scripts. An overlay may ship an idempotent setup.py at its root (the recommended form: it runs under the same Python that runs dotagents, so it works on every OS). After add/sync copies the overlay in, dotagents runs the script automatically — so anything a human would otherwise hand-follow (PATH/lib wiring, self-registration) is one script the tool runs, not a doc. When both are present, setup.py wins. Presence of a script is the opt-in; skip it with --no-setup. The contract for authors:

• Idempotent — safe to run on every add/sync; check-then-act, never blindly append.
• cwd is the installed overlay dir (<scope>/.agents/overlays/<name>/), so reference your own files by relative path.
• Env carries AGENTS_HOME (the resolved store path — never hardcode ~/.agents) and AGENTS_OVERLAY_DIR (your own installed dir).
• A non-zero exit fails the install with a clear error (not a silent skip). For any outward or irreversible action the script must confirm first — the runner invokes a script you chose to install; it does not second-guess it.

Downloadable dotagents.pyz — a self-contained zipapp with duho/ pathlib_next and the required tools/ bundled in, so it needs no pip install:

python -m dotagents build-pyz --out dist/dotagents.pyz   # build it (needs this repo checkout)
python dist/dotagents.pyz init --bin-dir ~/.local/bin    # lay down the base + a `dotagents` command, offline

Then wire your runner to it — e.g. Claude Code: put @AGENTS.md in ~/.claude/CLAUDE.md... which is exactly what the installed CLAUDE.md contains.

Or let your agent do it: point it at this repo and say —

Read README.md, run python install.py init && python install.py overlays add engineering -g, and confirm ~/.agents/overlays/flows/flows/PLAN.md exists.

Validate

python tools/audit.py --root .                  # validate THIS REPO's layout (CI tooling)
python tools/audit.py --check-templates --root .  # + template checks (needs 3.11+)

Customize

Fork it — that's the point. Keep the base AGENTS.md small (the audit warns past ~2.5KB); put opinionated content in overlays. Your ~/.agents/dotagents/DECISIONS.md is your private, per-install design log (index + decisions/ files) — installed empty, edited directly, never distributed. This repo follows the same rule: its own design log and all working material live in an untracked .agents/dotagents/, never committed — so what's public here is only the CLI, the base overlay, and the opt-in overlays. If you fork, keep the tracked surface free of personal paths and private project names. dotagents audit validates config structure only; personal-leak scanning (machine paths, private plan names, session trailers) is a separate, personal tool you run locally before a push — it lives in your private .agents/, not shipped in this repo.

Documentation

Full docs — install modes, the overlay model, the CLI command surface, private sync, authoring your own overlays and commands, and the API reference — are at jose-pr.github.io/dotagents.

License

MIT — see LICENSE.