https://github.com/btucker/tracegrep
grep with backtrace context for coding agents
https://github.com/btucker/tracegrep
claude-code codex cursor ripgrep
Last synced: 2 months ago
JSON representation
grep with backtrace context for coding agents
- Host: GitHub
- URL: https://github.com/btucker/tracegrep
- Owner: btucker
- License: mit
- Created: 2026-03-09T14:20:41.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-17T19:38:18.000Z (3 months ago)
- Last Synced: 2026-03-18T09:19:46.104Z (3 months ago)
- Topics: claude-code, codex, cursor, ripgrep
- Language: Rust
- Homepage:
- Size: 252 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# tracegrep
`tracegrep` layers backtrace context on top of `rg` ([ripgrep](https://github.com/BurntSushi/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](https://github.com/tree-sitter/tree-sitter).
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`
```rust
212: let blocks = extract_tool_blocks(session_events);
279:fn extract_tool_blocks(events: &[StreamEvent]) -> Vec {
```
`$ tg tool_block`
```rust
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 {
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)
```bash
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:
```bash
curl -fsSL https://raw.githubusercontent.com/btucker/tracegrep/main/install.sh | INSTALL_DIR=/usr/local/bin sh
```
Or install a specific version:
```bash
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:
```bash
cargo install --path .
```
This installs both `tracegrep` and `tg`.
Then install shell completions:
```bash
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:
```text
/plugin marketplace add btucker/tracegrep
```
Then install the plugin from that marketplace:
```text
/plugin install tracegrep@tracegrep-dev
```
### Codex and other agents
Use the CLI directly and point the agent at the local skill file:
```text
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:
```bash
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.
```bash
# 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 ``, 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.