feat(codegraph): per-workspace CodeGraph indexing for agent sessions #47

Open

lz wants to merge 12 commits from feat/codegraph into main

pull from: feat/codegraph

merge into: lz:main

lz:main

lz:fix/workspace-artifacts

lz:fix/comment-collapse

lz:feat/api-proxy

Conversation 0 Commits 12 Files changed 16 +1273 -4

lz commented 2026-06-27 09:22:52 +02:00

Owner

Copy link

Summary

Adds CodeGraph (@colbymchenry/codegraph) support so the claude agent inside worker sessions gets the codegraph_explore MCP tool, backed by a pre-built code-knowledge-graph (tree-sitter → SQLite). The agent can query call paths / impact instead of grep/read loops. Agent-tool only — no operator-facing UI beyond an opt-out toggle.

Architecture: build the graph once at workspace creation (synchronous, post-clone in the entrypoint), then copy the seed .codegraph/ into each new worktree at createSession. Each session's own codegraph serve --mcp watcher then tracks its branch; its startup reconciliation re-parses only drifted files, so a copy that lags /workspace's HEAD self-corrects on session launch. Per-workspace opt-out, default on.

Changes

• worker/Dockerfile — bake @colbymchenry/codegraph into the base image.
• worker/entrypoint.sh — gated, idempotent CodeGraph block: exclude .codegraph/ via common-dir info/exclude, register the stdio MCP server in the per-worker ~/.claude.json (same seam as forgejo-mcp), and codegraph init /workspace once (guarded by [ ! -d .codegraph ]). Placed before tmux new-session so the seed is ready before any session exists. Covered by worker/codegraph-entrypoint.test.sh.
• createSession (sessions/service.ts) — copy the seed into each new worktree (clearing the stale daemon.pid/daemon.sock that cp -r drags along), best-effort with debug logging.
• sessions/codegraph.ts — pure helpers buildCodegraphSeedCommand + codegraphEnvEntry (unit-tested).
• Migration 0013 — workers.codegraph_enabled (INTEGER NOT NULL DEFAULT 1).
• spawnWorker — persist the column, inject CODEGRAPH_ENABLED env, expose in WorkerDTO.
• API + client + NewWorker.svelte — "Index codebase with CodeGraph" checkbox (default on) threads the flag end-to-end.
• AGENTS.md — new fact #19 + CODEGRAPH_ENABLED env-var row.

DB-copy safety (relative paths, daemon keyed by absolute root, startup reconciliation) was confirmed against codegraph source; rationale is captured in docs/superpowers/specs/2026-06-26-codegraph-support-design.md.

Test Plan

• pnpm test — 565/565 pass (incl. migration 0013 + codegraph helper tests)
• pnpm exec tsc --noEmit — clean
• pnpm exec svelte-check --threshold error — 0 errors
• sh worker/codegraph-entrypoint.test.sh — 3/3 cases (enabled+fresh, disabled, enabled+already-indexed) + no regression in other worker shell tests
• Deferred (needs docker): docker build --target base worker/ builds and codegraph --version runs in the image
• Deferred (needs docker): end-to-end seed→copy→query smoke — codegraph init /workspace, cp -r into a worktree, clear daemon lock, confirm codegraph status reports a populated index resolving correctly (validates relative-path portability live)

https://claude.ai/code/session_01DPMvaAf6Ay8ZtLpCRyCe8F

## Summary Adds [CodeGraph](https://github.com/colbymchenry/codegraph) (`@colbymchenry/codegraph`) support so the `claude` agent inside worker sessions gets the `codegraph_explore` MCP tool, backed by a pre-built code-knowledge-graph (tree-sitter → SQLite). The agent can query call paths / impact instead of grep/read loops. **Agent-tool only** — no operator-facing UI beyond an opt-out toggle. Architecture: build the graph **once** at workspace creation (synchronous, post-clone in the entrypoint), then **copy** the seed `.codegraph/` into each new worktree at `createSession`. Each session's own `codegraph serve --mcp` watcher then tracks its branch; its startup reconciliation re-parses only drifted files, so a copy that lags `/workspace`'s HEAD self-corrects on session launch. Per-workspace opt-out, default on. ### Changes - **`worker/Dockerfile`** — bake `@colbymchenry/codegraph` into the base image. - **`worker/entrypoint.sh`** — gated, idempotent CodeGraph block: exclude `.codegraph/` via common-dir `info/exclude`, register the stdio MCP server in the per-worker `~/.claude.json` (same seam as forgejo-mcp), and `codegraph init /workspace` once (guarded by `[ ! -d .codegraph ]`). Placed before `tmux new-session` so the seed is ready before any session exists. Covered by `worker/codegraph-entrypoint.test.sh`. - **`createSession`** (`sessions/service.ts`) — copy the seed into each new worktree (clearing the stale `daemon.pid`/`daemon.sock` that `cp -r` drags along), best-effort with debug logging. - **`sessions/codegraph.ts`** — pure helpers `buildCodegraphSeedCommand` + `codegraphEnvEntry` (unit-tested). - **Migration 0013** — `workers.codegraph_enabled` (INTEGER NOT NULL DEFAULT 1). - **`spawnWorker`** — persist the column, inject `CODEGRAPH_ENABLED` env, expose in `WorkerDTO`. - **API + client + `NewWorker.svelte`** — "Index codebase with CodeGraph" checkbox (default on) threads the flag end-to-end. - **`AGENTS.md`** — new fact #19 + `CODEGRAPH_ENABLED` env-var row. DB-copy safety (relative paths, daemon keyed by absolute root, startup reconciliation) was confirmed against codegraph source; rationale is captured in `docs/superpowers/specs/2026-06-26-codegraph-support-design.md`. ## Test Plan - [x] `pnpm test` — 565/565 pass (incl. migration 0013 + codegraph helper tests) - [x] `pnpm exec tsc --noEmit` — clean - [x] `pnpm exec svelte-check --threshold error` — 0 errors - [x] `sh worker/codegraph-entrypoint.test.sh` — 3/3 cases (enabled+fresh, disabled, enabled+already-indexed) + no regression in other worker shell tests - [ ] **Deferred (needs docker):** `docker build --target base worker/` builds and `codegraph --version` runs in the image - [ ] **Deferred (needs docker):** end-to-end seed→copy→query smoke — `codegraph init /workspace`, `cp -r` into a worktree, clear daemon lock, confirm `codegraph status` reports a populated index resolving correctly (validates relative-path portability live) https://claude.ai/code/session_01DPMvaAf6Ay8ZtLpCRyCe8F

