Getting started

Repo: paullukic/coograph on GitHub. The legacy paullukic/copilot-template URL redirects via a README notice.

This page assumes you already have one of the supported tools installed (Claude Code, VS Code Copilot, OpenAI Codex CLI, OpenCode, Cursor, Windsurf, Aider, or Cline) and want to add Coograph to a project.

Requirements

Python 3.10+
uv (recommended; auto-installs dependencies on first run)
A Git repository

Install

From your project root:

# Clone Coograph as a sibling directory
git clone https://github.com/paullukic/coograph.git ../coograph

Then trigger the initializer in your AI tool’s chat. Each tool has its own invocation syntax.

Tool	Invoke with
Claude Code	`/coograph-init`
VS Code Copilot	`/coograph-init`
Codex CLI	`$coograph-init` or “initialize the project” — Codex reserves `/` for built-ins
OpenCode	`/coograph-init`
Cursor	`/coograph-init` (string match, no menu)
Windsurf	`/coograph-init` (string match)
Aider	`/coograph-init` (string match)
Cline	`/coograph-init` (string match)

Natural-language paraphrases (“initialize the project”, “set up coograph”) work in every tool — each config file lists those triggers alongside the slash form.

The initializer auto-detects your stack, fills the _TBD_ placeholders in .github/copilot-instructions.md, and (if you opt in) builds the code-graph for your project.

Build the graph manually

If you skipped the initializer’s code-graph step, you can build it later:

uv run --with-requirements .github/code-graph/requirements.txt \
  .github/code-graph/server.py --build

This parses every source file in your repo and writes .code-graph/graph.db (SQLite, MB-scale, gitignored).

Wire the MCP server

Coograph exposes graph queries to your AI tool via Model Context Protocol.

Claude Code (`.mcp.json` at repo root)

{
  "mcpServers": {
    "code-graph": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--with-requirements",
        "${workspaceFolder}/.github/code-graph/requirements.txt",
        "${workspaceFolder}/.github/code-graph/server.py"
      ]
    }
  }
}

VS Code Copilot (`.vscode/mcp.json`)

{
  "servers": {
    "code-graph": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--with-requirements",
        "${workspaceFolder}/.github/code-graph/requirements.txt",
        "${workspaceFolder}/.github/code-graph/server.py"
      ]
    }
  }
}

First query

Inside a session with the agent of your choice:

“What files would I need to read to add caching to OrderService.place_order?”

The agent calls get_minimal_context(...) against the graph and returns four to six files instead of grepping every match.

Auto-update

Install the git hooks once:

cp .github/code-graph/post-commit  .git/hooks/post-commit
cp .github/code-graph/post-merge   .git/hooks/post-merge
cp .github/code-graph/post-rewrite .git/hooks/post-rewrite
chmod +x .git/hooks/post-{commit,merge,rewrite}

The graph re-parses only the files whose SHA-1 changed on every commit, merge, or rebase. Updates take milliseconds.

If Coograph earned its keep, a GitHub star helps the next person find it.

Code graph — what’s inside graph.db and how to query it
Workflow — Plan → Propose → Apply for safe, large changes

Edit this page on GitHub →