Repository navigation
Add an install plan receipt before mutating agent configs/hooks #388
Description
Context
codebase-memory-mcp is doing the useful but sensitive thing: one installer can configure MCP entries, instruction files, Skills, and pre-tool hooks across many coding agents.
The README already says the tool reads the codebase and writes agent configuration files. That is a good disclosure. The missing trust primitive I would look for as a user is a machine-readable install plan/receipt before those writes happen.
Proposal
Add an install --plan / install --dry-run mode, or have install emit a pre-mutation receipt before applying -y, with fields like:
{
"type": "agent.install.plan.v1",
"project_root": "<path or redacted>",
"agents_detected": ["claude-code", "opencode", "openclaw"],
"agents_selected": ["claude-code"],
"config_files_planned": ["~/.claude/settings.json", ".claude/skills/..."],
"instruction_files_planned": [".claude/skills/.../SKILL.md"],
"hooks_planned": [
{
"agent": "claude-code",
"event": "PreToolUse",
"tools": ["Grep", "Glob"],
"blocking": false,
"command_source": "installed shim"
}
],
"backups_planned": ["~/.claude/settings.json.bak"],
"writes_started": false,
"network_after_install": false,
"next_safe_command": "codebase-memory-mcp install -y"
}The important part is writes_started=false: users and agents can inspect the plan before any config/hook mutation happens.
Why this matters
This project crosses several boundaries at once:
- MCP server registration
- agent instruction/Skill installation
- repo or user config edits
- pre-tool hook installation
- optional indexing / local graph artifacts
For coding agents, those are not just setup details. They decide what tools become visible, what instructions get loaded, and what commands can run around future tool calls.
Acceptance sketch
codebase-memory-mcp install --planprints planned agent/config/hook/instruction writes and exits without mutating files.install -yeither prints the same receipt before mutation or writes it to a stable path/log.- The plan avoids raw source code, secrets, full environment dumps, prompts, transcripts, and raw tool output.
- The final install summary maps actual writes back to planned writes.
- If auto-detection selects multiple agents, the receipt makes that explicit.
This would make the installer easier to trust from Claude Code/OpenClaw/Cursor-style agents, because the agent can prove what it is about to mutate before it mutates the user's toolchain.
Activity
DeusData commentedon May 31, 2026
This is a thoughtful proposal and I agree with the framing — an installer that touches MCP registration, instruction files, Skills, and PreToolUse hooks should let you see what it will mutate before it does.
Worth noting: part of this already exists.
codebase-memory-mcp install --dry-runperforms exactly the no-mutation, inspect-first pass you describe — it detects agents, prints every planned config/instruction/hook write, modifies nothing, and ends with(dry-run — no files were modified). So the human-facing trust primitive (writes_started=false, inspect-then-apply) is there today via--dry-run(and-ycontrols the prompt for the apply path).The genuinely new part of your ask is the machine-readable receipt — the
agent.install.plan.v1JSON schema withagents_detected/agents_selected/config_files_planned/hooks_planned/backups_planned/next_safe_command, plus a final summary that maps actual writes back to the plan. That's the high-value piece for agent-driven installs, and it's a stable public contract once shipped, so I want to design it deliberately rather than bolt JSON onto the current human-readable output.Accepting this as a tracked enhancement with your acceptance sketch as the spec:
install --plan(and--dry-run --json) emitsagent.install.plan.v1and exits without mutatingKeeping this open as the tracking issue. A PR is very welcome if you'd like to draft the schema; otherwise I'll pick it up. Thanks for pushing on the trust model here.
feat(install): add `install --plan` machine-readable receipt (#388)
DeusData commentedon May 31, 2026
Thanks — agreed this is the right trust primitive for an installer that touches MCP entries, instruction files, Skills, and hooks across many agents. Implemented in commit 4c38c5a.
codebase-memory-mcp install --plannow emits theagent.install.plan.v1receipt and exits without mutating anything (no config writes, no index deletion, no network):{ "type": "agent.install.plan.v1", "agents_detected": ["claude-code", "cursor", "codex", ...], "config_files_planned": ["~/.cursor/mcp.json", "~/.codex/config.toml", ...], "instruction_files_planned": ["~/.codex/AGENTS.md", "<claude>/skills", ...], "hooks_planned": [{"agent": "Claude Code", "path": "<claude>/hooks/cbm-code-discovery-gate"}, ...], "writes_started": false, "network_after_install": false, "next_safe_command": "codebase-memory-mcp install -y" }Key design point (no drift): the plan isn't a hand-maintained mirror of the install logic — it's produced by running the actual install dispatch in record-only mode. A global recorder is populated at the same write sites that perform the real writes, with all mutations disabled. So the receipt can't silently diverge from what
installactually does. A regression test asserts both the receipt content and that building it creates zero config files.On your acceptance sketch:
install --planprints planned writes and exits without mutatingagents_detectedinstall -yapply, and a post-apply summary mapping actual→planned writes. The hooks_planned objects are also currently{agent, path}rather than the richer{event, tools, blocking}shape — happy to enrich that if you want it.Note
--dry-runremains as the human-readable inspection mode. Closing this as the core machine-readable receipt is now in. Thanks for pushing on the install trust model — please open a follow-up if you want the-ypre-apply receipt or the richer hook schema.