CodeGraph Skill Skill | Agent Skills

CodeGraph Skill

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

Read .terrain/agent/context.md (terrain-knowledge-skill)
Always <cg> sync first — cheap, incremental, and removes the need to trust status's own up-to-date claim
<cg> query <SymbolName> to locate definition
callers / callees / impact for relationship questions
repomix-context-skill for full source text of a specific file
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

Agent Skills: CodeGraph Skill

Install this agent skill to your local

Skill Files