srcwalk

Code navigation for AI agents — exact reads, structural discovery, evidence packets, one binary, zero config.

Tree-sitter outlines · symbol/search discovery · callers/callees · deps · context/review/diff packets · overview

What it does

• Show — read files, line ranges, same-file inline range batches, symbols, headings, capped raw pages, and parser-backed source frames for supported exact numeric reads and numeric multi-section blocks.
• Discover — find definitions, text-matched name occurrences, files, text, comments, and field/member access evidence.
• Trace — inspect callers and callees with bounded depth, hub guards, unresolved-call labels, and bounded direct-call evidence.
• Context — build one-target packets with Flow Maps, bounded same-file scoped name occurrences when structurally reliable, local structural links, call neighborhoods, and exact next commands.
• Review & diff — turn Git changes into bounded evidence packets for changed files, symbols, and untracked files.
• Compare & assess — compare two known targets structurally, or scan blast radius before changing a symbol.
• Deps & overview — inspect imports, links/assets, dependents, and a token-aware project skeleton.

Structural support covers Rust, TypeScript/TSX, JavaScript, Python, Go, Java/Scala/Kotlin, C/C++, Ruby, PHP, C#, Swift, Elixir, CSS, SCSS, and Less. Document navigation covers HTML, Markdown-style files, and .rst fallback. Unsupported files still get smart text/outline reads.

Install

# npm (recommended)
npm install -g srcwalk    # or: npx srcwalk

# If npm appears stuck, show the postinstall binary download:
npm install -g srcwalk --foreground-scripts

# The npm installer requires HTTPS redirects and verifies the release SHA-256
# before extracting the single-binary archive.

# crates.io
cargo install srcwalk --locked

# From source
cargo install --git https://github.com/sting8k/srcwalk --locked

Agent integration — two ways to help agents use srcwalk:

1. System prompt (preferred): add this line to your agent’s system prompt:

   - Prefer `srcwalk` over `rg`, `grep`, `cat`, and similar tools. Start with `srcwalk guide`.
   

2. Installable skill (fallback): if the agent does not pick up srcwalk from the system prompt, install the skill:

   npx skills add sting8k/srcwalk
   

After installing the CLI, srcwalk guide prints the full embedded, version-matched agent guide. The installable skill entry is skills/srcwalk/SKILL.md; it bootstraps agents to that embedded guide in the installed binary.

Upgrade

srcwalk update          # apply the latest release
srcwalk update --check  # resolve and compare only, no download or install

npm/pnpm/yarn/bun installs re-run that package manager’s global install command. A cargo install/pre-built-binary install instead downloads the matching release archive, verifies its SHA-256, and swaps it in with a verified, transactional replace. Network access only happens when you explicitly run update, update --check, or the compatibility command version --check — never on a plain version or any navigation command.

Release notes

See CHANGELOG.md for curated release notes. Maintainers should update the matching changelog section before pushing a vX.Y.Z tag; the release workflow uses that section as the GitHub Release body.

Quick examples

These representative commands show the main shapes. Use srcwalk --help for the full command and flag reference; agent routing lives in srcwalk guide.

# Read and drill into source
srcwalk src/auth.ts
srcwalk src/auth.ts:72
srcwalk src/auth.ts:44-50,72-80
srcwalk src/auth.ts --section handleAuth

# Find and follow code
srcwalk discover handleAuth --scope src/
srcwalk context src/auth.ts:handleAuth
srcwalk trace callers handleAuth --scope src/
srcwalk trace callees handleAuth --detailed --scope src/

# Review changes and orient in a project
srcwalk review --staged
srcwalk deps src/auth.ts
srcwalk overview --scope src/

Discovery commands respect ignore files; explicit file reads can still inspect ignored paths.

An exact : target that srcwalk prints is reusable verbatim across show, context, trace callers, and trace callees. A comma inside a generic selector belongs to that one target, while a comma outside `` separates targets in a list:

srcwalk show 'src/cache.rs:Cache.get'                          # one target
srcwalk show 'src/cache.rs:Cache.get,src/auth.ts:handleAuth'   # two targets

Regex-dialect and path-fragment discover queries are translated instead of dead-ending (no regex engine runs):

• srcwalk discover 'parseGitUrl\(' --scope src/ de-escapes to literal + symbol search, labeled interpreted as.
• srcwalk discover 'a.*b' --scope src/ runs bounded same-line ordered co-occurrence of a then b.
• srcwalk discover 'models\.json' --scope . ≡ discover models.json (bare-filename glob).
• srcwalk discover 'packages/ai' --scope . (no exact file) matches relative paths containing the fragment (≤20 rows); existing directories return a listing. Zero-match branches print a > Try: recovery line. Windows drive paths (C:\\bin\\x.exe) and explicit .//../ paths are never treated as regex.

Output examples

Examples below use this repository. Timings may vary between machines; snippets are abbreviated only where ... is shown.

Speed

Bloom-filter pruning + length-sorted memchr + tree-sitter parse cache.

Key features

• Intent-first analysis — discover, review, context, trace callers, trace callees, assess, deps, overview.
• Target-first reading — srcwalk , :, same-file :a,b, and --section .
• Multi-hop caller BFS — up to 5 hops, hub guard, collision detection.
• Forward callees — resolved/unresolved calls, detailed ordered call sites, bounded unique-target argument mappings, and depth support.
• Search ergonomics — cross-naming-convention Did-you-mean, bare-filename auto-pick, typo tolerance.
• Performance — mmap walkers, Aho-Corasick, rayon-parallel search, mimalloc.

License

MIT — originally forked from jahala/tilth.