pi-codebase-memory-hooks

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.

What is included

• Native graph context hooks — forward Pi lifecycle, grep, find, and read events 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.md template — 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.

Quick start

1. Install the Pi package

pi install npm:pi-codebase-memory-hooks

You can pin an exact version for reproducible setups:

pi install npm:pi-codebase-memory-hooks@0.1.0

Restart Pi or run /reload after installing so the extension is loaded.

2. Install and configure codebase-memory-mcp

Inside Pi, run:

/cbm-install

The command shows a native lifecycle plan, asks for confirmation before mutation, and then:

1. delegates first install to the documented installer from the pinned latest-tested CBM release;
2. delegates managed updates to the adjacent official installer;
3. preserves externally managed binaries (Homebrew, mise, nix, and similar owners);
4. generates the Official Pi Bridge (a thin extension that wraps CBM CLI tools); and
5. indexes the current project unless --no-index is 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.

3. Check readiness

/cbm-status

This reports the active/managed binary paths, generated bridge readiness, release compatibility, and project status from the native canonical resolver.

Try without installing

pi -e npm:pi-codebase-memory-hooks

This loads the package for the current Pi run only.

Commands

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.

How the hooks work

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.

Configuration

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 pi

CBM_HOOKS_DEBUG=1 pi

Installation alternatives

Install from the Git repository when testing unreleased changes:

pi install git:github.com/ramaaudra/pi-codebase-memory-hooks

Or load a local clone:

pi install /absolute/path/to/pi-codebase-memory-hooks

Remove the Pi package with:

pi remove npm:pi-codebase-memory-hooks

Removing the Pi package does not remove an already-installed CBM binary or generated Official Pi Bridge.

Package layout

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

Development

npm install
npm run typecheck
npm test
npm pack --dry-run

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

Troubleshooting

/cbm-status says the binary or bridge is unavailable

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.

The current project is not indexed

Run /cbm-install without --no-index. The native installer decides whether a managed binary needs updating, then the native indexer reports its outcome separately.

MCP tools are not visible after installation

Run /reload or restart Pi. The Official Pi Bridge is generated by /cbm-install and loaded at session start.

The hooks appear silent

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.

Compatibility gate

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.

Learn more

• Pi package documentation
• Pi package catalog
• codebase-memory-mcp
• Report an issue