Initial publish v0.1.0: standalone workflow core (corpus + examples + guards)
This commit is contained in:
octopus
@@ -0,0 +1,213 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user