code-graph-llm

v5.1.0

Published

3 months ago

Compact, language-agnostic codebase mapper for LLM token efficiency.

0High
0Medium
0Low

jabhijeet

llm context token-efficiency codebase-map ai-agent documentation

CODE-GRAPH (v5.1.0)

Inspired by Andrej Karpathy skills, juliusbrussee/caveman, and the community's work building better agent workflows.

A language-agnostic, ultra-compact codebase mapper and agent memory system for LLM agents. Code-Graph gives agents a compact file, symbol, and dependency index, then pairs it with persistent project learnings so agents can avoid repeating mistakes across sessions.

New in v5.1.0

MCP Tools (3 new): Added get_project_graph (reads full llm-code-graph.md — use instead of Read), search_symbols (symbol search across all files — use instead of Grep), and trace_dependencies (upstream/downstream blast radius for a file — use instead of manual EDGES parsing). Server now exposes 8 tools total.
MCP Structured Errors: All tool handlers return { isError: true, content: [{ type: "text", text: JSON.stringify({ error_type, message, retryable, suggested_action }) }] }. Error types: GRAPH_NOT_FOUND, FILE_NOT_IN_GRAPH, INVALID_PATH, INVALID_INPUT, TOOL_TIMEOUT, UNKNOWN_TOOL, INTERNAL_ERROR. Agents can branch on error_type and use suggested_action to self-correct.
MCP Timeouts: All tool calls are wrapped in Promise.race with a timeout. Default: 30s. generate_graph: 300s (5 min). Timeout returns TOOL_TIMEOUT with retryable: true.
Agent Descriptions (WHEN/INSTEAD): All sub-agent descriptions for Claude Code, Gemini, Kiro, Antigravity, and generic platforms now follow the WHEN/INSTEAD pattern — describing trigger conditions and what they replace (Read, Grep, manual EDGES parsing) rather than abstract capability labels.
Skills (MCP awareness): ProjectMap and Reflections skills now include conditional MCP tool guidance for all 40+ supported platforms: get_project_graph instead of Read, search_symbols instead of Grep, add_reflection/get_reflections instead of CLI and direct file reads.
Generated rules (MCP section): llm-agent-rules.md scaffolded by code-graph init now includes a full MCP tools section listing all 8 tools with INSTEAD guidance.
Gitignore (generated platform files): Added all generated platform output files to .gitignore (GEMINI.md, AGENTS.md, .clinerules, .roorules, .kiro/, .opencode/, .roo/, .cursor/rules/, llm-agent-rules.md, llm-agent-project-learnings.md, and others) to prevent machine-specific paths from being committed.
Tests: Fixed 2 broken error tests (new structured error format), added 13 new tests for handleGetProjectGraph, handleSearchSymbols, handleTraceDependencies, INVALID_PATH validation, and GRAPH_NOT_FOUND with suggested_action. 24 tests total in mcp-server.test.js.

See RELEASE_NOTES.md for full history.

Installation

# Global installation (recommended for CLI usage)
npm install -g code-graph-llm

# Project-level installation
npm install --save-dev code-graph-llm

Quick Start

# 0. Check version and help
code-graph --version
code-graph --help

# 1. Initialize rules and memory
code-graph init

# 2. Build the graph
code-graph generate

# 3. Install all bundled skills for one agent
code-graph install-skills claude

# 4. Or install globally for all projects
code-graph install-skills -g claude

Every install prints each target it writes:

[Code-Graph v5.0.0] Installed/updated: /absolute/path/to/AGENTS.md
[Code-Graph v5.0.0] Installed/updated: /absolute/path/to/.codex/hooks.json

Core Concepts

Code-Graph operates in two modes: Passive Skills and Active Agents.

Unified Installation

Get the full Code-Graph experience by installing both skills and the active sub-agent in one command.

code-graph install gemini

Uninstall with:

code-graph uninstall <platform>

Passive Skills

