Pi-facing lifecycle and hook adapters for codebase-memory-mcp.
The official CBM Pi bridge remains the authority for tool registration, graph queries, project membership, coverage, binary identity, and hook semantics. This package only supplies Pi command/UI translation and forwards hook events to the official hook-augment frontend.
Warning
Pi extensions run with full system access. Review the source before installing. /cbm-install downloads the official CBM installer from GitHub and executes it with bash; use that command only when you trust the source and the network connection.
- Native graph context hooks — forward Pi lifecycle,
grep,find, andreadevents to the official CBM hook frontend. Failures pass through silently. - Bootstrap commands — delegate first install, managed update, Official Pi Bridge refresh, and optional indexing to the official installer/CLI.
- Codebase Memory skill — the knowledge-graph workflow for choosing
search_graph,trace_path,get_code_snippet, and related tools. AGENTS.mdtemplate — the same managed guidance that codebase-memory-mcp can add for other coding agents.
The package does not bundle the CBM binary. The binary and generated Official Pi Bridge are installed explicitly by /cbm-install or by your own setup.
pi install npm:pi-codebase-memory-hooksYou can pin an exact version for reproducible setups:
pi install npm:pi-codebase-memory-hooks@0.1.0Restart Pi or run /reload after installing so the extension is loaded.
Inside Pi, run:
/cbm-install
The command shows a native lifecycle plan, asks for confirmation before mutation, and then:
- delegates first install to the documented installer from the pinned latest-tested CBM release;
- delegates managed updates to the adjacent official installer;
- preserves externally managed binaries (Homebrew, mise, nix, and similar owners);
- refreshes the generated Official Pi Bridge with native
install --skip-binary --clients=pi; and - indexes the current project unless
--no-indexis supplied.
It never writes ~/.pi/agent/mcp.json and never registers a hand-picked local tool set. Restart Pi or run /reload after a successful bridge refresh.
/cbm-status
This reports the active/managed binary paths, generated bridge readiness, release compatibility, and project status from the native canonical resolver.
pi -e npm:pi-codebase-memory-hooksThis loads the package for the current Pi run only.
| Command | Purpose |
|---|---|
/cbm-install |
Delegate install/update, refresh the Official Pi Bridge, and index the current project. |
/cbm-install --no-index |
Install or update CBM without indexing the current project. |
/cbm-install --yes |
Give explicit consent in a non-interactive runner. |
/cbm-install --dir <path> |
Select the official managed install directory. |
/cbm-install --force |
Request the official managed lifecycle even when the binary is already present. -f is an alias. |
/cbm-status |
Show read-only binary, bridge, release, and project-index status. |
/reload |
Reload installed packages and MCP tools after setup changes. |
All install, bridge-refresh, and indexing work is explicit. Nothing downloads or changes Pi's configuration merely because the package was loaded. If CBM is available, read-only native hook calls may run during agent and tool events.
| Capability | Pi event | Behavior |
|---|---|---|
| Session and subagent guidance | before_agent_start |
Delegates the native graph-first lifecycle context to CBM. |
grep enrichment |
tool_result |
Adds matching graph symbols and locations to successful grep results. |
find enrichment |
tool_result |
Adds indexed files matching the requested pattern to successful find results. |
| Read coverage | tool_result |
Warns when a supported code file has no graph nodes in an indexed project. |
The enrichment hooks invoke the official codebase-memory-mcp hook-augment frontend. They do not parse graph output, list projects, infer coverage, or impose a second timeout policy. CBM owns daemon admission, canonical paths, query formatting, coverage, and its documented hook deadline. If CBM is unavailable or a lookup fails, Pi keeps the original result unchanged.
Enrichment is intentionally quiet when:
- the CBM binary cannot be found;
- the working directory is not inside an indexed project; or
- the tool result is an error.
The grep and find augmentations are the Pi equivalent of CBM's Claude Code PreToolUse hooks: Pi can modify tool input, but it cannot attach additionalContext beside a tool call, so context is added to the returned result instead.
| Variable | Default | Effect |
|---|---|---|
CBM_BIN |
unset | Explicit binary path used only when no generated Official Pi Bridge is present. Once the bridge exists, its embedded path is authoritative. |
CBM_INSTALL_DIR |
~/.local/bin |
Destination used by /cbm-install. |
CBM_HOOKS_DISABLE |
unset | Set to 1 or true to disable both hooks and bootstrap commands. |
CBM_HOOKS_DEBUG |
unset | Set to 1 or true to log hook and CLI failures to stderr. |
Examples:
CBM_BIN=/opt/codebase-memory-mcp piCBM_HOOKS_DEBUG=1 piInstall from the Git repository when testing unreleased changes:
pi install git:github.com/ramaaudra/pi-codebase-memory-hooksOr load a local clone:
pi install /absolute/path/to/pi-codebase-memory-hooksRemove the Pi package with:
pi remove npm:pi-codebase-memory-hooksRemoving the Pi package does not remove an already-installed CBM binary or generated Official Pi Bridge.
extensions/
├── cbm-graph-context.ts # Thin Pi → official hook-augment adapter
├── cbm-bootstrap.ts # /cbm-install and /cbm-status adapter
├── cbm-lifecycle.ts # Native lifecycle phase/outcome seam
└── cbm-native.ts # Official installer/CLI process effects
skills/
└── codebase-memory/
└── SKILL.md # Codebase Memory workflow
AGENTS.md # Optional static managed-context template
npm install
npm run typecheck
npm test
npm pack --dry-runpackage.json declares the Pi resources under the pi key and includes the pi-package keyword so the package can be discovered by the Pi package catalog. Pi supplies @earendil-works/pi-coding-agent at runtime; it is kept as an optional peer dependency and is not bundled.
Run /cbm-install, or set CBM_BIN to an existing executable path. The default managed location is ~/.local/bin/codebase-memory-mcp. A bridge generated by an unsupported or old CBM release is reported as incompatible rather than silently replaced by a local implementation.
Run /cbm-install without --no-index. The native installer decides whether a managed binary needs updating, then the native indexer reports its outcome separately.
Run /reload or restart Pi. The Official Pi Bridge is generated by the native installer and loaded at session start.
This is expected outside an indexed project, when the native daemon is unavailable, or when the active release is below the supported range. Set CBM_HOOKS_DEBUG=1 and restart Pi to inspect adapter failures.
The declared supported range currently starts at CBM 0.10.4; 0.10.4 is the latest tested release. Older or malformed versions are rejected. Newer versions are accepted with a forward-compatibility warning. The generated bridge must be a default Pi extension, embed the official binary path, register the canonical tools, and request machine-readable CLI results. Releases whose generated bridge still consumes default tree output are reported as incompatible until upstream releases the fix.
Bootstrap is intentionally macOS/Linux-only in this first lifecycle pass. Hook and status adapters remain path-safe and cross-platform; Windows users should run the official PowerShell installer directly.