Metadata-Version: 2.5
Name: dotagents-cli
Version: 0.5.0
Summary: The dotagents CLI: install and manage a portable ~/.agents config for AI coding agents
Project-URL: Homepage, https://github.com/jose-pr/dotagents/
Project-URL: Repository, https://github.com/jose-pr/dotagents
Project-URL: Documentation, https://jose-pr.github.io/dotagents/
Author: Jose A.
License: MIT License
        
        Copyright (c) 2026 Jose A.
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: duho<0.6,>=0.5.0
Requires-Dist: pathlib-next<0.10,>=0.9.0
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.5; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
Provides-Extra: http
Requires-Dist: pathlib-next[http]; extra == 'http'
Provides-Extra: s3
Requires-Dist: pathlib-next[s3]; extra == 's3'
Provides-Extra: sftp
Requires-Dist: pathlib-next[sftp]; extra == 'sftp'
Provides-Extra: uri
Requires-Dist: pathlib-next[uri]; extra == 'uri'
Description-Content-Type: text/markdown

# dotagents

[![Test](https://img.shields.io/github/actions/workflow/status/jose-pr/dotagents/test.yml?branch=main&label=tests)](https://github.com/jose-pr/dotagents/actions/workflows/test.yml)
[![PyPI](https://img.shields.io/pypi/v/dotagents-cli.svg)](https://pypi.org/project/dotagents-cli/)
[![Documentation](https://img.shields.io/badge/docs-online-blue.svg)](https://jose-pr.github.io/dotagents/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/jose-pr/dotagents/blob/main/LICENSE)

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](https://jose-pr.github.io/dotagents/)
  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`) — that is the whole shipped surface; commands beyond it come from overlays or your own `cmds/` modules |
| `src/dotagents/_overlay/` | The **base overlay** `init` writes: `AGENTS.md` scaffolding, `CLAUDE.md`, `dotagents/DECISIONS.md` (empty design-log index), and an empty `dotagents/cmds/` dir — your drop-in point for your own command modules. Neutral — imposes no flows, ships no command |
| `tools/` | Repo tooling, not shipped: `audit.py` (CI structure check) 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()`, kept at this filename for muscle memory |

The **example overlays** — the `flows` workflow set, per-language `kb/` + templates,
`references`, `release`, `private-sync`, `net`, `recovery`, `tools` — live on a separate
[`overlays` branch](https://github.com/jose-pr/dotagents/tree/overlays), 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](https://jose-pr.github.io/dotagents/) 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](#managing-overlays) below.

## Install

```bash
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`).

```bash
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](https://github.com/jose-pr/dotagents/tree/overlays)) 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/`.

```bash
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`:

```bash
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

```bash
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](https://jose-pr.github.io/dotagents/).

## License

MIT — see [LICENSE](LICENSE).
