Summary
Connects to your local codebase via tree-sitter AST parsing and exposes precise retrieval tools: fetch individual functions, classes, or methods by name instead of reading entire files. Supports 25+ languages and cuts token usage by 95%+ in retrieval-heavy workflows because your agent stops scanning thousands of irrelevant lines. Index once with stdio transport, then query symbols, outlines, references, and scoped context bundles with byte-level precision. Ships with a compact wire format (MUNCH) that shrinks responses by another 45% median. Reach for this when your agent burns tokens opening giant files just to find one implementation, or when you need structured code navigation without the brute-force tax.
Install to Claude Code
verifiedclaude mcp add jcodemunch-mcp -- uvx jcodemunch-mcpRun in your terminal. Replace YOUR_* placeholders with real values; add --scope user to install for every project.
Review the command, arguments, and environment values before installing — MCP servers run with your local permissions.
Fastest browser for AI agents to run web automation tasks, always free.
Download Free life-time →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →
Connect your Claude agent to live crypto prices and trading routes via 1inch
Get the MCP →
Tools
Verified live against the running server on Jun 10, 2026.
verified live80 tools
index_repoIndex a GitHub repository's source code. Fetches files, parses ASTs, extracts symbols, and saves to local storage. Set JCODEMUNCH_USE_AI_SUMMARIES=false to disable AI summaries globally.4 params
Index a GitHub repository's source code. Fetches files, parses ASTs, extracts symbols, and saves to local storage. Set JCODEMUNCH_USE_AI_SUMMARIES=false to disable AI summaries globally.
Parameters* required
extra_ignore_patternsarrayAdditional gitignore-style patterns to exclude from indexing (merged with JCODEMUNCH_EXTRA_IGNORE_PATTERNS env var)
incrementalbooleanWhen true and an existing index exists, only re-index changed files.default: true
url*stringGitHub repository URL or owner/repo string
use_ai_summariesbooleanUse AI to generate symbol summaries. Supports Anthropic, Gemini, OpenAI-compatible endpoints, MiniMax, and GLM-5 via env vars. When false, uses docstrings or signature fallback.default: true
index_folderIndex a local folder of source code. Response surfaces `discovery_skip_counts` and `no_symbols_files` for diagnosing missing files.7 params
Index a local folder of source code. Response surfaces `discovery_skip_counts` and `no_symbols_files` for diagnosing missing files.
Parameters* required
extra_ignore_patternsarrayAdditional gitignore-style exclude patterns.
follow_symlinksbooleanInclude symlinked files. Symlinked directories are never followed.default: false
identity_modestringRepo-identity strategy. `config` (default): respect existing index. `local`: path-keyed. `git`: git-root-keyed (monorepo subdir merging).one of
config · local · gitdefault: configincrementalbooleanWhen an existing index exists, only re-index changed files.default: true
path*stringPath to local folder (absolute or relative; ~ expands).
pathsarrayOptional explicit paths (absolute or relative to `path`). When set, skips the directory walk; directories in the list are recursed. Walk-path validation applies.
use_ai_summariesbooleanGenerate symbol summaries via AI. When false, falls back to docstrings or signature.default: true
summarize_repoRe-run AI summarization on all symbols in an existing index. Use this when index_folder completed but AI summaries are missing — e.g., the background summarization thread was interrupted, AI was disabled at index time, or the summarizer provider wasn't configured yet. With for...2 params
Re-run AI summarization on all symbols in an existing index. Use this when index_folder completed but AI summaries are missing — e.g., the background summarization thread was interrupted, AI was disabled at index time, or the summarizer provider wasn't configured yet. With for...
Parameters* required
forcebooleanIf true, clear all existing summaries and re-summarize every symbol. Required when index_folder already applied signature fallbacks. If false, only process symbols with no summary at all.default: false
repo*stringRepository identifier (owner/repo or local/hash)
index_fileIndex a single file within an existing index. Surgical update after edits. The file must be under an already-indexed folder's source_root. Can also add new files.3 params
Index a single file within an existing index. Surgical update after edits. The file must be under an already-indexed folder's source_root. Can also add new files.
Parameters* required
context_providersbooleanWhether to run context providersdefault: true
path*stringAbsolute path to the file to index.
use_ai_summariesbooleanGenerate symbol summaries via AI. When false, falls back to docstrings or signature.default: true
import_runtime_signalIngest a runtime trace file into the runtime_* tables for the target repo. source='otel' takes OTel JSON / JSON-Lines / .gz and maps spans via (file_path, line_no, function_name); source='sql_log' takes pg_stat_statements CSV or a generic SQL JSON-Lines log and maps queries vi...4 params
Ingest a runtime trace file into the runtime_* tables for the target repo. source='otel' takes OTel JSON / JSON-Lines / .gz and maps spans via (file_path, line_no, function_name); source='sql_log' takes pg_stat_statements CSV or a generic SQL JSON-Lines log and maps queries vi...
Parameters* required
path*stringAbsolute filesystem path to the trace file
redact_enabledbooleanOverride the runtime_redact_enabled config key. Disable ONLY for offline debugging on synthetic data.
repostringRepository identifier (owner/name) — defaults to the current directory's resolved repo
sourcestringTrace source format. Phases 1+4+5 accept 'otel', 'sql_log', and 'stack_log'.one of
otel · sql_log · stack_log · apmdefault: otelget_runtime_coverageRuntime coverage histogram for a repo or a single file: count of indexed symbols with vs without runtime evidence, plus the diagnostic list of unmapped runtime spans (likely reflective dispatch the AST missed). Pairs with Phase 2's per-result _runtime_confidence stamping. Retu...3 params
Runtime coverage histogram for a repo or a single file: count of indexed symbols with vs without runtime evidence, plus the diagnostic list of unmapped runtime spans (likely reflective dispatch the AST missed). Pairs with Phase 2's per-result _runtime_confidence stamping. Retu...
Parameters* required
file_pathstringOptional repo-relative file path. When set, scopes the histogram to this file.
repo*stringRepository identifier (owner/name)
unmapped_limitintegerCap on the unmapped_runtime list (default 50)default: 50
find_hot_pathsTop-N symbols ranked by total runtime hit count across ingested traces, with per-symbol p50/p95 latency, sources contributing, and last_seen. Optionally filtered by a name substring. Pairs with get_blast_radius to answer 'is this PR touching code that runs 4M times/day?' Retur...3 params
Top-N symbols ranked by total runtime hit count across ingested traces, with per-symbol p50/p95 latency, sources contributing, and last_seen. Optionally filtered by a name substring. Pairs with get_blast_radius to answer 'is this PR touching code that runs 4M times/day?' Retur...
Parameters* required
querystringOptional case-insensitive substring filter on symbol name
repo*stringRepository identifier (owner/name)
top_nintegerCap on returned rows (default 20, max 200)default: 20
find_unused_pathsSymbols with zero (or stale) runtime hits over the look-back window. Distinct from find_dead_code: this surfaces code that's reachable on paper but never executed — only possible to detect with runtime data. Excludes test files and entry-point filenames by default. Returns an...5 params
Symbols with zero (or stale) runtime hits over the look-back window. Distinct from find_dead_code: this surfaces code that's reachable on paper but never executed — only possible to detect with runtime data. Excludes test files and entry-point filenames by default. Returns an...
Parameters* required
include_entry_pointsbooleanInclude symbols in entry-point filenames (main.py, wsgi.py, etc.)default: false
include_testsbooleanInclude symbols in test filesdefault: false
max_resultsintegerCap on returned rows (default 200, max 1000)default: 200
repo*stringRepository identifier (owner/name)
since_daysintegerLook-back window in days (default 90)default: 90
get_redaction_logPer-pattern PII redaction counts from runtime_redaction_log. Operators run this to verify the redaction chokepoint is firing on production traffic — covers the OTel / SQL / stack ingest paths (file-based or HTTP live-ingest, Phase 6). Returns {patterns: [{source, pattern, coun...3 params
Per-pattern PII redaction counts from runtime_redaction_log. Operators run this to verify the redaction chokepoint is firing on production traffic — covers the OTel / SQL / stack ingest paths (file-based or HTTP live-ingest, Phase 6). Returns {patterns: [{source, pattern, coun...
Parameters* required
repo*stringRepository identifier (owner/name)
since_daysintegerLookback window for last_redacted filter (default 30)default: 30
sourcestringOptional filter to a single source labelone of
otel · sql_log · stack_log · apmlist_reposList all indexed repositories. START HERE before using Grep/Read/search tools — check if the project is already indexed, then use search_symbols / get_symbol_source instead of native file reads. If jcodemunch tools appear as deferred in your tool list, call ToolSearch to load...
List all indexed repositories. START HERE before using Grep/Read/search tools — check if the project is already indexed, then use search_symbols / get_symbol_source instead of native file reads. If jcodemunch tools appear as deferred in your tool list, call ToolSearch to load...
No parameters — call it with no arguments.
get_watch_statusReport watch-all daemon coverage: every locally-indexed repo, each repo's staleness / reindex-in-progress state, and the OS-level service status. Call before relying on index freshness when you suspect files may have changed since the last index.
Report watch-all daemon coverage: every locally-indexed repo, each repo's staleness / reindex-in-progress state, and the OS-level service status. Call before relying on index freshness when you suspect files may have changed since the last index.
No parameters — call it with no arguments.
resolve_repoResolve a filesystem path to its indexed repo identifier. O(1) lookup — faster than list_repos for finding a single repo. Accepts repo root, worktree, subdirectory, or file path.1 params
Resolve a filesystem path to its indexed repo identifier. O(1) lookup — faster than list_repos for finding a single repo. Accepts repo root, worktree, subdirectory, or file path.
Parameters* required
path*stringAbsolute filesystem path (repo root, worktree, subdirectory, or file)
get_file_treeGet the file tree of an indexed repository, optionally filtered by path prefix. Results are capped at max_files (default 500) to prevent token overflow; use path_prefix to scope large trees.4 params
Get the file tree of an indexed repository, optionally filtered by path prefix. Results are capped at max_files (default 500) to prevent token overflow; use path_prefix to scope large trees.
Parameters* required
include_summariesbooleanInclude file-level summaries in the tree nodesdefault: false
max_filesintegerMaximum number of files to return (default 500). When truncated, response includes total_file_count and a hint to use path_prefix.default: 500
path_prefixstringOptional path prefix to filter (e.g., 'src/utils')default:
repo*stringRepository identifier (owner/repo or just repo name)
get_file_outlineGet all symbols (functions, classes, methods) in a file with full signatures (including parameter names) and summaries. Use signatures to review naming at parameter granularity without reading the full file. Pass repo and file_path (e.g. 'src/main.py').3 params
Get all symbols (functions, classes, methods) in a file with full signatures (including parameter names) and summaries. Use signatures to review naming at parameter granularity without reading the full file. Pass repo and file_path (e.g. 'src/main.py').
Parameters* required
file_pathstringPath to the file within the repository (e.g., 'src/main.py')
file_pathsarrayList of file paths to query in batch mode. Returns a grouped results array.
repo*stringRepository identifier (owner/repo or just repo name)
get_symbol_sourceGet full source of one symbol (symbol_id → flat object) or many (symbol_ids[] → {symbols, errors}). Supports verify, context_lines, and fqn (PHP FQN via PSR-4).6 params
Get full source of one symbol (symbol_id → flat object) or many (symbol_ids[] → {symbols, errors}). Supports verify, context_lines, and fqn (PHP FQN via PSR-4).
Parameters* required
context_linesintegerNumber of lines before/after symbol to include for contextdefault: 0
fqnstringPHP fully-qualified class name (e.g. 'App\Models\User'). Resolves to symbol_id via PSR-4. Alternative to symbol_id.
repo*stringRepository identifier (owner/repo or just repo name)
symbol_idstringSingle symbol ID — returns flat symbol object
symbol_idsarrayMultiple symbol IDs — returns {symbols, errors}
verifybooleanVerify content hash matches stored hash (detects source drift)default: false
get_file_contentGet cached source for a file, optionally sliced to a line range.4 params
Get cached source for a file, optionally sliced to a line range.
Parameters* required
end_lineintegerOptional 1-based end line (inclusive)
file_path*stringPath to the file within the repository (e.g., 'src/main.py')
repo*stringRepository identifier (owner/repo or just repo name)
start_lineintegerOptional 1-based start line (inclusive)
search_symbolsSearch for symbols matching a query across the entire indexed repository. Returns matches with signatures and summaries.19 params
Search for symbols matching a query across the entire indexed repository. Returns matches with signatures and summaries.
Parameters* required
debugbooleanWhen true, each result includes a score_breakdown showing per-field scoring contributions (name_exact, name_contains, name_word_overlap, signature_phrase, signature_word_overlap, summary_phrase, su...default: false
decoratorstringOptional filter: only return symbols with this decorator (case-insensitive substring match, e.g. 'route', 'property', 'Deprecated')
detail_levelstringControls result verbosity. 'compact' returns id/name/kind/file/line only (~15 tokens each, best for broad discovery). 'standard' returns signatures and summaries (default). 'full' inlines source co...one of
compact · standard · fulldefault: standardfile_patternstringOptional glob pattern to filter files (e.g., 'src/**/*.py')
fqnstringPHP fully-qualified class name (e.g. 'App\Models\User'). Resolves via PSR-4 and uses the class name as query. Alternative to query.
fusionbooleanEnable multi-signal fusion (Weighted Reciprocal Rank) across lexical, structural, similarity, and identity channels. Produces higher-quality ranking than linear score addition. When True, sort_by i...default: false
fuzzybooleanEnable fuzzy matching. When true, uses trigram overlap + Levenshtein distance as fallback when BM25 scores are low. Fuzzy results include match_type, fuzzy_similarity, and edit_distance fields.default: false
fuzzy_thresholdnumberMinimum Jaccard trigram similarity (0.0–1.0) for fuzzy candidates. Lower values surface more candidates. Default 0.4.default: 0.4
kindstringOptional filter by symbol kindone of
function · class · method · constant · type · templatelanguagestringOptional filter by languageone of
ada · al · ansible · apex · arduino · asmmax_edit_distanceintegerMaximum Levenshtein distance for direct name matching (catches typos). Default 2.default: 2
max_resultsintegerMaximum number of results to return (ignored when token_budget is set)default: 10
query*stringSearch query (matches symbol names, signatures, summaries, docstrings)
repo*stringRepository identifier (owner/repo or just repo name)
semanticbooleanEnable semantic (embedding-based) search. Requires an embedding provider: JCODEMUNCH_EMBED_MODEL (sentence-transformers), GOOGLE_API_KEY+GOOGLE_EMBED_MODEL (Gemini), or OPENAI_API_KEY+OPENAI_EMBED_...default: false
semantic_onlybooleanSkip BM25 entirely and rank solely by embedding cosine similarity. Implies semantic=true.default: false
semantic_weightnumberWeight for semantic score in hybrid BM25+embedding ranking (0.0–1.0). BM25 receives 1-weight. Default 0.5. Set to 0.0 for identical results to pure BM25; set to 1.0 for pure semantic.default: 0.5
sort_bystringRanking strategy. 'relevance' (default) = BM25 text match. 'centrality' = filter by query, rank by PageRank. 'combined' = BM25 + PageRank weighted.one of
relevance · centrality · combineddefault: relevancetoken_budgetintegerToken budget cap. When set, results are sorted by score and greedily packed until the budget is exhausted. Overrides max_results. Reports token_budget, tokens_used, and tokens_remaining in _meta.
invalidate_cacheDelete the index and cached files for a repository. Forces a full re-index on next index_repo or index_folder call.1 params
Delete the index and cached files for a repository. Forces a full re-index on next index_repo or index_folder call.
Parameters* required
repo*stringRepository identifier (owner/repo or just repo name)
search_textFull-text search across indexed file contents. Useful when symbol search misses (e.g., string literals, comments, config values). Supports regex (is_regex=true) and context lines around matches (context_lines=N, like grep -C).6 params
Full-text search across indexed file contents. Useful when symbol search misses (e.g., string literals, comments, config values). Supports regex (is_regex=true) and context lines around matches (context_lines=N, like grep -C).
Parameters* required
context_linesintegerLines of context to include before and after each match (like grep -C N). Essential for understanding code around matches.default: 0
file_patternstringOptional glob pattern to filter files (e.g., '*.py')
is_regexbooleanWhen true, treat query as a Python regex (re.search, case-insensitive). Supports alternation (|), character classes, lookaheads, etc.default: false
max_resultsintegerMaximum number of matching lines to returndefault: 20
query*stringText to search for. Case-insensitive substring by default. Set is_regex=true for full regex (e.g. 'estimateToken|tokenEstimat|\.length.*0\.25').
repo*stringRepository identifier (owner/repo or just repo name)
get_repo_outlineGet a high-level overview of an indexed repository: directories, file counts, language breakdown, symbol counts. Lighter than get_file_tree.1 params
Get a high-level overview of an indexed repository: directories, file counts, language breakdown, symbol counts. Lighter than get_file_tree.
Parameters* required
repo*stringRepository identifier (owner/repo or just repo name)
find_importersFind all files that import a given file. Answers 'what uses this file?'. has_importers=false on a result means that importer is itself unreachable (dead code chain). Supports dbt {{ ref() }} edges. Use file_paths for batch queries. Set cross_repo=true to also find importers in...5 params
Find all files that import a given file. Answers 'what uses this file?'. has_importers=false on a result means that importer is itself unreachable (dead code chain). Supports dbt {{ ref() }} edges. Use file_paths for batch queries. Set cross_repo=true to also find importers in...
Parameters* required
cross_repobooleanWhen true, also search other indexed repos for cross-repo importers. Default: false (or JCODEMUNCH_CROSS_REPO_DEFAULT env var).default: false
file_pathstringTarget file path within the repo (e.g. 'src/features/intake/IntakeService.js'). Use for single-file queries. Cannot be used together with file_paths.
file_pathsarrayList of target file paths for batch queries. Returns a results array. Cannot be used together with file_path.
max_resultsintegerMaximum results per filedefault: 50
repo*stringRepository identifier
find_referencesFind all files that import or reference an identifier via the import graph. Answers 'where is this imported / re-exported?'. SCOPE: import sites + dbt `{{ ref() }}` edges + (when `include_call_chain=true`) symbols whose bodies textually mention the identifier. Does NOT exhaust...5 params
Find all files that import or reference an identifier via the import graph. Answers 'where is this imported / re-exported?'. SCOPE: import sites + dbt `{{ ref() }}` edges + (when `include_call_chain=true`) symbols whose bodies textually mention the identifier. Does NOT exhaust...
Parameters* required
identifierstringSymbol or module name to search for (e.g. 'bulkImport', 'IntakeService'). Use for single-identifier queries. Cannot be used together with identifiers.
identifiersarrayList of symbol or module names to search for (batch mode). Returns a results array. Cannot be used together with identifier.
include_call_chainbooleanWhen true (singular mode only), each reference entry includes calling_symbols: symbols in that file whose bodies mention the identifier. Default false.default: false
max_resultsintegerMaximum resultsdefault: 50
repo*stringRepository identifier
check_referencesCheck if an identifier is referenced anywhere: imports + file content. Combines find_references and search_text into one call. Returns is_referenced (bool) for quick dead-code detection. Accepts multiple identifiers in one call via identifiers param.5 params
Check if an identifier is referenced anywhere: imports + file content. Combines find_references and search_text into one call. Returns is_referenced (bool) for quick dead-code detection. Accepts multiple identifiers in one call via identifiers param.
Parameters* required
identifierstringSingle identifier to check
identifiersarrayMultiple identifiers to check in one call. Returns grouped results.
max_content_resultsintegerMax files to return per identifier for content search.default: 20
repo*stringRepository identifier
search_contentbooleanAlso search file contents (not just imports). Set false for fast import-only check.default: true
search_columnsSearch column metadata across indexed models. Works with any ecosystem provider that emits column data (dbt, SQLMesh, database catalogs, etc.). Returns model name, file path, column name, and description. Use instead of grep/search_text for column discovery — 77% fewer tokens.4 params
Search column metadata across indexed models. Works with any ecosystem provider that emits column data (dbt, SQLMesh, database catalogs, etc.). Returns model name, file path, column name, and description. Use instead of grep/search_text for column discovery — 77% fewer tokens.
Parameters* required
max_resultsintegerMaximum number of results to returndefault: 20
model_patternstringOptional glob to filter by model name (e.g., 'fact_*', 'dim_provider')
query*stringSearch query (matches column names and descriptions)
repo*stringRepository identifier (owner/repo or just repo name)
get_context_bundleGet full source + imports for one or more symbols in one call. Multi-symbol bundles deduplicate shared imports. Set token_budget to cap response size; use budget_strategy to control what's kept. Supports fqn (PHP FQN via PSR-4) as alternative to symbol_id.9 params
Get full source + imports for one or more symbols in one call. Multi-symbol bundles deduplicate shared imports. Set token_budget to cap response size; use budget_strategy to control what's kept. Supports fqn (PHP FQN via PSR-4) as alternative to symbol_id.
Parameters* required
budget_strategystring'most_relevant' (default) ranks by file centrality (import in-degree). 'core_first' keeps the primary symbol first, ranks rest by centrality. 'compact' strips source bodies — returns signatures only.one of
most_relevant · core_first · compactdefault: most_relevantfqnstringPHP fully-qualified class name (e.g. 'App\Models\User'). Resolves to symbol_id via PSR-4. Alternative to symbol_id.
include_budget_reportbooleanWhen true, include a 'budget_report' field showing tokens used, symbols included/excluded, and strategy applied.default: false
include_callersbooleanWhen true, each symbol entry includes a 'callers' list of files that directly import its defining file.default: false
output_formatstring'json' (default) or 'markdown' — markdown renders a paste-ready document with imports, docstrings, and source blocks.one of
json · markdowndefault: jsonrepo*stringRepository identifier (owner/repo or just repo name)
symbol_idstringSingle symbol ID (backward-compatible). Use symbol_ids for multi-symbol bundles.
symbol_idsarrayList of symbol IDs for a multi-symbol bundle. Imports are deduplicated across symbols that share a file.
token_budgetintegerMax tokens to return. When set, symbols are ranked and trimmed to fit. Uses budget_strategy to prioritize.
get_session_statsGet token savings stats for the current MCP session. Returns tokens saved and cost avoided (this session and all-time), per-tool breakdown, session duration, and cumulative totals. Use to see how much jCodeMunch has saved you.
Get token savings stats for the current MCP session. Returns tokens saved and cost avoided (this session and all-time), per-tool breakdown, session duration, and cumulative totals. Use to see how much jCodeMunch has saved you.
No parameters — call it with no arguments.
analyze_perfPer-tool latency telemetry: p50/p95/max in ms, error rate, plus cache hit-rate by tool. Defaults to the in-memory session ring; pass window=1h|24h|7d|all to query persisted telemetry.db (requires perf_telemetry_enabled). Useful for finding slow tools, cold caches, and regressi...5 params
Per-tool latency telemetry: p50/p95/max in ms, error rate, plus cache hit-rate by tool. Defaults to the in-memory session ring; pass window=1h|24h|7d|all to query persisted telemetry.db (requires perf_telemetry_enabled). Useful for finding slow tools, cold caches, and regressi...
Parameters* required
compare_releasestringCompare current session against a saved baseline at benchmarks/token_baselines/v{version}.json (e.g. "1.74.0"). Adds baseline_diff to the response with per-tool deltas in tokens_saved and latency.
ledgerbooleanInclude ranking_ledger summary (per-repo and per-tool event counts, average confidence, identity hits, semantic usage). Reads telemetry.db ranking_events table populated since v1.78.0; requires per...default: false
toolstringRestrict the analysis to a single tool name.
topintegerCap on slowest tools to return.default: 20
windowstringsession = in-memory ring; others read telemetry.db.one of
session · 1h · 24h · 7d · alldefault: sessioncheck_embedding_driftPin (or re-check) a 16-string canary against the active embedding provider. On first run with capture=True (or force=True), embeds CANARY_STRINGS and persists the vectors to ~/.code-index/embed_canary.json. Subsequent calls re-embed those strings and report cosine drift; alarm...3 params
Pin (or re-check) a 16-string canary against the active embedding provider. On first run with capture=True (or force=True), embeds CANARY_STRINGS and persists the vectors to ~/.code-index/embed_canary.json. Subsequent calls re-embed those strings and report cosine drift; alarm...
Parameters* required
capturebooleanPin a fresh canary instead of running the drift check. No-ops when a canary already exists unless force=True.default: false
forcebooleanRe-pin the canary before checking. Use after intentional provider/model upgrades.default: false
thresholdnumberCosine-distance threshold above which the alarm fires (per-canary maximum, not mean).default: 0.05
tune_weightsLearn per-repo retrieval weights from the v1.78.0 ranking ledger. Computes confidence correlations for the semantic and identity-match channels and writes overrides to ~/.code-index/tuning.jsonc. search_symbols reads those overrides at query time when the caller doesn't pass a...4 params
Learn per-repo retrieval weights from the v1.78.0 ranking ledger. Computes confidence correlations for the semantic and identity-match channels and writes overrides to ~/.code-index/tuning.jsonc. search_symbols reads those overrides at query time when the caller doesn't pass a...
Parameters* required
dry_runbooleanCompute proposed deltas without writing tuning.jsonc.default: false
explainbooleanInclude per-signal correlations (mean confidence with/without semantic and identity channels) in the response.default: false
min_eventsintegerSkip repos with fewer ledger events than this (defends against overfitting on small samples).default: 50
repostringLimit tuning to a single repo. Default: every repo present in the ledger.
get_session_contextGet the current session context — files accessed, searches performed, and edits registered during this MCP session. Use to avoid re-reading the same files.2 params
Get the current session context — files accessed, searches performed, and edits registered during this MCP session. Use to avoid re-reading the same files.
Parameters* required
max_filesintegerMaximum number of files to return in files_accessed.default: 50
max_queriesintegerMaximum number of queries to return in recent_searches.default: 20
get_session_snapshotGet a compact session snapshot for context continuity. Returns a ~200 token markdown summary of files explored, edits made, searches performed, and dead ends. Designed for injection after context compaction to restore session orientation.4 params
Get a compact session snapshot for context continuity. Returns a ~200 token markdown summary of files explored, edits made, searches performed, and dead ends. Designed for injection after context compaction to restore session orientation.
Parameters* required
include_negative_evidencebooleanInclude dead-end searches (negative evidence) in snapshot.default: true
max_editsintegerMaximum edited files to include.default: 10
max_filesintegerMaximum focus files to include.default: 10
max_searchesintegerMaximum key searches to include.default: 5
get_file_riskPer-symbol composite risk for one file. For each function or method, returns a 0-100 composite score (higher = healthier; lower = riskier) plus per-axis sub-scores (complexity, exposure, churn, test_gap). Powers the VS Code risk-density gutter. complexity is per-symbol (cyclom...2 params
Per-symbol composite risk for one file. For each function or method, returns a 0-100 composite score (higher = healthier; lower = riskier) plus per-axis sub-scores (complexity, exposure, churn, test_gap). Powers the VS Code risk-density gutter. complexity is per-symbol (cyclom...
Parameters* required
file_path*stringPath to the file within the indexed repo.
repo*stringRepo identifier (owner/name, full id, or bare display name).
diff_health_radarCompare two health-radar payloads (from get_repo_health.radar) and return axis-by-axis deltas, composite delta, grade movement, and a one-line verdict. Pure data transform — no index access, no I/O. Designed for PR-time diff-grade reports: run get_repo_health on the base branc...2 params
Compare two health-radar payloads (from get_repo_health.radar) and return axis-by-axis deltas, composite delta, grade movement, and a one-line verdict. Pure data transform — no index access, no I/O. Designed for PR-time diff-grade reports: run get_repo_health on the base branc...
Parameters* required
baseline*objectRadar payload from baseline (e.g. base branch). The `radar` field of a get_repo_health response.
current*objectRadar payload from current (e.g. PR branch). The `radar` field of a get_repo_health response.
digestAgent stand-up briefing for a repo. Returns a tight (~200 token) markdown digest of (a) what changed since the agent's last session (by tracking git HEAD between calls), (b) the current risk surface (top hotspots by complexity × churn), and (c) dead-code candidates. Each item...5 params
Agent stand-up briefing for a repo. Returns a tight (~200 token) markdown digest of (a) what changed since the agent's last session (by tracking git HEAD between calls), (b) the current risk surface (top hotspots by complexity × churn), and (c) dead-code candidates. Each item...
Parameters* required
max_changed_filesintegerCap on changed-files list (default 5).default: 5
max_dead_codeintegerCap on dead-code candidates (default 3).default: 3
max_hotspotsintegerCap on hotspot list (default 3).default: 3
repo*stringRepo identifier (owner/name, full id, or bare display name).
since_shastringOverride the last-seen SHA (for re-running a delta).
plan_turnPlan the next turn by analyzing query against the codebase. Returns confidence level (high/medium/low), recommended symbols/files, and guidance. Use as opening move for any task.4 params
Plan the next turn by analyzing query against the codebase. Returns confidence level (high/medium/low), recommended symbols/files, and guidance. Use as opening move for any task.
Parameters* required
max_recommendedintegerMaximum number of symbols to recommend.default: 5
modelstringOptional. Your active model identifier (e.g. 'claude-haiku-4-5'). When supplied and adaptive_tiering is enabled, plan_turn invokes the tier-switch logic as a side effect — the exposed tool list is...
query*stringWhat you're looking for (task description or symbol name).
repo*stringRepository identifier.
register_editRegister file edits to invalidate caches. Call after editing files to clear BM25 cache and search result cache for the repo.3 params
Register file edits to invalidate caches. Call after editing files to clear BM25 cache and search result cache for the repo.
Parameters* required
file_paths*arrayList of file paths that were edited.
reindexbooleanIf True, also reindex the files.default: false
repo*stringRepository identifier.
audit_agent_configAudit agent configuration files (CLAUDE.md, .cursorrules, copilot-instructions.md, etc.) for token waste. Reports per-file token cost, stale symbol references, dead file paths, redundancy between global and project configs, bloat patterns, and scope leaks. Cross-references aga...2 params
Audit agent configuration files (CLAUDE.md, .cursorrules, copilot-instructions.md, etc.) for token waste. Reports per-file token cost, stale symbol references, dead file paths, redundancy between global and project configs, bloat patterns, and scope leaks. Cross-references aga...
Parameters* required
project_pathstringProject directory to scan for config files. Defaults to cwd.
repostringRepository identifier for cross-referencing symbols and files. If omitted, skips stale-reference and dead-path checks.
get_dependency_graphGet the file-level dependency graph for a given file. Traverses import relationships up to 3 hops. Use to understand what a file depends on ('imports'), what depends on it ('importers'), or both. Prerequisite for blast radius analysis. Set cross_repo=true to include cross-repo...5 params
Get the file-level dependency graph for a given file. Traverses import relationships up to 3 hops. Use to understand what a file depends on ('imports'), what depends on it ('importers'), or both. Prerequisite for blast radius analysis. Set cross_repo=true to include cross-repo...
Parameters* required
cross_repobooleanWhen true, include cross-repo edges (imports that resolve to packages in other indexed repos). Default: false.default: false
depthintegerNumber of hops to traverse (1–3)default: 1
directionstring'imports' (files this file depends on), 'importers' (files that depend on this file), or 'both'one of
imports · importers · bothdefault: importsfile*stringFile path within the repo (e.g. 'src/server.py')
repo*stringRepository identifier (owner/repo or just repo name)
get_symbol_diffDiff symbol sets between two indexed snapshots. Shows added, removed, and changed symbols. Branch workflow: index branch A as repo-main, index branch B as repo-feature, then diff.2 params
Diff symbol sets between two indexed snapshots. Shows added, removed, and changed symbols. Branch workflow: index branch A as repo-main, index branch B as repo-feature, then diff.
Parameters* required
repo_a*stringFirst repo identifier (the 'before' snapshot)
repo_b*stringSecond repo identifier (the 'after' snapshot)
get_class_hierarchyGet the full inheritance hierarchy for a class: ancestors (base classes via extends/implements) and descendants (subclasses/implementors). Works across Python, Java, TypeScript, C#, and any language where class signatures contain 'extends' or 'implements'.2 params
Get the full inheritance hierarchy for a class: ancestors (base classes via extends/implements) and descendants (subclasses/implementors). Works across Python, Java, TypeScript, C#, and any language where class signatures contain 'extends' or 'implements'.
Parameters* required
class_name*stringName of the class to analyse
repo*stringRepository identifier (owner/repo or just repo name)
get_related_symbolsFind symbols related to a given symbol using heuristic clustering: same-file co-location (weight 3), shared importers (weight 1.5), and name-token overlap (weight 0.5/token). Useful for discovering what else to read when exploring an unfamiliar codebase.3 params
Find symbols related to a given symbol using heuristic clustering: same-file co-location (weight 3), shared importers (weight 1.5), and name-token overlap (weight 0.5/token). Useful for discovering what else to read when exploring an unfamiliar codebase.
Parameters* required
max_resultsintegerMaximum results (default 10, max 50)default: 10
repo*stringRepository identifier (owner/repo or just repo name)
symbol_id*stringID of the symbol to find relatives for
suggest_queriesSuggest search queries, entry-point files, and index stats. Good first call on an unfamiliar repo — surfaces most-imported files, top keywords, and ready-to-run example queries.1 params
Suggest search queries, entry-point files, and index stats. Good first call on an unfamiliar repo — surfaces most-imported files, top keywords, and ready-to-run example queries.
Parameters* required
repo*stringRepository identifier (owner/repo or just repo name)
get_blast_radiusFind all files affected by changing a symbol. Returns confirmed files (import + name match) and potential files (import only, e.g. wildcard). Use before renaming or deleting a symbol. Set cross_repo=true to also find consumers in other indexed repos. Set include_source=true to...10 params
Find all files affected by changing a symbol. Returns confirmed files (import + name match) and potential files (import only, e.g. wildcard). Use before renaming or deleting a symbol. Set cross_repo=true to also find consumers in other indexed repos. Set include_source=true to...
Parameters* required
call_depthintegerWhen > 0, also find symbols that *call* this symbol (call-level analysis). Returns a callers list alongside the import-level confirmed/potential. Max 3. Default 0 (disabled).default: 0
cross_repobooleanWhen true, also find files in other indexed repos that consume this repo's package. Default: false.default: false
decorator_filterstringOptional: filter confirmed results to only those containing symbols with this decorator (case-insensitive substring match)
depthintegerImport hops to traverse (1 = direct importers only, max 3). Default 1.default: 1
fqnstringPHP fully-qualified class name (e.g. 'App\Models\User'). Resolves to symbol via PSR-4. Alternative to symbol.
include_depth_scoresbooleanWhen true, adds impact_by_depth (files grouped by hop distance) and per-depth risk scores. overall_risk_score and direct_dependents_count are always included. Default false.default: false
include_sourcebooleanWhen true, each confirmed file includes source_snippets (lines referencing the symbol) and symbols_in_file (nearby symbol signatures). Use for fix-ready context without extra tool calls. Default fa...default: false
repo*stringRepository identifier (owner/repo or just repo name)
source_budgetintegerMax tokens for source snippets across all files (default 8000). Files are prioritized by reference count.default: 8000
symbol*stringSymbol name or ID to analyse (e.g. 'calculateScore' or a full symbol ID)
get_call_hierarchyReturn incoming callers and outgoing callees for a symbol, N levels deep. Uses AST-derived call detection: callers = symbols in importing files that mention this name; callees = imported symbols mentioned in this symbol's body. Useful for understanding how a symbol fits into t...4 params
Return incoming callers and outgoing callees for a symbol, N levels deep. Uses AST-derived call detection: callers = symbols in importing files that mention this name; callees = imported symbols mentioned in this symbol's body. Useful for understanding how a symbol fits into t...
Parameters* required
depthintegerMaximum hops to traverse (1–5). Default 3.default: 3
directionstring'callers' = who calls this symbol; 'callees' = what this symbol calls; 'both' (default).one of
callers · callees · bothdefault: bothrepo*stringRepository identifier (owner/repo or just repo name)
symbol_id*stringSymbol name or full ID to analyse. Use search_symbols to find IDs.
get_impact_previewShow what breaks if a symbol is removed or renamed. Walks the call graph transitively to find every symbol that calls this one, returning affected symbols grouped by file with call-chain paths. Use this before deleting or renaming a symbol to understand full impact. For a stru...2 params
Show what breaks if a symbol is removed or renamed. Walks the call graph transitively to find every symbol that calls this one, returning affected symbols grouped by file with call-chain paths. Use this before deleting or renaming a symbol to understand full impact. For a stru...
Parameters* required
repo*stringRepository identifier (owner/repo or just repo name)
symbol_id*stringSymbol name or full ID to analyse. Use search_symbols to find IDs.
get_symbol_provenanceTrace the complete authorship lineage and evolution narrative of a symbol through git history. Returns every commit that touched the symbol (or its file), classified into semantic categories (creation, bugfix, refactor, feature, perf, rename, revert, etc.) with extracted commi...3 params
Trace the complete authorship lineage and evolution narrative of a symbol through git history. Returns every commit that touched the symbol (or its file), classified into semantic categories (creation, bugfix, refactor, feature, perf, rename, revert, etc.) with extracted commi...
Parameters* required
max_commitsintegerMaximum commits to analyse (default 25, max 100).default: 25
repo*stringRepository identifier (owner/repo or just repo name)
symbol*stringSymbol name or full ID as returned by search_symbols.
get_pr_risk_profileProduce a unified risk assessment for all changes between two git refs (branch, PR, or SHA range). Fuses five signals — blast radius, complexity, churn, test gaps, and change volume — into a single composite risk_score (0.0–1.0) with actionable recommendations. Returns the top...4 params
Produce a unified risk assessment for all changes between two git refs (branch, PR, or SHA range). Fuses five signals — blast radius, complexity, churn, test gaps, and change volume — into a single composite risk_score (0.0–1.0) with actionable recommendations. Returns the top...
Parameters* required
base_refstringBase SHA/ref to compare from. Defaults to the SHA stored at index time.
daysintegerChurn look-back window in days (default 90).default: 90
head_refstringHead SHA/ref to compare to (default 'HEAD').default: HEAD
repo*stringRepository identifier (owner/repo or just repo name)
get_dependency_cyclesDetect circular import chains in a repository. Returns every strongly-connected component (set of files that mutually import each other, directly or transitively). Run this to identify architectural problems before a refactor, or to understand why a module is hard to test in i...1 params
Detect circular import chains in a repository. Returns every strongly-connected component (set of files that mutually import each other, directly or transitively). Run this to identify architectural problems before a refactor, or to understand why a module is hard to test in i...
Parameters* required
repo*stringRepository identifier (owner/repo or just repo name)
get_coupling_metricsReturn afferent coupling (Ca), efferent coupling (Ce), and instability score for a file/module. Ca = files that import this module (dependents). Ce = files this module imports (dependencies). Instability I = Ce/(Ca+Ce): 0 = stable, 1 = unstable. Use to identify fragile modules...2 params
Return afferent coupling (Ca), efferent coupling (Ce), and instability score for a file/module. Ca = files that import this module (dependents). Ce = files this module imports (dependencies). Instability I = Ce/(Ca+Ce): 0 = stable, 1 = unstable. Use to identify fragile modules...
Parameters* required
module_path*stringFile path within the repo (e.g. 'src/utils.py')
repo*stringRepository identifier (owner/repo or just repo name)
get_layer_violationsCheck whether imports respect declared architectural layer boundaries. Reports every import that crosses a forbidden layer boundary. Layer rules can be passed directly or defined in .jcodemunch.jsonc under 'architecture.layers'. Use to enforce clean architecture and detect dep...2 params
Check whether imports respect declared architectural layer boundaries. Reports every import that crosses a forbidden layer boundary. Layer rules can be passed directly or defined in .jcodemunch.jsonc under 'architecture.layers'. Use to enforce clean architecture and detect dep...
Parameters* required
repo*stringRepository identifier (owner/repo or just repo name)
rulesarrayLayer definitions. Each entry: {name, paths: [...], may_not_import: [...]}. If omitted, reads from .jcodemunch.jsonc architecture.layers.
check_rename_safeCheck whether renaming a symbol to a new name would cause name collisions. Scans the symbol's own file and every file that imports it, looking for an existing symbol with the proposed new name. Returns safe=true when no collisions are found. Run this before any rename/refactor...3 params
Check whether renaming a symbol to a new name would cause name collisions. Scans the symbol's own file and every file that imports it, looking for an existing symbol with the proposed new name. Returns safe=true when no collisions are found. Run this before any rename/refactor...
Parameters* required
new_name*stringProposed new symbol name (not a full ID, just the name).
repo*stringRepository identifier (owner/repo or just repo name)
symbol_id*stringSymbol ID to rename (e.g. 'src/utils.py::helper#function'). Bare name accepted when unambiguous.
check_delete_safeComposite preflight: can this symbol be deleted safely? Combines find_importers (cross-repo), check_references, find_dead_code confidence, runtime evidence (Phase 7 traces when available), and entry-point heuristics into a single verdict + one-line recommended_action. Verdict...4 params
Composite preflight: can this symbol be deleted safely? Combines find_importers (cross-repo), check_references, find_dead_code confidence, runtime evidence (Phase 7 traces when available), and entry-point heuristics into a single verdict + one-line recommended_action. Verdict...
Parameters* required
cross_repobooleanInclude other indexed repos in the analysis (default true).default: true
include_runtimebooleanConsult runtime_calls for production evidence (default true).default: true
repo*stringRepository identifier
symbol*stringSymbol ID or name to evaluate for deletion safety.
find_implementationsFind concrete implementations of an interface, abstract class, or method. Multi-source resolution with confidence scoring: LSP dispatch (1.0), AST class hierarchy (0.85), duck-typed name match (0.65), decorator handler (0.45). Classifies each impl (subclass_override / interfac...8 params
Find concrete implementations of an interface, abstract class, or method. Multi-source resolution with confidence scoring: LSP dispatch (1.0), AST class hierarchy (0.85), duck-typed name match (0.65), decorator handler (0.45). Classifies each impl (subclass_override / interfac...
Parameters* required
cross_repobooleanAlso search other indexed repos via the package registry (default false).default: false
include_subclassesbooleanWalk class hierarchy for class-kind targets (default true).default: true
max_resultsintegerCap on returned implementations (default 50).default: 50
rank_by_importancebooleanSort by confidence then PageRank × byte_length (default true).default: true
relationship_kindsarrayOptional whitelist: subclass_override, interface_impl, duck_typed, decorator_handler, subclass. Defaults to all.
repo*stringRepository identifier
symbol*stringSymbol ID or name of the interface/abstract/method to analyse.
token_budgetintegerHard cap on response payload (default 4000).default: 4000
plan_refactoringGenerate edit-ready refactoring instructions for renaming, moving, extracting, or changing the signature of a symbol. Returns {old_text, new_text} blocks for every affected file — directly compatible with Edit tool. Handles import rewrites, collision detection, new file genera...7 params
Generate edit-ready refactoring instructions for renaming, moving, extracting, or changing the signature of a symbol. Returns {old_text, new_text} blocks for every affected file — directly compatible with Edit tool. Handles import rewrites, collision detection, new file genera...
Parameters* required
depthintegerImport hops to traverse (1-3, default 2).default: 2
new_filestringDestination file path for move/extract operations.
new_namestringNew name for rename operations.
new_signaturestringNew function signature (e.g. 'foo(x, y, z=0)').
refactor_type*stringType of refactoring to plan.one of
rename · move · extract · signaturerepo*stringRepository identifier (owner/repo or just repo name)
symbol*stringSymbol name or ID to refactor. For extract, comma-separated list (e.g. 'helper,process_data').
get_dead_code_v2Find likely-dead functions and methods using three independent evidence signals: (1) the symbol's file is not reachable from any entry point via the import graph (filename heuristic + package.json main/module/exports/bin), (2) no indexed symbol calls this symbol in the call gr...5 params
Find likely-dead functions and methods using three independent evidence signals: (1) the symbol's file is not reachable from any entry point via the import graph (filename heuristic + package.json main/module/exports/bin), (2) no indexed symbol calls this symbol in the call gr...
Parameters* required
file_patternstringOptional glob (e.g. `src/**`, `*.py`) — only analyse symbols whose file matches.
include_testsbooleanInclude test files in analysis (default false).default: false
max_resultsintegerCap on returned dead symbols (default 100, 0 = unlimited). _meta.truncated + _meta.total_matches flag when capped.default: 100
min_confidencenumberMinimum confidence threshold 0.0–1.0 (default 0.5 = at least 2/3 signals).default: 0.5
repo*stringRepository identifier (owner/repo or just repo name)
get_extraction_candidatesIdentify functions in a file that are good candidates for extraction to a shared module. A candidate must have high cyclomatic complexity (doing a lot) AND be called from multiple other files (already implicitly shared). Results are ranked by score = complexity × caller_file_c...4 params
Identify functions in a file that are good candidates for extraction to a shared module. A candidate must have high cyclomatic complexity (doing a lot) AND be called from multiple other files (already implicitly shared). Results are ranked by score = complexity × caller_file_c...
Parameters* required
file_path*stringRelative file path within the repo (e.g. 'src/utils.py').
min_callersintegerMinimum number of distinct caller files (default 2).default: 2
min_complexityintegerMinimum cyclomatic complexity threshold (default 5).default: 5
repo*stringRepository identifier (owner/repo or just repo name)
get_symbol_complexityReturn cyclomatic complexity, nesting depth, and parameter count for a single symbol. Complexity data is stored at index time (requires jcodemunch-mcp >= 1.16 / INDEX_VERSION 7). assessment field: 'low' (1-4), 'medium' (5-10), 'high' (11+). Re-index the repo if all metrics sho...2 params
Return cyclomatic complexity, nesting depth, and parameter count for a single symbol. Complexity data is stored at index time (requires jcodemunch-mcp >= 1.16 / INDEX_VERSION 7). assessment field: 'low' (1-4), 'medium' (5-10), 'high' (11+). Re-index the repo if all metrics sho...
Parameters* required
repo*stringRepository identifier (owner/repo or just repo name)
symbol_id*stringFull symbol ID as returned by search_symbols or get_file_outline.
get_churn_rateReturn git churn metrics for a file or symbol: commit count, unique authors, first_seen date, last_modified date, and churn_per_week over a configurable window. assessment: 'stable' (<=1/week), 'active' (<=3/week), 'volatile' (>3/week). Requires a locally indexed repo (index_f...3 params
Return git churn metrics for a file or symbol: commit count, unique authors, first_seen date, last_modified date, and churn_per_week over a configurable window. assessment: 'stable' (<=1/week), 'active' (<=3/week), 'volatile' (>3/week). Requires a locally indexed repo (index_f...
Parameters* required
daysintegerLook-back window in days (default 90).default: 90
repo*stringRepository identifier (owner/repo or just repo name)
target*stringRelative file path (e.g. 'src/utils.py') or a full symbol ID.
get_hotspotsReturn the top-N highest-risk symbols ranked by hotspot score = cyclomatic_complexity x log(1 + commits_last_N_days). Identifies code that is both complex and frequently changed — the highest bug-introduction risk in the codebase. Methodology matches CodeScene/Adam Tornhill. R...4 params
Return the top-N highest-risk symbols ranked by hotspot score = cyclomatic_complexity x log(1 + commits_last_N_days). Identifies code that is both complex and frequently changed — the highest bug-introduction risk in the codebase. Methodology matches CodeScene/Adam Tornhill. R...
Parameters* required
daysintegerChurn look-back window in days (default 90).default: 90
min_complexityintegerMinimum cyclomatic complexity to include (default 2).default: 2
repo*stringRepository identifier (owner/repo or just repo name)
top_nintegerNumber of results to return (default 20).default: 20
get_repo_healthReturn a one-call triage snapshot of the entire repository: symbol counts, dead code %, average cyclomatic complexity, top 5 hotspots, dependency cycle count, and unstable module count. Designed to be the first tool called in any new session — one call gives a complete picture...2 params
Return a one-call triage snapshot of the entire repository: symbol counts, dead code %, average cyclomatic complexity, top 5 hotspots, dependency cycle count, and unstable module count. Designed to be the first tool called in any new session — one call gives a complete picture...
Parameters* required
daysintegerChurn look-back window for hotspot calculation (default 90).default: 90
repo*stringRepository identifier (owner/repo or just repo name)
get_untested_symbolsFind functions and methods with no evidence of being exercised by any test file. Uses import-graph reachability + name matching (AST call_references when available, word-boundary text heuristic as fallback). Returns symbols classified as 'unreached' (no test file imports the s...4 params
Find functions and methods with no evidence of being exercised by any test file. Uses import-graph reachability + name matching (AST call_references when available, word-boundary text heuristic as fallback). Returns symbols classified as 'unreached' (no test file imports the s...
Parameters* required
file_patternstringOptional glob to narrow which source files are analysed (e.g. 'src/**/*.py').
max_resultsintegerCap on returned symbols (default 100).default: 100
min_confidencenumberMinimum confidence to include (0.0–1.0, default 0.5).default: 0.5
repo*stringRepository identifier (owner/repo or just repo name)
search_astCross-language AST pattern matching. Finds structural code patterns across all 70+ indexed languages using a single query — no need to know language-specific AST node types. Two modes: (1) preset anti-patterns (empty_catch, bare_except, deeply_nested, nested_loops, god_functio...6 params
Cross-language AST pattern matching. Finds structural code patterns across all 70+ indexed languages using a single query — no need to know language-specific AST node types. Two modes: (1) preset anti-patterns (empty_catch, bare_except, deeply_nested, nested_loops, god_functio...
Parameters* required
categorystringRun all presets in a category: security, error_handling, complexity, performance, maintenance, or all.
file_patternstringGlob filter on file paths (e.g. 'src/**/*.py').
languagestringRestrict scan to one language (e.g. 'python', 'typescript').
max_resultsintegerCap on total matches returned (default 50).default: 50
patternstringPreset name (empty_catch, bare_except, deeply_nested, nested_loops, god_function, eval_exec, hardcoded_secret, todo_fixme, magic_number, reassigned_param) or custom query (call:NAME, string:/REGEX/...
repo*stringRepository identifier (owner/repo or just repo name)
get_symbol_importanceReturn the most architecturally important symbols in a repo, ranked by PageRank or in-degree centrality on the import graph. Useful for orientation: surfaces the symbols that most of the codebase depends on. New tool: use after indexing to understand repo architecture at a gla...4 params
Return the most architecturally important symbols in a repo, ranked by PageRank or in-degree centrality on the import graph. Useful for orientation: surfaces the symbols that most of the codebase depends on. New tool: use after indexing to understand repo architecture at a gla...
Parameters* required
algorithmstring'pagerank' (default) = full PageRank on import graph; 'degree' = simple in-degree count (faster).one of
pagerank · degreedefault: pagerankrepo*stringRepository identifier (owner/repo or just repo name)
scopestringLimit to a subdirectory prefix (e.g. 'src/core')
top_nintegerNumber of top symbols to return (default 20, max 200)default: 20
find_similar_symbolsFind clusters of similar functions/methods/classes — consolidation candidates. Blends three signals: semantic (embedding cosine when embed_repo has run), structural (signature-token Jaccard + size ratio), and behavioral (callee-set Jaccard). Runs union-find clustering, classif...9 params
Find clusters of similar functions/methods/classes — consolidation candidates. Blends three signals: semantic (embedding cosine when embed_repo has run), structural (signature-token Jaccard + size ratio), and behavioral (callee-set Jaccard). Runs union-find clustering, classif...
Parameters* required
include_kindsarraySymbol kind whitelist. Defaults to ['function', 'method', 'class'].
include_testsbooleanWhen False (default), test files are skipped — tests intentionally share shapes.default: false
max_clustersintegerCap on clusters returned (default 25).default: 25
min_sizeintegerMinimum byte_length per symbol (default 30; filters out getters/wrappers).default: 30
repo*stringRepository identifier (owner/repo or just repo name)
scopestringOptional glob to limit to a subdirectory (e.g. 'src/core/*').
semantic_weightnumberEmbedding weight when embeddings are present (0.0–1.0). Default 0.6.default: 0.6
thresholdnumberMinimum combined similarity to form a cluster edge (0.0–1.0). Default 0.80.default: 0.8
token_budgetintegerHard cap on the response's payload (default 4000).default: 4000
get_repo_mapQuery-less, token-budgeted, signature-level overview of a repository. Groups symbols by file, ranks files by PageRank on the import graph, and greedy-packs signatures (not bodies) under token_budget. Designed for cold-start orientation — 'I just cloned this repo, what matters...5 params
Query-less, token-budgeted, signature-level overview of a repository. Groups symbols by file, ranks files by PageRank on the import graph, and greedy-packs signatures (not bodies) under token_budget. Designed for cold-start orientation — 'I just cloned this repo, what matters...
Parameters* required
include_kindsarrayOptional list of symbol kinds to restrict results (e.g. ['class', 'function']).
max_per_fileintegerMax signatures emitted per file (default 5, capped at 50).default: 5
repo*stringRepository identifier (owner/repo or just repo name)
scopestringOptional glob to limit to a subdirectory (e.g. 'src/core/*').
token_budgetintegerHard cap on returned tokens (default 2048).default: 2048
find_dead_codeFind dead code — files and symbols with zero importers and no entry-point role. Uses the import graph to identify unreachable code. Returns confidence scores (1.0 = provably unreachable, 0.7 = all importers are themselves dead). Set granularity='file' for file-level results only.5 params
Find dead code — files and symbols with zero importers and no entry-point role. Uses the import graph to identify unreachable code. Returns confidence scores (1.0 = provably unreachable, 0.7 = all importers are themselves dead). Set granularity='file' for file-level results only.
Parameters* required
entry_point_patternsarrayAdditional glob patterns to treat as live roots (e.g. 'cli/*.py', 'scripts/*').
granularitystring'symbol' (default) returns dead symbols; 'file' returns dead files only.one of
symbol · filedefault: symbolinclude_testsbooleanTreat test files as live roots (default false — test files are excluded from dead code candidates).default: false
min_confidencenumberMinimum confidence threshold 0.0–1.0. Default 0.8. Use 1.0 for provably unreachable only.default: 0.8
repo*stringRepository identifier (owner/repo or just repo name)
get_ranked_contextAssemble the best-fit context for a query within a token budget. Ranks all symbols by relevance (BM25) and/or centrality (PageRank), loads source for the top candidates, and packs greedily until token_budget is exhausted. Use when you want 'the best N tokens of context for thi...7 params
Assemble the best-fit context for a query within a token budget. Ranks all symbols by relevance (BM25) and/or centrality (PageRank), loads source for the top candidates, and packs greedily until token_budget is exhausted. Use when you want 'the best N tokens of context for thi...
Parameters* required
fusionbooleanEnable multi-signal fusion (Weighted Reciprocal Rank) for ranking. Combines lexical, structural, and identity channels.default: false
include_kindsarrayOptional list of symbol kinds to restrict results (e.g. ['class', 'function']).
query*stringNatural language or identifier describing the task (max 500 chars)
repo*stringRepository identifier (owner/repo or just repo name)
scopestringOptional glob pattern to limit search to a subdirectory (e.g. 'src/core/*').
strategystring'combined' (default) = BM25 + PageRank weighted sum. 'bm25' = pure text relevance. 'centrality' = PageRank only, filtered to query-matching symbols.one of
combined · bm25 · centralitydefault: combinedtoken_budgetintegerHard cap on returned tokens (default 4000).default: 4000
assemble_task_contextTask-aware single-call orchestrator. Auto-classifies task into explore/debug/refactor/extend/audit/review intent, runs the right sub-tools, returns one source-attributed capsule under token_budget.7 params
Task-aware single-call orchestrator. Auto-classifies task into explore/debug/refactor/extend/audit/review intent, runs the right sub-tools, returns one source-attributed capsule under token_budget.
Parameters* required
cross_repobooleanWhen True, layer cross-repo signals (default false).default: false
includearrayOptional whitelist of stages to run (e.g. ['anchor', 'blast', 'runtime']).
intentstringOptional override; auto-detected from task when omitted.one of
explore · debug · refactor · extend · audit · reviewrepo*stringRepository identifier
symbolsarrayOptional anchor symbol IDs or names; auto-extracted from task when omitted.
task*stringNatural-language task description. Anchors auto-extracted from task text.
token_budgetintegerEnd-to-end hard cap on returned tokens (default 8000).default: 8000
get_changed_symbolsMap a git diff to affected symbols: given two commits, returns which symbols were added, removed, modified, or renamed. Useful after merging a PR to answer 'what actually changed?' for code review or regression triage. Requires a locally indexed repo (index_folder). Defaults t...5 params
Map a git diff to affected symbols: given two commits, returns which symbols were added, removed, modified, or renamed. Useful after merging a PR to answer 'what actually changed?' for code review or regression triage. Requires a locally indexed repo (index_folder). Defaults t...
Parameters* required
include_blast_radiusbooleanAlso return downstream importers (blast radius) for each changed symbol (default false).default: false
max_blast_depthintegerHop limit when include_blast_radius=true (default 3, max 5).default: 3
repo*stringRepository identifier — must be locally indexed with index_folder
since_shastringCompare from this git SHA or ref. Defaults to the SHA stored at index time.
until_shastringCompare to this git SHA or ref (default 'HEAD').default: HEAD
embed_repoPrecompute and cache symbol embeddings for semantic search. Optional warm-up: search_symbols with semantic=true lazily embeds missing symbols on first use, but embed_repo warms the cache upfront so the first semantic query returns immediately. Requires an embedding provider (J...3 params
Precompute and cache symbol embeddings for semantic search. Optional warm-up: search_symbols with semantic=true lazily embeds missing symbols on first use, but embed_repo warms the cache upfront so the first semantic query returns immediately. Requires an embedding provider (J...
Parameters* required
batch_sizeintegerSymbols per embedding batch (default 50).default: 50
forcebooleanRecompute all embeddings even if they already exist (default false).default: false
repo*stringRepository identifier (owner/repo or just repo name)
get_cross_repo_mapReturn which indexed repos depend on which other indexed repos at the package level. Shows the full cross-repository dependency map based on package names extracted from manifest files (pyproject.toml, package.json, go.mod, Cargo.toml, etc.). Use to visualize how your indexed...1 params
Return which indexed repos depend on which other indexed repos at the package level. Shows the full cross-repository dependency map based on package names extracted from manifest files (pyproject.toml, package.json, go.mod, Cargo.toml, etc.). Use to visualize how your indexed...
Parameters* required
repostringOptional repo ID to filter. If omitted, returns the full cross-repo map.
get_group_contractsSurface the de-facto API contracts across a group of indexed repos. Walks each member's named imports, resolves them to symbols in other members via the package registry, and classifies each shared symbol into one of four verdict tiers: 'de_facto_api' (used by ≥min_importers e...8 params
Surface the de-facto API contracts across a group of indexed repos. Walks each member's named imports, resolves them to symbols in other members via the package registry, and classifies each shared symbol into one of four verdict tiers: 'de_facto_api' (used by ≥min_importers e...
Parameters* required
churn_daysintegerWindow for stability scoring (default 90).default: 90
classifybooleanAttach verdict tier per contract. Default true.default: true
include_dead_contractsbooleanSurface public symbols with zero external importers. Default false.default: false
include_internalbooleanSurface leaky_internal contracts (architecture violations). Default true.default: true
max_contractsintegerCap on returned contracts (default 50).default: 50
min_importersintegerMinimum distinct external repo importers to surface a contract (default 2).default: 2
repos*arrayList of indexed repo IDs (owner/name or bare names). Must be ≥2.
token_budgetintegerHard cap on response payload (default 4000).default: 4000
get_tectonic_mapDiscover the logical module topology of a codebase by fusing three coupling signals: structural (import edges), behavioral (shared symbol references), and temporal (git co-churn). Returns tectonic plates (auto-detected file clusters), each with an anchor file, cohesion score,...3 params
Discover the logical module topology of a codebase by fusing three coupling signals: structural (import edges), behavioral (shared symbol references), and temporal (git co-churn). Returns tectonic plates (auto-detected file clusters), each with an anchor file, cohesion score,...
Parameters* required
daysintegerGit co-churn look-back window in days (default 90)default: 90
min_plate_sizeintegerMinimum files per plate to include; smaller groups go to isolated_files (default 2)default: 2
repo*stringRepository identifier (owner/repo or just repo name)
get_signal_chainsDiscover how external signals (HTTP requests, CLI commands, scheduled tasks, events) propagate through the codebase via the call graph. Each signal chain traces a path from a gateway (entry point) through its callees to leaf symbols. Two modes: (1) Discovery — omit symbol to m...5 params
Discover how external signals (HTTP requests, CLI commands, scheduled tasks, events) propagate through the codebase via the call graph. Each signal chain traces a path from a gateway (entry point) through its callees to leaf symbols. Two modes: (1) Discovery — omit symbol to m...
Parameters* required
include_testsbooleanInclude test_* functions as gateways (default false).default: false
kindstringFilter gateways by kind: http, cli, event, task, main, test.one of
http · cli · event · task · main · testmax_depthintegerBFS depth limit per chain (1–8, default 5).default: 5
repo*stringRepository identifier (owner/repo or just repo name)
symbolstringSymbol name or ID for lookup mode. When provided, returns only chains containing that symbol. Omit for discovery mode (all chains).
render_diagramRender any graph-producing tool's output as rich, annotated Mermaid markup. Pass the raw output dict from get_call_hierarchy, get_signal_chains, get_tectonic_map, get_dependency_cycles, get_impact_preview, get_blast_radius, or get_dependency_graph. Auto-detects the source tool...3 params
Render any graph-producing tool's output as rich, annotated Mermaid markup. Pass the raw output dict from get_call_hierarchy, get_signal_chains, get_tectonic_map, get_dependency_cycles, get_impact_preview, get_blast_radius, or get_dependency_graph. Auto-detects the source tool...
Parameters* required
max_nodesintegerMaximum nodes before smart pruning (default 80, range 10–200).default: 80
source*objectRaw output dict from any supported graph-producing tool.
themestringVisual theme: 'flow' (architecture), 'risk' (impact), 'minimal' (docs). Default: flow.one of
flow · risk · minimaldefault: flowget_project_intelAuto-discover and parse non-code knowledge files (Dockerfiles, CI configs, docker-compose, K8s manifests, .env templates, Makefiles, package.json scripts) and cross-reference them to indexed code symbols. Returns structured intelligence grouped by category: infra, ci, config,...3 params
Auto-discover and parse non-code knowledge files (Dockerfiles, CI configs, docker-compose, K8s manifests, .env templates, Makefiles, package.json scripts) and cross-reference them to indexed code symbols. Returns structured intelligence grouped by category: infra, ci, config,...
Parameters* required
categorystringCategory to return: all, infra, ci, config, deps, api, data.one of
all · infra · ci · config · deps · apidefault: allrepo*stringRepository identifier (owner/repo or display name).
scope_pathstringOptional subpath (relative to source_root) to restrict intel discovery to a single workspace member — e.g. 'packages/api'. When omitted, the whole repo is scanned. Use `list_workspaces` to enumerat...
list_workspacesEnumerate monorepo workspace members for an indexed repo. Detects pnpm (pnpm-workspace.yaml), yarn/npm (package.json workspaces), turborepo (turbo.json), lerna (lerna.json), rush (rush.json), Go (go.work), and Cargo ([workspace] members). Returns [{path, package_name, manager}...1 params
Enumerate monorepo workspace members for an indexed repo. Detects pnpm (pnpm-workspace.yaml), yarn/npm (package.json workspaces), turborepo (turbo.json), lerna (lerna.json), rush (rush.json), Go (go.work), and Cargo ([workspace] members). Returns [{path, package_name, manager}...
Parameters* required
repo*stringRepository identifier (owner/repo or display name).
winnow_symbolsRun a multi-axis constraint query against the index in a single round trip. Accepts an ordered list of criteria (AND) intersecting signals no other tool composes: kind, language, name (regex), file glob, cyclomatic complexity, decorator, direct call references, summary/docstri...5 params
Run a multi-axis constraint query against the index in a single round trip. Accepts an ordered list of criteria (AND) intersecting signals no other tool composes: kind, language, name (regex), file glob, cyclomatic complexity, decorator, direct call references, summary/docstri...
Parameters* required
criteria*arrayOrdered list of filters. Each item is {axis, op, value}. Supported axes: kind (in/eq), language (in/eq), name (eq/matches), file (matches - glob), complexity (>,<,>=,<=,==), decorator (contains), c...
max_resultsintegerHard cap on returned results.default: 20
orderstringone of
asc · descdefault: descrank_bystringRanking axis for survivors.one of
importance · complexity · churn · namedefault: importancerepo*stringRepository identifier (owner/repo or just repo name)
set_tool_tierExplicit tier override for the current session. Narrows or widens the exposed tool list to 'core' / 'standard' / 'full'. Prefer plan_turn(model=...) for routine per-task use; use set_tool_tier only when you need an explicit override (e.g. escalate mid-task to 'full' after a ca...1 params
Explicit tier override for the current session. Narrows or widens the exposed tool list to 'core' / 'standard' / 'full'. Prefer plan_turn(model=...) for routine per-task use; use set_tool_tier only when you need an explicit override (e.g. escalate mid-task to 'full' after a ca...
Parameters* required
tier*stringone of
core · standard · fullannounce_modelAgent self-reports its active model identifier. Server resolves to a tier via model_tier_map (fuzzy: normalize → exact → glob → substring → '*' → 'full') and narrows the exposed tool list accordingly. Idempotent: a second call with the same model is a cheap no-op. Prefer calli...1 params
Agent self-reports its active model identifier. Server resolves to a tier via model_tier_map (fuzzy: normalize → exact → glob → substring → '*' → 'full') and narrows the exposed tool list accordingly. Idempotent: a second call with the same model is a cheap no-op. Prefer calli...
Parameters* required
model*stringYour active model identifier, e.g. 'claude-haiku-4-5'.
jCodeMunch MCP
The most token-efficient MCP server for precise source code retrieval via tree-sitter AST parsing. Cut AI token costs 86-99% on code exploration (96% average, benchmarked at 28.3x fewer tokens than a grep-and-read agent) and stop burning your context window reading entire files.
Real results, live from production 838B+ tokens saved · 136,000+ reporting installs · $4.2M+ in AI spend avoided · 100,000+ kg CO₂ prevented Counter figures as of 2026-08-17, valued at the $5/MTok Claude Opus input rate. All four only grow, so read them as floors. Live at jcodemunch.com.
Works with Claude Code, Cursor, VS Code, Codex CLI, Windsurf, Continue, and any MCP-compatible client.
Install now · Quickstart · See the evidence · Pricing
Free for personal use. Use it to make money, and Uncle J. gets a taste. Fair enough? Commercial licenses below. Our guarantee: if jCodeMunch doesn't pay for itself, you don't pay for jCodeMunch.
Why jCodeMunch?
Most AI agents explore repositories the expensive way: open entire files, skim thousands of irrelevant lines, repeat. That is not "a little inefficient." That is a token incinerator.
jCodeMunch indexes a codebase once and lets agents retrieve only the exact code they need: functions, classes, methods, constants, outlines, and tightly scoped context bundles, with byte-level precision. It parses source with tree-sitter, stores structured symbol metadata (signature, kind, qualified name, summary, byte offsets) alongside raw file content in a local index, and fetches exact implementations on demand instead of re-reading files over and over.
| Task | Traditional approach | With jCodeMunch |
|---|---|---|
| Find a function | Open and scan large files | Search symbol, fetch exact implementation |
| Understand a module | Read broad file regions | Pull only relevant symbols and imports |
| Explore repo structure | Traverse file after file | Query outlines, trees, and targeted bundles |
| "What breaks if I change X?" | Not possible | get_blast_radius |
Index once. Query cheaply. Keep moving. Precision context beats brute-force context.
Evidence
Reproducible token efficiency benchmark
Measured with tiktoken cl100k_base across three public repos pinned to upstream commits, run 2026-09-03 on v1.108.316. Workflow: search_symbols (top 5) + get_symbol_source × 3 per query. Two baselines, same run, same corpus, same file reader:
- Grep-top-3:
rg -lthe query terms, rank files by match count, open the top 3 whole. This is what a competent agent without the tool actually does, and it is the number to quote. - Read-all: every indexed source file concatenated. A ceiling nobody pays; retained for continuity with previously published figures.
| Repository | Files | Symbols | Grep-top-3 baseline | jCodeMunch | vs grep | vs read-all |
|---|---|---|---|---|---|---|
| expressjs/express | 186 | 455 | 15,724 avg | 1,007 avg | 15.6x | 153.5x |
| fastapi/fastapi | 1,186 | 13,240 | 85,296 avg | 2,149 avg | 39.7x | 384.1x |
| gin-gonic/gin | 98 | 1,451 | 31,975 avg | 1,537 avg | 20.8x | 98.8x |
| Grand total (15 task-runs) | 664,975 | 23,467 | 28.3x | 241.1x |
Against a grep-and-read agent: 96.5% reduction, 28.3x fewer tokens. No single multiple describes every query; the per-repo rows above are the spread. Against read-all the figure is 99.6%, but nobody pays that ceiling. Compact MUNCH wire encoding then trims a median 45.5% more bytes off responses.
Full methodology, pinned commits, harness, and known caveats: benchmarks/METHODOLOGY.md · Reproduce it yourself · TOKEN_SAVINGS.md
Independent A/B test on a production codebase
50-iteration A/B test on a real Vue 3 + Firebase production codebase, jCodeMunch vs native tools (Grep/Glob/Read), Claude Sonnet 4.6, fresh session per iteration: success rate 80% vs 72%, timeout rate 32% vs 40%, mean cache creation down 10.5%. Tool-layer savings isolated from fixed overhead: 15-25%. One finding category appeared exclusively in the jCodeMunch variant: orphaned file detection via find_importers, a structural query native tools cannot answer without scripting. Full report: benchmarks/ab-test-naming-audit-2026-03-18.md
Mentioned by
- Artur Skowroński (VirtusLab): "roughly 80% fewer tokens, or 5× more efficient — index once, query cheaply forever" · GitHub All-Stars #15
- Traci Lim (AWS · ASEAN AI Lead): "structural queries that native tools can't answer: find_importers, get_blast_radius, get_class_hierarchy, find_dead_code" · 5 Repos That Save Token Usage in Claude Code
- Julian Horsey (Geeky Gadgets): "3,850 tokens reduced to just 700 — a 5.5× improvement" · JCodeMunch AI Token Saver
- Eric Grill: "context is the scarce resource. Cut it by 90% and the whole stack gets cheaper and more reliable" · jCodemunch: Context Engine for AI Agents
Install
One-click installs
Recommended: one command
uv tool install jcodemunch-mcp
jcodemunch-mcp init
No virtualenv to manage, nothing written into system Python, and it works as-is on PEP 668 distros (Ubuntu 24.04+, Debian 12+) where bare pip install is refused. Don't have uv yet?
init auto-detects your MCP clients (Claude Code, Claude Desktop, Cursor, Windsurf, Continue), writes their config entries, installs the CLAUDE.md prompt policy so your agent actually uses jCodeMunch, optionally installs enforcement hooks, optionally indexes your project, and audits your agent config files for token waste.
Other install paths
| Command | Use it when |
|---|---|
uvx jcodemunch-mcp | Zero install. Runs from an ephemeral environment — nothing lands on disk permanently. The client entries init writes already invoke the server this way, so for most setups this is all that ever runs. ⚠ Enforcement hooks are the exception: they're spawned by a minimal-PATH subshell and resolve the executable by name, so they need uv tool install (or pipx/pip) to work. |
pipx install jcodemunch-mcp | You already standardise on pipx |
pip install jcodemunch-mcp | Inside a virtualenv you manage yourself |
Verify:
jcodemunch-mcp --version
Manual Claude Code setup
claude mcp add -s user jcodemunch -- uvx jcodemunch-mcp
No install step — uvx fetches and runs the server on demand. Prefer it on your PATH (and required for enforcement hooks)? uv tool install jcodemunch-mcp, then claude mcp add -s user jcodemunch jcodemunch-mcp.
Then tell the agent to prefer the tools. This matters more than people think; installation makes the tools available but does not break the agent's brute-reading habit. One line in your CLAUDE.md does it:
Call the jcodemunch_guide tool and strictly follow its instructions.
Using Cursor, Windsurf, Codex CLI, Antigravity, Gemini CLI, Qwen Code, Kiro, Cline, Zed, Goose, Hermes, Odysseus, or Paperclip? Every tested client configuration lives in CLIENTS.md. Optional extras (local semantic search, AI summaries per provider) are in QUICKSTART.md; the system surfaces each extra pulls in are documented in SECURITY.md.
Quickstart
Full walkthrough: QUICKSTART.md. The two-minute version, inside your agent after init:
- Ask: "Index this repo with jcodemunch."
- Ask: "Using jcodemunch, find the function that handles authentication and show me its source."
The agent should answer via search_symbols and get_symbol_source, returning tens of lines instead of whole files. Confirm with get_session_stats: it reports tokens served and savings for the session. That is where the numbers on the meter come from.
Want to skip initial indexing for popular frameworks? Pre-built starter packs: jcodemunch-mcp install-pack --list (free packs need no license).
What you can do
- Retrieve one symbol instead of loading a file.
get_symbol_sourcereturns the exact function body, byte-precise, for the majority of edits that touch one function in a 700-line file (~95% savings on that read). - Assemble a whole task's context in one call.
assemble_task_contextclassifies the task intent, extracts anchor symbols, and runs the right tool sequence under one token budget.plan_turnroutes the turn before the first read. - Ask structural questions grep can't answer.
find_importers,get_blast_radius,get_call_hierarchy,find_dead_code,get_changed_symbols,get_hotspots,search_astanti-pattern sweeps, and more. Two of them sound alike and are not:check_referencesanswers where a name is used (import sites plus every file whose content mentions it),find_referencesanswers who imports it, over the import graph alone, so a call site is invisible to it. - Preflight risky changes, and know when to stop.
check_edit_safe,check_delete_safe,get_pr_risk_profile, andplan_refactoringwith edit-ready{old_text, new_text}blocks. The two safety checks returnstop_rule.terminal: true means no further jcodemunch call moves the verdict, so re-runningfind_importersorcheck_referencesto be sure is wasted work. It means final, not safe. Hand the server your type checker's own output (jcodemunch-mcp import-trace --diagnostics <file>:mypy --output json,pyright --outputjson,tsc --pretty false,ruff --output-format json) andcheck_edit_safe,get_changed_symbols,get_pr_risk_profileandget_symbol_provenancesay which symbols the checker already flags, as of which commit. Nothing runs a checker for you. False names the specific thing that would change the answer. - Trust the answers. Calibrated confidence scores, freshness flags, coverage contracts on absence claims, compiler-verified references via SCIP import, and automatic secret redaction before anything reaches the LLM.
- Keep the index fresh automatically. Watch modes, agent hooks, and a VS Code extension close the staleness gap.
That's the highlight reel. The complete tour of 90+ tools, the MUNCH compact wire format, evidence receipts, offloadable-work annotation, and the session-economics instrumentation is in CAPABILITIES.md, with internals in UNDER_THE_HOOD.md.
What's new
- v1.108.318 (2026-09-11) — the process is code that cannot skip a step, and the field is measured from result files
- v1.108.317 (2026-09-04) — CI runs the harness on every change; publishing is a dispatched workflow
- v1.108.316 (2026-09-02) — A display preference edited the data it was displaying
When does it help (and when doesn't it)?
| Scenario | Native tool | jCodeMunch | Savings |
|---|---|---|---|
| Edit one function (700-line file) | Read → 700 lines | get_symbol_source → 30 lines | ~95% |
| Understand a file's structure | Read → full content | get_file_outline → names + signatures | ~80% |
| Find which file to edit | Grep many files | search_symbols → exact match | comparable |
| Edit requires whole-file context | Read → full content | get_file_content → full content | ~0% |
| "What breaks if I change X?" | not possible | get_blast_radius | unique capability |
It helps most on targeted edits (one function, one method, one class), which is the majority of real editing work. Edits that genuinely require the entire file (restructuring file-level state, reordering logic spanning hundreds of lines) see no advantage. Best fits: large repositories, unfamiliar codebases, agent-driven exploration, refactoring and impact analysis, and teams cutting AI token costs without making agents dumber.
Languages: 70+ via tree-sitter, including Python, JavaScript/TypeScript, Go, Rust, Java, C/C++, C#, PHP, Ruby, Swift, and Kotlin. Full matrix: LANGUAGE_SUPPORT.md. Monorepos: yes; incremental indexing, workspace-member detection, subpath scoping.
Deferring the tool schemas (Anthropic tool search)
If you reach jCodeMunch through the MCP connector on a model that supports tool search, you can keep our schemas out of your context prefix entirely and let Claude load only the two or three tools a request needs. You do not set defer_loading per tool — set it once for the whole server:
{
"mcp_servers": [
{ "type": "url", "url": "https://your-host/mcp", "name": "jcodemunch" }
],
"tools": [
{ "type": "tool_search_tool_bm25_20251119", "name": "tool_search_tool_bm25" },
{
"type": "mcp_toolset",
"mcp_server_name": "jcodemunch",
"default_config": { "defer_loading": true },
"configs": {
"resolve_repo": { "defer_loading": false },
"search_symbols": { "defer_loading": false },
"get_ranked_context": { "defer_loading": false }
}
}
]
}
Send it with the beta header mcp-client-2025-11-20. Both halves are required — mcp_servers alone is a validation error, and so is mcp_toolset without the matching mcp_server_name.
⚠ The MCP connector takes a URL, so this applies to jCodeMunch served over sse or streamable-http (jcodemunch-mcp serve --transport streamable-http), not to the default local stdio setup. On stdio, whether schemas are deferred is up to your client, and tool_surface: "counter" below is the lever you control.
The configs block above follows Anthropic's own advice — keep your 3–5 most-used tools resident so common requests skip the search round trip — and per-tool configs overrides default_config.
Deferred definitions are excluded from the system-prompt prefix and appended inline as tool_reference blocks when Claude discovers them, so prompt caching is preserved — this is not the cache-invalidating kind of dynamic tool list. At least one tool in the request must stay non-deferred, or the API returns a 400.
⚠ This is a different mechanism from our own tool_surface: "counter", and you do not need both. Tool search is host-side and works across every MCP server you have connected; the Counter is server-side, works on any host including ones with no tool-search support, and is what init configures on a first-ever install. Pick whichever your host supports — see CONFIGURATION.md for the Counter and jcodemunch-mcp surface for what your install actually advertises.
Security, privacy, and background behavior
Local-first by design: indexes live at ~/.code-index/, and the base package's only default network behavior is an anonymous savings counter (random ID plus aggregate token counts, no code, no paths, no PII; opt out with share_savings: false). Everything the server does beyond answering a tool call (file watching, the opt-in login service, license validation, model downloads, org reporting) is opt-in or opt-out, visible, and reversible, and every item is enumerated in SECURITY.md alongside the path-traversal, symlink, and secret-redaction controls.
Grammar pack override (#608). The dependency tree-sitter-language-pack is pinned <1.0.0 because the 0.x wheels bundle every grammar and parsing stays local. You can override it with pip install -U tree-sitter-language-pack after installing; nothing in the code refuses it. What you accept, measured against 1.17.0 on 2026-09-11: the 1.x pack ships no grammars and fetches each one over the network into its cache directory (measured on Windows: %LOCALAPPDATA%\tree-sitter-language-pack\v<version>\libs; jcodemunch-mcp install-status prints the path on any platform) the first time a language is parsed, so an airgapped install parses nothing, and the nim grammar changed upstream, so nim files yield no symbols (the manifest also lacks autohotkey, ejs and verse, which costs nothing here: those three are parsed by jCodeMunch's own extractors, not by tree-sitter). An install on a 1.x pack says so: every index_folder result carries a grammar_pack block and a warning naming the version, the cache directory and each language whose grammar failed, and jcodemunch-mcp install-status prints the same. Dropping the pin is a separate decision that needs the offline story first.
Per-project configuration
Most settings live in the global ~/.code-index/config.jsonc, but any of them can be overridden for a single repository by dropping a .jcodemunch.jsonc at its root. It is an overlay: keys it declares win, keys it omits fall through to global and then to the built-in default, so it only needs to contain what differs.
// <your-repo>/.jcodemunch.jsonc
{
"max_file_size": 1048576,
"languages": ["python", "typescript", "racket"]
}
Declaring Racket defining forms
Racket projects routinely define their own defining forms with define-syntax, and a static parser cannot know what those bind — (defstep (check-admin) ...) is indistinguishable from a function call. Declaring them makes their bindings searchable:
{
"racket_definition_forms": {
"defstep": "function",
"defstudy": "constant",
"defvar": "constant",
"define-schema": "class"
}
}
Each entry maps a form name to what it binds: function, constant, class or type. Where the name sits is read from the source rather than declared — (defstep (check-admin) ...) takes the head of the parameter list, (defstudy consent ...) takes the bare symbol — so a form that appears in both shapes works either way.
⚠ This is an assertion, not something jCodeMunch can verify. A wrong declaration puts a name in the index that Racket does not actually bind. Declarations are also matched only after every built-in form, so declaring define or struct has no effect — the built-in handling wins.
Declaring what a Racket #lang looks like
A #lang line names a reader, and jCodeMunch's Racket parser reads S-expressions. The distribution's langs are built in (racket/*, typed/racket*, s-exp, info, at-exp …, and the document langs scribble/*, pollen, punct, markdown …), but a project's own lang is unknown to it and is treated as a document — no symbols, still text-searchable — until you say what its syntax is:
{
"racket_langs": {
"conscript": "at-exp",
"mylang": "sexp"
}
}
sexp is plain S-expressions; at-exp is at-exp text bodies over Racket (read with @ as the command character, exactly as #lang at-exp reads them, so prose containing ; " # or | is prose); text is a document language that is never walked. A key also covers its sub-langs (conscript matches conscript/with-require), and a project may demote a lang as well as promote one. An at-exp lang whose reader uses another command character declares it with the object form — "mylang": {"tier": "at-exp", "command_char": "◊"} — the way Racket's make-at-readtable takes #:command-char.
Both keys change what the parser emits for unchanged files, so a change to either is stamped on the index and forces one full re-parse on the next index (rebuild_reason: "racket_config_changed"); you do not need to touch the files or clear the index. An index holding Racket files that was built before this stamp existed re-parses once the same way (rebuild_reason: "racket_index_predates_gate").
Documentation
| Doc | What it covers |
|---|---|
| QUICKSTART.md | Zero-to-indexed in three steps |
| CLIENTS.md | Tested configuration for every MCP client |
| USER_GUIDE.md | Full tool reference, workflows, and best practices |
| CAPABILITIES.md | The complete capability reference beyond the highlight reel |
| CONFIGURATION.md | Config file reference, token-control levers, tool tiering, the Counter |
| UNDER_THE_HOOD.md | The technical manual: verdicts, ranking internals, provenance contracts |
| ARCHITECTURE.md | Internal design, storage model, and extension points |
| GROQ.md | Groq Remote MCP, the gcm CLI, speedreview GitHub Action |
| HEADLESS.md | Using jCodeMunch with claude -p |
| AGENT_HOOKS.md | Agent hooks and prompt policies |
| LANGUAGE_SUPPORT.md | Supported languages and parsing details |
| SECURITY.md | Security controls, data movement, background behavior |
| TROUBLESHOOTING.md | Common issues and fixes |
| CHANGELOG.md · ROADMAP.md | Release history and what's next |
Licensing and commercial use
jCodeMunch-MCP is released under the jCodeMunch-MCP Dual-Use License (full terms). Free for non-commercial use. Commercial use requires a paid license, one-time, sold by jMunch LLC via Stripe:
jCodeMunch-only: Builder, $79 (1 developer) · Studio, $349 (up to 5) · Platform, $1,999 (org-wide internal deployment)
Full jMunch suite (code + docs + data): Trio Builder, $99 · Trio Studio, $449 · Trio Platform, $2,499
Not sure it's worth it? Run your own numbers through the ROI calculator, or forward the finance-team version to whoever signs off. The guarantee stands: if jCodeMunch doesn't pay for itself, you don't pay for jCodeMunch.
Conditions on all uses: retain the copyright notice, clearly mark modifications and keep the original author's name intact (he's kinda full of himself), and include a prominent modification notice in source redistributions. The Software may not be renamed, rebranded, or published to any public package registry, and is provided "AS IS" without warranty. LICENSE controls.
FAQ
How much can I save on Claude / Opus tokens? In retrieval-heavy workflows, code-reading tokens typically drop 86-99%, benchmarked at 96.5% average (28.3x) against a grep-and-read agent across 15 tasks and 3 repositories. Per-query results span 7.6x to 81.2x. Methodology: TOKEN_SAVINGS.md and benchmarks/.
How is this different from RAG or grep-based tools? jCodeMunch retrieves at the symbol level with byte-level precision (functions, classes, importers, blast radius, hierarchies) rather than fuzzy chunks (RAG) or raw line matches (grep) the agent still has to read and reason over.
Is it free for personal use? Yes. Commercial use needs a license; see above.
Where's the deep-dive on X? Capabilities: CAPABILITIES.md. Config: CONFIGURATION.md. Clients: CLIENTS.md. Internals: UNDER_THE_HOOD.md. Or the firehose: jcodemunch.com.
Extras: OSS code-health observatory (weekly six-axis snapshots of Express, FastAPI, Gin, Django, and friends) · Token Cost Radar (daily AI token cost intelligence) · jMunch Console (free MIT GUI for one-click upgrades)
Featured
Fastest browser for AI agents to run web automation tasks, always free.
Download Free life-time →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →Connect your Claude agent to live crypto prices and trading routes via 1inch
Get the MCP →Registryactive
Packagejcodemunch-mcp
TransportSTDIO
Prompts5
Tools verifiedJun 10, 2026
UpdatedMar 21, 2026