codegraph

Files (1)

• SKILL.md

SKILL.md (first lines)

# CodeGraph - Semantic Code Intelligence

## Overview

CodeGraph builds a semantic knowledge graph of codebases — symbol relationships, call graphs, and code structure — so agents query the graph instantly instead of scanning files with grep/glob/read.

```
               Github Copilot CLI
                       │
                       │
                 Sisyphus Agent
                       │
         ┌─────────────┼─────────────┐
    Explore Agent  Explore Agent  Explore Agent
         │             │             │
         └─────────────┼─────────────┘
                       ▼
            CodeGraph MCP Server
        ┌─────┬─────┬──────┬──────┐
      Search Callers Callees Impact
        └─────┴─────┴──────┴──────┘
                       ▼
              SQLite Graph DB
         • 1000s of symbols, edges
         • Instant lookups
         • OS file watcher → auto-sync
```

## When to Use

- **Every session start** — Load `.codegraph/config.json`, check `codegraph_status`
- **Code exploration** — Instead of grep/glob/Read, use `codegraph_search`, `codegraph_context`
- **Before editing** — Use `codegraph_impact` to check what's affected
- **Trace call flow** — Use `codegraph_callers` / `codegraph_callees`
- **Understanding systems** — Delegate to Explore agents with `codegraph_explore` as primary tool

## Architecture

### How It Works

1. **Extraction** — tree-sitter parses source code into ASTs. Language-specific queries extract nodes (functions, classes, methods) and edges (calls, imports, extends, implements)
2. **Storage** — Everything goes into a local SQLite database (`.codegraph/codegraph.db`) with FTS5 full-text search
3. **Resolution** — After extraction, references are resolved: function calls → definitions, imports → source files, class inheritance, and framework-specific patterns
4. **Auto-Sync** — The MCP server watches your project using native OS file events. Changes are debounced (2-second quiet window), filtered to source files only, and incrementally synced

### File Structure

```
<project-root>/
└── .codegraph/
    ├── codegraph.db     # SQLite graph database
    └── config.json      # Indexing configuration
```

## Installation & Setup

### Quick Install

```bash
npx @colbymchenry/codegraph
```

### Manual Setup

```bash
npm install -g @colbymchenry/codegraph
```

Add to `~/.mcp.json`:
```json
{
  "mcpServers": {
    "codegraph": {
      "type": "stdio",
      "command": "codegraph",
      "args": ["serve", "--mcp"]
    }
  }
}
```

### Initialize Projects

```bash
cd your-project
codegraph init -i     # Interactive init + index
```

That's it. When `.codegraph/` exists, CodeGraph tools are available.

## MCP Tools Reference

| Tool | Purpose | Use In |
|------|---------|--------|
| `codegraph_search` | Find symbols by name across the codebase | Main session (lightweight) |
| `codegraph_context` | Build relevant code context for a task | Explore agent (primary) |
| `codegraph_callers` | Find what calls a function | Main session (lightweight) |
| `codegraph_callees` | Find what a function calls | Main session (lightweight) |
| `codegraph_impact` | Analyze what's affected by changing a symbol | Main session before edits |
| `codegraph_node` | Get details about a specific symbol (optionally with source code) | Main session (lightweight) |
| `codegraph_files` | Get indexed file structure (faster than filesystem scanning) | Main session (lightweight) |
| `codegraph_status` | Check index health and statistics | Session start |

## CLI Reference

```bash
codegraph                         # Run interactive installer
codegraph install                 # Run installer (explicit)
codegraph init [path]             # Initialize in a project (--index to also index)
codegraph uninit [path]           # Remove CodeGraph (--force to skip prompt)
codegraph index [path]            # Full index (--force to re-index, --quiet for less output)
codegraph sync [path]             # Incremental update
codegraph status [path]           # Show statistics
codegraph query <search>          # Search symbols (--kind, --limit, --json)
codegraph files [path]            # Show file structure (--format, --filter, --max-depth, --json)
codegraph context <task>          # Build context for AI (--format, --max-nodes)
codegraph affected [files...]     # Find test files affected by changes
codegraph serve --mcp             # Start MCP server
```

From tainn03/oh-my-copilot, MIT.

More from tainn03/oh-my-copilot