cymbal CLI
A tree-sitter code navigator: a local SQLite index answers an agent about symbols, callers and change impact in milliseconds
- 377 ★ on the repository
- Last commit
- MIT
Minimal access
Why this level
- cymbal reads source files and writes only its own local SQLite index, while hooks change hints for the agent.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/cymbalDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewMinimal accessThe tool runs nothing and makes no network calls.
- cymbal reads source files and writes only its own local SQLite index, while hooks change hints for the agent.
This is third-party code. Review the repository files before installing.
What it does
cymbal parses a repository into a local SQLite index and answers questions about code from the terminal or an agent. The index builds itself on the first query and later reparses only changed files. Three commands cover most investigations. `cymbal investigate` returns a symbol's source, its callers and impact or class members in one call. `cymbal trace` shows what a symbol depends on, and `cymbal impact` shows what breaks if it changes, split into production code and tests. `cymbal changed` turns the current git diff into a list of affected symbols and their impact. `cymbal hook install claude-code` and `cymbal hook install opencode` connect cymbal to the agent and gently steer it from grep and find to the index. Go, Python, JavaScript, TypeScript, Rust, C and C++, C#, Java, Ruby, Swift, Kotlin, PHP and a dozen more languages are supported.
Who it is for. Developers on large or unfamiliar codebases where the agent burns tokens on grep chains and reading whole files.
Good fit when
- The agent loops through search, show and refs and loses context on a big repository.
- Before refactoring a function you need all callers, split into code and tests.
- A pull request touches a dozen files, and you want to know which symbols and modules it affects.
- A newcomer needs a dependency map around a module as a graph.
Not a fit when
- The project uses a language cymbal has no tree-sitter grammar for, such as Haskell or Zig.
- You need semantic search over code meaning through embeddings.
- The repository has a couple of files, and plain reading is enough.
Example request
Use cymbal to show what breaks if the handleAuth signature changes, separately for code and tests.Limitations
Only languages with a tree-sitter grammar and symbol, import and reference extraction are indexed. Haskell, Zig, Erlang, OCaml, R and Perl are recognized by file type but not indexed. Ready hook installers exist only for Claude Code and OpenCode, and HOOKS.md has snippets for other agents. The grep-to-cymbal nudge in OpenCode does not work in Windows shells. cymbal never updates itself and only suggests the update command.
How to disable. Run `cymbal hook uninstall claude-code` or `cymbal hook uninstall opencode`, then `brew uninstall cymbal`. Indexes sit in cymbal's data folder, on Windows in `%LOCALAPPDATA%\cymbal\repos\`.
FAQ
How do I connect cymbal to Claude Code?
Run `cymbal hook install claude-code`. The hook reminds the agent to start with `cymbal investigate` and steers it from grep and find to the index.
Do I have to build the index by hand?
No, it builds itself on the first query and refreshes changed files. `cymbal index .` is only an optional warm-up.
How many tokens does cymbal save?
In the author's tests on 11 repositories, focused investigations use 40–100% fewer tokens than grep chains. Most queries finish in 10–40 ms.
Can I get a dependency graph?
Yes, `--graph` on `trace`, `impact`, `importers` and `impls` draws a visual map. Without it the output is text, and `--json` gives structured output.
How do I assess the impact of uncommitted changes?
`cymbal changed` takes the git diff of the working tree, `--staged` or `--base` and lists affected symbols with their impact.
Discussion
No questions or reviews yet.
Related
CLI toolsA Rust CLI that indexes code symbols locally so agents search by structure instead of grep and spend 40-50% fewer tokens.
A local semantic code index: the agent searches by meaning, then follows hits into definitions, callers and dependency paths
A local MCP server builds a SQLite and tree-sitter code index so an agent finds symbols, calls and meaning in one query
A Rust MCP server and CLI with a call graph and hybrid semantic code search for Claude Code and Codex
A local code graph answers agent questions about symbols and callers, so they reread whole files far less often.
Local code graph for agents: an MCP server returns entry points, symbol links and change impact in one call
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| cymbal (this card) | no | 377 | ||
| Serena | no | not required | 31,335 | an MCP server with semantic tools through language servers; here a CLI with a tree-sitter index and hooks, no server |
| ast-grep | no | 16,589 | syntax tree pattern search and rewrite; here callers, dependencies and change impact from an index |
README in short
The README lists install options, a quick start and a table of all commands. Separate sections show graph mode, benchmark results on 11 repositories and rules for agents, with the full manual in MANUAL.md.