CodeGraph Multi-Root Workspace Issue

[kun-yx]

CodeGraph Multi-Root Workspace Issue

Problem

CodeGraph does not index code inside Windows Junction directories, which makes it hard to build a single aggregated workspace for a multi-repo / submodule-style project.

Environment

• OS: Windows
• Shell: PowerShell
• CodeGraph: v1.1.1
• Backend: node:sqlite - built-in (full WAL)
• Project layout: one root workspace with multiple independent repositories as Git submodules / gitlinks

Example root layout:

repo-root/
  service-a/
  service-b/
  service-c/
  shared-sdk/
  client-app/

The root repository records these module directories as 160000 gitlink entries.

Use Case

I want to use one CodeGraph MCP project to query the whole workspace across modules, instead of creating and switching between separate CodeGraph indexes for each module.

To do this, I created an aggregated workspace:

repo-root/.cg-workspace/
  service-a -> repo-root/service-a
  service-b -> repo-root/service-b
  service-c -> repo-root/service-c
  shared-sdk -> repo-root/shared-sdk
  client-app -> repo-root/client-app
  .codegraph/
repo-root/.codegraph/

On Windows these entries are Junction directories.

The CodeGraph metadata directory is also shared through a Junction:

repo-root/.codegraph -> repo-root/.cg-workspace/.codegraph

So both the repository root and the aggregated workspace point to the same CodeGraph database directory.

Actual Behavior

Running CodeGraph on the aggregated workspace only indexes a few direct files and does not traverse the Junction directories.

Example:

codegraph index .cg-workspace

Result:

Indexing project
  * Scanning files - 3 found
  * Parsing code - done
  * Resolving refs - done

Indexed 3 files
12 nodes, 17 edges

However, the files are reachable through the Junctions:

rg --files .cg-workspace
# 79 files

rg --files -L .cg-workspace
# 10272 files

So the Junctions are valid, but CodeGraph appears not to follow Windows reparse points during scanning.

There is also an intermittent behavior when using the Junction-based workspace with MCP:

• At the beginning, CodeGraph may appear to work for a short period.
• After several MCP queries or file operations, the index seems to degrade or become ineffective.
• Running codegraph status then shows only a very small number of indexed files, even though the linked modules contain many source files.
• The status still reports [OK] Index is up to date, but the index statistics become unexpectedly small.

Example normal status before degradation:

CodeGraph Status

Project: repo-root\.cg-workspace

Index Statistics:
  Files:     8,798
  Nodes:     179,256
  Edges:     306,904
  DB Size:   403.63 MB
  Backend:   node:sqlite - built-in (full WAL)
  Journal:   wal

Nodes by Kind:
  method          44,968
  import          44,778
  enum_member     17,472
  function        17,116
  type_alias      11,904
  file            8,779
  struct          6,755
  class           6,700
  field           6,669
  constant        5,133
  enum            3,535
  variable        2,611
  namespace       2,517
  interface       319

Files by Language:
  cpp             3,641
  kotlin          2,468
  c               1,935
  xml             673
  java            61
  properties      17
  yaml            2
  python          1

[OK] Index is up to date

Example degraded status:

CodeGraph Status

Project: repo-root\.cg-workspace

Index Statistics:
  Files:     3
  Nodes:     12
  Edges:     17
  DB Size:   403.63 MB
  Backend:   node:sqlite - built-in (full WAL)
  Journal:   wal

Nodes by Kind:
  function        6
  import          5
  file            1

Files by Language:
  yaml            2
  python          1

[OK] Index is up to date

This makes the setup feel unstable: the workspace may look usable initially, but after a few rounds of usage the effective index no longer represents the full workspace.

Expected Behavior

CodeGraph should provide a way to index an aggregated workspace that uses Windows Junctions / symlinks to compose multiple repositories.

Possible solutions:

