CodeGraph 0.2.0

CodeGraph

Give your AI coding agents structural code understanding instead of grep.

CodeGraph is a Roslyn-powered CLI tool that builds a semantic graph of your C# codebase and writes it as JSON — queryable by LLM agents. Instead of dumping thousands of grep matches into a prompt, your AI assistant gets the actual dependency structure, call chains, and type hierarchy.

Why CodeGraph?

Before — your AI assistant runs grep "OrderService" and gets 200+ hits:

src/Orders/OrderService.cs:14:public class OrderService : IOrderService
src/Orders/OrderService.cs:28:    public async Task<Order> PlaceOrder(...)
src/Api/Startup.cs:42:services.AddScoped<IOrderService, OrderService>();
src/Api/Controllers/OrderController.cs:18:    private readonly IOrderService _orderService;
tests/Orders/OrderServiceTests.cs:12:public class OrderServiceTests
... 195 more results

After — codegraph query OrderService --depth 1 --format context returns the actual structure:

# Query: OrderService
Commit: abc1234 | Branch: main | 2026-01-15T10:30:00Z

## Target: MyApp.Services.OrderService (Type)
File: src/Orders/OrderService.cs [14–87]
Signature: public class OrderService : IOrderService
Accessibility: Public

### Outgoing Relationships
**Implements:**
  → IOrderService

**Calls:**
  → IOrderRepository.SaveAsync(Order)
  → IEventBus.PublishAsync(OrderPlacedEvent)

**DependsOn:**
  → Order
  → OrderRequest

### Incoming Relationships
**Calls:**
  ← OrderController.PlaceOrder(OrderRequest)

**ResolvesTo:**
  ← IOrderService (via DI)

**Covers:**
  ← OrderServiceTests.PlaceOrder_ShouldPublishEvent

Your AI assistant gets a focused, structured view — not a wall of text.

Quick Start

# Install as a global .NET tool
dotnet tool install -g CodeGraph

# In your repo — initialize config + MCP registration:
codegraph init
# → Creates codegraph.json, .vscode/mcp.json, .mcp.json, apm.yml

# Build the graph:
codegraph index --solution MyApp.sln

# Query the graph:
codegraph query PlaceOrder --depth 1
codegraph query IOrderRepository --kind resolves-to
codegraph query "Order*" --format json --depth 2

After codegraph init, AI agents that support MCP (VS Code Copilot, Claude Code, Cursor) will auto-discover codegraph_query as a tool — no configuration needed.

Output

The index command writes JSON files to .codegraph/:

• One file per assembly/project — sized for LLM context windows
• _external.json — SBOM-like graph of all external/NuGet dependencies
• meta.json — git metadata, statistics, and index timestamp

The query command reads those files and returns a focused subgraph.

CLI Reference

codegraph init

Auto-detect your solution, create config + MCP server registration files, and scaffold agent skill files.

codegraph init [--agent <name>] [--solution <path.sln|path.slnx>] [--output <dir>] [--force]

Step 1 — Config + MCP files (always):

• codegraph.json — index/query configuration
• .vscode/mcp.json — MCP server for VS Code Copilot / Cursor
• .mcp.json — MCP server for Claude Code
• apm.yml — MCP server for APM (Agent Package Manager)

Step 2 — Agent skill files (auto-detected or explicit):

Auto-detects which AI agents are configured in the repo (looks for .claude/, CLAUDE.md, .github/copilot-instructions.md, AGENTS.md, .cursorrules, .cursor/rules/), then writes agent-specific skill files so each agent understands how to use CodeGraph:

codegraph index

Build the semantic graph from your C# solution.

codegraph index --solution <path.sln|path.slnx> [options]

codegraph query

Query the graph for symbols, relationships, and dependencies.

codegraph query <symbol-pattern> [options]

Symbol patterns support wildcards (Order*, *Service), exact match (OrderService), and kind prefix (type:OrderService, method:PlaceOrder).

Edge kind aliases:

codegraph diff

Compare two graph snapshots and report structural changes.

codegraph diff [options]

codegraph mcp

Start an MCP (Model Context Protocol) stdio server. This is how AI agents discover and use CodeGraph as a native tool.

codegraph mcp [--graph-dir <dir>]

The server exposes one tool — codegraph_query — with a typed JSON schema. Agents call it like any other tool (no shell commands, no prompt engineering). The server starts on demand via stdio and exits when the agent disconnects.

Configuration is automatic — codegraph init generates the MCP config files. To add manually:

// .vscode/mcp.json (VS Code Copilot, Cursor)
{
  "servers": {
    "codegraph": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["codegraph", "mcp"],
      "cwd": "${workspaceFolder}"
    }
  }
}

