---
slug: "cheriki-pi-cymbal"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/miladcheriki/pi-cymbal-standalone@main/README.md"
repo: "https://github.com/miladcheriki/pi-cymbal-standalone"
source_file: "README.md"
branch: "main"
---
# 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:

```sh
pi install npm:@cheriki/pi-cymbal
```

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

```sh
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:

```sh
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:

```sh
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

```sh
npm install
npm run vendor
npm run validate
```

Local Pi smoke test:

```sh
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.