cm-codeintell

Code Intelligence — Structural Understanding for AI Agents

TL;DR

• Use to index codebase for fast structural understanding
• Outputs: skeleton index, AST graph, Mermaid diagrams
• Token saving: ~95% for onboarding, ~30% for deep analysis
• Next: cm-planning or cm-debugging

Stop scanning. Start querying. Skeleton Index (<4s, zero deps) + AST graph + architecture diagrams = instant code understanding.

Inspired by CodeGraph + GitDiagram.

TRIZ-optimized: 10 inventive principles applied.

When to Use

ALWAYS for medium-to-large projects. This is infrastructure, not an action skill.

• Auto-triggered by: cm-start Step 0.7 (project init) — ALWAYS runs Layer 0
• Manually triggered for: "understand this codebase", "what calls X?", "what breaks if I change Y?"
• Skip when: NEVER — Layer 0 (Skeleton) works on any project size

Detection Thresholds (Auto-Trigger)

TRIGGER if ANY of these are true:
  → Project has >50 source files
  → User wants to refactor or re-code an existing project
  → User says "understand the codebase" / "what does this do?"
  → cm-execution encounters >3 grep/glob calls for one task
  → cm-debugging needs callers/callees to trace a bug

Architecture: 4 Layers

┌──────────────────────────────────────────────────────────────────────────┐
│                           cm-codeintell                                 │
├──────────────────┬──────────────────┬──────────────────┬────────────────┤
│  LAYER 0         │  LAYER 1         │  LAYER 2         │  LAYER 3       │
│  Skeleton Index  │  Code Graph      │  Architecture    │  Smart Context │
│  (Instant)       │  (Structure)     │  Diagram (Visual)│  (Synthesis)   │
├──────────────────┼──────────────────┼──────────────────┼────────────────┤
│ grep/find/awk    │ tree-sitter AST  │ File tree + LLM  │ All layers +   │
│ → skeleton.md    │ → SQLite graph   │ → Mermaid.js     │ qmd → focused  │
│ (~5K tokens)     │ → MCP server     │ → .cm/ storage   │ context packet │
├──────────────────┼──────────────────┼──────────────────┼────────────────┤
│ ZERO deps        │ codegraph_*      │ Auto-generated   │ Feeds: exec,   │
│ <4 seconds       │ MCP tools        │ at project init  │ plan, debug    │
│ ANY project size │ 50+ files        │ 20+ files        │ All consumers  │
└──────────────────┴──────────────────┴──────────────────┴────────────────┘

TRIZ Principles Applied

| # | Principle | How Applied | |---|-----------|-------------| | #1 Segmentation | 4 independent layers — each usable alone | | #2 Taking Out | Extract only signatures, discard function bodies | | #5 Merging | CodeGraph + GitDiagram + Skeleton → one unified skill | | #10 Prior Action | Pre-index at project init, not at query time | | #13 Inversion | Code summarizes ITSELF to agent (push, not pull) | | #15 Dynamicity | Adaptive: skeleton (<20) vs graph (>50) vs full (>200) | | #25 Self-Service | Auto-detect project size → auto-select intelligence level | | #28 Mechanics Substitution | Replace file reading (slow) with pattern matching (fast) | | #35 Parameter Changes | Unit: file content → function signature → 95% compression | | #40 Composite | One skill = skeleton + graph + diagrams + context builder |

Layer 0: Skeleton Index (Instant — Zero Dependencies)

Purpose: Lightning-fast grep-based extraction of function signatures, class definitions, exports, and module boundaries. Produces a compact .cm/skeleton.md that gives the agent instant understanding of any codebase.

How It Works

1. SCAN     → find all source files (14 languages supported)
2. EXTRACT  → grep for function/class/export signatures only
3. GROUP    → organize by directory (module boundaries)
4. CAP      → limit per-dir (15 files) + total (600 lines)
5. OUTPUT   → .cm/skeleton.md (~5K tokens for 600-file project)

