# pi-codebase-memory-hooks

[![npm version](https://img.shields.io/npm/v/pi-codebase-memory-hooks?style=flat-square)](https://www.npmjs.com/package/pi-codebase-memory-hooks)
[![Pi package catalog](https://img.shields.io/badge/Pi-package%20catalog-8b5cf6?style=flat-square)](https://pi.dev/packages)

Pi-facing lifecycle, native-tool, and hook adapters for [codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp).

This package generates a package-owned native Pi bridge with schema-aware `cbm_*` tools and delegates every graph, index, and hook operation to the official `codebase-memory-mcp` CLI. It does not use Pi MCP transport or write `mcp.json`.

> [!WARNING]
> Pi extensions run with full system access. Review the source before installing. `/cbm-install` downloads the pinned official CBM installer from GitHub, verifies its SHA-256 checksum, 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.
- **Native CBM tool facade** — register schema-aware `cbm_*` tools, keep advanced tools lazy, bound output, and invoke the official CLI through stdin.
- **Bootstrap commands** — delegate first install, managed update, bridge refresh, and explicit project indexing to the official installer/CLI.
- **Codebase Memory skill** — the knowledge-graph workflow for choosing the native `cbm_search_graph`, `cbm_trace_path`, `cbm_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 native bridge are installed explicitly by `/cbm-install` or by your own setup.

`full_output`, `max_output_chars`, and `timeout_ms` are native-bridge controls, not arguments understood by the CBM CLI. They are removed before forwarding the request. Normal output is passed through; oversized text is compacted with a temp-file recovery path, and `full_output: true` asks the bridge to return it directly.

## Quick start

### 1. Install the Pi package

```bash
pi install npm:pi-codebase-memory-hooks
```

You can pin an exact version for reproducible setups:

```bash
pi install npm:pi-codebase-memory-hooks@0.2.0
```

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

### 2. Install and configure codebase-memory-mcp

Inside Pi, run:

```text
/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 package-owned schema-aware native Pi bridge; and
5. skips indexing by default. Use `/cbm-install --index` or `/cbm-index` when indexing is intentional.

It never writes `~/.pi/agent/mcp.json`, and it reuses a usable managed binary unless `--force` is supplied. Restart Pi or run `/reload` after a successful bridge refresh.

### 3. Check readiness

```text
/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

```bash
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 and refresh the native Pi bridge. Indexing is skipped by default. |
| `/cbm-install --index` | Opt in to indexing the current project after setup. |
| `/cbm-install --no-index` | Explicitly skip project indexing. |
| `/cbm-install --dry-run` | Show the lifecycle plan without consent prompts or mutations. |
| `/cbm-install --yes` | Give explicit consent in a non-interactive runner. |
| `/cbm-install --dir <path>` | Select the official managed install directory. |
| `/cbm-install --force` | Run the official managed lifecycle even when the binary is already present. `-f` is an alias. |
| `/cbm-index` | Index the current project without changing binary or bridge state. |
| `/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. The adapter caps injected hook context and avoids adding a context block already present in the result. 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 fallback when the bridge is missing or incompatible. A ready bridge's embedded path is authoritative. |
| `CBM_INSTALL_DIR` | `~/.local/bin` | Destination used by `/cbm-install`; `~` is expanded. |
| `PI_CODING_AGENT_DIR` | `~/.pi/agent` | Pi agent directory where the generated native bridge is written. |
| `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:

```bash
CBM_BIN=/opt/codebase-memory-mcp pi
```

```bash
CBM_HOOKS_DEBUG=1 pi
```

## Installation alternatives

Install from the Git repository when testing unreleased changes:

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

Or load a local clone:

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

Remove the Pi package with:

```bash
pi remove npm:pi-codebase-memory-hooks
```

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

## Package layout

```text
extensions/
├── cbm-graph-context.ts   # Thin Pi → official hook-augment adapter
├── cbm-bootstrap.ts       # /cbm-install, /cbm-index, and /cbm-status
├── cbm-bridge.ts          # Schema-aware native bridge source generator
├── 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

```bash
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](https://pi.dev/packages). 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-index`, or run `/cbm-install --index`. Installation deliberately skips indexing unless you opt in.

### MCP tools are not visible after installation

Run `/reload` or restart Pi. The native 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 is a default native Pi extension with schema-aware `cbm_*` tools, lazy advanced tools, bounded output, an embedded official binary path, and machine-readable CLI results. The pinned installer script is SHA-256 verified. Legacy generic `{ args: string }` bridges are reported as incompatible and regenerated.

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](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md)
- [Pi package catalog](https://pi.dev/packages)
- [codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- [Report an issue](https://github.com/ramaaudra/pi-codebase-memory-hooks/issues)