code-graph-llm

CODE-GRAPH (v3.2.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.2: Universal Agent OS

• Enhanced Platform Matrix: Full surgical integration for Antigravity, Kiro, and Roo Code.
• Segregated Skill Hooks: Isolated preToolUse and beforeTool hooks for Mapping vs. Reflections.
• Deep Steering: Standardized AGENTS.md and .cursor/rules/ for non-hookable platforms.
• Production-Ready Core: Refactored Service-based architecture with full async support.

🛠️ The Code-Graph Skills

Code-Graph provides two primary skills that can be installed independently or together (default).

1. Structural Mapping (projectmap)

• What it does: Scans your project for symbols (classes, functions, interfaces) and builds a dense dependency graph (imports, requires, inheritance).
• Skill Goal: High-level architectural awareness and navigation.
• Agent Benefit: Prevents "hallucinating" file paths and reduces token usage by giving the agent a compact map (llm-code-graph.md) instead of raw file content.

2. Memory Persistence (reflections)

• What it does: Logs non-obvious fixes, environment quirks, and architectural lessons into llm-agent-project-learnings.md.
• Skill Goal: Persistent project memory across sessions.
• Agent Benefit: Enables "Cross-Session Memory." If an agent fixes a bug in one session, the next agent reads the reflection and avoids the same pitfall.

🚀 Automated Agent Integration

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
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 / etc.	code-graph install-skills <platform>

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:

Example Map Entry:

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

## GRAPH EDGES
[src/auth.js] -> [imports] -> [jwt-library]
[AdminUser] -> [inherits] -> [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."

How it works

• 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.