octopus-workflow/core/skills/codegraph-setup/SKILL.md

name, description, triggers, role

name	description	triggers	role
codegraph-setup	Use ONLY when installing, configuring, initializing, or troubleshooting CodeGraph (@colbymchenry/codegraph — https://github.com/colbymchenry/codegraph) in the octopus environment. Covers global CLI install, per-project `.codegraph/` indexing, and maintenance commands (status, sync, upgrade, uninstall). MCP wiring into octopus.jsonc is handled by the kickoff pipeline (`octopus kickoff` or `/kickoff`). Also use when a project session reports a missing/stale `.codegraph/` index.	codegraph code graph codegraph setup codegraph install codegraph init .codegraph codegraph_explore codegraph_node codegraph_callers codegraph_status install codegraph 代码图 代码图谱 代码索引 索引代码 装代码图 初始化代码图	Producer

CodeGraph Setup in the Octopus Environment

CodeGraph is a local-first code intelligence layer (https://github.com/colbymchenry/codegraph) that octopus consumes as a stdio MCP server. It exposes the codegraph_explore, codegraph_node, codegraph_callers, codegraph_search, and codegraph_status tools, letting agents query a pre-indexed knowledge graph instead of scanning files.

Per .octopus/rules/code-graph.md (the L1 code-graph rule): Code Graph First is mandatory. Structural questions MUST use codegraph_explore / codegraph_search / codegraph_callers; grep is the fallback for fuzzy text only. So a working CodeGraph install is a prerequisite for every cross-file task.

Setup has two independent layers. Each can be installed/reinstalled without touching the others:

1. Global CLI — the codegraph binary, installed once per machine.
2. Per-project index — the .codegraph/ directory, built once per repo.

MCP wiring into octopus.jsonc is handled by the kickoff pipeline (octopus kickoff or /kickoff). See the project-kickoff skill for details.

---

1. Install the global CLI

The package is @colbymchenry/codegraph on npm. It bundles its own runtime and ships platform-specific binaries as optional dependencies (e.g. @colbymchenry/codegraph-linux-x64), so there is nothing to compile.

Pick one method (all equivalent; they only differ in how the binary lands on $PATH):

# Via bun global (what this environment currently uses)
bun add -g @colbymchenry/codegraph

# Via npm global
npm i -g @colbymchenry/codegraph

# Run-once, no install
npx @colbymchenry/codegraph

# Via the official install scripts (puts `codegraph` on PATH, no shell change)
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh   # macOS / Linux
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex          # Windows (PowerShell)

In this environment, the install is bun-global:

Item	Value
Binary on PATH	~/.bun/bin/codegraph (symlink)
Real package dir	~/.bun/install/global/node_modules/@colbymchenry/codegraph/
Entry point	npm-shim.js → resolves to the platform binary
Platform binary	@colbymchenry/codegraph-linux-x64
Version	1.0.0

Verify the install:

codegraph --version    # prints the installed version
which codegraph        # should resolve under ~/.bun/bin or ~/.npm-global/bin

Upgrade any time — it auto-detects how you installed:

codegraph upgrade              # upgrade to latest
codegraph upgrade --check      # only report if an update exists
codegraph upgrade 1.2.3        # pin a specific version

---

2. Initialize the per-project index

Run once from inside each project you want indexed. -i builds the initial graph in the same step; omit it to create the .codegraph/ dir and build later with codegraph index.

codegraph init -i            # create .codegraph/ AND build the initial graph
codegraph init               # create .codegraph/ only; run `codegraph index` afterwards

This creates (relative to the project root):

.codegraph/
├── .gitignore               # ignores itself; safe to leave uncommitted
├── codegraph.db             # the SQLite knowledge graph (full WAL mode)
├── codegraph.db-shm         # SQLite shared-memory (WAL)
├── codegraph.db-wal         # SQLite write-ahead log
├── daemon.log               # watcher/MCP daemon log
├── daemon.pid               # daemon process id
└── daemon.sock              # daemon IPC socket

codegraph init writes a .gitignore inside .codegraph/, so the index dir is normally left uncommitted (it is machine- and version-specific). If you choose to commit it anyway, add .codegraph/*.db* to the repo .gitignore instead and treat the index as a build artifact.

In this environment the index is already built:

Metric	Value
Files indexed	1,868
Nodes	32,592
Edges	118,912
DB size	~85 MB
Backend	node:sqlite — built-in (full WAL)

Check any project's own stats at any time:

codegraph status

Auto-sync — you do not normally run codegraph sync

Once the MCP server (codegraph serve --mcp) is running, three layers keep the index in step with your code without manual sync:

1. Debounced file watcher. A native FSEvents (macOS) / inotify (Linux) / ReadDirectoryChangesW (Windows) watcher captures every create/modify/delete and re-indexes after a debounce. Default 2000 ms; tune via CODEGRAPH_WATCH_DEBOUNCE_MS (clamped to [100ms, 60s]).
2. Connect-time catch-up. On (re)connect the server reconciles (size, mtime) + content-hash against the working tree, so edits made while no MCP server was running (a git pull from the terminal, another editor, a previous session that exited) are absorbed before the first query.
3. On-demand sync. codegraph sync is available as an escape hatch.

Disable the watcher on slow filesystems (WSL2 /mnt drives, network mounts):

codegraph serve --mcp --no-watch

Workflow worktrees get their own index ([org-internal #2561] / TD-006)

The main checkout's .codegraph/ does NOT cover git worktrees — they live outside the repo path, so nearest-.codegraph/ resolution finds nothing under them and graph queries degrade to grep+read. Both worktree lifecycle scripts hook a per-worktree init into their create flow:

• script/session-worktree.sh create <slug> and script/scratch-worktree.sh create <slug> <base> run codegraph init -i <worktree-path> in the background. Best-effort: a missing CLI, an existing index, or an init failure never blocks worktree creation — the ready/failed signal lands in <worktree>/.codegraph/init.log (one line). The background subshell never holds the caller's stdout pipe, so output-capturing callers (CI, nested scripts) are not blocked either.
• CODEGRAPH_SKIP=1 disables the hook (selftests / CI).
• Worktrees created before this hook landed have no index — run codegraph init -i once from inside them.
• After create, the index builds asynchronously (a full repo takes ~minutes). Verify readiness with codegraph status INSIDE the worktree (Files > 0, Nodes > 0) before relying on graph queries.

---

3. Verification checklist

After a fresh setup, confirm each layer is working:

1. CLI — codegraph --version prints a version; which codegraph resolves.
2. Index — codegraph status from the project root shows Files > 0 and Nodes > 0; .codegraph/codegraph.db exists.

---

4. How octopus uses CodeGraph (usage rules)

This skill covers setup only. Usage conventions (query the graph before reading; codegraph_explore for flows, codegraph_search/codegraph_callers for symbols; grep is the fallback) are normative in .octopus/rules/code-graph.md — refer there. The short version: run codegraph_status on session start, and prefer graph tools over grep+read for any structural question.