Skip to main content

dotagents

Test PyPI Documentation License: MIT

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 managed block). 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.

Path What
src/dotagents/ The installable dotagents CLI (init/overlays/context/env/build-pyz/about, plus the bundled findings/launch) — that is the whole shipped surface; commands beyond it come from overlays or your own dotagents/cmds/ modules
src/dotagents/_overlay/ The base overlay: the AGENTS.md block template init renders into the store (no dotagents/ dir, no design log), the two bundled commands (findings, launch), and the hook scripts init deploys into an agent's config dir. Neutral — imposes no flows
tools/ Repo tooling, not shipped: audit.py (CI structure check), pyz_smoke.sh (the .pyz smoke test) and cloud-setup.sh. Personal scanning tools are not here either — keep them as command modules in your own private .agents/dotagents/cmds/
install.py Thin shim over dotagents.cli.main() for a source checkout; installs the checkout's dependencies into the virtual environment running it (--bootstrap to allow another interpreter)

The example overlays — engineering (the planning/execution/review workflow set, its rules, repo templates and helper tools), the per-language python / node / rust, release, private-sync, net and recovery — live on a separate repo branch, not in main's tree: they are swappable payloads, not part of the tool. Name that branch as a repo (--repo, see below) to install them. See the docs for what each ships.

This repo's own working material (decisions, findings, plans) lives privately in its untracked .agents/ — like every project, .agents/ is never tracked or pushed.

Overlays follow the Agent Overlay Specification (AOS): each may carry an overlay.cfg manifest (name/description/requires/routing, and what it needs that is not a default: environment, path additions, setup, runtime), read by the dotagents overlays subcommand, which manages overlays by name (add/remove/list/sync/show) — 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).

Quick start

dotagents init -g   # the base config in ~/.agents, plus the Claude Code include and hooks
export AGENTS_OVERLAYS_REPO="https://github.com/jose-pr/dotagents.git@repo#overlays"
dotagents overlays add engineering python -g   # cloned with git, so git must be on PATH
dotagents overlays list -g
ls ~/.agents/overlays/engineering/flows/PLAN.md

AGENTS_OVERLAYS_REPO names where overlays come from; set it in your shell profile, or pass --repo <spec> to each overlays command instead. CI runs this block as written.

dotagents init

init lays down the neutral base config. It writes the store's AGENTS.md managed block, points Claude Code at it (an include in ~/.claude/CLAUDE.md for the user store, <project>/.claude/CLAUDE.md for a project), and wires each supporting agent's hooks so dotagents env and dotagents context reach it at session start (--no-hooks opts out) — but imposes no opinions (those come from overlays add). The block is marker-delimited, so re-running init never clobbers what you've added around it. Scope: the user store with -g/--global (~/.agents, or $AGENTS_HOME); without it, the current directory's .agents — run it from the project root. When a session has pinned $AGENTS_PROJECT_ROOT (or $CLAUDE_PROJECT_DIR) and you are inside that directory, the pinned root is used; outside it, the nearest directory up with a .git or its own .agents, with a warning.

dotagents init                          # project: ./.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's content wholesale (backed up)

