agedum

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|.yaml> [harness args] — the primary form. Read a provider config — JSON, or YAML declaring schema: agedum-provider/v1 or /v2 — (all relative refs resolved under ${AGENTS_PROVIDERS_DIR:-~/.config/agents/providers}; absolute paths are used as-is, with no CWD fallback), 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. Interactive --prompt is unsupported for kimi, reasonix, and aider. --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 and its children. The injected content is temporary, not a no-writes guarantee: mountpoint stubs, prepared state/injection directories, writable provider seeds, and harness state can touch the host. 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. An optional global Claude overlay also binds settings.json + hook scripts/ read-only; automatic project transcript hooks bind .claude/settings.local.json read-only when untracked. Do not rely on permission saves to that overlaid file. Your ~/.claude.json auth is not overlaid.

kimi (--wrapper kimi) is also supported. kimi reads the project AGENTS.md natively, so agedum leaves it in place; global AGENTS.md binds to ~/.kimi-code/AGENTS.md. Skills are binds: global → ~/.kimi-code/skills/, project → ./.kimi-code/skills/ (both auto-read). Global targets honour KIMI_CODE_HOME; no instruction flags are appended. --run maps to kimi --prompt "<text>" (no --print), dropping interactive permission/plan flags; agedum's interactive --prompt is unsupported.

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 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 at a read-only bound cache path named by aider's --read flag, 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 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 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, 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

# 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 claude/my-claude.json                      # relative to the providers root, not CWD
agedum /absolute/path/my-claude.yaml              # absolute config path
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 / *.yaml / *.yml 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 untracked — agedum refuses to overlay a git-tracked file (the namespace shares your real .git). Keep targets gitignored as an operator prerequisite; agedum does not enforce gitignore.

Documentation

Full docs at agedum.vcoeur.com:

• Source & scopes — the AGENTS.md + .agents/skills/ layout, and the project vs global scopes
• Wrapper mode — run a command in the injected context; how each harness resolves
• Provider mode — launch a harness from a provider config (JSON or YAML)
• Harnesses — one page per harness: wrapper resolution + provider config
• CLI reference and Internals — the mount-namespace launch and its safety rules

Install

pipx install agedum        # standalone CLI (once published)

Develop

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

Python ≥ 3.12, managed with 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.