Why KiroGraph

KiroGraph is a semantic code knowledge graph built specifically for Kiro. It gives Kiro a pre-indexed understanding of your codebase: symbol relationships, call graphs, type hierarchies, impact radius, so it can answer complex questions in a single MCP tool call instead of cascading through file reads, greps, and globs.

The problem

When an AI coding agent works on a complex task, it explores your codebase one tool call at a time: read a file, grep for a symbol, glob for related files, read another file. Each of those burns context window and adds latency. On large codebases this becomes the bottleneck: not the reasoning, but the exploration.

The approach

KiroGraph parses your entire codebase with tree-sitter, extracts symbols and their relationships into a local SQLite graph database, and optionally generates vector embeddings for natural-language search. The result is a structured knowledge graph that can answer "who calls this function?", "what breaks if I change this?", or "find code related to authentication" in milliseconds, without reading a single file.

Why Kiro

KiroGraph is designed around Kiro's architecture:

• MCP integration: Kiro's native MCP support means KiroGraph tools are auto-approved and always available, no manual configuration needed.
• Hooks system: Kiro's file event hooks (fileEdited, fileCreated, fileDeleted, agentStop) keep the index fresh automatically with zero overhead during editing. No background watcher process.
• Steering files: Kiro's steering mechanism teaches the agent to prefer graph tools over file scanning, always in context with no extra tool calls.
• CLI agent: Kiro CLI's agent system allows a dedicated KiroGraph agent with inlined instructions and session-boundary sync hooks.

This tight integration is why Kiro is the primary and fully supported target. The hooks, steering, and agent config are all Kiro-native concepts that make the experience seamless.

Scope and other tools

The core of KiroGraph (the graph database, tree-sitter parsing, MCP server, and CLI) is tool-agnostic. Any MCP-capable client can query the same graph. Experimental integrations for Claude Code and Codex are available via kirograph install --target claude|codex, but they lack the automatic sync hooks and steering that make the Kiro experience seamless.

Issues and PRs for non-Kiro targets are welcome, but there is no guarantee they will be supported or merged without active help from the contributor. The project's development focus remains on the Kiro integration.

Installation

From npm

npm install -g kirograph

From source

git clone https://github.com/davide-desio-eleva/kirograph.git
cd kirograph
npm install
npm run build
sudo npm install -g .

After building, both kirograph and the short alias kg are available globally.

Verify

kirograph --version

Uninstalling

# Remove from a project
kirograph uninit [path]      # prompts to remove integration files and .kirograph/ data
kirograph uninit --force     # remove everything without confirmation

# Remove the CLI globally (npm)
npm uninstall -g kirograph

# Remove the CLI globally (from source)
cd kirograph && npm uninstall -g .

Quick Start

Run this inside any project you want to index:

kirograph install    # interactive setup: wires MCP + hooks + steering + CLI agent

The installer prompts you for:

• Whether to enable embeddings (semantic search)
• Embedding model and semantic engine
• Whether to enable architecture analysis
• Caveman mode level
• Whether to run an initial index immediately

Then restart Kiro IDE (or run kiro-cli --agent kirograph). Kiro will now use KiroGraph tools automatically whenever you ask it to work on your code.

How Indexing Works

Indexing has three layers: structural (always on), semantic (opt-in), and architecture (opt-in).

Structural layer

tree-sitter parses every source file into an AST. Nodes and edges are extracted and written to .kirograph/kirograph.db. This powers all graph traversal tools and exact/FTS symbol search. No extra dependencies. Runs on every kirograph index or kirograph sync.

Extracts 24 node kinds: function, method, class, interface, struct, trait, protocol, enum, type_alias, property, field, variable, constant, enum_member, parameter, import, export, route, component, file, module, namespace, and more.

13 edge types: calls, imports, exports, extends, implements, contains, references, instantiates, overrides, decorates, type_of, returns, uses.

Semantic layer (opt-in)

When enableEmbeddings: true, KiroGraph generates 768-dimensional vector embeddings for every embeddable symbol using nomic-ai/nomic-embed-text-v1.5 (~130 MB, downloaded once to ~/.kirograph/models/). Powers natural-language search in kirograph_context.

