Design: a launcher adapter so grandma can drive CLIs other than Claude Code

[anshulforyou]

Today grandma is wired to one tool. claude shows up in three shapes across the engine, and any multi-CLI story has to account for all three. Launch injects the assembled memory bundle with exec claude --append-system-prompt. Headless runs claude -p over a transcript for distill and watch. Hooks wire rehydrate-after-compaction and session-end distill into .claude/settings.local.json. So this is not swap the binary name. It is an adapter with a small honest interface, where a CLI implements what it supports and grandma drops cleanly what it cannot.

Here is a suggested design, checked against each target's own docs rather than assumed.

What the targets actually support. The one injection channel every CLI has is the initial user prompt text. The ephemeral system-prompt slot is a Claude Code luxury: neither Gemini CLI nor Codex has an append-system-prompt, and their replace-the-system-prompt knobs (GEMINI_SYSTEM_MD, experimental_instructions_file) clobber the CLI's own coding brain, so they are the wrong place for memory. Memory rides in through the native context file (AGENTS.md for Codex and opencode, GEMINI.md for Gemini, a conventions file for aider) or prepended into the first prompt, never the system slot. Headless mode is strong everywhere (codex exec, gemini -p, aider -m, opencode run), all JSON output except claude. Lifecycle hooks are the scarce resource: only opencode has a real event system (session.compacted, session.idle), while Codex, Gemini and aider have none, so rehydrate-after-compaction simply does not fire there and degrades to a manual grandma rehydrate.

The adapter interface. lib/adapters/.sh, each a bash file defining the same function names, sourced by launch, save and watch. The engine never re-assembles memory, it hands the adapter the bundle assemble.sh already built.
Required:

• adapter_capabilities. Prints a flag set the engine reads: injection mode (append, contextfile, or prepend), headless yes or no, which hooks it can install, and auto_commit so grandma can force it off.
• adapter_headless. Run the model non-interactively over a prompt, print the result, honest exit. Judge output by content, not exit code, since each CLI fails differently.
• adapter_launch. Start an interactive session with the bundle injected. Crucially, on a target with no session-end hook the adapter wraps the session rather than execs, so the launcher's existing HUP and TERM trap still runs the session-end distill.
  Optional, engine degrades if absent:
• adapter_install_compaction_hook. Wire rehydrate. Only Claude Code and opencode can. Everyone else is a no-op and rehydrate just does not fire.
• adapter_context_file_path. Where the contextfile mode writes, and what to clean up on exit.

Selection, highest precedence first: a GRANDMA_CLI env var, then a per-sweater cli field in the sweater's frontmatter (so you can keep a Claude sweater and a Gemini sweater side by side), then a cli line in the GRANDMA_HOME config, then the built-in default claude. This mirrors how the engine already takes env overrides.

