with one click
pathfinder
// Session bootstrap + workflows for Pathfinder semantic navigation tools. Covers: discovery protocol, tool chaining patterns (explore, impact, audit, debug), search optimization, LSP degraded mode, and error recovery.
// Session bootstrap + workflows for Pathfinder semantic navigation tools. Covers: discovery protocol, tool chaining patterns (explore, impact, audit, debug), search optimization, LSP degraded mode, and error recovery.
| name | pathfinder |
| description | Session bootstrap + workflows for Pathfinder semantic navigation tools. Covers: discovery protocol, tool chaining patterns (explore, impact, audit, debug), search optimization, LSP degraded mode, and error recovery. |
Before any code exploration or analysis, confirm Pathfinder is available:
mcp({ server: "pathfinder" })
Check once per session. Re-check only if a tool call fails with a connection error.
All Pathfinder tools that take a semantic_path require file_path::symbol_chain:
src/auth.ts::AuthService.logincrates/pathfinder/src/server.rs::PathfinderServer.newAuthService.login (interpreted as a file named "AuthService.login")login (interpreted as a file named "login")Bare file paths (no ::) are valid only for whole-file operations like read_source_file.
1. get_repo_map(path=".", depth=5, visibility="public")
ā Full project skeleton with semantic paths
ā Low coverage_percent? Increase max_tokens
ā Files show [TRUNCATED]? Increase max_tokens_per_file
ā Use changed_since="3h" to scope to recent changes
ā Use include_extensions=["ts","tsx"] for language focus
ā Use include_tests=false to exclude test symbols
2. search_codebase(query="<entry point>", path_glob="src/**/*")
ā Find main handlers, routes, or CLI commands
ā Copy enclosing_semantic_path for next step
ā Check files_searched/files_in_scope/coverage_percent for completeness
3. read_with_deep_context(semantic_path="<entry point>")
ā Source + signatures of everything it calls
ā First call may take 5-30s during LSP warmup
4. find_callers_callees(semantic_path="<key function>", max_depth=3)
ā Who calls it (incoming) + what it calls (outgoing)
Done when: You can explain the architecture and trace a request through the system.
1. read_with_deep_context(semantic_path="<target>")
ā Current code + dependency signatures
2. find_callers_callees(semantic_path="<target>", max_depth=3)
ā All callers = blast radius
ā For large API changes: use max_depth=4-5
ā When NOT degraded: empty arrays = LSP confirmed zero
3. For each caller:
read_symbol_scope(semantic_path="<caller>")
ā Verify assumptions about the target's interface
4. get_definition(semantic_path="<suspicious dependency>")
ā Jump to external dependency source
Rule: ALWAYS run find_callers_callees before recommending a refactor.
1. get_repo_map(path=".", depth=5, visibility="all")
2. For each module:
a. read_source_file(filepath="<file>", detail_level="source_only")
ā For targeted line reading (lowest tokens)
b. read_source_file(filepath="<file>", detail_level="compact")
ā For code + flat symbol list
c. read_with_deep_context(semantic_path="<complex function>")
d. search_codebase(query="<danger pattern>", is_regex=true)
Go: panic|log\.Fatal
Rust: unwrap\(\)|expect\(|panic!
Python: except:|pass\s+# noqa
TypeScript: as any|@ts-ignore
e. search_codebase(query="TODO|FIXME|HACK", filter_mode="comments_only")
3. For critical findings:
find_callers_callees(semantic_path="<problem>")
ā Blast radius before recommending changes
1. read_with_deep_context(semantic_path="<failing function>")
ā Source + all dependencies
2. get_definition(semantic_path="<suspicious call>")
ā Jump to the callee's definition
3. find_callers_callees(semantic_path="<failing function>", max_depth=1)
ā Find callers to understand inputs
4. search_codebase(query="<error message>")
ā Locate error origin
search_codebase parameters for token efficiency:
| Parameter | Default | Effect |
|---|---|---|
filter_mode | code_only | code_only skips comments/strings; comments_only for TODOs; all for everything |
path_glob | **/* | Scope search (e.g. src/**/*.ts) |
exclude_glob | "" | Skip files before reading (e.g. **/*.test.*) |
known_files | [] | Files already in context ā matches return metadata only, no content |
group_by_file | false | One version_hash per file group instead of per match |
is_regex | false | Regex mode (e.g. `unwrap() |
max_results | 50 | Cap results |
context_lines | 2 | Context above/below matches |
Coverage metadata:
files_searched ā actual files that were searchedfiles_in_scope ā files matching path_globcoverage_percent ā % of in-scope files searched. <100% means some files skipped.Search counts:
total_matches ā post-filter count (equals matches.len()). This is the ground truth.raw_match_count ā ripgrep pre-filter count (before filter_mode drops comments/strings).filtered_count ā raw_match_count - total_matches (how many rows were removed by the filter).truncated ā result set was capped at max_results. Increase max_results or narrow your query.Token-saving pattern:
search_codebase(query="deprecated_api",
known_files=["src/fileA.ts", "src/fileB.ts"],
exclude_glob="**/*.test.*",
group_by_file=true)
Use these parameters to prevent context-window overflow in large repos:
find_callers_callees budget parameters| Parameter | Default | Effect |
|---|---|---|
project_only | true | true = only workspace files (no stdlib/vendor); false = all references |
max_references | 50 | Hard cap on total BFS references returned across incoming + outgoing |
max_depth | 3 | BFS traversal depth (clamped 1ā5). Use 3 for standard refactoring, 4-5 for large-scale API changes. |
When references_truncated: true in the response, the budget was hit ā either increase max_references or decrease max_depth.
read_with_deep_context budget parameters| Parameter | Default | Effect |
|---|---|---|
project_only | true | true = filter stdlib/vendor callees; false = include all |
max_dependencies | 50 | Hard cap on outgoing dependency entries |
When dependencies_truncated: true in the response, increase max_dependencies to see more.
get_repo_map budget parameters| Parameter | Default | Effect |
|---|---|---|
max_tokens | auto | Auto-scales for repos > 20 files: clamp(file_count Ć 800, 16000, 48000) |
max_tokens_per_file | 2000 | Per-file skeleton cap before file is shown as a stub |
include_tests | true | Include test functions/modules regardless of visibility |
Check max_tokens_used in the response to see the effective budget applied.
Tools that use LSP: get_definition, find_callers_callees, read_with_deep_context, find_all_references.
Visual indicator: When degraded, text output starts with:
ā ļø DEGRADED ({reason}) ā {tool-specific guidance}
Every response includes degraded (bool), degraded_reason, and lsp_readiness:
degraded_reason | Meaning | Action |
|---|---|---|
null | LSP confirmed | Trust fully |
no_lsp | No language server available | Accept limited results |
lsp_warmup_empty_unverified | LSP indexing; empty = unverified | Re-run in 10-30s |
lsp_warmup_grep_fallback | LSP returned null; fell back to grep | Verify with read_source_file |
lsp_timeout_grep_fallback | LSP timed out; fell back to grep | Re-run or use tree-sitter tools |
lsp_error_grep_fallback | LSP error; fell back to grep | Check lsp_health |
no_lsp_grep_fallback | No LSP; fell back to grep | Install language server |
grep_fallback_file_scoped | File-scoped grep | Good confidence |
grep_fallback_impl_scoped | Impl-block grep | Good for methods |
grep_fallback_global | Global grep | Least precise ā verify |
unsupported_language_filter_bypassed | Language unsupported; filter bypassed | Results may include noise |
unsupported_language | Language not supported | Use read_file for raw content |
git_error | Git operation failed | get_repo_map changed_since fell back |
LSP Readiness values:
"ready" ā LSP is fully operational"warming_up" ā LSP still indexing"unavailable" ā No LSP availableCritical rule: When degraded: true, never treat empty results as confirmed-zero. Re-run after LSP finishes indexing, or check lsp_health.
Null vs Empty Array distinction:
incoming: null (or outgoing: null, references: null) ā unknown, degradedincoming: [] (or outgoing: [], references: []) ā LSP confirmed: truly zeroSYMBOL_NOT_FOUND with did_you_mean suggestions:
Error: SYMBOL_NOT_FOUND for "src/auth.ts::AuthServce.login"
data.details.did_you_mean: ["AuthService.login", "AuthService.logout"]
ā Use the corrected path from did_you_mean
ā If suggestions list is empty: use search_codebase(query="login") to find the right file
SYMBOL_NOT_FOUND ā no suggestions (wrong file):
Error: SYMBOL_NOT_FOUND, did_you_mean: []
ā The symbol probably lives in a different file
ā search_codebase(query="<symbol_name>") ā find file ā retry with correct path
LSP Timeout / Degraded Navigation:
degraded=true, degraded_reason="lsp_warmup_empty_unverified"
ā Check lsp_health for indexing status
ā Re-run after indexing completes
ā If no_lsp: use search_codebase + read_symbol_scope as fallback
If get_definition("logic.go::CompleteLesson") returns SYMBOL_NOT_FOUND,
the symbol might be defined in a different file. The semantic path requires the
actual file where the symbol is defined, not just any file in the module.
Solution:
search_codebase(query="CompleteLesson") to find which file defines the symbolread_source_file(filepath="logic.go", detail_level="symbols") to see all symbols in a specific file| File Type | Tool | Why |
|---|---|---|
| .rs, .go, .ts, .tsx, .js, .jsx, .py, .vue | read_source_file | AST parsing, symbol extraction, semantic paths |
| .yaml, .yml, .toml, .json, .env, .md, .txt, Dockerfile, package.json | read_file | Raw content, no AST needed |
| Unknown | read_file | Safe default, returns raw text |
| Option | Output | Use Case |
|---|---|---|
source_only | Source code only | Lowest token cost, targeted reading |
compact (default) | Source + flat symbol list | General purpose |
symbols | Symbol tree only, no source | Discover available symbols |
full | Source + nested symbol tree | Deep understanding |
| I want to... | Tool chain |
|---|---|
| Understand a new project | get_repo_map ā read_with_deep_context |
| Read one function precisely | read_symbol_scope |
| Read a full source file | read_source_file (use detail_level="source_only" for minimal tokens) |
| Find a function by name/pattern | search_codebase ā read_symbol_scope |
| Resolve a symbol name to its file | find_symbol (faster than search_codebase for name lookup) |
| Batch read multiple files | read_files (max 10 files per call) |
| Get full symbol overview | symbol_overview (source + callers + callees + refs) |
| See all callers of a function | find_callers_callees |
| See all callees of a function | read_with_deep_context or find_callers_callees |
| Find ALL references (including non-call) | find_all_references |
| Jump to a definition | get_definition |
| Find tech debt | search_codebase(query="TODO|FIXME", filter_mode="comments_only") |
| Check LSP status | lsp_health |
| Read a config file | read_file |
If tools are not available, fall back transparently:
| Pathfinder | Built-in |
|---|---|
read_symbol_scope / read_with_deep_context | Read with line ranges |
read_source_file / read_file / read_files | Read |
search_codebase | Grep |
get_repo_map | Glob or ls |
find_callers_callees / get_definition | Grep (approximate) |
find_symbol / symbol_overview | Grep + Read (approximate) |
Do not block on Pathfinder. Complete the work with built-in tools.