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

---
name: codegraph-setup
description: >
  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.
triggers:
  - codegraph
  - code graph
  - codegraph setup
  - codegraph install
  - codegraph init
  - .codegraph
  - codegraph_explore
  - codegraph_node
  - codegraph_callers
  - codegraph_status
  - install codegraph
  # Chinese — bare nouns for code-graph concepts. The English "codegraph" brand
  # name above already covers mixed-language phrasings; these cover pure Chinese.
  - 代码图
  - 代码图谱
  - 代码索引
  - 索引代码
  - 装代码图
  - 初始化代码图
role: 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`):

```bash
# 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:

```bash
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:

```bash
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`.

```bash
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:

```bash
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):

```bash
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.