Usage

# Run from project root
bash scripts/index-codebase.sh

# Custom paths
bash scripts/index-codebase.sh /path/to/project /path/to/output.md

What It Extracts (Per Language)

| Language | Patterns Extracted | |----------|-------------------| | TypeScript/JavaScript | export, function, class, interface, type, enum, const =, routes | | Python | def, async def, class, @app.route, from...import | | Go | func, type...struct, type...interface, package | | Rust | pub fn, struct, enum, impl, trait, mod | | Java/Kotlin | class, interface, fun, data class, package | | PHP | function, class, interface, trait, namespace | | Ruby | def, class, module | | C/C++ | function declarations, struct, class, typedef, #define | | Swift | func, class, struct, protocol, extension |

Output Format

# 🦴 Skeleton Index: my-project

| Meta | Value |
|------|-------|
| Source Files | 127 |
| Languages | typescript(89) python(38) |
| Framework | next.js+cloudflare |

## Entry Points
- `src/index.ts`
- `app/layout.tsx`

## Directory Structure
(compact tree, depth 2)

## Code Skeleton
### `src/auth/`
**AuthService.ts**
‍‍‍
3:export class AuthService
5:export async function login(email, password)
12:export function validateToken(token)
‍‍‍

### `src/api/`
**routes.ts**
‍‍‍
8:export const router
15:router.get('/users'
22:router.post('/auth'
‍‍‍

Compression Stats

┌──────────────────┬────────────┬────────────────┬──────────────┐
│ Project Size     │ Raw Tokens │ Skeleton Tokens│ Compression  │
├──────────────────┼────────────┼────────────────┼──────────────┤
│ 50 files (small) │ ~20,000    │ ~1,500         │ 92.5%        │
│ 200 files (med)  │ ~80,000    │ ~3,000         │ 96.3%        │
│ 600 files (large)│ ~240,000   │ ~5,000         │ 97.9%        │
└──────────────────┴────────────┴────────────────┴──────────────┘

Agent Protocol

AT SESSION START:
  1. Check if .cm/skeleton.md exists
  2. IF exists → read it (~5K tokens) → instant codebase understanding
  3. IF not exists → run: bash scripts/index-codebase.sh
  4. Use skeleton to:
     → Know what functions exist and where
     → Understand module boundaries
     → Navigate to the right file for any task
     → Skip grep/list_dir when exploring

WHEN TO RE-GENERATE:
  → After major refactoring (>20 files changed)
  → After branch switch
  → When skeleton is >24h old
  → User requests: "re-index the codebase"

Layer 1: Code Graph (Structure)

Purpose: Pre-indexed AST-based knowledge graph. Functions, classes, imports, call relationships — all queryable instantly.

Setup

# Install CodeGraph (one-time)
npx @colbymchenry/codegraph

# Initialize for current project
codegraph init .

# Index the codebase (tree-sitter AST extraction)
codegraph index .

MCP Server Setup

Add to your MCP config (.mcp.json, claude_desktop_config.json, etc.):

{
  "mcpServers": {
    "codegraph": {
      "command": "codegraph",
      "args": ["serve"]
    }
  }
}

Key MCP Tools

| Tool | What It Does | Replaces | |------|-------------|----------| | codegraph_context(task) | Build focused context for a task | Multiple grep + view_file calls | | codegraph_search(query) | Find symbols by name or meaning | grep -r "pattern" | | codegraph_callers(symbol) | What calls this function? | Manual file-by-file search | | codegraph_callees(symbol) | What does this function call? | Reading entire function + tracing | | codegraph_impact(symbol) | What breaks if I change this? | Nothing (CM couldn't do this) | | codegraph_files(path) | Project structure with metadata | list_dir recursive + view_file | | codegraph_node(symbol) | Full details of one symbol | view_file + manual parsing |

When Agents Use These Tools

INSTEAD OF:                          USE:
─────────────────────────────────    ─────