Compass
Compass is a browser-based codebase explorer that maps files, dependencies, architecture roles, and change impact without uploading the repository.
Hackathon buildAug 2026BuilderCollabute × TheBlockwith Huaicheng Su
Open source under the MIT License.
TL;DR
- Huaicheng Su's earlier JetBrains dependency-visualisation plugin became a broader browser-first explorer during the Collabute × TheBlock hackathon.
- Open a local repository and Compass turns its files and internal dependencies into an interactive graph, with architecture roles, isolated files, and a recommended reading order.
- The path is open, map, explore, ask: local parsing builds the structure before the developer follows change impact or asks a grounded question.
- Selecting a file exposes its role, dependencies, dependents, and transitive change impact, with a file-scoped assistant grounded in that context.
- Source stays on the machine. Collaboration publishes a derived digest of paths, identifiers, roles, packages, and dependency edges rather than repository contents.
- The browser analyzer, Convex collaboration layer, grounded AI tools, and external dependency intelligence form three distinct layers.
- Vite, D3, Web Workers, Convex, Groq, Context.dev, npm, PyPI, and OSV keep the implementation focused on analysis and exploration.
- Released under the MIT License after the August 2026 hackathon; functional and public, but not operated as a commercial product.
Origin
From an IDE plugin to a browser-first codebase explorer.
Huaicheng Su had previously built a JetBrains plugin around visualising dependencies inside a codebase.
For the Collabute × TheBlock hackathon, Huaicheng and I took that starting point and pushed it further: move the experience into the browser, redesign the interface around exploration rather than the IDE, expand analysis across multiple languages, and add change impact, architecture discovery, codebase questions, collaboration, and dependency intelligence.
The result became Compass.
The product
Most unfamiliar repositories give you files. Compass gives you a map.
Opening a large codebase normally means jumping between folders, imports, and search results until a mental model starts forming. Compass builds that model first.
Choose a local project and it parses the source files, resolves internal imports, and renders the repository as an interactive dependency graph. The analyzer supports Java, Kotlin, JavaScript, TypeScript, and Python, with internal relationships resolved locally in the browser.
How it works
One path from opening a repository to understanding how it fits together.
01
Open
Select a project from the computer. Compass filters generated and vendor directories, then reads supported source files locally.
02
Map
The analyzer extracts symbols and imports, resolves internal dependencies, and builds the repository graph.
03
Explore
Navigate files visually, inspect incoming and outgoing relationships, find isolated files, follow a recommended reading order, and trace transitive change impact.
04
Ask
Ask about the whole codebase or focus the assistant on one file. Shared notes and presence let teammates explore the same mapped project together.
Change impact
Selecting one file reveals why it matters to the rest of the repository.
A selected node opens the file view: its path, language, architectural role, direct relationships, and an explanation grounded in the graph. That turns a dependency map into an answer to the practical question developers usually have first: what could this change affect?
The same context gives the file assistant a narrower scope. It can summarise the file, explain why it has many dependents, walk through a reading order, or identify likely breakage without treating the file as an isolated snippet.
The main constraint
AI was useful only if the source code did not have to leave the machine.
Uploading an unfamiliar private repository just to understand it defeats a major reason developers would want a tool like Compass. The parsing and dependency analysis therefore happen locally.
When collaboration is enabled, Compass publishes a derived digest containing paths, identifiers, architecture roles, dependency edges, and package names. The shared Convex representation does not store the repository's source contents. That digest is enough to support shared structure, taxonomy, notes, presence, and dependency intelligence.
The exception is explicit: if someone attaches an external file to an assistant question, that file can be sent for that question rather than being silently included with the project.
Architecture
Three layers support the experience.
The taxonomy system runs in two passes. It first derives a small architecture vocabulary for the specific repository, then assigns files against that fixed vocabulary. The implementation uses openai/gpt-oss-120b through Groq and caches the result per project.
Browser
Where the repository is analysed
Local analyzer
Parses source files, symbols, and imports
Dependency graph
Maps internal file relationships
D3
Renders and navigates the graph
Web Worker
Keeps repository analysis off the main UI thread
Realtime + AI
What makes the map collaborative and easier to understand
Convex
Stores derived graph state, notes, presence, and cached results
Project taxonomy
Derives architecture categories for each repository
Codebase assistant
Answers questions using known structural context
File summaries
Explains individual files and caches the result
Dependency intelligence
What sits outside the repository itself
Context.dev
Provides migration and dependency guidance
npm / PyPI / OSV
Provide package and vulnerability information
Cached refreshes
Avoid repeating external lookups unnecessarily
Stack
Interface
Browser application and graph exploration.
Analysis
Local parsing and dependency mapping stay off the main UI thread.
Backend
Realtime shared state and server-side actions.
AI
Repository taxonomy, file summaries, and grounded codebase questions.
Dependency intelligence
Package versions, advisories, and migration context.
Where it stands
Built for Collabute × TheBlock and released as an open-source hackathon project.
Compass was built during the Collabute × TheBlock hackathon in August 2026. It is functional and publicly available, but remains a hackathon build rather than a product currently being operated or commercialised.
The repository includes the browser analyzer, Convex backend, dependency-intelligence integration, automated analyzer tests, and an MIT licence.
