code-graph-llm

v4.19.0

Published

7 days 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 (v4.19.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 v4.19.0

Fix (Generate — large file hang): Files over 100KB now skip symbol extraction instead of running the regex parser. Compiled/generated files like drift_worker.js (343KB Dart→JS) caused catastrophic regex backtracking that blocked the Node.js event loop entirely, preventing timeouts and heartbeats from firing. Large files are still indexed in the graph with their description; only symbol extraction is skipped.
Fix (Generate — file timeout reduced): Per-file timeout reduced from 15s to 5s. Timed-out files are now logged as errors (console.error) instead of warnings.
Fix (Generate — readdir timeout): Directory reads (readdir) now have an 8s timeout. If a directory hangs (e.g. broken symlink, network path), the scanner logs an error and skips it instead of blocking forever.
UX (Generate — elapsed timestamps): Every Scanning: log line now shows elapsed time since generation started (e.g. +0.3s), making it easy to spot which directory is slow.
UX (Generate — heartbeat): A Still scanning... heartbeat fires every 5s during the walk phase, confirming the process is alive on large repos.
UX (Generate — per-file processing log): Each file logs Processing: <path> before parse begins, so if the process hangs the last visible line identifies the culprit file.
UX (Generate — skip summary): End-of-run summary lists every skipped file with reason (large-no-parse, file-timeout, readdir-timeout, oversized, permission, exception).

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 v4.19.0] Installed/updated: /absolute/path/to/AGENTS.md
[Code-Graph v4.19.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: General project-map and reflection specialist.
code-graph-locator: Finds the smallest relevant file and symbol set before raw source reads.
code-graph-tracer: Traces dependency and inheritance paths from ## EDGES.
code-graph-reviewer: Checks map freshness, reflection coverage, scope creep, and dependency freshness.

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

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