GRAPHIQ

Local code search that understands how your code is connected

+48% NDCG@10, +128% MRR@10 vs grep across 300 benchmark queries
Structural graph indexing · zero network · single SQLite file · ~18μs query latency

Docs · Benchmarks · Research · Discussions

---

Local code search with structural memory GraphIQ turns a repository into a searchable code graph: symbols, files, calls, imports, type flow, error surfaces, comments, constants, and the relationships between them. Substring search finds what you typed. GraphIQ finds what the code is connected to. Ask for "rate limit middleware" and GraphIQ can land on rateLimitMiddleware, then follow the graph to TokenBucket, ThrottleConfig, and checkRateLimit even when those names do not share the same words.

query | lexical seeds | structural graph / | \ calls imports constants \ | / ranked symbols zero network · single SQLite file · no LLM required

⚡ Start in 20 seconds

graphiq index /path/to/project
graphiq search "rate limit middleware"

Or wire it into an editor/agent harness:

graphiq setup --project /path/to/project

Use graphiq setup --harness cursor or any supported harness name to target one integration.

📦 Install

Homebrew

brew tap aaf2tbz/graphiq
brew install graphiq

Install script (Recommended Method

curl -fsSL https://raw.githubusercontent.com/aaf2tbz/graphiq/main/install.sh | bash

From source

git clone https://github.com/aaf2tbz/graphiq.git
cd graphiq
cargo build --release

Installs graphiq, graphiq-mcp, and graphiq-bench.

Why it works

🎯 [01] Lexical precision BM25 FTS5 handles exact symbol names, identifiers, file paths, and decomposed camelCase/snake_case terms.

🕸️ [02] Graph recall Seed results expand through calls, imports, constants, type edges, error surfaces, and local neighborhoods.

🧭 [03] Query routing Eight query families tune scoring for symbols, natural language, relationships, errors, files, constants, and architecture questions.

BM25 name match + graph walk + structural aliases + family weights | | | | +----------------+------------------+--------------------+ | stable ranked results

The result is a compact local index with the codebase's structure baked in, so agents can search by intent without shipping your source to a remote embedding service.

📈 Benchmark Signal

Current v3.1 benchmarks cover 300 queries across signetai, esbuild, and tokio. Full methodology lives in docs/benchmarks.md.

Codebase	Grep NDCG@10	GraphIQ NDCG@10	Grep MRR@10	GraphIQ MRR@10
signetai	0.143	0.286 (+100%)	0.144	0.450 (+213%)
esbuild	0.200	0.318 (+59%)	0.145	0.551 (+280%)
tokio	0.193	0.192 (-1%)	0.330	0.411 (+25%)
Overall	0.179	0.265 (+48%)	0.206	0.471 (+128%)

Query shape	Result vs grep	Signal
Relationship queries	3.9x	Graph traversal finds connected symbols substring search misses
Natural language queries	2.0x	Identifier decomposition plus family-aware scoring
Error/debug queries	1.2x	Error surfaces and shared constants become searchable structure
Exact symbol queries	tied	BM25 is already excellent when names are known

🛠️ Agent Tools

graphiq-mcp exposes 14 JSON-RPC tools over stdio:

Tools

Tool	Use it for
briefing	Project overview and starting context
search	Ranked symbol search with filters
context	Source plus structural neighborhood
blast	Forward/backward impact analysis
interrogate	Deep symbol inspection
topology	Local code topology
why	Ranking explanation
explain	Natural-language symbol explanation
dead_code	Unreachable symbols grouped by file
constants	Numeric/string constant lookup
status	Index stats and health
doctor	Artifact validation
index	Manual reindex
upgrade_index	Rebuild stale artifacts

Supported Harnesses

Claude Code · Claude Desktop · OpenCode · Codex CLI · Cursor · Windsurf · Gemini CLI · Hermes Agent · Aider

Config / Setup

Configure all supported harnesses

graphiq setup --project /path/to/project

Configure one harness only

graphiq setup --harness cursor

Run the MCP server with file watching

graphiq-mcp /path/to/project --watch

The MCP server lazily builds its in-memory index on first search and detects/recreates corrupted databases automatically.

🗂️ What gets indexed

Layer	Examples
Symbols	functions, methods, classes, interfaces, traits, structs, enums, modules
Structure	calls, imports, type flow, references, constants, containment
Context	comments, signatures, file paths, sibling symbols, error surfaces
Maintenance	dead code, blast radius, topology, index health

🧩 System Shape

Query
  → Query Family Router (8 families)
  → Seed Generation (BM25 FTS5 → per-term expansion → graph walk → numeric bridges)
  → Scoring (IDF coverage + name overlap + neighbor fingerprints + specificity scaling + structural aliases)
  → Ranked results

The full architecture is documented in How GraphIQ works.

🌐 Languages

Full parsing: TypeScript, TSX, JavaScript, JSX, Rust, Python, Go, Java, C, C++, Ruby, YAML, TOML, JSON, HTML, CSS

File tracking: Kotlin, Swift, C#, PHP, Lua, Dart, Scala, Haskell, Elixir, Zig, GraphQL, Protobuf, Shell, SQL, Markdown, XML, SCSS, CMake, Dockerfile, Makefile, Meson

⚙️ Performance

Mode	Latency
Cold CLI (first run)	~5–10s
Warm CLI (cached)	~50ms
In-process (MCP)	~18μs

Index size for a ~20K symbol codebase: ~6.5MB.

📚 Docs

How GraphIQ works · Benchmarks · Research notes

🧪 Development

git clone https://github.com/aaf2tbz/graphiq.git
cd graphiq
cargo build --release
cargo test

Desktop App

cd apps/desktop
npm install
npm run dev

Build an installable desktop package with:

cd apps/desktop
npm run package

The packaged app is written to apps/desktop/release/.

cargo bench
graphiq index .
graphiq search "query family router"

Requirements: Rust 1.75+, macOS or Linux.

🔌 Agent Skill

GraphIQ is available as an installable agent skill on skills.sh.

npx skills add aaf2tbz/graphiq

Installs the GraphIQ skill into Claude Code, Cursor, OpenCode, Codex, Windsurf, and 40+ other agents.

🧼 Uninstall

curl -fsSL https://raw.githubusercontent.com/aaf2tbz/graphiq/main/install.sh | bash -s -- uninstall

License

MIT.

---

[GitHub](https://github.com/aaf2tbz/graphiq) · [Homebrew](https://github.com/aaf2tbz/homebrew-graphiq) · [skills.sh](https://skills.sh/aaf2tbz/graphiq/graphiq) · [crates.io](https://crates.io/crates/graphiq) · [discussions](https://github.com/aaf2tbz/graphiq/discussions) · [issues](https://github.com/aaf2tbz/graphiq/issues)