cviz — 2.5D Codebase Visualizer

Overview

cviz is a native desktop application that visualises any git repository as an interactive 2.5D spatial map. The layout is driven entirely by the git history: files that change together cluster together. Directories group into convex hull backgrounds. Click any node to inspect its commit history and co-changed neighbours.

The motivating question: is there a genuinely different way to perceive a codebase — not a file tree, not a search box, but a spatial map you can navigate by memory?

Architecture

Five async pipeline stages running on a tokio background thread:

Stage	What it does
GitCollector	Walks commit graph via git2, builds Jaccard co-change matrix
Embedder	TF-IDF on file paths with camelCase/snake_case tokenisation
LayoutEngine	Barnes-Hut O(n log n) force-directed simulation, 500 iterations
Renderer	wgpu instanced circles, glow shaders, convex hull directories, bitmap font labels
SocketListener	Unix domain socket for real-time agent event ingestion

The Barnes-Hut approximation is what makes this usable on real repos. A naive force simulation is O(n²) per iteration. Barnes-Hut treats distant node clusters as point masses, reducing it to O(n log n). On a 350-node repo, that’s seconds instead of minutes.

Layout

Two files are placed close together if they frequently appear in the same commit. Co-change affinity is computed as a Jaccard similarity: |shared_commits| / |union_commits|. TF-IDF semantic similarity on tokenised path components provides a secondary signal for files with sparse co-change history.

The result is an emergent layout that reflects actual coupling — without any manual configuration. Auth files cluster together. Test files form halos around the code they cover. Utility modules sit at the periphery.

Claude Code Integration

A PostToolUse hook sends a JSON event to a Unix socket whenever Claude Code reads or edits a file:

#!/bin/bash
echo '{"tool":"'"$CLAUDE_TOOL_NAME"'","path":"'"$CLAUDE_TOOL_INPUT_PATH"'"}' \
  | nc -U /tmp/cviz-$(echo "$PWD" | md5).sock 2>/dev/null || true

The SocketListener picks this up and the Renderer applies a cyan tint and a ring to the affected node. The practical effect: you watch the agent navigate the codebase spatially in real time — and can see at a glance whether it’s missing files that seem relevant.

Features

Zoom-to-cursor, smooth pan/zoom interpolation
LOD: labels and small nodes hidden when zoomed out
Colour modes: file type / recency (press C)
Depth modes: recency / coupling / importance (press 1/2/3)
Click any node: lines of code, commit count, co-changed files in terminal
Convex hull backgrounds per directory
Agent activity: cyan tint + ring on files touched via socket

Test Results

Repo	Files	Co-change pairs	Result
ising-rs	352	1,511	Dense Rust core, clear directory clusters, Python notebooks isolated
physics-llm-research	30	2	Embedding-driven clustering dominates
portfolio	237	21	Sparse co-change, directory structure visible

Status

Working prototype, 30 commits, tested on three repos. Next steps: Ollama embeddings for semantic clustering based on file content, trail animation showing agent navigation paths.