polyglot-ast-slicer

A local call-graph context tool for AI coding agents. It parses Python and TypeScript/JavaScript with tree-sitter, builds a directed call graph, and returns byte-exact source slices over MCP. It does not execute code, makes no network calls after the first run, and keeps its index outside the repository. No code leaves your machine.

What it does

• Indexes a repository and resolves call edges from imports, receivers, annotations and constructor calls, with an explicit confidence per edge.
• Slices one symbol plus N call hops into exact byte ranges under a token budget.
• Exposes the graph through MCP and a CLI (index, slice, blast, cycles, search, stats, impact).

Install

uvx --from polyglot-ast-slicer polyglot-ast-slicer --help

Or install the command:

uv tool install polyglot-ast-slicer

Requires Python 3.12+. The first run downloads the tree-sitter grammars, so it needs internet once; after that it runs offline. The SQLite index lives in the OS cache directory, never in the repository.

MCP configuration

serve uses --repo when given, otherwise POLYGLOT_AST_REPO, otherwise the current working directory. A project-level Cursor config (.cursor/mcp.json) can therefore omit the repository:

{
  "mcpServers": {
    "polyglot-ast-slicer": {
      "command": "uvx",
      "args": ["polyglot-ast-slicer", "serve"]
    }
  }
}

Claude Code:

claude mcp add polyglot-ast-slicer -- uvx polyglot-ast-slicer serve

Claude Desktop does not guarantee the server's working directory, so pass the repository explicitly in claude_desktop_config.json:

{
  "mcpServers": {
    "polyglot-ast-slicer": {
      "command": "uvx",
      "args": [
        "polyglot-ast-slicer", "serve",
        "--repo", "/absolute/path/to/your/repo"
      ]
    }
  }
}

Worked example: Python

$ polyglot-ast-slicer slice --repo verify/fixtures/readme/python --symbol process_payment
### backend/service.py:1-7 [Ledger, Ledger.record] (data_schema, downstream_callee)
class Ledger:
    def __init__(self) -> None:
        self.entries: list[int] = []

    def record(self, amount: int) -> int:
        self.entries.append(amount)
        return sum(self.entries)

### backend/service.py:10-12 [process_payment] (target)
def process_payment(amount: int, ledger: Ledger) -> int:
    fee = amount // 10
    return ledger.record(amount - fee)

Worked example: TypeScript

$ polyglot-ast-slicer slice --repo verify/fixtures/readme/typescript --symbol processPayment
### src/service.ts:1-8 [Ledger, Ledger.record] (data_schema, downstream_callee)
export class Ledger {
  private entries: number[] = [];

  record(amount: number): number {
    this.entries.push(amount);
    return this.entries.reduce((total, value) => total + value, 0);
  }
}

### src/service.ts:10-13 [processPayment] (target)
export function processPayment(amount: number, ledger: Ledger): number {
  const fee = Math.floor(amount / 10);
  return ledger.record(amount - fee);
}

Results

Ground truth is Jedi for Python and the TypeScript compiler API for TS/JS. Scope is production source only (test, story and benchmark files are excluded per repository); held-out repositories were never used for tuning. Intervals are 95% Wilson score intervals. Precision counts a site as wrong when the tool reports a different project declaration; recall counts resolved sites as missed when the tool reports no edge.

Performance

Measured by verify/scale_probe.py on the development machine, one process per corpus. Each refresh is a one-line edit to one of 30 distinct files; latency varies with file size and disk state, so the table reports median and p95 rather than a fixed promise. Synthetic corpora use seed 42.

Slice size comparison

Default slice payload tokens (tiktoken on the exact JSON), the entry symbol's whole file, and every unique file containing its callers and callees. Thirty symbols per language, stratified as 10 per repository (seed 42). These are sizes only; they do not show that a slice is sufficient.

Files above 20k tokens among the sampled entry files: src/click/core.py (33,701 tokens, python), src/types.ts (39,169 tokens, typescript).

Languages

Generated from the parser extension map.

What it does not do

• Dynamic dispatch and reflection. getattr(obj, name)(), obj[name](), dependency injection, and *args forwarding produce no edge.
• Monkeypatching and runtime rewriting. Decorators, metaclasses and prototype mutation are not interpreted.
• Callbacks and higher-order dataflow. A function passed as a value is not followed when it is invoked through an unrelated parameter.
• Same-file siblings. A bare call is resolved only when the binding is unambiguous; computed member calls and unresolved receivers are left without an edge.
• Cross-language edges. Python calling into TypeScript (or the reverse) is not linked.
• Test selection. impact_of_diff returns changed and impacted symbols; it does not choose tests.
• Express-style prototype patterns. Assigned function bodies are indexed, but prototype dispatch and dynamic property lookup are not resolved.

When another tool fits better

If you need type-aware refactoring, rename, or exhaustive reference search, use a language server such as pyright or tsserver, or a code index such as SCIP or Sourcegraph. If you need retrieval by meaning rather than by call edges, use an embedding or vector-search tool. This tool is for exact call-context retrieval.

Development

uv sync --all-extras
uv run pytest                       # 107 tests collected
uv run python scripts/generate_metrics.py --check
uv run ruff check .
uv run mypy polyglot_ast_slicer

Measured numbers live in METRICS.md, generated from the committed scripts and pinned repositories. CI runs the offline --check and fails if METRICS.md or README.md drifts.

License

MIT — see LICENSE.