abby v0.12.0

Highlights

abby v0.12.0 makes installing agents into Claude Code, Codex and Gemini CLI safe and previewable. This is Phase C of the MCP 2026-07-28 adaptation (#14).

• Runtime CLIs when they can express the entry.
  • Claude Code: claude mcp add-json / remove, run in the project root. If adding fails after the old entry was removed, abby restores the old entry.
  • Gemini CLI: its CLI is used at user scope only.
  • Codex: abby always edits the file, because its CLI can't set cwd or timeouts.
  • Choose with --config-method auto|cli|file or ABBY_CONFIG_METHOD.
• Safe config file edits.
  • A file that doesn't parse is refused (commented or duplicate-key JSON included), and nothing is written.
  • Edits are atomic and keep the file's mode, and its owner under sudo. Symlinks are followed to the real file.
  • The first edit makes a one-time *.abbyfile.bak backup.
  • Only the keys abby owns are touched. In Codex TOML, comments and unrelated tables are kept, and any edit that would change something outside the agent's own entry is refused.
• Preview and summary. --dry-run on install, build and uninstall writes nothing. Every change is planned before any is applied, and a summary table shows each runtime, scope, method, target and backup.
• Richer entries. Project-scope entries get a cwd, --env KEY=VALUE sets environment variables, and each entry gets a timeout of the agent's largest tool limit plus 10s.
• Mandatory checksums. A downloaded agent is verified against its release checksum before it runs. --insecure-skip-checksum bypasses this, with a warning. Remote agent names are validated.
• New abby doctor. It checks, for each installed agent:
  • the binary;
  • each runtime's config entry;
  • the MCP handshake in both protocol eras;
  • the effective sandbox and stale timeouts;
  • leftover ~/.claude/mcp.json entries.
• abby update keeps your env and the binary's location, and exits non-zero when any agent fails to update. abby uninstall keeps the registry entry when a config removal fails, so you can re-run it.

Migration notes

1. abby install requires a checksum asset. abby publish has uploaded <agent>-sha256sums.txt since v0.7.0. For releases without one, pass --insecure-skip-checksum. abby update has no bypass flag.
2. Claude Code user-scope entries now go to ~/.claude.json (or $CLAUDE_CONFIG_DIR/.claude.json), or through claude mcp add-json. Older abby versions wrote ~/.claude/mcp.json, which Claude Code never read. abby doctor reports those leftovers; reinstall with abby install --global, then delete the file.
3. Runtimes are detected by their CLI being on PATH or their config dir existing (~/.claude, ~/.codex / $CODEX_HOME, ~/.gemini), no longer by $HOME existing.
4. Config edits are stricter.
   • Unparsable, commented or duplicate-key files are refused; edit them by hand first.
   • The first edit of a Codex config.toml normalizes blank-line runs between tables to a single blank line.
   • JSON configs are rewritten with LF line endings.
   • Consider adding *.abbyfile.bak to your project's .gitignore.
5. Entries now carry cwd, env and a timeout. Codex loads a project's .codex/config.toml only in trusted projects. --env values in project files are often committed, so prefer ${VAR} references for secrets.
6. Agent names use letters, digits, - and _. A repo whose name contains a dot needs the agent named explicitly, as in github.com/owner/my.repo/my-agent. install --all works either way.
7. Rebuild your agents with abby build. Generated agents pin github.com/teabranch/abbyfile v0.12.0.

See docs/guides/distribution.md for the full guide.

What's Changed

• feat: MCP adaptation Phase C — safe install & runtime config (v0.12.0) by @d-teller in #14

Full Changelog: v0.11.0...v0.12.0