Metadata-Version: 2.4
Name: agedum
Version: 0.46.0
Summary: Drive any agent CLI from an agent-neutral source shape (AGENTS.md + .agents/skills), translating per harness at launch.
Project-URL: Repository, https://github.com/vcoeur/agedum
Project-URL: Issues, https://github.com/vcoeur/agedum/issues
Author: Alice Voland
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
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.12
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.9
Description-Content-Type: text/markdown

# agedum

> Latin *agedum* — "go on! / get going!"

Drive any agent CLI from an **agent-neutral source shape**, translating per harness
at launch. You keep one set of sources; agedum renders them for whichever agent CLI
you run.

- **Instructions** live in a root `AGENTS.md` (plain markdown).
- **Skills** live in `.agents/skills/<name>/` as `SKILL.md` (+ optional task files,
  scripts, and a per-harness `SKILL.<harness>.md` overlay).

agedum has two modes:

- **`agedum <provider-name|config.json> [harness args]`** — the primary form. Read a
  provider config JSON (a name resolved under `~/.config/agents/providers`, or a path),
  resolve its secrets from a `.env`, set the provider/model/auth environment, and launch
  the harness named in the config — inside the virtual-file context below. `--prompt
  "<text>"` seeds an initial prompt and stays interactive; `--run "<text>"` runs it
  non-interactively and exits. `--dry-run` prints the resolved env (secrets masked) + argv
  without launching.
- **`agedum --wrapper <harness> -- <command>`** — compile the source to the harness's
  native layout in a throwaway dir, then run your command inside a **private mount
  namespace** (bubblewrap) where the compiled files appear at their expected paths —
  visible only to that process, never written into your real tree or `$HOME`. For Claude:
  `AGENTS.md` → `CLAUDE.md` and `.agents/skills/<name>/` → `.claude/skills/<name>/` (the
  base `SKILL.md` merged with an optional `SKILL.claude.md` overlay). Provider mode runs
  this same launch after setting the environment.

