KiroGraph

Semantic code knowledge graph for Kiro: fewer tool calls, instant symbol lookups, 100% local.

Inspired by CodeGraph by colbymchenry for Claude Code, rebuilt natively for Kiro's MCP and hooks system.

Full support is for Kiro only. Experimental integrations for 34 other MCP-capable tools (Cursor, Copilot, Claude Code, Windsurf, Cline, and more) are available with auto-detection. See Integrations for the full list.

Why KiroGraph?

When you ask Kiro to work on a complex task, it explores your codebase using file reads, grep, and glob searches. Every one of those is a tool call, and tool calls consume context and slow things down.

KiroGraph gives Kiro a semantic knowledge graph that's pre-indexed and always up to date. Instead of scanning files to understand your code, Kiro queries the graph instantly: symbol relationships, call graphs, type hierarchies, impact radius, all in a single MCP tool call.

The result is fewer tool calls, less context used, and faster responses on complex tasks.

Features

| Feature | Description | |---------|-------------| | Graph & Analysis (KiroGraph-Core) | | | 🕸️ Semantic Graph | tree-sitter AST parsing across 33+ languages — functions, classes, call edges, type hierarchies, all in SQLite | | 🎯 Context Building | One tool call returns entry points, related symbols, and code snippets for any task description | | 💥 Impact Analysis | Blast-radius traversal before making changes — know what breaks at any depth | | 🧬 Type Hierarchy | Traverse inheritance chains — base types, derived types, implementations | | 🔄 Circular Dependency Detection | Find import cycles using Tarjan's SCC algorithm | | 💀 Dead Code Detection | Find unexported symbols with zero incoming references | | 🔥 Hotspots & Surprises | Identify most-connected symbols and unexpected cross-module coupling | | 🧪 Affected Tests | Find test files impacted by source changes — useful in CI and pre-commit hooks | | 🌐 Graph Export | Interactive browser dashboard with search, clustering, path finding, and analytics | | Semantic Search | | | ⚡ 7 Semantic Engines | Cosine, sqlite-vec, Orama, PGlite, LanceDB, Qdrant, Typesense — pick the best fit for your project | | 🤖 Custom Embedding Models | Use any HuggingFace feature-extraction model — nomic, Gemma, MiniLM, BGE, or bring your own | | Architecture (KiroGraph-Arch opt-in module) | | | 🏛️ Architecture Analysis | Package graph, layer detection, coupling metrics (Ca/Ce/instability) | | 📸 Snapshots & Diff | Save graph state before refactors, diff after to verify structural changes | | Security | | | 🔒 Security (KiroGraph-Sec opt-in module) | Goes beyond "this dependency has a CVE" — uses the call graph to determine if vulnerable code is actually reachable from your entry points. Maps your attack surface (which HTTP routes reach vulnerable deps). Detects hardcoded secrets and shows how many entry points expose them. SAST-lite finds SQL injection, path traversal, and dangerous eval in your code. AST-based SAST (opt-in via enablePatterns) runs 10 bundled structural pattern rules via @ast-grep/napi — matches actual code structure, not just symbol names. Supply chain health checks OpenSSF Scorecard scores and detects dependency confusion attacks. Covers 14 ecosystems, outputs CycloneDX SBOM/VEX and CI-ready SARIF reports. | | Knowledge & Data | | | 🧠 Persistent Memor (KiroGraph-Mem opt-in module) | Cross-session observations — decisions, errors, patterns — auto-linked to code symbols | | 👁️ Watchmen (KiroGraph-Watchmen opt-in module) ⚠️ experimental | Auto-synthesizes accumulated memory observations into workspace briefs and inclusion: manual skill files. Fires via the watchmenReady signal in kirograph_mem_store when threshold is reached. Local model (default, watchmenSynthesisMode: 'local'): runs gemma-4-E4B-it-ONNX on-device via @huggingface/transformers — ~3–4 GB one-time download, ~3–5 GB RAM, 8–15 s on Apple Silicon M1+. No API key, no background daemon, no external calls. Agent mode also available for Kiro (watchmenSynthesisMode: 'agent', uses active session). ⚠️ Experimental: output quality in local mode depends heavily on the model chosen and your hardware. Smaller models or slower machines may produce incomplete briefs and lower-quality skill files. Use agent mode for best results. | | 📖 Documentation Indexing (KiroGraph-Doc opt-in module) | Section-level retrieval from Markdown, MDX, RST, AsciiDoc, OpenAPI — 92-97% token savings | | 📊 Data Navigation (KiroGraph-Data opt-in module) | Query CSV/JSON/Excel/Parquet with filters, aggregations, joins — all server-side in SQLite | | Token Optimization | | | 🗜️ Shell Compression (KiroGraph-RTK opt-in module) | Token-optimized command output (git, tests, linters, docker, AWS) — 60-90% savings | | 🪨 Caveman Mode (KiroGraph-Caveman opt-in module) 🪨 | Agent prose compression (lite → ultra) — fewer tokens on explanations without touching code | | 📈 Token Analytics (KiroGraph-Gain core module) | Track cumulative savings from graph tools and shell compression over time | | Integration (KiroGraph-Integration core module) | | | 🔌 Multi-tool Support | Native Kiro + 32 experimental targets (Cursor, Copilot, Claude Code, Codex, Windsurf, Cline, and more) |

