Getting started

This page assumes you already have one of the supported tools installed (Claude Code, VS Code Copilot, OpenAI Codex CLI, OpenCode, Cursor, Devin Desktop, 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 AGENTS.md and .github/copilot-instructions.md, and (if you opt in) builds the code-graph for your project and adds the instruction layout checks to CI.

Claude Code plugin

In Claude Code you can install Coograph as a plugin instead of a sibling clone, and update it with one command:

claude plugin marketplace add paullukic/coograph
claude plugin install coograph@coograph

# later
claude plugin update coograph@coograph

Then run /coograph:coograph-init in your project. An update refreshes the plugin’s own skills, agents and hooks; files init copied into a project (instructions, .claude/hooks/, .github/code-graph/, the MCP config) are refreshed by running init again.

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 -p 3.12 --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).

The -p 3.12 pin makes uv run the server on Python 3.12, downloaded on demand. Without it uv resolves against the machine’s default Python; below 3.10 the server dies at start-up with your requirements are unsatisfiable, and the MCP host shows only CONNECTION_CLOSED. Harmless where the default is already new enough.

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",
        "-p",
        ">=3.10",
        "--with-requirements",
        "${workspaceFolder}/.github/code-graph/requirements.txt",
        "${workspaceFolder}/.github/code-graph/server.py"
      ],
      "env": { "UV_NO_MANAGED_PYTHON": "1", "UV_PYTHON_DOWNLOADS": "never" }
    }
  }
}

-p ">=3.10" takes any Python new enough for the MCP SDK. The two env pins keep uv on a system-installed Python: on Windows machines with Smart App Control or Defender Application Control, uv’s own Python downloads can be blocked from loading, and the server then dies at start with DLL load failed while importing _overlapped. Drop the pins if you have no system Python 3.10 or newer.

OpenCode (opencode.json)

OpenCode reads neither .mcp.json nor .github/skills/. Register the project with opencode in its tools and code_graph: true, and sync generates an opencode.json with the skills path and the code-graph server. It holds this machine’s absolute paths on purpose: OpenCode resolves a relative cwd against the folder it was started in, so relative paths break when you start it in a subfolder. It is created only when missing, never rewritten, and should not be committed.

VS Code Copilot (.vscode/mcp.json)

{
  "servers": {
    "code-graph": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "-p",
        ">=3.10",
        "--with-requirements",
        "${workspaceFolder}/.github/code-graph/requirements.txt",
        "${workspaceFolder}/.github/code-graph/server.py"
      ],
      "env": { "UV_NO_MANAGED_PYTHON": "1", "UV_PYTHON_DOWNLOADS": "never" }
    }
  }
}

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(...). It resolves OrderService and place_order against the graph, seeds from the file that defines them, and walks the dependency edges out — four to six files instead of every match for the keyword. It also returns the graph’s size, the risk of the uncommitted changes, and which tool to use to widen.

When the task names something the graph does not hold, the file list comes back empty or from a broader word in the same sentence, and files_reason says which. An answer that is a guess is labelled as one.

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.

Keeping projects up to date

A project registered in the Coograph checkout’s projects.json is synced on every git pull of Coograph: skills, agents, hooks, the Retro analyzer and the layout checker are refreshed. Sync never overwrites a file you edited. Each file it would replace is compared with what it last wrote and with every version Coograph ever shipped; a file that matches neither is kept, the new upstream version is parked in .coograph/upstream/<path>, and the log says KEPT <path> (local edit). To take the new version, copy it over yours and sync again. CLAUDE.md, AGENTS.md, copilot-instructions.md, layout.json, rules.json and GOTCHAS.md are yours and are never written once they exist.

Next

• Code graph — what’s inside graph.db and how to query it
• Workflow — Plan → Propose → Apply for safe, large changes
• Instruction layout: keep instruction files under a budget