pi-cymbal

Pi extension for Cymbal.

Cymbal is agent-native code navigation. It indexes code with tree-sitter and returns symbol, reference, import, and diff context for agents.

Why this package?

Pi has file and shell tools. pi-cymbal adds Cymbal tools so agents can inspect indexed code before using broad grep, find, or read loops.

Features

• Adds cymbal_* tools to Pi.
• Searches symbols and text through Cymbal's index.
• Reads symbols, files, and line ranges with cymbal_show.
• Inspects references, impacts, imports, implementations, and symbol diffs.
• Runs Cymbal nudges before eligible bash, grep, find, and read calls.
• Leaves original tool calls unchanged.

Requirements

• Pi on Node.js >=22.19.0
• Cymbal v0.14.0. CI pins this version for the documented tool and flag surface. Other versions may expose a different command contract.
• Cymbal binary on PATH, or CYMBAL_BIN set

export CYMBAL_BIN=/absolute/path/to/cymbal

Install

pi install npm:pi-cymbal

From GitHub:

pi install git:github.com/raphapr/pi-cymbal

Local development:

pi --no-extensions -e .

--no-extensions avoids conflicts with an already installed pi-cymbal.

Quick start

Use Cymbal to map this repo before editing.

Find references to registerCymbalHooks with Cymbal.

Available tools

Need	Pi tool	Cymbal command
Repo overview	cymbal_map	cymbal ls [path] --stats
Structural summary	cymbal_structure	cymbal structure
Symbol search	cymbal_search	cymbal search <query>
Text search	cymbal_search with text: true	cymbal search --text <query>
File outline	cymbal_outline	cymbal outline <file>
Symbol, file, or range content	cymbal_show	cymbal show <target>
References	cymbal_refs	cymbal refs <symbol>
Upstream impact	cymbal_impact	cymbal impact <symbol>
Import relationships	cymbal_importers	cymbal importers <file-or-package>
Implementation relationships	cymbal_impls	cymbal impls <symbol>
Diff-scoped impact	cymbal_changed	cymbal changed
Symbol diff	cymbal_diff	cymbal diff <symbol> [base]
Explicit index refresh	cymbal_index	cymbal index [path]
Guided investigation	cymbal_investigate	cymbal investigate <symbol>
Call trace	cymbal_trace	cymbal trace <symbol>
Context bundle	cymbal_context	cymbal context <symbol>

Common workflows

Orient first

Use cymbal_map or cymbal_structure before editing unfamiliar code.

Useful params:

• cymbal_map: path, depth, stats, repos
• cymbal_structure: limit

Search and read narrowly

Use cymbal_search, cymbal_outline, and cymbal_show instead of broad grep/read loops.

Check relationships before refactors

Use cymbal_refs, cymbal_impact, cymbal_importers, and cymbal_impls before changing exported symbols or imports.

Review what your diff affects

Use cymbal_changed to see the changed symbols of your current git diff plus their references and transitive impact in one call, before refactors or PRs. Scope it with staged (staged changes) or base (diff against a git ref); the two cannot be combined. Tune the blast radius with depth, limit, maxSymbols, maxImpact, noTests, and resolveScope.

Cross-language and blast-radius params

• resolveScope (same | family | all, default family) on cymbal_impact, cymbal_trace, cymbal_investigate, and cymbal_changed constrains cross-language name resolution.
• noTests on cymbal_impact and cymbal_changed excludes callers in test files from the impact set.
• includeUnresolved keeps unresolved targets that are otherwise filtered out: on cymbal_trace it affects text, JSON, and graph output; on cymbal_impact it adds unresolved nodes to the graph output.
• graph, graphFormat (mermaid | dot | json), and graphLimit on cymbal_impact and cymbal_trace render call graphs, matching cymbal_importers and cymbal_impls.

Note: in Cymbal v0.14.0, single-symbol cymbal_trace/cymbal_impact --json output is object-shaped (previously array-wrapped). pi-cymbal only re-pretty-prints this JSON, so the change is surfaced verbatim.

Review diffs by symbol

Use cymbal_diff for a focused diff on one symbol.

Refresh the index only when needed

Use cymbal_index only when the index looks stale or the user asks to refresh it. Cymbal auto-indexes during normal navigation.

Agent nudges

At session start, pi-cymbal runs:

cymbal hook remind --format=text --update=if-stale

Before eligible bash, grep, find, and read calls, it runs:

cymbal hook nudge --format=json

Nudges do not block. They are hidden from TUI output. Pi may show them as notifications. Duplicate nudges are suppressed per cwd for 60s. Read and Glob suppress per tool.

Paths and Repos

pi-cymbal relies on Cymbal's Git repo auto-detection.

For non-Git directories, use Pi file tools such as find, grep, ls, and read.

Output

Tools default to Cymbal's agent-native text output.

Pass format: "json" for JSON:

Use cymbal_search with format json to find registerCymbalHooks.

Large outputs use bounded in-memory previews. Tool details include a session-managed temp-file path with the full output. Pi removes managed spill files on session shutdown. Cancellation terminates the Cymbal process tree before returning control.

Development

npm install
npm run validate

# Require the real pinned CLI smoke locally when Cymbal v0.14.0 is installed
REQUIRE_CYMBAL=1 CYMBAL_BIN="$(command -v cymbal)" \
  node --import tsx --test test/cli-smoke.test.mjs

Local Pi smoke:

pi --no-extensions -e . --no-session -p \
  "Use cymbal_structure to orient in this repo, then use cymbal_diff on registerCymbalHooks."

Build

The published extension entry is a single bundled dist/index.ts, produced by npm run build (run automatically by pretest and prepack). Bundling src/ into one file cuts Pi's startup module-load cost by ~75% versus loading the multi-file source graph.

The bundle is emitted as .ts, not .js, on purpose. Pi's loader runs extensions through jiti with tryNative: a .js entry loads natively and resolves @earendil-works/* from disk (a second framework copy, ~950ms), while a .ts entry keeps the jiti path that aliases the framework to Pi's already-loaded copies. Framework packages and typebox are kept external for the same reason. Do not switch the entry to .js.

Publishing

1. Bump package.json version.
2. Create a GitHub release with a matching tag, such as vX.Y.Z.
3. GitHub Actions validates and publishes with npm provenance.

Use the manual Publish to npm workflow with dry_run: true to test packaging. Every live publish must run from the exact v<package-version> tag and fails closed if npm version availability cannot be verified.

License

MIT