// .mcp.json (Claude Code)
{
  "mcpServers": {
    "codegraph": {
      "command": "dotnet",
      "args": ["codegraph", "mcp"]
    }
  }
}

Agent Integration

codegraph init generates the MCP config files automatically. The agent sees codegraph_query as a native tool.

Agent Skills (skills.sh)

CodeGraph provides packaged agent skills compatible with the skills.sh ecosystem. Install all skills with:

npx skills add droosma/vibe-codeGraph

Or install individual skills:

Each skill includes a standalone SKILL.md with trigger phrases, CLI reference, examples, and best practices. See the skills/ directory for details.

APM (Agent Package Manager) Support

CodeGraph supports Microsoft APM for managing agent configuration. If you use APM, run:

apm install --mcp codegraph -- dotnet codegraph mcp

Or use the apm.yml generated by codegraph init and run apm install to wire CodeGraph into all detected agent clients.

See docs/agent-setup.md for detailed per-agent instructions.

Configuration

CodeGraph is configured via a codegraph.json file in your repo root. Run codegraph init to generate one, or see the full reference at docs/configuration.md.

See codegraph.json.example for a single-solution example, or codegraph.multi-solution.json.example for a multi-solution example.

How It Works

┌─────────────┐     ┌──────────────┐     ┌──────────────┐     ┌───────────┐
│ dotnet       │────▸│ Syntax Pass  │────▸│ Semantic Pass │────▸│ JSON Graph│
│ restore +    │     │ (structure)  │     │ (relations)  │     │ (per-asm) │
│ Hybrid       │     └──────────────┘     └──────────────┘     └───────────┘
└─────────────┘           │                     │                    │
                          │              ┌──────────────┐            ▼
                          │              │   DI Pass    │     ┌─────────────┐
                          │              │ (ResolvesTo) │     │ _external   │
                          │              └──────────────┘     │   (SBOM)    │
                          │              ┌──────────────┐     └─────────────┘
                          │              │ Test Pass    │            │
                          │              │  (Covers)    │            ▼
                          │              └──────────────┘     ┌─────────────┐
                          └──────────────────────────────────▸│ Query Engine│
                                                              │ (BFS + rank)│
                                                              └─────────────┘

1. Hybrid Workspace Loader — Runs dotnet restore, then parses .sln / .slnx / .csproj / project.assets.json to assemble Roslyn CSharpCompilation objects directly (no MSBuildWorkspace). If the restore fails, a warning is emitted to stderr and indexing continues with best-effort compilation.
2. Syntax Pass — Walks syntax trees to extract namespaces, types, methods, properties, fields, constructors, and events. Creates structural Contains edges. Enriches nodes with metadata (isAbstract, isStatic, isAsync, returnType, etc.).
3. Semantic Pass — Uses the Roslyn semantic model to resolve calls, inheritance, interface implementations, type dependencies, references, and overrides. Creates external nodes for cross-assembly references.
4. DI Pass — Detects AddScoped/AddTransient/AddSingleton patterns to emit ResolvesTo edges with lifetime metadata.
5. Test Coverage Pass — Detects test methods (xUnit, NUnit, MSTest) and emits Covers/CoveredBy edges linking tests to production code.
6. Graph Writer — Outputs JSON files split by assembly (one per project), external nodes to _external.json (SBOM), plus meta.json with git metadata and statistics.
7. Query Engine — Pattern-matches symbols, performs BFS traversal, filters by edge type/namespace/project, ranks by relevance, and formats output.

For a deep dive, see docs/architecture.md.

CI/CD Integration

Keep your graph fresh in CI

- name: Update CodeGraph
  run: |
    dotnet tool install -g CodeGraph
    codegraph index --solution MyApp.sln --changed-only

Publishing a new release

Push a version tag to trigger the NuGet publish workflow:

git tag v0.1.0
git push origin v0.1.0

This runs .github/workflows/publish.yml which builds, tests, packs, and pushes to NuGet.org. You'll need to add a NUGET_API_KEY secret to your GitHub repository.

Contributing

We welcome contributions! See CONTRIBUTING.md for development setup, code style, and PR guidelines.

Running Tests

# Unit tests
dotnet test

# Mutation testing (requires dotnet-stryker tool)
dotnet tool restore
cd tests/CodeGraph.Core.Tests && dotnet stryker
cd tests/CodeGraph.Indexer.Tests && dotnet stryker
cd tests/CodeGraph.Query.Tests && dotnet stryker

Stryker generates HTML reports in StrykerOutput/ with mutation scores per project. The CI pipeline runs mutation testing automatically on PRs that touch src/ or tests/.

Documentation

• Architecture Deep Dive
• Graph Schema Reference
• Configuration Reference
• Agent Setup Guide
• Graph Diff How-to Guide

License

MIT © 2026 CodeGraph Contributors