code-graph-llm

CODE-GRAPH (v3.4.0)

A language-agnostic, ultra-compact codebase mapper and agent memory system designed specifically for LLM agents. It optimizes context and token usage while enabling agents to learn from their own mistakes across sessions.

🚀 New in v3.4: Hyper-Condensed Context

• Token Minification: Condensed llm-code-graph.md output by 30-50% using minified notation.
• Grouped Edges: Consolidated dependency mapping ([src] -> [target1, target2]) for extreme density.
• Metadata Stripping: Removed redundant timestamps from reflections to save context window.
• Robust Uninstall: Defensive file and directory cleanup for all 15+ supported platforms.

🛠️ The Code-Graph Architecture

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

Mode	Paradigm	Benefit	Command
Unified	Both	Complete setup of skills and agent.	code-graph install <platform>
Skills	Passive Context	Injects the graph into the agent's existing loop.	code-graph install-skills
Agents	Active Delegation	Registers code-graph as a specialized sub-agent.	code-graph install-agent

1. Unified Installation (Recommended)

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

# Recommended: Standard full setup
code-graph install gemini

Uninstall using code-graph uninstall <platform>.

2. Code-Graph Skills (Passive)

Skills are "always-on" configurations. They ensure your agent always sees the codebase map before it acts.

• ProjectMap Skill: Architectural awareness and navigation via llm-code-graph.md.
• Reflections Skill: Persistent project memory via llm-agent-project-learnings.md.

Usage:

# Install all skills for a platform
code-graph install-skills gemini

# Selective installation
code-graph install-skills cursor projectmap

2. Code-Graph Agents (Active)

Agents are specialized personas. Instead of just reading a file, the main orchestrator (like Gemini CLI or Claude) can delegate complex mapping or analysis tasks to the Code-Graph agent.

• Native Sub-Agents: Gemini, Antigravity, and Kiro register code-graph as an expert in their global config.
• MCP Servers: Claude and Cursor use the Model Context Protocol to call code-graph as a live tool.
• Persona Prompts: Aider and others use a .code-graph-agent.md system prompt to "become" the specialist.

Usage:

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

# The main agent can now say:
# "Hey code-graph, analyze the dependency chain of the auth module."

🚀 Platform Support Matrix

Configure your agent to use these skills by running the install-skills command. Both skills are installed by default.

Platform	Command
Claude Code	code-graph install-skills claude
Cursor	code-graph install-skills cursor
Gemini CLI	code-graph install-skills gemini
Antigravity	code-graph install-skills antigravity
Kiro IDE/CLI	code-graph install-skills kiro
Roo Code (Cline)	code-graph install-skills roocode
IntelliJ / JetBrains	code-graph install-skills intellij
Codex	code-graph install-skills codex
OpenCode	code-graph install-skills opencode
GitHub Copilot CLI	code-graph install-skills copilot
VS Code Copilot Chat	code-graph install-skills vscode
Aider / Trae / Hermes	code-graph install-skills aider

Selective Installation

You can choose to install or uninstall specific skills:

# Install only the project map
code-graph install-skills gemini projectmap

# Install only reflections
code-graph install-skills cursor reflections

# Uninstall only reflections
code-graph uninstall-skills claude reflections

Uninstall all skills by using uninstall-skills <platform>.

🧠 Workflow: The Reflection Cycle

Skill Installation Details

Platform	Action Taken	Directory / Files
Claude Code	Injects instructions and installs preToolUse hooks for glob and grep.	CLAUDE.md, .claude/settings.json
Cursor	Writes global rule files with alwaysApply: true.	.cursor/rules/projectmap.mdc, .cursor/rules/reflections.mdc
Gemini CLI	Copies skills globally and adds beforeTool hooks for read_file and run_shell_command.	~/.gemini/skills/, GEMINI.md, .gemini/settings.json
Antigravity	Writes always-on rules and registers slash command workflows.	.agent/rules/, .agent/workflows/
Kiro IDE/CLI	Writes global skills and steering files.	~/.kiro/skills/, .kiro/steering/
Codex	Updates AGENTS.md and installs a preToolUse hook for bash.	AGENTS.md, .codex/hooks.json
OpenCode	Registers a plugin that fires before bash tool calls.	AGENTS.md, .opencode/plugins/, opencode.json
Roo Code	Injects instructions into project rule files.	.clinerules, .roomodes
IntelliJ / JetBrains	Adds architectural context to a discoverable file.	AGENTS.md
GitHub Copilot CLI	Copies skills globally for persistence.	~/.copilot/skills/
VS Code Copilot	Writes session-persistent instructions.	.github/copilot-instructions.md
Aider / Trae / etc.	Updates AGENTS.md and copies skills globally.	~/.<platform>/skills/, AGENTS.md

How agents use it:

