Jidra

JIDRA: Just Indexing Dependencies, Repositories, & Agents

[](https://github.com/akhilsinghcodes/jidra/actions/workflows/ci.yml)

JIDRA is a structured context backend that reduces LLM input tokens by 68-95% for code-native queries by giving Claude a pre-analyzed call graph instead of raw source files. Multi-language support: Scala (~90% resolution), Java (~85% resolution), TypeScript (~80% resolution), Python (~68.5% resolution), Go (tree-sitter-based, best-effort resolution).

Language Supported Currently: Java/Scala/TypeScript/Python/Go

What This Means

Real Claude Code sessions, same question, same model (claude-sonnet-4-6 1M):

Without JIDRA:  833,782 input tokens  ($0.2298)  — Claude read files manually
With JIDRA:     227,095 input tokens  ($0.2275)  — Claude used graph tools
Reduction:          72.8% fewer input tokens, same answer quality

At Opus pricing ($15/M input):
Without JIDRA:  $12.51/query
With JIDRA:      $3.41/query
Savings:         $9.10/query  →  $4,550/year at 500 queries

JIDRA connects to Claude Code as an MCP server — one command to set up:

This project is intentionally focused and graph-driven.

Pitch (TL;DR)

• Multi-language → Scala, Java, TypeScript, Python, Go (auto-detected)
• Index once → Get a deterministic call graph (AST-based, language-optimized)
• Reduce noise → Remove phantom edges (Java: runtime validation, TS/Python/Scala/Go: static analysis)
• Generate context → 68-95% smaller prompt-ready context for Claude/Codex/Gemini
• Trace execution → See likely business flow with uncertainty markers
• Reduce LLM cost → Proven token reduction on code-native workflows (measured on real projects)
• Ship agents & skills → jidra init installs a Haiku subagent + two slash commands into your repo's .claude/ — blast radius analysis and code navigation, no manual setup

Real Proof — Claude Code sessions, same question, same model (claude-sonnet-4-6):

| Session | Input tokens | Output tokens | Cost | |---------|-------------|---------------|------| | Without JIDRA (filesystem tools only) | 833,782 | 5,161 | $0.2298 | | With JIDRA (MCP graph tools) | 227,095 | 1,784 | $0.2275 | | Reduction | 72.8% | 65.4% | ~same |

Same cost today at Sonnet pricing because output tokens dominate — but 606k fewer input tokens per query. At Opus pricing ($15/M input vs $3/M) that gap is $9.09 saved per query.

Screenshots

jidra up is the one-command setup flow — prompts, a live spinner while parsing, and a styled summary panel when it's done:

Live progress while indexing is in flight:

jidra up writes its output (graph + visualization) under jidra/output/-/, never into the target repo:

The generated graph_visualization.html — interactive graph, Graphviz DOT, and JSON export tabs:

Click any node to inspect its module, signature, and file location; "Show Neighbors" highlights its direct call relationships:

Search by method or class name to jump straight to a node:

The same view also exports the full graph as Graphviz DOT or pretty-printed JSON, in-place:

jidra up also offers to index your docs//README.md and link doc chunks to the classes/methods they describe — rendered as its own interactive doc graph:

Every index, reindex, and doc-index run is recorded to a local telemetry dashboard (jidra history --html, served from ~/.jidra/telemetry/telemetry.html):

What JIDRA Does

• Indexes Scala, Java, TypeScript, Python, and Go source into deterministic call graphs
• Validates with language-specific strategies (Spring Actuator for Java, compiler-resolved for Scala, static analysis for TS/Python/Go)
• Searches the graph by keyword or natural language (FTS5-backed jidra_search / jidra_explore)
• Surfaces framework structure as first-class data — HTTP endpoints, React/Vue/Angular components & hooks (jidra_get_endpoints, jidra_get_components, jidra_get_framework_summary)
• Answers impact-analysis questions — what breaks if I change this file (jidra_get_file_dependents / _dependencies)
• Resolves interface→implementation and class surface — list every concrete implementation of an interface/abstract class in one call (jidra_get_implementations), or every method and field of a class (jidra_get_class_members)
• Generates noise-free context (68-95% smaller depending on language), auto-scaled to repo size (budget tiers)
• Traces method/function execution with uncertainty markers
• Stays fresh automatically via git hooks + an in-daemon file watcher (no manual reindex)
• Exports as JSON, MCP tools, or interactive HTML
• Integrates with Claude/Codex/Gemini via MCP (shared-daemon proxy mode shares one in-memory graph across editor windows)
• Reduces LLM token costs by 68-95% (proven on real projects)

Benchmarked vs CodeGraph (agent-in-loop)

JIDRA was evaluated against the CodeGraph MCP server using a real coding agent (Haiku 4.5): the same LLM was given a navigation task and exactly one backend's tools, then scored on correctness, tool calls, tokens, and hallucinations. Three languages evaluated.

Java (Spring Boot monorepo, ~1,200 methods, 8 tasks)

| Backend | correct | avg tool calls | avg tokens | total cost | halluc. | |---|---|---|---|---|---| | JIDRA (+ tool selection skill) | 8/8 | 1.6 | 18.4k | $0.131 | 0/8 | | CodeGraph | 7/8 | 2.4 | 36.6k | $0.248 | 0/8 |

2.0× token ratio. JIDRA 8/8; CodeGraph permanently fails T1 (can't produce exact implementation counts — blast-radius design gap). T4 standout: JIDRA 2c/8k vs CG 5c/108k (13×). T1/T3 avg pulled up by stochastic limit=100/depth=10 parameter over-reach; stripping those two outliers: ~12.8k avg, ~4–5× ratio. Tool selection skill (decision table + few-shot ✓/✗ examples) routes existence checks → get_implementations, method existence → get_method_source, behavioral search → jidra_explore. Full per-task data: [docs/archive/FINDINGSjidravscodegraphv18.md](docs/archive/FINDINGSjidravscodegraphv18.md).

Python (~891–1,100 methods, 5 tasks)

| version | JIDRA correct | CG correct | JIDRA avg tok | CG avg tok | tok ratio | JIDRA cost | CG cost | |---|---|---|---|---|---|---|---| | v2 | 5/5 | 4/5 | 11,444 | 139,716 | 12.2× | $0.054 | $0.573 |

CG fails PY1 (caller enumeration — same reverse-edge design gap as Java T3). PY4 (definition lookup in a 1,200-line file): CG used 13 calls / 533k tokens; JIDRA: 2 calls / 12k.

TypeScript (~630 methods, 6 tasks)

| Backend | correct | avg tool calls | avg tokens | total cost | tok ratio | |---|---|---|---|---|---| | JIDRA (+ tool selection skill + examples) | 6/6 | 1.5 | 11.6k | $0.065 | — | | CodeGraph | 6/6 | 4.7 | 87.9k | $0.444 | 7.6× |

7.6× token ratio. Both 6/6 correct. CG TS2 stochastic spiral drove avg to 87.9k (12c/310k for a call-graph traversal); JIDRA TS2: 3c/16.9k. JIDRA TS3 (absence check): 1c/7.6k via jidra_search(exact=True) → 0 results → done. Full delta across 8 TypeScript runs.

Cross-language summary

| language | JIDRA | CG | token ratio | JIDRA cost | CG cost | |---|---|---|---|---|---| | Java | 8/8 | 7/8 | 2.0× | $0.131 | $0.248 | | Python | 5/5 | 4/5 | 12.2× | $0.054 | $0.573 | | TypeScript | 6/6 | 6/6 | 7.6× | $0.065 | $0.444 |

Java ratio is lower because Java tasks include T1/T3 stochastic bloat; ex-outliers ~4–5×. Python/TypeScript tasks are traversal-heavy where CG's lack of scalpel tools is fatal. Root cause in all three languages: codegraph_explore cannot walk reverse call edges, extract a single method from a large file by name, or count implementations with precision. JIDRA's tools answer each in 1 call. Tool selection skill (decision table + few-shot examples) is required for full JIDRA efficiency — without it, behavioral queries waste calls.

Full methodology and per-task data: [FINDINGSjidravscodegraph.md](FINDINGSjidravscodegraph.md).

Benchmarked vs CodeGraph (method-level retrieval)

Separate retrieval benchmark mirroring CodeGraph's own runner.ts methodology (Recall@10 + MRR). Four TypeScript repos, 48 cases total, method symbols only.

| repo | methods | JIDRA passed | CG passed | JIDRA recall | CG recall | |---|---|---|---|---|---| | MTKruto | ~2,300 | 12/12 (100%) | 11/12 (92%) | 0.847 | 0.764 | | Trezor Suite | ~12,600 | 10/12 (83%) | 8/12 (67%) | 0.708 | 0.500 | | PostyBirb | ~2,200 | 10/12 (83%) | 9/12 (75%) | 0.708 | 0.625 | | Shapeshift Web | ~6,200 | 12/12 (100%) | 7/12 (58%) | 0.792 | 0.458 | | Aggregate | — | 44/48 (92%) | 35/48 (73%) | 0.764 | 0.587 |

When CodeGraph misses, it returns 0 results — methods exist in the repo but aren't indexed (standalone functions, React hooks, route handlers in monorepo sub-packages). JIDRA's tree-sitter extractor captures all of these. Explore gap widens in complex monorepo structures: Shapeshift 6/6 vs 3/6 because CodeGraph's traversal doesn't cross package boundaries. Full data: [JIDRAvsCodeGraphretrievalfinal.md](docs/JIDRAvsCodeGraphretrievalfinal.md).

SWE-bench Style File Retrieval (8 repos, 279 cases)

Broader evaluation using SWE-bench issue-to-file mapping: given a GitHub issue description, retrieve the files a human developer actually touched. Scored at file level (≥50% file recall = pass). Four-way comparison: JIDRA search, JIDRA explore, CodeGraph search, and CodeGraph explore†.

| Repo | Cases | JIDRA Search | JIDRA Explore | CG Search | CG Explore† | |------|------:|:------------:|:-------------:|:---------:|:-----------:| | axios | 6 | 100% | 83% | 50% | 17% | | preact | 17 | 94% | 94% | 47% | 29% | | matplotlib | 23 | 91% | 83% | 26% | 9% | | django | 114 | 87% | 74% | 31% | 16% | | caddy | 14 | 79% | 71% | 7% | 21% | | sympy | 77 | 70% | 70% | 14% | 10% | | docusaurus | 5 | 60% | 40% | 20% | 0% | | scikit-learn | 23 | 48% | 43% | 30% | 22% | | Aggregate | 279 | ~78% | ~70% | ~28% | ~16% |

† CG explore is a 1-hop edge approximation of CodeGraph's semantic exploration — not an exact equivalent of JIDRA's multi-hop graph traversal.

Key findings:

• JIDRA search beats CodeGraph search by ~50 percentage points on average across all 8 repos
• JIDRA explore (the mode used by the MCP agent) adds graph-traversal context that further improves file discovery for multi-file changes
• CodeGraph's FTS gaps are most severe in Go (caddy: 7%) and domain-heavy Python (sympy: 14%); JIDRA's tree-sitter extractor indexes standalone functions and hooks CG misses
• scikit-learn's 48% ceiling is a semantic gap: high-level math concept queries (e.g. "ridge regression convergence") have no lexical match to function names — requires embedding-based search

Per-repo detailed reports: [docs/evals/](docs/evals/) Consolidated analysis: [docs/FINDINGSPYTHON.md](docs/FINDINGSPYTHON.md) · [docs/FINDINGSTYPESCRIPT.md](docs/FINDINGSTYPESCRIPT.md) · [docs/JIDRAvsCodeGraphretrievalall.md](docs/JIDRAvsCodeGraphretrievalall.md)

What JIDRA Does NOT Do (By Design)

• ❌ Autonomous agent loops - Claude already does this; we provide context
• ❌ Multi-service distributed reasoning - Requires service mesh, not code analysis
• ❌ Interactive debugging sessions - Single-shot context generation (not loops)
• ❌ Config-driven behavior analysis - YAML/JSON parsing planned for v2.0
• ❌ Full semantic Java correctness - AST + Actuator validation is best-effort

Bottom line: JIDRA is infrastructure FOR agents, not a replacement agent.

Project Layout

jidra/
├── pyproject.toml
├── requirements.txt
├── Cargo.toml                     # workspace root for jidra-resolver
├── README.md
├── src/jidra/                     # Python package (src layout)
│   ├── cli.py
│   ├── models.py
│   ├── config.yaml
│   ├── extractors/
│   │   ├── extractor.py           # dispatcher — routes to language-specific extractor
│   │   ├── ts_extractor.py        # TypeScript (tree-sitter or Docker sidecar)
│   │   ├── ts_treesitter.py       # in-process tree-sitter TS backend (default, no Docker)
│   │   ├── go_extractor.py        # Go (tree-sitter, in-process)
│   │   ├── py_extractor.py        # Python (AST + symbol table)
│   │   ├── scala_extractor.py     # Scala (SemanticDB two-pass)
│   │   └── smithy_extractor.py    # Smithy IDL extraction
│   ├── filters/
│   │   ├── filters.py             # Java file iteration
│   │   ├── file_filters.py        # shared file-level filtering helpers
│   │   ├── ts_filters.py          # TS language detection + file iteration
│   │   ├── go_filters.py          # Go file iteration + excluded dirs
│   │   ├── py_filters.py          # Python language detection
│   │   ├── py_type_provider.py    # Python type validation (Pyright)
│   │   └── scala_filters.py       # Scala file iteration + excluded dirs
│   ├── graph/
│   │   ├── graph_store.py         # SQLite graph DB (read/write, FTS5, migrations)
│   │   ├── graph_rag.py           # retrieval-augmented graph search
│   │   ├── graph_validator.py     # Spring Actuator validation + edge filtering
│   │   └── graph_visualizer.py    # interactive HTML export
│   ├── engine/
│   │   ├── engine.py              # full index pipeline orchestrator
│   │   ├── reindexer.py           # incremental reindex (fingerprint-based)
│   │   ├── parallel.py            # parallel extraction workers
│   │   ├── ranking.py             # result ranking / budget tiers
│   │   ├── daemon.py              # shared-graph daemon (Unix socket RPC, hot-reload)
│   │   └── watcher.py             # debounced filesystem watcher → incremental reindex
│   ├── server/
│   │   ├── mcp_server.py          # MCP tool surface (primary + full tiers)
│   │   ├── proxy.py               # stdio↔socket MCP proxy (spawns daemon)
│   │   └── actuator_client.py     # Spring Actuator HTTP client
│   ├── flow/
│   │   ├── flow_stitcher.py       # deterministic flow-doc generator
│   │   └── flow_doc_agent.py      # LLM-assisted flow documentation
│   ├── indexing/
│   │   ├── doc_indexer.py         # doc/README indexer
│   │   ├── doc_store.py           # doc chunk storage
│   │   ├── doc_graph_visualizer.py
│   │   ├── resources_chunker.py
│   │   ├── resources_indexer.py
│   │   └── resources_linker.py    # links doc chunks to graph nodes
│   ├── llm/
│   │   ├── llm_client.py          # LiteLLM provider wrapper
│   │   ├── trace_engine.py        # method execution trace + uncertainty markers
│   │   ├── cost_calculator.py     # token/cost measurement
│   │   └── telemetry.py           # run history + telemetry dashboard
│   ├── utils/
│   │   ├── context_builder.py     # prompt-ready context assembly
│   │   ├── selector.py            # method selector resolution
│   │   ├── git_hooks.py           # post-commit/merge/checkout hook installer
│   │   ├── cache.py
│   │   ├── parser.py
│   │   └── ui.py                  # CLI rich output helpers
│   ├── smithy/
│   │   ├── smithy_bridge.py       # Smithy → graph bridge
│   │   └── smithy4j_builder.py
│   ├── ui/                        # Flask API server (serves the React UI)
│   │   ├── app.py
│   │   └── routes/
│   │       ├── graph_routes.py
│   │       ├── index_routes.py
│   │       ├── explore_routes.py
│   │       ├── docs_routes.py
│   │       ├── history_routes.py
│   │       ├── mcp_routes.py
│   │       ├── sql_routes.py
│   │       └── util_routes.py
│   └── claude_install/            # files shipped into .claude/ by `jidra init`
│       ├── agents/                # jidra-investigator agent definition
│       └── skills/                # jidra-navigate + jidra-blast-radius skills
├── jidra-resolver/                # Rust extension (PyO3/maturin) — fast call resolution
│   ├── Cargo.toml

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [akhilsinghcodes](https://github.com/akhilsinghcodes)
- **Source:** [akhilsinghcodes/jidra](https://github.com/akhilsinghcodes/jidra)
- **License:** MIT

Install and usage instructions live in the source repository linked above.