lz added 12 commits 2026-06-27 09:22:52 +02:00

docs(codegraph): design spec for agent-tool CodeGraph support f7e4561e00

docs(codegraph): confirm DB copy is safe (relative paths); clear stale daemon lock on copy dd45b225ad

docs(codegraph): implementation plan + seed-staleness resolution (startup reconciliation) f860570484

feat(worker): install @colbymchenry/codegraph in base image afd49f7513

feat(db): add workers.codegraph_enabled column (default on) ... dd01ac04a2

Migration 0013 adds codegraph_enabled INTEGER NOT NULL DEFAULT 1 to the
workers table. Uses Generated<number> in the schema type so inserts may
omit it. Fix the synthetic DTO construction in spawnWorker to mirror the
existing worker_image ?? default pattern for the new Generated column.

Claude-Session: https://claude.ai/code/session_01DPMvaAf6Ay8ZtLpCRyCe8F

feat(sessions): add codegraph seed-copy and env-entry helpers eb671297ab

feat(sessions): seed CodeGraph index into each new worktree ... a57ad44f02

Claude-Session: https://claude.ai/code/session_01DPMvaAf6Ay8ZtLpCRyCe8F

feat(workers): persist codegraph_enabled and inject CODEGRAPH_ENABLED env ... 41798e691f

Claude-Session: https://claude.ai/code/session_01DPMvaAf6Ay8ZtLpCRyCe8F

feat(ui): per-workspace CodeGraph toggle on the New Workspace form ... a759ab20e3

Claude-Session: https://claude.ai/code/session_01DPMvaAf6Ay8ZtLpCRyCe8F

feat(worker): seed CodeGraph + register MCP in entrypoint (gated, idempotent) ... 791a1cabae

Claude-Session: https://claude.ai/code/session_01DPMvaAf6Ay8ZtLpCRyCe8F

docs(codegraph): document CodeGraph indexing in AGENTS.md ... 4adaaf7d21

Add verified fact #19 describing the codegraph init/copy/MCP-register
flow, the relative-path portability guarantee, and the catchUpSync
self-correction behaviour. Add CODEGRAPH_ENABLED to the env-var table,
positioned next to the other worker per-spawn var.

Claude-Session: https://claude.ai/code/session_01DPMvaAf6Ay8ZtLpCRyCe8F

fix(codegraph): log best-effort seed-copy failure; clarify entrypoint degraded-boot gating in spec 50359b08d0

Some checks failed

Hide all checks

ci / nexus (pull_request) Successful in 3m12s

Details

ci / images (./nexus, agent-nexus) (pull_request) Successful in 5m18s

Details

ci / images (./worker, agent-nexus-worker, base) (pull_request) Successful in 3m34s

Details

ci / images (PLAYWRIGHT_CLI_VERSION=0.1.13, ./worker, agent-nexus-worker, -playwright0.1.13, playwright) (pull_request) Failing after 7m55s

Details

This pull request can be merged automatically.

This branch is out-of-date with the base branch

You are not authorized to merge this pull request.

View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u origin feat/codegraph:feat/codegraph

git switch feat/codegraph

Merge

Merge the changes and update on Forgejo.

git switch main

git merge --no-ff feat/codegraph

git switch feat/codegraph

git rebase main

git switch main

git merge --ff-only feat/codegraph

git switch feat/codegraph

git rebase main

git switch main

git merge --no-ff feat/codegraph

git switch main

git merge --squash feat/codegraph

git switch main

git merge --ff-only feat/codegraph

git switch main

git merge feat/codegraph

git push origin main

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

bug

Something is not working

  

duplicate

This issue or pull request already exists

  

enhancement

New feature

  

help wanted

Need some help

  

invalid

Something is wrong

  

question

More information is needed

  

wontfix

This won't be fixed

No labels

bug

duplicate

enhancement

help wanted

invalid

question

wontfix

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

lz/agent-nexus!47

No description provided.