• Add an option such as --follow-symlinks / --follow-junctions
• Detect Windows Junctions and allow traversal when explicitly enabled
• Add a workspace configuration file that can include multiple roots
• Add first-class multi-root / monorepo workspace support for MCP

Why This Matters

For multi-repo projects, indexing each module separately makes MCP usage inconvenient:

• Cross-module search and call-chain exploration is fragmented
• The MCP client has to choose one projectPath at a time
• It is hard to ask workspace-level questions across services/modules

A single aggregated CodeGraph project would make MCP usage much more practical.

Additional Notes

Indexing the root repository directly also does not solve this case because the module directories are Git submodule/gitlink entries. CodeGraph indexes only the root repository files and does not expand the submodule contents.

So both current approaches fail for whole-workspace indexing:

1. Root repository indexing skips gitlink/submodule contents.
2. Aggregated workspace indexing skips Junction contents.
3. Junction-based MCP usage may appear to work briefly, then degrade to an incomplete index after several operations.

A supported multi-root or follow-junction mode would solve this.

[colbymchenry]

Update after digging into this: the core of what you need is fixed in #1038 (merged to main, ships in the next release), and the junction workspace turns out to be unnecessary once it lands.

What was actually wrong: your repo-root is a git repo whose modules are recorded as 160000 submodule/gitlink entries, and indexing it "skipped gitlink/submodule contents." That was a real bug — CodeGraph wasn't descending into nested repos tracked as gitlinks. It now does: indexing a git root pulls in every nested module repo that has a working tree on disk, recursively. (Verified with a workspace whose modules are submodule gitlinks — all module files index from a single codegraph init at the root.)

So the fix for your use case is simpler than the junction setup: after the next release, point CodeGraph directly at the real repo-root (not .cg-workspace). The module contents will index into one aggregated graph — which is exactly the whole-workspace index you were after.

That also makes the two junction-related symptoms go away, because they were side effects of the workaround rather than separate problems:

• Junctions not traversed — only mattered because .cg-workspace used junctions instead of being the real git root.
• Index degrading to ~3 files — you had repo-root/.codegraph junctioned to .cg-workspace/.codegraph, so two different roots shared one database and their background syncs overwrote each other. Indexing a single real root removes that entirely.

One caveat: a submodule has to be checked out on disk to be indexed (an uninitialized/empty submodule has no files to index) — but your 8,798 files status shows yours are checked out, so repo-root should cover them.

Closing as resolved by #1038. Once it's released, give repo-root a try — and if indexing the real root doesn't pull in your modules for some reason, please reopen with what codegraph status shows and I'll dig back in. Thanks again for the detailed report.

[colbymchenry]

Follow-up: a related rough edge is now fixed too, in #1039 (merged to main).

Once nested repos index into one workspace graph, working inside a submodule resolves up to the workspace index correctly — but CodeGraph was still showing a "different git working tree" warning there and suggesting codegraph init -i, which would have split the submodule back into its own index and undone the unified view. That was a false positive: the submodule's code is already part of the workspace index. CodeGraph now recognizes that and stays quiet (the warning still fires for a genuine git worktree — a second checkout of the same repo on another branch — since that's the case it's for).

Net, for the next release: index your real repo-root, and querying/editing from inside any module — including the agent talking to you from within a sub-repo — uses the one workspace index, stays fresh on edits (verified on macOS and Linux), and no longer nags about worktrees. Both fixes (#1038, #1039) ship together.

[colbymchenry]

One more hardening fix from this thread landed in #1041 (merged to main).

While validating the submodule-workspace flow on Windows, I found that the background daemon could abort on shutdown (a libuv fs.watch teardown race, exit code 0xC0000409) specifically when the indexed tree contains a nested repo — exactly your layout. It exited anyway, but with a crash code and a stderr assertion instead of a clean exit. The daemon now drains cleanly on Windows shutdown (~instant). Not something you'd have to do anything about, but it's tidied up for the next release alongside the indexing and worktree-warning fixes.

[kun-yx]

Thank you very much for your reply, thank you!