Getting started

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.

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.

Codex CLI notes

Codex CLI registers custom workflows differently from the other seven tools. If you use Codex, skim this once.

Slash is reserved

Codex reserves / for ~30 built-in commands. Typing /coograph-init returns Unrecognized command. Use one of:

• $coograph-init — explicit $skill-name invocation.
• /skills — built-in command that lists every installed skill. Useful to verify Coograph is loaded.
• Natural language — "initialize the project", "set up coograph", "wire up coograph in this repo". Codex matches against the skill description and auto-activates.

Where Codex looks for skills

Codex scans these directories in priority order (source):

1. $CWD/.agents/skills
2. Parent directories’ .agents/skills
3. $REPO_ROOT/.agents/skills
4. $HOME/.agents/skills
5. /etc/codex/skills
6. Built-in system skills

Coograph ships .agents/skills/coograph-init/SKILL.md at the repo root, so step 3 finds it from anywhere inside the project.

Verify the skill loaded

Run /skills in a Codex session. If coograph-init is missing, either your Codex build is too old for skills, or the project’s .agents/skills/ folder is gone — re-run /coograph-init from another supported tool to restore it.

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.

Next

• 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 →