/codegraph-skill

name: codegraph-skill
description: Use when a coding agent needs symbol relationships, callers, callees, or change impact. Guides CodeGraph CLI usage (not MCP).
version: 1.3.0

CodeGraph Skill

[CodeGraph](https://colbymchenry.github.io/codegraph/) provides a pre-indexed **AST code graph** for this project.

Terrain uses **CLI only** — do not run `codegraph install` (that configures MCP/agent rules separately).

Resolve the CodeGraph command (read first)

Use **conventional paths only** — never machine-specific absolute paths like `/Users/...` or `C:\Users\...`.

On Windows, the wrapper may be `codegraph.cmd` or `codegraph.exe` under `~/.terrain/bin/`.

| Priority | Command | When | |----------|---------|------| | 1 | `~/.terrain/bin/codegraph` | Terrain env integration (see existence check below) | | 2 | `bunx codegraph` | No Terrain install; needs network once | | 3 | `npx codegraph` | Same as bunx if Bun unavailable |

Optional manifest (local, gitignored): `.terrain/env/agent-tools.json` — same `~/.terrain/bin/…` conventions.

**Existence check (cross-platform):**

| Shell | Check | |-------|-------| | bash / zsh / Git Bash | `[ -x ~/.terrain/bin/codegraph ] \|\| [ -f ~/.terrain/bin/codegraph.exe ] \|\| [ -f ~/.terrain/bin/codegraph.cmd ]` | | PowerShell | `Test-Path "$HOME\.terrain\bin\codegraph*"` |

In examples below, `<cg>` means your resolved prefix (`~/.terrain/bin/codegraph` or `bunx codegraph`).

Prerequisites

The **index** is per-repo under `.codegraph/`. If missing, initialize from the repo root:

# bash / Git Bash
if [ -x ~/.terrain/bin/codegraph ] || [ -f ~/.terrain/bin/codegraph.exe ] || [ -f ~/.terrain/bin/codegraph.cmd ]; then
  ~/.terrain/bin/codegraph init -i
else
  bunx codegraph init -i
fi

Refresh after edits: `<cg> sync`

Health check:

<cg> status

**`<cg> status` can lie ("up to date" when it is not).** Observed case: index untouched for 10 days while 24 commits changed source files, `status` still reported fresh, and `<cg> query` on a symbol added days earlier returned nothing. Do not treat `status` as authoritative on its own.

CLI commands

| Intent | Command | |--------|---------| | Find symbol by name | `<cg> query <name>` | | Who calls X | `<cg> callers <symbol>` | | What X calls | `<cg> callees <symbol>` | | Change blast radius | `<cg> impact <symbol>` | | Tests affected by file changes | `<cg> affected <files…>` | | Project file tree | `<cg> files` | | Index health | `<cg> status` | | Refresh after edits | `<cg> sync` |

Recommended workflow

1. Read `.terrain/agent/context.md` (`terrain-knowledge-skill`) 2. **Always** `<cg> sync` first — cheap, incremental, and removes the need to trust `status`'s own up-to-date claim 3. `<cg> query <SymbolName>` to locate definition 4. `callers` / `callees` / `impact` for relationship questions 5. `repomix-context-skill` for full source text of a specific file 6. Use **`rtk-skill`** for any follow-up shell commands (tests, git)

Independent staleness cross-check (mandatory before impact/callers analysis)

Because `<cg> status` is not reliable, cross-check with Terrain's own git-based drift report before trusting `impact`/`callers`/`callees` results for anything safety-relevant (e.g. "is it safe to remove this function"):

~/.terrain/bin/terrain tools codegraph-drift --project <slug>
# or: bunx @terrain-ai/cli tools codegraph-drift --project <slug>

This compares `.codegraph/codegraph.db`'s mtime against `git log --since` — independent of CodeGraph's own bookkeeping. If `likely_stale: true`, run `<cg> sync` and re-check before trusting query results.

When to use vs other skills

| Use CodeGraph | Use instead | |---------------|-------------| | Symbol lookup, call chains | Architecture → `context.md` | | Impact before refactor | Business rules → `knowledge/` | | File/symbol graph | Raw source slice → repomix | | Verbose test/git output | `<rtk> cargo test`, `<rtk> git diff` |

Do not

• Run `codegraph install` (Terrain manages AGENTS.md)
• Blind `grep` the whole repo to re-verify CodeGraph AST results
• Chain `query` + manual file reads when `impact` answers the question

Staleness

If `<cg> status` shows pending files after your edits, or `terrain tools codegraph-drift` reports `likely_stale: true`:

<cg> sync