Quick Start

kirograph install        # auto-detects your AI tools and configures them all

Or target a specific platform:

kirograph install --target kiro       # Kiro only
kirograph install --target cursor     # Cursor only
kirograph install --target claude     # Claude Code only
kirograph install --all               # all detected platforms (no prompt)

Or using the short alias:

kg install

All Kiro integration files are written to .kiro/. Restart Kiro IDE, or switch to the kirograph agent in Kiro CLI.

Documentation

📖 Full documentation on GitHub Pages

| Page | Description | |------|-------------| | Installation | Install from npm or source, uninstall, verify | | How It Works | Indexing layers (structural, semantic, architecture, memory, docs, data) | | Integrations | Kiro setup, 34 other tools, auto-detection | | Comparison | Feature comparison vs CodeGraph, code-review-graph, and others | | MCP Tools | Full reference for all MCP tools | | CLI Reference | All CLI commands with examples | | Configuration | Config fields, semantic engines, architecture analysis | | Security | Full SCA+: 14 ecosystems, EPSS, reachability, attack surface, secrets, SAST-lite, AST pattern matching (opt-in), supply chain, SBOM/VEX/SARIF | | Languages & Frameworks | Supported languages, frameworks, and detection | | Changelog | Release history | | Contributing | How to contribute | | Code of Conduct | Community guidelines | | Security | Security policy |

How It Works

┌─────────────────────────────────────────┐
│                  Kiro                   │
│                                         │
│  "Fix the auth bug"                     │
│           │                             │
│           ▼                             │
│  kirograph_context("auth bug")          │
│           │                             │
└───────────┼─────────────────────────────┘
            ▼
┌───────────────────────────────────────────┐
│         KiroGraph MCP Server              │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐   │
│  │  search  │ │ callers  │ │ context  │   │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘   │
│       └────────────┼────────────┘         │
│         SQLite Graph DB (.kirograph/)     │
└───────────────────────────────────────────┘

What Gets Indexed?

KiroGraph uses tree-sitter to parse your source files into an AST and extract:

• Nodes: functions, methods, classes, interfaces, types, enums, variables, constants, routes, components, dependencies, vulnerabilities, and more (26 node kinds total)
• Edges: calls, imports, exports, extends, implements, contains, references, instantiates, overrides, decorates, type_of, returns

Everything is stored in a local SQLite database (.kirograph/kirograph.db). Nothing leaves your machine. No API keys. No external services.

Requirements

• Node.js >= 18
• Kiro IDE (fully supported)
• Other MCP-capable tools (experimental — see Integrations)

Credits

KiroGraph is inspired by CodeGraph by Colby McHenry. The original concept of building a semantic code graph for AI coding agents comes from his work.

Inspirations

• cavemem by Julius Brussee: the memory module's hook-based observation capture, deterministic compression, and SQLite storage pattern.
• watchmen by firstbatch: the watchmen module's session-mining concept, workspace brief generation, and AGENTS.md mirroring pattern.
• jDocMunch-MCP by J. Gravelle: the documentation module's section-first retrieval approach, stable section IDs, and byte-offset addressing.
• jDataMunch-MCP by J. Gravelle: the data module's column profiling, streaming parsers, and server-side aggregation approach.
• code-review-graph by Tirth Kanani: community detection, execution flow tracing, refactoring tools, and multi-platform auto-detection patterns.
• lean-ctx by Yves Gugger: file read caching, multiple read modes, and context budget governance concepts.

Contributors

• Alessandro Franceschi — Claude Code and Codex integration, Elixir/Phoenix language and framework support.
• Mauro Argo — original idea for the architecture layer analysis feature.

How It Compares

KiroGraph combines capabilities from 7 separate tools into one integrated MCP server:

| Capability | Inspired by | What KiroGraph adds | |-----------|-------------|---------------------| | Code graph | CodeGraph | Architecture metrics, community detection, execution flows | | Memory | cavemem | Symbol-linked observations, 7 semantic engines | | Docs | jDocMunch-MCP | Code ↔ docs cross-references | | Data | jDataMunch-MCP | Unified with code graph in one server | | Shell compression | rtk | Integrated as MCP tool, no separate binary | | Prose compression | caveman | Multi-level (lite/full/ultra) via steering | | Context layer | lean-ctx | File caching, read modes, budget governance |

See the full comparison for a detailed feature matrix against CodeGraph, code-review-graph, jCodeMunch, and others.

Star History

License

MIT

| Document | Description | |----------|-------------| | License | MIT License — permissions, conditions, copyright | | Disclaimer | Limitations of use, no professional advice, data handling | | Warranty Disclaimer | Software provided "as is", no warranties of any kind | | Limitation of Liability | Exclusion of liability for damages arising from use | | Terms of Use | Permitted and prohibited use, user obligations, privacy |