> **Status:** Claude harness, **project + global scope**, implemented. Each scope
> lands at its *own* Claude location — project → `./CLAUDE.md` + `./.claude/skills/`,
> global (`~/.config/agents/AGENTS.md` + `~/.config/agents/skills/`) → `~/.claude/CLAUDE.md`
> + `~/.claude/skills/` (honours `$CLAUDE_CONFIG_DIR`). They're never merged; Claude
> reads both. Only those two `~/.claude` paths are overlaid for the child — your
> `~/.claude.json` auth and other settings are untouched.
>
> **kimi** (`--wrapper kimi`) is also supported. kimi reads the project `AGENTS.md`
> natively, so agedum leaves it in place; it has no user-scope `AGENTS.md`, so the global
> `AGENTS.md` is injected via a transient `--agent-file` YAML (no `--agent-file` is
> added when there's no global scope). Skills are binds: global → `~/.kimi/skills/`,
> project → `./.kimi/skills/` (both auto-read by kimi).
>
> **opencode** (`--wrapper opencode`) is supported too — pure path-discovery, like
> Claude. The project `AGENTS.md` is read natively (`./AGENTS.md`); the global
> `AGENTS.md` binds to `~/.config/opencode/AGENTS.md`; skills bind to `./.opencode/skills/`
> (project) and `~/.config/opencode/skills/` (global), both searched before
> `.agents/skills/` so the overlaid copy wins. No extra flags. Wrapper mode is Linux-only
> and requires `bwrap` on PATH.
>
> **Cline** (`--wrapper cline`) is supported as well — like opencode, pure
> path-discovery. The project `AGENTS.md` is read natively (Cline reads it as a
> cross-tool rules file); the global `AGENTS.md` binds to the cross-tool path
> `~/.agents/AGENTS.md`; skills bind to `./.cline/skills/` (project) and
> `~/.cline/skills/` (global, `$CLINE_DATA_DIR`-aware). No extra flags. Cline also works
> in **provider mode** — `agedum <provider>` maps the config to Cline's CLI flags
> (`--model`/`--provider`/`--thinking`/`--plan`) and passes the token via `--key`.
>
> **reasonix** (`--wrapper reasonix`) is supported as well — the DeepSeek-native
> [reasonix](https://github.com/esengine/DeepSeek-Reasonix) agent, pure path-discovery like
> opencode/Cline. The project `AGENTS.md` is read natively (one of its memory docs); the
> global `AGENTS.md` binds to `~/.config/reasonix/AGENTS.md`; skills bind to
> `./.reasonix/skills/` (project) and `~/.reasonix/skills/` (global), both outranking
> `.agents/skills/` so the overlaid copy wins. No extra flags. reasonix also works in
> **provider mode** — `agedum <provider>` maps `model` to `--model <name>` on the `chat`/`run`
> subcommand and exports the token (reasonix reads it via the provider's `api_key_env`);
> `--run` maps to `reasonix run "<text>"`, while `--prompt` is unsupported (`chat` can't be
> pre-seeded).
>
> **aider** (`--wrapper aider`) is supported as well — but it differs from the others.
> aider has **no native instruction discovery** and **no skills mechanism**, so agedum
> injects each scope's `AGENTS.md` via aider's `--read` read-only-context flag (the
> instructions analogue of kimi's `--agent-file`; no binds), and does not inject skills. In
> **provider mode** the config maps to aider's CLI flags (`--model` / `--weak-model` /
> `--editor-model` / `--reasoning-effort`), the key rides the environment (litellm), and a
> `baseUrl` sets `OPENAI_API_BASE`. **Git integration is disabled by default** (`--no-git`),
> because agedum's namespace shares the real `.git` and aider auto-commits — set `git: true`
> to opt back in. `--run` maps to `aider --message "<text>"`; `--prompt` is unsupported
> (`--message` runs once and exits).

> [!NOTE]
> **pi** (`--wrapper pi`) is supported as well — the earendil-works
> [pi](https://pi.dev) agent, pure path-discovery like opencode/Cline/reasonix. The project
> `AGENTS.md` is read natively (cwd→root walk); the global `AGENTS.md` binds to
> `~/.pi/agent/AGENTS.md`; skills bind to `./.pi/skills/` (project) and `~/.pi/agent/skills/`
> (global). No extra flags. In **provider mode** `model` / `provider` / `thinking` map to
> CLI flags and the key rides the environment by name. pi has no base-URL flag, so a
> `baseUrl` makes agedum generate `~/.pi/agent/models.json` (a provider named `agedum`, key
> referenced by `$VAR`); a `subagentModel` generates `~/.pi/agent/settings.json` routing
> every [pi-subagents](https://pi.dev/packages/pi-subagents) built-in agent — both merged
> onto your existing files. `--prompt` seeds `pi "<text>"`; `--run` maps to `pi --print
> "<text>"`.

> [!NOTE]
> **codex** (`--wrapper codex`) is supported as well — the OpenAI
> [Codex CLI](https://github.com/openai/codex), pure path-discovery like opencode/Cline/reasonix/pi.
> The project `AGENTS.md` is read natively (work-dir→root walk); the global `AGENTS.md` binds to
> `~/.codex/AGENTS.md` (`$CODEX_HOME`-aware); skills bind to `./.codex/skills/` (project) and
> `~/.codex/skills/` (global). No extra flags. In **provider mode** `model` maps to `-m` and the
> key rides the environment by name. codex has no base-URL flag, so a `baseUrl` is passed as
> `-c model_providers.…` overrides (a provider named `agedum`). Recent codex speaks only the
> Responses API, so a Chat-Completions endpoint (DeepSeek etc.) sets `chatCompletions: true` and
> agedum interposes a local `ResponsesToChatProxy` (the `FoldProxy` sibling) that translates
> codex's Responses requests to/from `/chat/completions`. codex custom agents are bound three
> ways: `subagentModel` (one fast `~/.codex/agents/flash.toml`), `codexAgents: <dir>` (bind every
> `*.toml` into `~/.codex/agents/`, personal scope), and `codexProjectAgents: <dir>` (into
> `.codex/agents/`, project scope) — sandbox defaulted by agedum, delegates the primary can spawn.
> `--prompt` seeds `codex "<text>"`; `--run` maps to `codex exec "<text>"`.

## Usage

```bash
# Provider mode — launch a harness from a provider config, env resolved from .env:
agedum claude-deepseek-auto                       # resolve the named provider, launch claude
agedum claude-deepseek-auto -p "review this"      # extra args go to the harness
agedum claude-deepseek-auto --prompt "review this"  # seed an initial prompt, stay interactive
agedum claude-deepseek-auto --run "review this"     # run the prompt non-interactively, then exit
agedum ./providers/my-claude.json                 # a config path instead of a name
agedum claude-deepseek-auto --dry-run             # print resolved env, virtual files + argv

# Wrapper mode (low-level; provider mode builds on it) — virtual files, no provider env:
agedum --wrapper claude -- claude --model sonnet -p "review this"
agedum --wrapper cline -- cline task "review this"  # drive Cline with the same source
agedum --wrapper reasonix -- reasonix chat          # drive reasonix with the same source
agedum --wrapper aider -- aider --no-git            # drive aider (pass --no-git in wrapper mode)
agedum --wrapper pi -- pi                           # drive pi with the same source
agedum --wrapper codex -- codex                     # drive codex with the same source
agedum --wrapper claude --dry-run -- claude       # list what would be injected, don't run

agedum --providers                                # list the provider configs (name, harness, model)
agedum --version
```

`agedum --providers` lists every `*.json` config in `$AGENTS_PROVIDERS_DIR` (default
`~/.config/agents/providers`) as `name  harness  model` — the names you pass to
`agedum <name>`.

`agedum <name>` is the normal way to launch. Wrapper mode is the lower-level entry it
uses: everything after `--` is the command, run verbatim, and `--wrapper <harness>`
chooses the format; `--dry-run` prints the injected virtual files without running.
Injected paths must be gitignored — agedum refuses to overlay a git-tracked file (the
namespace shares your real `.git`).

## Documentation

Full docs at **[agedum.vcoeur.com](https://agedum.vcoeur.com)**:

- [Source & scopes](https://agedum.vcoeur.com/source-shape/) — the `AGENTS.md` + `.agents/skills/` layout, and the project vs global scopes
- [Wrapper mode](https://agedum.vcoeur.com/wrapper/) — run a command in the injected context; how each harness resolves
- [Provider mode](https://agedum.vcoeur.com/provider/) — launch a harness from a provider config JSON
- [Harnesses](https://agedum.vcoeur.com/harnesses/) — one page per harness: wrapper resolution + provider config
- [CLI reference](https://agedum.vcoeur.com/cli/) and [Internals](https://agedum.vcoeur.com/internals/) — the mount-namespace launch and its safety rules

## Install

```bash
pipx install agedum        # standalone CLI (once published)
```

## Develop

```bash
make dev-install   # uv sync --all-groups
make test          # pytest
make lint          # ruff check + format --check
make run -- --version
make docs          # build the docs site (strict); docs-serve for live preview
```

Python ≥ 3.12, managed with [uv](https://docs.astral.sh/uv/). The version is
derived from the git tag (`vX.Y.Z`) at build time via hatch-vcs — never committed.

## Release

Tag the commit `vX.Y.Z` and push the tag; the `release` workflow builds and
publishes to PyPI via OIDC trusted publishing.

## License

MIT — see [LICENSE](LICENSE).
