pi-cymbal

Standalone Pi extension for Cymbal code navigation.

@cheriki/pi-cymbal bundles Cymbal v0.13.5 binaries for macOS arm64/x64 and Linux arm64/x64. Users install one Pi package:

pi install npm:@cheriki/pi-cymbal

Before the npm package is published, install directly from GitHub:

pi install git:github.com/miladcheriki/pi-cymbal-standalone

No Homebrew, Go, or separate Cymbal install is required. Windows is not bundled in this release.

Security note: Pi packages execute local code. This package includes prebuilt Cymbal binaries pinned to v0.13.5; the vendoring script verifies upstream release checksums, the repository tracks checksums for the extracted binaries, and bundled license notices are included in THIRD_PARTY_NOTICES.md.

Tools

Pi tool	Cymbal command
cymbal_investigate	cymbal investigate <symbol>
cymbal_search	cymbal search <query>
cymbal_show	cymbal show <target>
cymbal_outline	cymbal outline <file>
cymbal_refs	cymbal refs <symbol>
cymbal_graph	`cymbal trace
cymbal_structure	cymbal structure
cymbal_index	cymbal index [path]

The tool names are prefixed to avoid collisions with generic Pi tools and other code navigation packages.

Slash Command

/cymbal status shows the current platform, bundled binary path, binary source, and Cymbal version.

/cymbal remind runs:

cymbal hook remind --format=text

/cymbal config shows default limits, timeouts, and binary source.

Binary Resolution

For local development, set PI_CYMBAL_BIN to override the bundled binary:

export PI_CYMBAL_BIN=/absolute/path/to/cymbal

Without the override, pi-cymbal selects the bundled binary for process.platform and process.arch.

Supported bundled platforms:

• darwin-arm64
• darwin-x64
• linux-arm64
• linux-x64

Unsupported platforms return a clear tool error.

The package intentionally ships all supported macOS/Linux binaries in one npm tarball so pi install npm:@cheriki/pi-cymbal works without a separate Cymbal install. The package is large because of those bundled binaries.

Output

Tools default to Cymbal's agent-native text output. Pass json: true on tools where structured output is useful.

Large outputs are capped before returning to the model. The truncation note suggests narrowing the symbol/path, lowering a limit, or using graph limits.

On very large repositories, the first Cymbal call may spend time building the SQLite index. If a normal tool times out on first use, run cymbal_index once from Pi and retry the original request.

Development

npm install
npm run vendor
npm run validate

Local Pi smoke test:

pi install .
/reload

Then ask Pi to use cymbal_investigate in a Git repository.

Publishing

The npm package is scoped as @cheriki/pi-cymbal to avoid conflicting with the existing unscoped pi-cymbal package.

The included GitHub Actions workflows validate pull requests and publish on release when npm trusted publishing is configured.

License

MIT. See THIRD_PARTY_NOTICES.md for bundled Cymbal notices.