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
• Cymbal v0.13.5+ for the full tool set
• 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 /home/raphael/repos/github.com/raphapr/pi-cymbal

--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>
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 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 are truncated. Tool details include a temp-file path with the full output.

Development

npm install
npm run validate

Local Pi smoke:

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

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.

License

MIT