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|impact|importers|impls <target> --graph | | 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.