Seven pluggable semantic engines:

Architecture layer (opt-in)

When enableArchitecture: true, KiroGraph detects packages and architectural layers (api, service, data, ui, shared) and computes coupling metrics (Ca, Ce, instability) between them. Results stored in arch_* tables in kirograph.db.

Supported Languages

General-purpose

Frontend & UI

Domain-specific

Configuration & Infrastructure

Framework Detection

KiroGraph auto-detects frameworks and enriches the graph with framework-specific semantics (routes, components, lifecycle methods).

Web Frameworks

Infrastructure as Code

Containers & Orchestration

Configuration Management

Detected frameworks are stored in config and used to improve symbol extraction and resolution. Routes, components, and lifecycle methods are extracted as first-class nodes in the graph.

Using with Kiro

kirograph install sets up four things in your Kiro workspace. All coexist, so you can switch between IDE and CLI freely. Kiro is the primary and fully supported target.

MCP Server (.kiro/settings/mcp.json)

Registers the KiroGraph MCP server with all 18 tools auto-approved. Used by both the IDE and the CLI agent.

{
  "mcpServers": {
    "kirograph": {
      "command": "kirograph",
      "args": ["serve", "--mcp"],
      "autoApprove": [
        "kirograph_search", "kirograph_context", "kirograph_callers",
        "kirograph_callees", "kirograph_impact", "kirograph_node",
        "kirograph_status", "kirograph_files", "kirograph_dead_code",
        "kirograph_circular_deps", "kirograph_path", "kirograph_type_hierarchy",
        "kirograph_architecture", "kirograph_coupling", "kirograph_package",
        "kirograph_hotspots", "kirograph_surprising", "kirograph_diff"
      ]
    }
  }
}

IDE Auto-Sync Hooks (.kiro/hooks/)

Hooks fire for: .ts, .tsx, .js, .jsx, .py, .go, .rs, .java, .cs, .rb, .php, .swift, .kt, .dart, .ex, .exs

CLI Agent Config (.kiro/agents/kirograph.json)

A custom agent for Kiro CLI that wires up the MCP server and inlines steering instructions. Sync is handled at session boundaries:

kiro-cli --agent kirograph
# or, inside an active session:
/agent swap kirograph

Steering File (.kiro/steering/kirograph.md)

Teaches the Kiro IDE to prefer graph tools over file scanning when .kirograph/ exists. Uses inclusion: always so it's in context on every turn. The CLI agent has the same instructions inlined in its prompt field.

Other Tools (Experimental)

KiroGraph can also be installed for other MCP-capable coding agents. All targets share the same .kirograph/ data; if the project is already initialized, installing another target only writes that tool's integration files.

Claude Code

kirograph install --target claude

Writes .mcp.json (project-scoped MCP config), .kirograph/claude.md (tool guidance), and imports it from CLAUDE.md. Claude Code prompts for MCP approval the first time it sees .mcp.json.

Codex

kirograph install --target codex

Writes .kirograph/codex.md (tool guidance) and a generated block in AGENTS.md. Codex MCP configuration is user-scoped, so the installer prints the exact codex mcp add ... command instead of editing files outside the project.

Configuration

All configuration is in .kirograph/config.json. The interactive kirograph install writes this for you.

Caveman Mode

Caveman mode compresses the agent's communication style, cutting token usage on responses without affecting tool calls or code output. Inspired by caveman by JuliusBrussee.

The rules are injected at session start via the steering file (IDE) and the inline agent prompt (kiro-cli), so they're always in context with no extra tool calls.

Caveman mode never touches code blocks, file paths, URLs, or technical terms, only prose.

Auto-clarity exceptions: the agent temporarily reverts to normal prose for security warnings, confirmations of irreversible actions (delete, overwrite, force-push), and multi-step sequences where fragment order could cause misunderstanding. Compressed style resumes immediately after.

kirograph caveman lite    # set mode
kirograph caveman         # show current mode

Credits

Original idea

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.

Contributors

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

Stargazers & Community

Thank you to everyone who contributed and starred the project on GitHub.