Code Compass

VS Code extension for repository understanding inside the editor.

This project combines three workflows into a single extension:

• AI chat for repo-level questions
• code threads attached directly to source code
• usage-insight style answers such as impact, ownership, and churn

What this project is

When a developer joins a new repo, changes code owned by another team, or tries to understand a large codebase, the usual workflow is fragmented:

• open code
• search Slack or docs
• ask a teammate
• manually trace dependencies

This extension is meant to bring that workflow into VS Code.

The current version focuses on:

• Explain mode for structure and file/function summarization
• Code mode for impact and repository-risk style questions
• inline code threads for asking and answering questions on selected code
• editor-native Add Thread actions inside the code view

Current features

1. AI Chat

The main sidebar view is AI Chat.

It supports:

• persistent chat history
• edit and delete for user messages
• timestamped history
• Explain and Code modes

Explain mode

• Entire Structure
• File
• Function

Function reads the active file and shows a picker of available functions. For Python files, there is a fallback parser for def and async def if symbol discovery is not available.

Code mode

• Impacted files
• Top-churn files
• Owner of code

Notes:

• Top-churn files and Owner of code are currently demo-style responses with improved UI rendering.
• Impacted files is wired as a chat action and is the current placeholder for deeper dependency analysis.

2. Code Threads

Threads can be created from:

• selected code
• the Code Threads view
• inline Add Thread actions shown in the editor

Thread capabilities:

• create a thread on selected code
• ask the first question
• add answers
• resolve and reopen threads
• delete threads
• jump from the sidebar thread list back to the exact code range

The extension includes:

• a Code Threads sidebar
• native VS Code comment threads in the editor
• an inline Add Thread CodeLens that follows the current line/visible code area

3. Usage-style insight routing

The extension contains an internal usage layer bridge for questions like:

• ownership
• churn
• impact
• dependency-style queries

Right now the system is in a hybrid state:

• some responses are hardcoded/demo responses for UI and interaction testing
• the architecture already includes a UsageTrackerService so a real backend can replace those demo responses later

Project structure

Core extension

• src/extension.ts
  • extension activation
  • command registration
  • webview providers
  • inline thread provider registration

Chat

• src/chat/ChatViewProvider.ts
  • webview-to-extension message bridge
• src/chat/getWebviewHtml.ts
  • chat webview shell
• media/main.js
  • chat UI behavior
• media/styles.css
  • chat styling

AI / usage layer

• src/core/ChatService.ts
  • chat history
  • canned/demo response routing
  • provider dispatch
• src/core/UsageTrackerService.ts
  • usage-style query routing hook
• src/core/providers/MockProvider.ts
  • local mock response provider
• src/core/providers/OpenAICompatibleProvider.ts
  • OpenAI-compatible chat provider

Threads

• src/threads/commentController.ts
  • VS Code native comment thread integration
• src/threads/sidebarProvider.ts
  • Code Threads webview provider
• src/threads/threadStore.ts
  • thread persistence
• src/threads/inlineThreadLensProvider.ts
  • inline Add Thread CodeLens
• src/threads/types.ts
  • thread-related types
• media/threadSidebar.html
  • thread sidebar UI

How to run locally

1. Clone the repository

Download the project from GitHub:

git clone https://github.com/aaron02nj/code-compass.git
cd code-compass

If you prefer SSH:

git clone git@github.com:aaron02nj/code-compass.git
cd code-compass

2. Open the project in VS Code

Open the cloned folder in VS Code.

3. Use the local Node.js runtime

If your machine already has Node.js and npm installed, you can use those directly.

If you are using a local portable Node installation, point your shell at that local bin directory first.

<project-root>/.local/<node-install>/bin

If your shell does not already know node or npm, run:

export PATH="<project-root>/.local/<node-install>/bin:$PATH"

4. Install dependencies

npm install

5. Build

npm run compile

6. Launch the extension

Press F5 in VS Code using the Run Extension launch config.

This opens an Extension Development Host window. In that new window:

• open the Repo Chat icon in the Activity Bar
• start with AI Chat
• open Code Threads from inside chat or from the view container

How to use

Ask repo questions

In AI Chat:

• choose Explain or Code
• click one of the suggestion buttons or type your own question

Examples:

• Summarize the entire structure.
• Summarize this file.
• Explain function make_video in this file.
• What files will be impacted if I modify this file?
• Show top 10 files by churn in this repository.
• Who is the best person to ask about this file?

Create a thread on code

Option 1:

• select code
• right click
• choose Repo Chat: New Code Thread

Option 2:

• click inline Add Thread above the current code line

Option 3:

• open Code Threads
• select code in the editor
• click + New Thread

Answer a thread

From the Code Threads sidebar:

• click Answer
• write the response
• press Enter or click Submit Answer

From the native editor thread:

• use the VS Code thread reply UI

Resolve or reopen a thread

In the Code Threads sidebar:

• click Mark resolved
• if that was accidental, click Mark unresolved

Configuration

Available settings:

• repoContextChat.provider
• repoContextChat.apiBaseUrl
• repoContextChat.apiKey
• repoContextChat.model
• repoContextChat.usageBackendUrl
• repoContextChat.usageRepo
• repoContextChat.enableUsageRouting
• repoContextChat.threadAuthor

Current limitations

• some usage insights are still hardcoded for demo and UI validation
• impact analysis is not yet backed by a full dependency graph engine
• thread answer generation is not yet connected to the same AI backend as chat
• the current inline Add Thread experience is implemented as a CodeLens, which is the most stable editor-native approximation of a floating hover button

Suggested next steps

1. Replace hardcoded churn and ownership answers with real usage backend calls.
2. Connect thread answers to the AI chat engine or a dedicated thread-answer backend.
3. Add real dependency graph analysis for Impacted files.
4. Package the extension as .vsix for distribution.
5. Publish the repo and add screenshots/demo GIFs for onboarding.