Keeping the clean-room intact. Adapters consume the same assemble.sh bundle, so the isolation invariant and the denylist and core-purity invariants already cover every CLI unchanged, the adapter transports the bundle and never re-selects memory. Add lib/adapters/* to the CORE list in grandma-test.sh so the no-scope-names and no-personal-data checks apply to adapters too. And add one new invariant for the contextfile mode: assert that after a wrapped session the adapter left no memory-bearing file (an AGENTS.md or GEMINI.md carrying bundle content) in the project working tree, tracked or untracked. That bites the leak-via-context-file failure mode that Claude Code's ephemeral flag never had.

Recommended first target: Gemini CLI. Its two hardest capabilities, headless and context injection, are both first-class, documented and stable, and it has the largest user base, so the payoff comes fast. Because it has no lifecycle hooks, it forces the graceful-degradation path to be real from day one, and that degraded path is the honest common case Codex and aider also share, so proving it once on Gemini de-risks all three. opencode is the stretch target that proves the full-hook path, a small JS plugin mapping session.compacted to rehydrate and session.idle to distill. aider's adapter must force --no-auto-commits to keep grandma's no-auto-commit promise.

Open questions:

• Headless output shape differs per CLI, so the distill junk-proposal filter is re-derived per adapter.
• Does prepend-into-prompt weaken memory versus a true system prompt, since Gemini and Codex weight their context files differently than a system slot.
• Per-adapter cost caps for the headless path, since each CLI bills differently.

Each adapter ships its definition of done: a GRANDMA_DRY_RUN smoke that prints a plan and never execs and survives set -u, and the kebab-fixture path test. This is a design and build thread. Argue the interface if you disagree, then build one adapter against it.

[anshulforyou]

Goal: adding the next CLI is a single drop-in file, not an engine change. Scope right now is CLIs only (Gemini, Codex, aider, opencode, alongside the current Claude Code). MCP and the web UIs are deliberately out of scope, see the last section for why.

The reframe: grandma does three separable jobs

Every integration is three jobs, and each CLI supports them to a different degree:

• LOAD put the user's memory into the session at start, and keep it loaded (the always-on promise).
• DISTILL run a headless model call over the session transcript to draft new memory.
• SURVIVE hook the lifecycle: checkpoint working-state before the context compacts, re-inject after, distill at session end.

Today all three are hardcoded to claude. The design turns them into a contract each target implements as far as it can, and the engine degrades the rest. That degradation is the whole point: it is what lets hookless aider run on the same engine as fully-hooked opencode.

One fact that shapes everything: on Claude Code, Gemini, and Codex the pre-compaction hook CANNOT inject context, only fire (and sometimes block). So the portable pattern is the one grandma already uses, and it generalizes cleanly: checkpoint in the pre-compaction hook, re-inject from the session-START hook.

The adapter contract (the extensibility answer)

A target is one file, lib/adapters/<name>.sh, defining a fixed set of functions plus one capability declaration. The engine never re-selects memory, it hands the adapter the bundle assemble.sh already built. Adding a CLI is writing this one file. No engine changes.

Required. adapter_capabilities prints the flag block the engine branches on (it branches on flags, never on the CLI name):

inject=append|contextfile|prepend      how memory loads
context_file=<path|empty>              the native always-on file (CLAUDE.md, GEMINI.md, AGENTS.md, ...)
headless=yes|no
headless_parse=text|json:<jq-path>     how to pull the answer out
hook_session_start=yes|no              can it inject at start (the rehydrate path)
hook_pre_compaction=yes|no             can it fire a checkpoint before compaction
hook_session_end=yes|no                does it signal end (else the launcher wraps+traps)
transcript=<glob|empty>                where the readable transcript lives
transcript_format=jsonl|json|markdown
auto_commit=yes|no                     if yes, the engine forces it off

• adapter_load bundle cwd puts memory in front of the model. contextfile mode writes the bundle to the native file and cleans it up on exit; prepend mode returns text to glue onto the first prompt; append mode uses the CLI's system-prompt-append flag. This is the always-on layer.
• adapter_launch init cwd starts the interactive session. On a target with no session-end hook the adapter WRAPS the process instead of exec, so the launcher's existing HUP and TERM trap still runs the session-end distill. This is why aider works at all.
• adapter_headless prompt cwd runs non-interactively and prints the model's answer. Judge output by content, never the exit code (grandma's existing lesson, generalized).

Optional, engine degrades to nothing if absent. adapter_install_hooks cwd scope wires the pre-compaction checkpoint and the session-start rehydrate into the CLI's own hook config. Absent means rehydrate just does not fire (or becomes a manual grandma rehydrate), and the launcher wrapper covers session-end.

Five functions, one optional. A capable target implements all five; aider implements three and declares the rest off; the engine reads the flags and does the right thing.

Selection

Highest precedence first: GRANDMA_CLI env var, then a per-sweater cli: field in the sweater frontmatter (keep a Claude sweater and a Gemini sweater side by side), then a cli line in the GRANDMA_HOME config, then the built-in default claude.

The four CLIs, concretely (verified against current docs)

Every CLI has a native context file plus a headless mode. The append-a-system-prompt flag is a Claude Code luxury, and the full-replace knobs (GEMINI_SYSTEM_MD, Codex model_instructions_file) clobber the CLI's own coding brain, so we never touch those. Memory rides the native file.

CLI	LOAD	DISTILL	SURVIVE	must guard
Gemini	GEMINI.md	gemini -p -o json (.response)	hooks v0.26.0+; PreCompress advisory-only, checkpoint there and re-inject from SessionStart resume	usageStatisticsEnabled=false, pin --model
Codex	AGENTS.md / developer_instructions	codex exec -o <file>	PreCompact + SessionStart(compact); no SessionEnd, use Stop	set --sandbox / -a, never --yolo
aider	--read <file> only	aider -m (plain text)	no hooks at all, wrap the process	--no-auto-commits --no-dirty-commits (auto-commits by default)
opencode	instructions[]	opencode run --format json	session.compacting + session.idle over SSE	restrictive permission block, pin version

Per-CLI notes:

• Gemini CLI. LOAD via GEMINI.md (auto-read). DISTILL gemini -p -o json, answer at .response. Hooks exist from v0.26.0 (version-gate). PreCompress is advisory-only, so checkpoint there and re-inject from SessionStart source=resume. Transcript under ~/.gemini/tmp/<hash>/chats (discover the hash, do not compute it).
• Codex CLI. LOAD via AGENTS.md (auto, hierarchical, 32 KiB cap) or developer_instructions (append). DISTILL codex exec -o <file>. SURVIVE PreCompact plus PostCompact, rehydrate from SessionStart source=compact, no SessionEnd so use Stop. Transcript ~/.codex/sessions/.../rollout-*.jsonl.
• aider. The heaviest lift, and the proof the degrade path is real. LOAD only via --read <memory-file> (also read-only, so aider will not edit it), there is no system-prompt override. DISTILL aider --message, plain text, expect status lines interleaved. NO hooks, so grandma owns the lifecycle by wrapping the process. Transcript .aider.chat.history.md (accumulates across sessions, track an offset). Launch with --no-auto-commits --no-dirty-commits, because aider auto-commits your tree under its own authorship by default.
• opencode. Richest hooks, best driven over its local server. LOAD via instructions[] in opencode.json. DISTILL opencode run --format json, or opencode serve once and attach. SURVIVE the experimental session.compacting hook (pre) and session.idle (end), over the SSE /event stream. Transcript ~/.local/share/opencode/storage (undocumented filenames, tolerate drift). Ship a restrictive permission block.

Build order: Gemini first. Its two hardest capabilities (headless, context injection) are first-class and stable, and because its pre-compaction hook cannot inject, it forces the real degrade path from day one, the same path Codex and aider need. Prove it once on Gemini and the rest fall out. Then Codex, then opencode (the full-hook showcase), then aider.

Clean-room and tests

Adapters consume the same assemble.sh bundle, so the isolation, denylist, and core-purity invariants already cover every CLI unchanged. Add lib/adapters/* to the CORE list so no-scope-names and no-personal-data apply to them too. One NEW invariant for the contextfile load mode: after a wrapped session, assert the adapter left no memory-bearing file (a GEMINI.md or AGENTS.md carrying bundle content) in the project working tree, tracked or untracked. That bites the leak-via-context-file failure mode Claude Code's ephemeral flag never had. Each adapter ships a GRANDMA_DRY_RUN smoke that prints a plan, never execs, survives set -u, plus the kebab-fixture path test.

Roadmap

1. The abstraction, zero behavior change: extract today's claude behavior into lib/adapters/claude.sh, add the capability model and selection, route launch, save, watch, and precompact through it. Proof it is safe: the entire existing suite stays green, because claude is still the adapter.
2. Gemini adapter (proves the degrade path) plus its test and the new contextfile-leak invariant.
3. Codex, then opencode, then aider.

Open questions

• Hook systems are new and version-gated on three of five (Gemini v0.26.0+, Codex 2026, opencode experimental). The adapter must detect the version and degrade to the wrapped-process path when hooks are absent. How much version-sniffing do we want in bash versus declaring capabilities per pinned version.
• Transcript schemas are unstable everywhere (Claude and opencode say so outright, Gemini may move JSON to JSONL). Parse defensively, and the distill junk-filter is re-derived per adapter.
• Per-adapter cost caps for the headless path, since each CLI bills differently.

Out of scope, on purpose

MCP (a pull protocol: it cannot deliver always-loaded memory and only re-plumbs what the context-file load already does) and the web UIs (ChatGPT, Claude.ai: unreachable without a public server, and their terms forbid the automated reading of chat history that a distill step needs). grandma is for tools that run in your terminal and keep a transcript you own.

This is a design and build thread. Argue the interface if you disagree, then build one adapter against it.

[abheyyy]

hey @anshulforyou. I would like to contribute to this. I really like your idea as a whole.
Will be sharing something from my side very soon, havent gone deep into the implementation yet but will do so and communicate accordingly. Thanks!
My Profile: If you are concerned abt authenticity. I am an AI research engineer by profession and would like to contribute to this OSS repo.