Add an install plan receipt before mutating agent configs/hooks

[caioribeiroclw-pixel]

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 --plan prints planned agent/config/hook/instruction writes and exits without mutating files.
• install -y either 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.

[DeusData]

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-run performs 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 -y controls the prompt for the apply path).

The genuinely new part of your ask is the machine-readable receipt — the agent.install.plan.v1 JSON schema with agents_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) emits agent.install.plan.v1 and exits without mutating
• redaction rules (no source, secrets, env dumps, prompts, transcripts, raw tool output)
• multi-agent selection made explicit in the receipt
• post-apply summary maps actual → planned writes

Keeping 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.

[DeusData]

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 --plan now emits the agent.install.plan.v1 receipt 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 install actually does. A regression test asserts both the receipt content and that building it creates zero config files.

On your acceptance sketch:

• ✅ install --plan prints planned writes and exits without mutating
• ✅ avoids source/secrets/env/prompts — only agent names + target paths
• ✅ multi-agent detection is explicit in agents_detected
• ⏳ Two items I'm leaving as focused follow-ups (didn't want to overload this change): emitting the receipt automatically before an install -y apply, 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-run remains 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 -y pre-apply receipt or the richer hook schema.