Skills are always-on configurations that tell your agent how to use the project map and memory files. code-graph install-skills <platform> installs all bundled skills by default for every supported platform.

ProjectMap: Reads llm-code-graph.md, the canonical file, symbol, and dependency index, before raw file searches.
Reflections: Reads and updates llm-agent-project-learnings.md so agents retain project-specific lessons.
ThinkBeforeCoding: Surfaces assumptions, ambiguity, tradeoffs, and simpler options before non-trivial work.
Simplicity: Keeps changes limited to what the task actually requires.
SurgicalChanges: Prevents unrelated refactors, style churn, and scope creep while allowing cleanup caused by your own diff.
GoalDriven: Forces explicit success criteria and verification before completion.
FreshDeps: Forces latest stable compatible dependencies and current, non-deprecated APIs.
ContextBudget: Periodically condenses working context to reduce token load and stale detail.

# Install all bundled skills
code-graph install-skills gemini

# Install one skill
code-graph install-skills cursor projectmap

# Install only dependency freshness rules
code-graph install-skills codex freshdeps

# Install surgical diff rules (CLI alias remains changelimit-compatible)
code-graph install-skills claude surgicalchanges

# Uninstall one skill
code-graph uninstall-skills claude reflections

# Uninstall all skills for a platform
code-graph uninstall-skills claude

Active Agents

Agents are specialized personas. Instead of only reading project files, a main orchestrator such as Gemini CLI or Claude Code can delegate mapping and analysis work to the Code-Graph agent.

# Register code-graph as a sub-agent
code-graph install-agent claude

# Example delegation:
# "Hey code-graph, analyze the dependency chain of the auth module."

Uninstall with:

code-graph uninstall-agent <platform>

Claude Code receives focused sub-agents when available:

code-graph: Use INSTEAD of reading source files for architectural overviews, refreshing the map, or persisting lessons after failures.
code-graph-locator: Use INSTEAD of Read/Grep when finding relevant files before exploring source. Trigger: "which files relate to X", "where is Y defined".
code-graph-tracer: Use INSTEAD of manual import tracing when assessing change impact. Trigger: "what depends on X", "what breaks if I change Y".
code-graph-reviewer: Use AFTER making changes to verify Code-Graph protocol compliance. Trigger: "check code-graph protocol", "is the map stale".

Supported Platforms

Use -g before the platform to install skills globally. Without -g, skills are installed for the current project when the platform supports project-level instructions.

Platform Integration Details

Every supported platform receives all bundled skills when installing all skills. Platforms with native skill or rule formats get native artifacts; the rest receive the same mandatory instructions through their project instruction file, usually AGENTS.md.

Agent Workflow

Instruct your agent to follow the strict protocol in llm-agent-rules.md:

Treat every bundled skill as mandatory: ProjectMap, Reflections, ThinkBeforeCoding, Simplicity, SurgicalChanges, GoalDriven, FreshDeps, and ContextBudget.
Read llm-agent-project-learnings.md before starting any task.
Read llm-code-graph.md before raw file searches or architecture analysis.
Surface assumptions and ambiguity before non-trivial work.
Define success criteria and report verification results or blockers.
Use latest stable compatible dependencies and current APIs; avoid deprecated packages, methods, functions, flags, and patterns.
Update reflections after failures, corrections, repeated mistakes, or non-obvious project behavior.
Regenerate llm-code-graph.md after structural code changes.

Recommended generic prompt:

Before acting, read llm-code-graph.md and follow llm-agent-rules.md. Treat all bundled skills as mandatory. Use latest stable compatible dependencies and current APIs; avoid deprecated choices. If you encounter a bug, environment quirk, or reusable project lesson, record it with code-graph reflect <CAT> <LESSON>.

Reading the Map

llm-code-graph.md is a compact index generated from the project. Each file entry is designed to help an agent decide which files matter before opening raw source:

