{"id":49034380,"url":"https://github.com/btucker/tracegrep","last_synced_at":"2026-04-19T10:35:54.939Z","repository":{"id":343510450,"uuid":"1176928831","full_name":"btucker/tracegrep","owner":"btucker","description":"grep with backtrace context for coding agents","archived":false,"fork":false,"pushed_at":"2026-03-17T19:38:18.000Z","size":258,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-18T09:19:46.104Z","etag":null,"topics":["claude-code","codex","cursor","ripgrep"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/btucker.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-09T14:20:41.000Z","updated_at":"2026-03-17T19:38:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/btucker/tracegrep","commit_stats":null,"previous_names":["btucker/tracegrep"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/btucker/tracegrep","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/btucker%2Ftracegrep","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/btucker%2Ftracegrep/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/btucker%2Ftracegrep/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/btucker%2Ftracegrep/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/btucker","download_url":"https://codeload.github.com/btucker/tracegrep/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/btucker%2Ftracegrep/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32004041,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"online","status_checked_at":"2026-04-19T02:00:07.110Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","codex","cursor","ripgrep"],"created_at":"2026-04-19T10:35:50.943Z","updated_at":"2026-04-19T10:35:54.929Z","avatar_url":"https://github.com/btucker.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tracegrep\n\n`tracegrep` layers backtrace context on top of `rg` ([ripgrep](https://github.com/BurntSushi/ripgrep)) results.\nIt 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.\nRust, Python, TypeScript, and JavaScript are currently supported via [treesitter](https://github.com/tree-sitter/tree-sitter).\n\nThis 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.\n\n`tracegrep` maintains a mostly compatible CLI to `ripgrep`.\n\n`$ rg tool_block`\n\n```rust\n212:    let blocks = extract_tool_blocks(session_events);\n279:fn extract_tool_blocks(events: \u0026[StreamEvent]) -\u003e Vec\u003cToolBlock\u003e {\n```\n\n`$ tg tool_block`\n\n```rust\nsrc/daemon/stream.rs:append_tool_data_effects\n212:    let blocks = extract_tool_blocks(session_events);\n  Called by:\n    src/daemon/stream.rs:process_lead_output:110  (when events.get(main_lead_session_name) is Some(lead_events) \u0026\u0026 ...)\n\nsrc/daemon/stream.rs:extract_tool_blocks\n279:fn extract_tool_blocks(events: \u0026[StreamEvent]) -\u003e Vec\u003cToolBlock\u003e {\n  Called by:\n    src/daemon/stream.rs:append_tool_data_effects:206\n    src/daemon/stream.rs:process_agent_output:552  (when events.get(name.as_str()) is Some(coworker_events))\n```\n\n## Installation\n\nNote: installation differs by environment. The CLI installs with Cargo. Claude Code can also load the plugin (skill + hooks) via the repo's plugin metadata.\n\n### CLI (quick install)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/btucker/tracegrep/main/install.sh | sh\n```\n\nThis downloads the latest release binary for your platform and installs it to `~/.local/bin`. You can customize the install directory:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/btucker/tracegrep/main/install.sh | INSTALL_DIR=/usr/local/bin sh\n```\n\nOr install a specific version:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/btucker/tracegrep/main/install.sh | VERSION=v0.1.0 sh\n```\n\n### CLI (from source)\n\nInstall `rg` first, then install `tracegrep` from this repo:\n\n```bash\ncargo install --path .\n```\n\nThis installs both `tracegrep` and `tg`.\n\nThen install shell completions:\n\n```bash\ntg --install-completions\n```\n\n`tg` auto-detects `bash`, `zsh`, or `fish` from `$SHELL`. For `bash` and `zsh`,\nit also updates your shell rc file so completions load in new shells. Restart the\nshell after installation, or source the updated rc file once.\n\n### Claude Code (via Plugin Marketplace)\n\nIn Claude Code, register the repository marketplace first:\n\n```text\n/plugin marketplace add btucker/tracegrep\n```\n\nThen install the plugin from that marketplace:\n\n```text\n/plugin install tracegrep@tracegrep-dev\n```\n\n### Codex and other agents\n\nUse the CLI directly and point the agent at the local skill file:\n\n```text\nskills/tracegrep/SKILL.md\n```\n\nThat keeps the setup explicit: the agent gets the search workflow from the skill, and `tg` provides the actual search behavior.\n\n### Verify installation\n\nVerify the CLI:\n\n```bash\ntracegrep --version\ntg --help\ntg --generate complete-zsh | head\n```\n\nIn 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`.\nWhen 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`.\n\n## Usage\n\nAfter `cargo install --path .`, both `tracegrep` and `tg` are installed.\n\n```bash\n# Install completions once for the current shell\ntg --install-completions\n\n# Search with caller/reference context\ntg tool_data /path/to/repo\n\n# Inline context onto the location line\ntg --compact tool_data /path/to/repo\n\n# Include test callers when they matter\ntg --include-tests --include-test-callers tool_data /path/to/repo\n\n# Search a subset of the repo with rg-style path arguments\ntg tool_data src tests\n\n# Emit a completion script without installing it\ntg --generate complete-zsh\n```\n\n## Caching\n\n- Each supported language is cached separately under `.git/tracegrep/` by default, then merged in memory at query time.\n- Set `TRACEGREP_CACHE_DIR` to override the cache root directory.\n- The call graph is rebuilt automatically when the relevant per-language cache is missing or its stored `HEAD` no longer matches the repo.\n\n## Limits\n\n- Most `rg` flags can be passed through before `\u003cpattern\u003e`, but tools that\n  expect raw `rg` output should keep using `rg`.\n- Function references passed as arguments are shown separately from direct callers.\n- The current resolver is heuristic and language-local; it does not attempt import-aware or type-aware cross-file analysis.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbtucker%2Ftracegrep","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbtucker%2Ftracegrep","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbtucker%2Ftracegrep/lists"}