How to Debug Issues Within the Graph Module in Hivemind

You can debug Hivemind's graph module by instrumenting the virtual filesystem (VFS) stack—starting with command parsing in graph-command.ts, proceeding through the dispatcher in vfs-handler.ts, and ending at the specific renderers in src/graph/render/—while using the bundled test suite under tests/shared/graph/ to isolate and reproduce failures.

The graph module in activeloopai/hivemind implements a virtual filesystem (VFS) that synthesizes text views of code-graph snapshots. When commands like cat ~/.deeplake/memory/graph/find/foo return errors such as No local graph for this worktree yet or unexpected not-found messages, you must trace execution through three distinct architectural layers to identify the root cause.

Understanding the Graph Module Architecture

The graph subsystem consists of three layers that handle every VFS read request.

Command Parsing Layer

Located in src/graph/graph-command.ts, the parseReadTargetPath function transforms shell commands (e.g., cat ..., ls ...) into virtual paths. The tryGraphRead function then forwards these paths to the dispatcher. Parsing logic includes pipe handling constraints around lines 52-62.

VFS Dispatcher Layer

The handleGraphVfs function in src/graph/vfs-handler.ts (lines 48-62) receives the virtual path and routes it to the appropriate renderer. It returns a not-found result if the path is invalid or a no-graph result if the snapshot cannot be loaded.

Renderer Layer

Individual renderers in src/graph/render/ (such as render/find.ts and render/show.ts) read the graph snapshot and emit markdown text for specific endpoints like index, find, show, and query.

Step-by-Step Debugging Workflow

Follow this sequence to isolate bugs in any of the three layers.

1. Reproduce the Issue Locally

Start by triggering the specific graph read that fails. For example:

cat ~/.deeplake/memory/graph/find/foo

If you see errors like No local graph for this worktree yet or not-found, you have identified the entry point for debugging.

2. Instrument the Command Parser

Add console.debug statements to src/graph/graph-command.ts to trace how the shell command is parsed. Insert logging near the top of parseReadTargetPath (around lines 49-55):

export function parseReadTargetPath(rewrittenCommand: string): string | null {
  console.debug('[graph-command] raw command →', rewrittenCommand);
  const cmd = rewrittenCommand.replace(/\s+2>\S+/g, "").trim();
  // ...
}

Re-run the cat command. If the function returns null, the parser rejected the command due to unsupported flags or pipe handling issues (see logic around lines 52-62).

3. Verify the VFS Dispatcher

Confirm the virtual path reaches handleGraphVfs by adding debug output in tryGraphRead before the dispatcher call (around lines 110-114):

export function tryGraphRead(rewrittenCommand: string, cwd: string): string | null {
  // ...
  const virtualPath = parseReadTargetPath(rewrittenCommand);
  console.debug('[graph-command] virtualPath →', virtualPath);
  // ...
}

If the path is missing the /graph/ prefix or is malformed, the bug lies in the parser's normalization logic.

4. Inspect the VFS Handler

Drill into src/graph/vfs-handler.ts to see which renderer is invoked or if the request fails early. Add logging at the start of handleGraphVfs (line 48):

export function handleGraphVfs(subpath: string, cwd: string): GraphVfsResult {
  console.debug('[vfs-handler] subpath →', subpath, 'cwd →', cwd);
  // ...
}

Check if the function returns a not-found result (lines 56-62) or reaches a specific renderer like renderFind.

5. Debug Snapshot Loading

If you encounter a no-graph result (lines 70-85), the snapshot cannot be loaded. The loadSnapshotOrError helper (lines 62-87) attempts to read from repoDir. Add path logging:

const snapPath = join(baseDir, "snapshots", `${fileBase}.json`);
console.debug('[vfs-handler] snapPath →', snapPath);

Common causes include:

• Cannot derive repo identity: The identity module cannot hash the current working directory (missing Git metadata).
• No local graph for this worktree yet: The graph has not been built; run hivemind graph build or hivemind graph pull.
• Snapshot file missing on disk: The JSON file was removed or repoDir has incorrect permissions.

6. Unit Test the Failing Path

The test suite in tests/shared/graph/ validates VFS behavior. Run specific tests to isolate the failure:

npm test -- tests/shared/graph/vfs-handler.test.ts

To simulate a corrupted snapshot, edit the temporary .find-handles.json file created by the test harness and re-run. The try...catch block at lines 111-115 in vfs-handler.ts surfaces thrown errors as no-graph results.

7. Check CLI Build Logs

If the issue originates during graph construction rather than VFS reads, use the CLI with the --dry-run flag. This outputs sub-command execution details and lock file locations (.graph-on-stop.log). The hook in src/hooks/graph-on-stop.ts emits messages like gate: FIRE or decideGate threw when the build process fails.

8. Clean Up and Rebuild

After fixing the bug, remove stale snapshots and rebuild:

rm -rf $(hivemind graph repo-dir)
hivemind graph build
cat ~/.deeplake/memory/graph/find/foo

Common Failure Patterns

Symptom	Location	Resolution
null path from parser	graph-command.ts (lines 52-62)	Check for unsupported pipe characters or flags in the command
not-found result	vfs-handler.ts (lines 56-62)	Verify the subpath matches an existing renderer endpoint
Cannot derive repo identity	Identity resolution logic	Ensure the directory is a Git repository with valid metadata
Missing snapshot errors	vfs-handler.ts (lines 70-85)	Run hivemind graph build to generate the JSON snapshot

Summary

• Debug the graph module by tracing the VFS stack from parseReadTargetPath through handleGraphVfs to the specific renderer in src/graph/render/.
• Instrument code with console.debug in src/graph/graph-command.ts and src/graph/vfs-handler.ts to trace command-to-path transformations and dispatcher routing.
• Handle snapshot errors by verifying the repository identity, checking file permissions in the repoDir, and rebuilding with hivemind graph build.
• Validate fixes using the unit test suite in tests/shared/graph/ and the --dry-run CLI flag for build-time issues.

Frequently Asked Questions

How do I enable verbose logging for graph commands?

Insert console.debug statements at the entry points of parseReadTargetPath in src/graph/graph-command.ts and handleGraphVfs in src/graph/vfs-handler.ts. Re-run the shell command that triggered the error and inspect the output to see the raw command string, parsed virtual path, and current working directory at each stage.

What does "No local graph for this worktree yet" mean?

This error originates in src/graph/vfs-handler.ts (lines 70-85) when loadSnapshotOrError cannot find a JSON snapshot for the current working directory. Run hivemind graph build to generate the graph, or hivemind graph pull to fetch a pre-built snapshot from remote storage.

How do I run the graph module unit tests?

Execute npm test -- tests/shared/graph/vfs-handler.test.ts to validate the VFS dispatcher and renderer logic. The tests simulate various graph states and verify that handleGraphVfs returns the correct results or error codes for malformed paths and missing snapshots.

Where are graph snapshots stored on disk?

Snapshots are JSON files stored in the snapshots/ subdirectory of the graph repository directory, which you can locate by running hivemind graph repo-dir. The loadSnapshotOrError function in src/graph/vfs-handler.ts constructs the full path using join(baseDir, "snapshots", \${fileBase}.json`)`.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}