• Direct Instructions: Most platforms are configured to read project-level files (CLAUDE.md, AGENTS.md, GEMINI.md, etc.) automatically. These files tell the agent: "Before searching files, read llm-code-graph.md."
• Tool Hooks (The "Always-On" Mechanism): For Claude, Gemini, and Codex, the tool installs a blocking hook. When the agent tries to use a search tool (like grep), the hook intercepts the call and injects a reminder: "Knowledge graph exists. Read llm-code-graph.md first." This forces the agent to use the graph for navigation instead of brute-force searching.
• Slash Commands: Some platforms (Kiro, Antigravity) register /code-graph as a command to manually invoke or refresh the graph context.

🧠 LLM Agent Strategy

1. The Mandatory Protocol

Instruct your agent to follow the STRICT AGENT PROTOCOL in llm-agent-rules.md. This ensures the agent:

• Reads llm-agent-project-learnings.md before starting any task.
• Updates reflections after any failure or "learned moment."
• Regenerates the project map (llm-code-graph.md) after structural changes.

2. The "Read First" Strategy

The llm-code-graph.md file provides a high-level map and structural graph for relational reasoning. It is minified for maximum token efficiency.

Notation Legend:

• * : Core Entry Point (God Node).
• (↑out ↓in) : Dependency counts (Outgoing ↑ / Incoming ↓).
• s: : Symbols (Classes, Functions, Types).
• d: : Description (Contextual Summary).

Example Map Entry:

- *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]

3. Example System Prompt

"Before acting, read llm-code-graph.md. Follow the protocol in llm-agent-rules.md. If you encounter a bug or an environment quirk, use the code-graph reflect tool to record the lesson in llm-agent-project-learnings.md."

🤖 Agent-Specific Integration

Maximize efficiency by pointing your agent directly to the llm-code-graph.md and llm-agent-rules.md files.

Roo Code (Cline)

Add this to your .clinerules file:

Before starting any task:
1. Read `llm-code-graph.md` for project structure.
2. Read `llm-agent-rules.md` for operational protocol.
3. Read `llm-agent-project-learnings.md` for past lessons.
4. **MANDATORY:** After any fix or learning event, you MUST update `llm-agent-project-learnings.md` using `code-graph reflect`.

Cursor / Windsurf

Add to .cursorrules or .windsurfrules:

Always reference `llm-code-graph.md` before editing. You are REQUIRED to follow the "Reflection Cycle" in `llm-agent-rules.md`. If a task involves a non-obvious fix or an environment quirk, you MUST record it in `llm-agent-project-learnings.md` immediately.

GitHub Copilot

Add to .github/copilot-instructions.md:

When answering questions about this codebase, prioritize the mapping data in `llm-code-graph.md`. You MUST suggest or perform a reflection entry for `llm-agent-project-learnings.md` after every bug fix or identified pitfall.

Gemini CLI

Create a GEMINI.md file (if not already using llm-agent-rules.md):

- Always read `llm-code-graph.md` as the primary source of truth.
- **CRITICAL:** Use `run_shell_command` to execute `code-graph reflect` after any bug fix or discovered quirk. Memory persistence is a mandatory part of every task completion.

OpenCode / OpenDevin / Aider

In your project instructions or session startup:

"Read llm-code-graph.md for a high-level overview. You are FORCED to record any project-specific quirk or non-obvious lesson using code-graph reflect <CAT> <LESSON> before finishing a task."

Codex / GPT-Engineer / AutoGPT

Add to your project prompt or prompts.md:

"Use llm-code-graph.md to navigate. Strictly adhere to the reflection cycle in llm-agent-rules.md. You MUST persist project memory by updating llm-agent-project-learnings.md on every failure or learned moment."

Generic Agent (System Prompt)

For any other agent, add this to your system instructions:

"This project uses code-graph-llm for context management. Always consult llm-code-graph.md. You ARE REQUIRED to persist new knowledge about the environment or logic using the code-graph reflect tool. Failure to update memory is a failure of the task."

🤖 Sub-Agent Registration

Register code-graph as an active sub-agent to enable explicit delegation.

Platform	Command	Action Taken
Gemini CLI	code-graph install-agent gemini	Registers global agent in ~/.gemini/subagents/.
Claude / Cursor	code-graph install-agent claude	Creates mcp-server-code-graph.json (MCP tool config).
Antigravity	code-graph install-agent antigravity	Registers agent in ~/.agent/subagents/.
Kiro IDE/CLI	code-graph install-agent kiro	Registers agent in ~/.kiro/agents/.
Generic Agent	code-graph install-agent generic	Generates .code-graph-agent.md persona prompt.

Uninstall using uninstall-agent <platform>.

🛠️ Implementation Details

• File Scanning: Recursively walks the directory, ignoring patterns in .gitignore.
• Context Extraction: Scans for classes, functions, and variables while ignoring matches in comments.
• Graph Extraction: Identifies imports, requires, extends, and implements.
• Reflection Management: Deduplicates and persists agent learning into a standardized Markdown format.
• Compilation: Writes a single, minified llm-code-graph.md file with a dedicated ## GRAPH EDGES section.