* marks a core entry point or high-importance file.
(↑out ↓in) shows dependency counts. Outgoing dependencies are files or packages this file references; incoming dependencies are files that reference it.
d: is a short description extracted from file comments or nearby context.
s: lists important symbols found in the file, such as classes, functions, types, and exported values.
The ## EDGES section lists dependency relationships in the form [source] -> [targets].

For example:

- *src/auth.js (3↑ 5↓) [TODO:Add JWT rotation] | d: Handles user authentication.
  - s: [login [(username, password)], validateToken [(token: string)]]

## EDGES
[src/auth.js] -> [jwt-lib, db-connector]
[AdminUser] -> [BaseUser]

This means src/auth.js is a core file with 3 outgoing dependencies and 5 incoming references. It contains the login and validateToken symbols, has a TODO about JWT rotation, depends on jwt-lib and db-connector, and includes an inheritance relationship where AdminUser extends or implements BaseUser.

Sub-Agent Registration

MCP Server (Claude Code integration)

Any Claude Code project can connect to code-graph as an MCP tool server.

Add to your project's .mcp.json:

{
  "mcpServers": {
    "code-graph": {
      "command": "code-graph",
      "args": ["mcp"]
    }
  }
}

Or if using a local dev install:

{
  "mcpServers": {
    "code-graph": {
      "command": "node",
      "args": ["/absolute/path/to/code-graph/index.js", "mcp"]
    }
  }
}

Available tools

| Tool | When to use | Description | |------|-------------|-------------| | get_project_graph | INSTEAD of Read on the graph file | Read full llm-code-graph.md — fastest way to get project structure | | search_symbols | INSTEAD of Grep for symbol lookup | Search symbol names across all files (case-insensitive) | | trace_dependencies | INSTEAD of manual EDGES parsing | Outgoing + incoming deps for a file, plus blast_radius count | | generate_graph | When map is stale or missing | Build/refresh llm-code-graph.md for any project path | | get_file_symbols | Targeted file lookup | Return symbols for one specific file from the graph | | search_graph | Broad search | Search file paths, symbols, and descriptions together with scoring | | add_reflection | INSTEAD of code-graph reflect CLI | Append a lesson to llm-agent-project-learnings.md | | get_reflections | INSTEAD of reading the reflections file | Return all lessons, optionally filtered by category |

All tools require project_path (absolute path) — one running server handles multiple projects.

Error format: All tools return structured errors with isError: true and JSON content: { error_type, message, retryable, suggested_action? }. Agents can branch on error_type (e.g. GRAPH_NOT_FOUND → call generate_graph first).

Implementation Details

Project Structure

index.js              CLI entry point and public re-exports
lib/
  config.js           Constants, regex patterns, shared utilities
  parser.js           CodeParser: symbol, edge, and tag extraction
  mapper.js           ProjectMapper: file walking and graph generation
  reflections.js      ReflectionManager: lesson persistence
  initializer.js      ProjectInitializer: rule and reflection scaffolding
  install-log.js      Shared versioned install target logging
  mcp-server.js       MCP stdio server: 8 tools, structured errors, per-tool timeouts
  skills.js           SkillManager: platform skill installation
  agents.js           AgentManager: sub-agent registration
test/
  index.test.js       Unit tests for parser, mapper, skills, and CLI behavior
  mcp-server.test.js  Unit tests for MCP server tool handlers
  platform-audit.js   Integration checks across supported platforms

Pipeline

File Scanning: Recursively walks the directory while respecting nested .gitignore patterns.
Context Extraction: Scans for classes, functions, variables, and comments while stripping literals to reduce false matches.
Graph Extraction: Identifies imports, requires, extends, and implements edges.
Tag Extraction: Captures TODO, FIXME, BUG, and DEPRECATED tags from comments.
Reflection Management: Deduplicates and persists agent learnings into a standardized Markdown file.
Compilation: Writes a compact llm-code-graph.md file with capped descriptions, symbols, tags, and a dedicated ## EDGES section.