cymbal

Overview

Cymbal indexes a repository once, then answers structural questions about it from that index. Not "which files contain this string" — what is this symbol, who calls it, what does it call, and what breaks if it changes.

The index is SQLite, per repo, built by tree-sitter parsers. Indexing is a one-time cost measured in milliseconds for most repos; every query after that reads the database rather than the filesystem. There is no daemon, no server, and no model in the loop — every answer is derived from the index.

Install

Homebrew is the shortest path on macOS and Linux.

$ brew install 1broseidon/tap/cymbal

If you are pointing a coding agent at a fresh repo, hand it this instead.

Install cymbal and index this repo for me.
1. Run: brew install 1broseidon/tap/cymbal
2. Run `cymbal index .` at the repo root.
3. Run `cymbal structure` and summarise the entry points for me.
4. Run `cymbal hook install claude-code` so you keep using it.
From here on, prefer `cymbal search` over grep for symbol lookup,
`cymbal show <sym>` over reading a whole file, and
`cymbal impact <sym>` before changing anything shared.

$ yay -S cymbal

> irm https://raw.githubusercontent.com/1broseidon/cymbal/main/install.ps1 | iex

$ CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" go install github.com/1broseidon/cymbal@latest

$ docker pull ghcr.io/1broseidon/cymbal:latest

# Mount a repo and run cymbal inside the container
$ docker run --rm -v "$(pwd)":/workspace ghcr.io/1broseidon/cymbal index .

# Worth aliasing if you use this flow regularly
$ alias cymbal='docker run --rm -v "$(pwd)":/workspace ghcr.io/1broseidon/cymbal'

Quickstart

Index once, then ask. Indexing a subdirectory updates that subtree in place — files outside it are neither reparsed nor pruned.

$ cymbal index .
indexed 105 files · 1921 symbols

# "I've never seen this repo — where do I start?"
$ cymbal structure

# Everything about one symbol, shaped to what it is
$ cymbal investigate OpenStore

# What breaks if I change this?
$ cymbal impact handleRegister -D 3

Queries refresh the index automatically, so you rarely re-run index by hand. Pass -f to force a full re-index.

Choosing a command

Three commands cover most questions, and they differ only in which way they walk the call graph. Getting this right is most of the tool.

Commands

Nineteen commands. Four flags are global; everything else is per-command.

Passive update notices are suppressed automatically under --json. Set CYMBAL_NO_UPDATE_NOTIFIER=1 to disable them entirely.

Graph output

trace, impact, importers and impls accept --graph when you want a relationship map rather than call-site detail. The default format is Mermaid on a TTY and JSON when piped; --graph-format mermaid|dot|json forces one. --graph-limit <n> caps dense graphs by degree, and impact --graph defaults to depth 1 unless you pass --depth yourself.

Stay on the normal text or JSON output when you need exact source lines or call sites you intend to edit against.

$ cymbal investigate OpenStore
$ cymbal investigate config.go:Config   # file hint
$ cymbal investigate auth.Middleware    # package hint
$ cymbal investigate Foo Bar Baz        # batch

$ cymbal search ParseFile
$ cymbal search --text TODO cmd internal/foo.go
$ cymbal search Foo Bar        # independent queries

$ cymbal show ParseFile
$ cymbal show App.handleSave                  # nested, qualified
$ cymbal show store.go:SearchSymbols          # narrowed by file hint
$ cymbal show internal/index/store.go:80-120  # line range
$ cymbal outline big.go -s --names | cymbal show --stdin

$ cymbal impact handleRegister
$ cymbal impact Save Load Delete   # union of callers
$ cymbal impact Save -D 3 --graph  # mermaid on a TTY

$ cymbal trace handleRequest
$ cymbal trace pkg/file.go:Name --include-unresolved

$ cymbal context OpenStore
$ cymbal context ParseFile --callers 10

$ cymbal impls Reader
$ cymbal impls Reader Writer Closer
$ cymbal impls Plugin --lang go
$ cymbal impls --of TimerActivityIntent   # inverse direction

$ cymbal changed              # unstaged, working tree vs index
$ cymbal changed --staged     # staged, index vs HEAD
$ cymbal changed --base main  # working tree vs a ref

$ cymbal diff ParseFile          # vs HEAD
$ cymbal diff ParseFile main     # vs a branch
$ cymbal diff --stat ParseFile   # diffstat only

$ cymbal outline internal/index/store.go -s
$ cymbal outline big.go --names | cymbal investigate --stdin

$ cymbal structure -n 20

$ cymbal ls --stats           # languages, file and symbol counts
$ cymbal ls --names --lang go
$ cymbal ls --repos

$ cymbal importers internal/index/store.go -D 2

$ cymbal hook install claude-code
$ cymbal hook install opencode

$ cymbal version
cymbal v0.15.0
  commit: ac79440
  go:     go1.26.7 linux/amd64

For agents

Cymbal was built to be called by something that isn't a person. Four properties matter for that.

Frontmatter, not JSON

The default output is YAML frontmatter followed by a content body — metadata an agent can parse, then source it can read. JSON quotes every field name and escapes every string; on the same refs result the frontmatter form runs about a third fewer tokens, which compounds across dozens of calls in one task.

---
symbol: handleAuth
total: 3
groups: 2
---

cmd/server/main.go (1 site):
  > handleAuth(w, r)

internal/api/router.go (2 sites):
  > mux.HandleFunc("/auth", handleAuth)
  > handleAuth(w, r)

Identical call sites in the same file are grouped, so the agent sees the pattern without paying for the repetition.

--json everywhere

Every command takes the global --json flag and returns structured output. Batch commands key their result map by the name you asked for, so a single call can dispatch several lookups.

Batching over round-trips

Most query commands accept multiple symbols, and --stdin reads newline-separated names. One call beats five.

$ cymbal show Foo Bar Baz
$ cymbal outline svc.go -s --names | cymbal investigate --stdin

Hooks that hold the line

Agents drift back to raw grep as their context fills. Prompting alone erodes; two agent-agnostic subcommands wire into whatever hook point a runtime offers.

Claude Code and OpenCode have first-class installers. Cursor, Windsurf, aider, Cline, Continue, Zed and the OpenAI Agents SDK wire the two subcommands in by hand — HOOKS.md has the snippet for each.

Languages

Thirty-nine languages are registered, in two tiers. Twenty-two ship a tree-sitter grammar and are parsed into symbols; the rest are recognised for the file inventory and text search but produce no symbol graph.

Parsed to symbols — 22

go · python · javascript · typescript · tsx · rust · ruby · java · c · cpp · csharp · dart · swift · kotlin · lua · php · bash · scala · yaml · elixir · hcl · protobuf

Recognised only — 17

apex · zig · toml · json · markdown · sql · erlang · haskell · ocaml · r · perl · vue · svelte · make · dockerfile · groovy · cmake

Notes

References are name-scoped

Cymbal resolves references by name against the AST, not by full semantic analysis. When a name has several definitions, counts may span them — that is reported as definition_count rather than hidden. Treat refs and impls as high-quality leads, not proofs.

The index follows the working tree

changed answers "what is affected now", so its impact data comes from the working-tree index. Arbitrary commit ranges whose new side isn't the working tree aren't supported.

Federation across worktrees

Symbols federate across worktrees of the same repo by default, so a query in one worktree can resolve into another. Pass --no-federate to restrict to a single database.