tracegrep

tracegrep

tracegrep layers backtrace context on top of rg (ripgrep) results. It exists to give coding agents instant context for how a line of code is used in the codebase. This allows the agent to gain a more complete understanding prior to making changes. Rust, Python, TypeScript, and JavaScript are currently supported via treesitter.

This repo includes a Claude Code plugin with a search skill and hooks (PreToolUse search guidance, PostToolUse call-graph annotations, SessionStart context injection), plus a standalone SKILL.md for Codex and Cursor.

tracegrep maintains a mostly compatible CLI to ripgrep.

$ rg tool_block

212:    let blocks = extract_tool_blocks(session_events);
279:fn extract_tool_blocks(events: &[StreamEvent]) -> Vec<ToolBlock> {

$ tg tool_block

src/daemon/stream.rs:append_tool_data_effects
212:    let blocks = extract_tool_blocks(session_events);
  Called by:
    src/daemon/stream.rs:process_lead_output:110  (when events.get(main_lead_session_name) is Some(lead_events) && ...)

src/daemon/stream.rs:extract_tool_blocks
279:fn extract_tool_blocks(events: &[StreamEvent]) -> Vec<ToolBlock> {
  Called by:
    src/daemon/stream.rs:append_tool_data_effects:206
    src/daemon/stream.rs:process_agent_output:552  (when events.get(name.as_str()) is Some(coworker_events))

Installation

Note: installation differs by environment. The CLI installs with Cargo. Claude Code can also load the plugin (skill + hooks) via the repo's plugin metadata.

CLI (quick install)

curl -fsSL https://raw.githubusercontent.com/btucker/tracegrep/main/install.sh | sh

This downloads the latest release binary for your platform and installs it to ~/.local/bin. You can customize the install directory:

curl -fsSL https://raw.githubusercontent.com/btucker/tracegrep/main/install.sh | INSTALL_DIR=/usr/local/bin sh

Or install a specific version:

curl -fsSL https://raw.githubusercontent.com/btucker/tracegrep/main/install.sh | VERSION=v0.1.0 sh

CLI (from source)

Install rg first, then install tracegrep from this repo:

cargo install --path .

This installs both tracegrep and tg.

Then install shell completions:

tg --install-completions

tg auto-detects bash, zsh, or fish from $SHELL. For bash and zsh, it also updates your shell rc file so completions load in new shells. Restart the shell after installation, or source the updated rc file once.

Claude Code (via Plugin Marketplace)

In Claude Code, register the repository marketplace first:

/plugin marketplace add btucker/tracegrep

Then install the plugin from that marketplace:

/plugin install tracegrep@tracegrep-dev

Codex and other agents

Use the CLI directly and point the agent at the local skill file:

skills/tracegrep/SKILL.md

That keeps the setup explicit: the agent gets the search workflow from the skill, and tg provides the actual search behavior.

Verify installation

Verify the CLI:

tracegrep --version
tg --help
tg --generate complete-zsh | head

In Claude Code, start a fresh session and ask it to search the repo. It should prefer tg/tracegrep-aware search flow rather than raw rg. When installed as a Claude Code plugin, tracegrep also ships a PreToolUse hook for the Grep and Search tools that blocks direct usage and tells Claude to run tg through the Bash tool instead. This does not block grep or tg commands that Claude runs inside Bash.

Usage

After cargo install --path ., both tracegrep and tg are installed.

# Install completions once for the current shell
tg --install-completions

# Search with caller/reference context
tg tool_data /path/to/repo

# Inline context onto the location line
tg --compact tool_data /path/to/repo

# Include test callers when they matter
tg --include-tests --include-test-callers tool_data /path/to/repo

# Search a subset of the repo with rg-style path arguments
tg tool_data src tests

# Emit a completion script without installing it
tg --generate complete-zsh

Caching

• Each supported language is cached separately under .git/tracegrep/ by default, then merged in memory at query time.
• Set TRACEGREP_CACHE_DIR to override the cache root directory.
• The call graph is rebuilt automatically when the relevant per-language cache is missing or its stored HEAD no longer matches the repo.

Limits

• Most rg flags can be passed through before <pattern>, but tools that expect raw rg output should keep using rg.
• Function references passed as arguments are shown separately from direct callers.
• The current resolver is heuristic and language-local; it does not attempt import-aware or type-aware cross-file analysis.