--from <source> selects another base: a base overlay directory, a dotagents checkout (its src/dotagents/_overlay), a file:, http(s):, zip:, sftp: or s3: URI (pip install "dotagents-cli[uri]" for all but file:, plus [sftp] or [s3] for those schemes), or a git repository (repo[@ref][#path]). A remote one is fetched into <user store>/.cache/overlays/. The bundled base ships inside the package, so --from is only for a base of your own. init records it (without any credentials in the URL), and later init and overlays runs compose over it.

init wires Claude Code plus any harness it is running inside (detected from its environment); --agents a,b replaces that set, so include claude to keep it.

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

Managing overlays

dotagents overlays manages opt-in overlays by name. add resolves 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 repo branch, whose overlays sit under overlays/<name>) 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 <store>/overlays/, and each records the repo it was installed from.

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

Scope is project by default (the current directory's .agents/, resolved as for init) or user with -g/--global (~/.agents/, the configurable store). Each overlay installs as a directory (kept, discoverable), what its manifest requires is installed first, its routing/rules merge into AGENTS.md's managed block, and its skills/<name>/ are symlinked (or --copy'd, for Windows / no-symlink) into the store's shared skills/ so every agent sees the same skills.

  • add and sync keep an installed overlay exactly as its source ships it: changed files are replaced and everything else is removed (tool caches and setup output included), anything edited there backed up under <store>/install_backup/ first, so the copy keeps the overlay's AOS tree digest. A source is refused before anything is written when its manifest does not validate, this machine lacks what its runtime needs, or the store pins it to another digest. A fresh add whose preparation (dependencies, then setup) fails is rolled back.
  • An overlay's packages install by default: lib/python/requirements.txt (a lock when every requirement has a --hash) and lib/node/package.json (locked by the package-lock.json beside it), on add and every sync, before setup. They go into the store's shared environment, a named one, or the overlay's own ([[runtime.python]] environment = "isolated"); two overlays pinning one package to two versions in one environment are both refused, naming the package. [defaults] deps = false turns this off.
  • Each store has a Python venv, <store>/.pyvenv/<version>-<os>-<arch>/, where skills run ($AGENTS_PYTHON): duho, the store's shared Python environment and every agent lib/ import there, layered project > user > system. pip comes from the interpreter, else its pinned wheel (cache, AGENTS_PIP_SOURCE, your index mirror, or a .pyz built --with-pip).
  • sync refreshes each overlay from the repo it was installed from (--repo replaces that source), installs a requires added upstream, and re-merges the managed block.
  • remove deletes the overlay's directory, unpublishes only the skills it published, and recomposes AGENTS.md's managed block over the overlays that remain, so its rules and routing leave with it. It refuses an overlay another installed overlay requires, unless --force.
  • list and show flag a requires no installed overlay provides; show names the repo an installed overlay came from.

Overlay setup. An overlay is activated only for the digest its last preparation (dependencies, then setup) succeeded for on this machine; overlays sync prepares it. An overlay's setup is the [[setup]] variant its overlay.cfg declares for this OS (interpreter, args, timeout, network), else one setup.<ext> at its root, the first this machine can run (.py, .js, .mjs, .cjs, then .ps1 on Windows, .bash, .sh elsewhere), taken to need the network. dotagents runs it after add/sync copies the overlay in and before remove deletes it, telling it the phase as its first argument and $AOS_SETUP_PHASE: install the first time, sync on every add or sync after that, remove on removal. --no-setup skips it. The contract for authors:

  • Idempotent, and a phase it does not know is success with nothing to do (exit 0).
  • An install or sync that fails keeps the overlay from being activated until a setup succeeds; a remove that fails is reported and the removal goes ahead.
  • cwd is the installed overlay root; write only into $AOS_OVERLAY_STATE, a directory outside the root, kept across syncs and deleted on removal, that sessions see as $<NAME>_OVERLAY_STATE.
  • Env is your environment, every overlay's root variable, the overlay's own declarations, AOS_OVERLAY_ROOT / AOS_OVERLAY_NAME / AOS_OVERLAY_STATE, and AGENTS_HOME (the user store — never hardcode ~/.agents), AGENTS_SCOPE_ROOT, AGENTS_SCOPE.
  • A non-zero exit or the timeout fails the install with a clear error, and everything the step started is stopped with it.

Downloadable dotagents.pyz

A self-contained zipapp with duho, pathapi and tomli bundled in (pure Python, so one file runs on any OS and on Python 3.9+), so it needs no pip install. Each release attaches one: https://github.com/jose-pr/dotagents/releases/latest/download/dotagents.pyz.

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

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

Read README.md, install dotagents-cli (into a virtual environment, or with pipx), run the Quick start block, and confirm ~/.agents/overlays/engineering/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. dotagents installs no design log: a config miss is a finding — dotagents findings add -g for the user store (~/.agents/findings/), no -g for a project (<project>/.agents/findings/) — and triage closes each with its resolution, which is the record. How you keep any decisions beyond that is up to you. A store's dotagents/ directory exists only for your own command modules (dotagents/cmds/), which you create when you add your first one, and for dotagents/config.toml, which records an init --from base and, if you set it, git_ssl_revoke (how git checks certificate revocation on Windows). This repo follows the same rule: its working material lives in an untracked .agents/, 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. tools/audit.py validates this repo's structure only; personal-leak scanning (machine paths, private plan names, session trailers) is a separate, personal tool you run locally before a push — keep it as a command module in your private .agents/dotagents/cmds/, not in the 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.

Metadata

Release files for dotagents-cli 0.9.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for dotagents-cli 0.9.1
File Size Uploaded Provenance Actions
dotagents_cli-0.9.1.tar.gz 590.4 kB With provenance Details for dotagents_cli-0.9.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for dotagents-cli 0.9.1
File Interpreter ABI Platform Actions
dotagents_cli-0.9.1-py3-none-any.whl Python 3 none any Details for dotagents_cli-0.9.1-py3-none-any.whl

Total release size: 890.5 kB

Release files / dotagents_cli-0.9.1.tar.gz

Download URL dotagents_cli-0.9.1.tar.gz
Size 590.4 kB
Tags Source
SHA-256 checksum
How to use checksums
6d4b31b746c081808b704d6aa7ca4a84b6796e40deb4b7a3e837cbabdf614341
BLAKE2b-256 checksum
How to use checksums
ab8676af75a2b07fb48539fb330b89460d6448deb03dfddbeeaccd5e4b2b9c6c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

Release files / dotagents_cli-0.9.1-py3-none-any.whl

Download URL dotagents_cli-0.9.1-py3-none-any.whl
Size 300.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9d215ab1e91e4dcd13f4c663976ef3a1e0e5ec8ee1a299129f20ec28454b2320
BLAKE2b-256 checksum
How to use checksums
a729aedf6f2e753ea2ab4c0dbd9288be28fa1becbb2fd5e4d5de387292e9a0a3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

Security for dotagents-cli 0.9.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for dotagents_cli-0.9.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page