Using the VS Code Extension

In this tutorial, you’ll learn how to use the Unfault VS Code extension to understand your code’s runtime context as you write it. We’ll explore function impact, file centrality, the context sidebar, and how to configure the experience.

Before You Start

You’ll need:

VS Code installed
The Unfault CLI installed and authenticated (unfault login)
A project with Python, Go, Rust, TypeScript, or JavaScript code

Install the Extension

Open VS Code
Press Cmd+Shift+X (macOS) or Ctrl+Shift+X (Windows/Linux)
Search for “Unfault”
Click Install

The extension activates automatically when you open a supported file.

The Status Bar

After installation, you’ll see the Unfault icon in the status bar (bottom right):

┌─────────────────────────────────────────────────────────┐
│                                        [$(unfault-logo)]│
└─────────────────────────────────────────────────────────┘

Click it to open the menu with all available actions.

Status Bar States

The icon changes based on context:

Display	Meaning
`$(unfault-logo)`	Extension running; open a supported file for context
`$(unfault-logo) 3`	3 diagnostics in current file (when enabled)
`$(unfault-logo) $(star)`	Moderately central file (more dependents)
`$(unfault-logo) $(hub)`	Hub file (many dependents)
`$(unfault-logo) $(loading~spin)`	Server starting
`$(unfault-logo)` (yellow background)	Server stopped/error (click for menu)

Code Lenses: Function Context at a Glance

The most visible feature is code lenses. Above each function, Unfault shows what it knows:

# uf: used by 3 places · reached by POST /api/checkout · worth a look
def process_payment(user_id: str, amount: float):
    response = requests.post(PAYMENT_API, json={"user": user_id, "amount": amount})
    return response.json()

The code lens tells you:

used by 3 places: This function is called from 3 locations
reached by POST /api/checkout: It’s in the call chain of an HTTP route
worth a look: There’s something to consider (findings exist)

Click the code lens to open the Context sidebar with full details.

The Context Sidebar

The Context sidebar lives in the Explorer panel. It shows detailed information about the function under your cursor.

Unfault groups observations so you can quickly tell where an issue lives:

Heads up: findings about the current function body (this is what triggers worth a look in the code lens)
Upstream: issues in callers and entry paths into the function (things that can break you)
Downstream: issues in functions you call (things you rely on / can propagate)

┌─────────────────────────────────────────┐
│ UNFAULT: CONTEXT                    📌  │
├─────────────────────────────────────────┤
│ process_payment                         │
│                                         │
│ CALLERS                                 │
│ ├─ checkout_handler (routes/api.py)     │
│ ├─ retry_payment (routes/api.py)        │
│ └─ BackgroundTask (workers/payments.py) │
│                                         │
│ ROUTES                                  │
│ ├─ POST /api/checkout                   │
│ │   └─ 99.9% Availability SLO           │
│ └─ POST /api/retry-payment              │
│                                         │
│ HEADS UP                                │
│ ├─ ⚠ No timeout on HTTP call            │
│ └─ ⚠ No circuit breaker                 │
│                                         │
│ UPSTREAM                                │
│ └─ ⚠ Caller does not handle errors      │
│                                         │
│ DOWNSTREAM                              │
│ └─ ⚠ Callee has no retries              │
└─────────────────────────────────────────┘

Following Your Cursor

By default, the sidebar follows your cursor. As you move between functions, it updates to show the context for wherever you are.

Pinning

Click the pin icon (📌) to lock the sidebar on a specific function. This is useful when you want to keep context visible while editing elsewhere.

File Centrality

When you open a file, Unfault calculates how central it is to your codebase:

Hub files are imported by many other files. Changes here have wide impact.
Leaf files have few dependents. Safer to modify.

The status bar shows this with icons, and hovering reveals details:

┌─────────────────────────────────────┐
│ Unfault: Context                    │
│                                     │
│ File Importance                     │
│ - Imported by: 12 files             │
│ - Imports: 4 files                  │
│                                     │
│ Dependents                          │
│ - 18 files depend on this           │
│                                     │
│ ─────────────────────────────────── │
│ Click for menu                      │
└─────────────────────────────────────┘

Seeing Dependents

When you’re about to change a central file, you might want to know exactly what depends on it.

Open a file
Click the status bar icon
Select Show File Dependents (or run Unfault: Show Files That Depend on This File)

A picker appears listing all files that import this one:

┌─────────────────────────────────────────────────────────┐
│ 12 files depend on src/core/auth.py                     │
├─────────────────────────────────────────────────────────┤
│ users.py          src/api/routes/users.py    Direct     │
│ admin.py          src/api/routes/admin.py    Direct     │
│ payments.py       src/api/routes/payments.py Transitive │
│ ...                                                     │
└─────────────────────────────────────────────────────────┘

Select a file to open it.

Diagnostics (Optional)

By default, Unfault doesn’t show squiggly underlines. The philosophy is “calm mode” - context is available when you want it, but it doesn’t interrupt your flow.

If you prefer inline diagnostics:

Open Settings (Cmd+,)
Search for “unfault diagnostics”
Enable Unfault: Diagnostics Enabled
Set Unfault: Diagnostics Min Severity (default: high)

def fetch_data():
    # Yellow squiggle under requests.get
    response = requests.get(url)  # ⚠ HTTP call has no timeout
    return response.json()

When enabled, findings appear as squiggles with hover explanations.

Click the Unfault status bar item to access all commands:

┌─────────────────────────────────────────────────────────┐
│ Unfault - Select an action                              │
├─────────────────────────────────────────────────────────┤
│ $(unfault-logo) Open Context     Open context sidebar    │
│ $(home) Welcome & Setup          Onboarding + auth help  │
│ $(references) Show File Dependents  Show dependents      │
│ $(gear) Open Settings            Configure settings      │
│ $(output) Show Output            View LSP logs           │
│ $(refresh) Restart Server        Restart the LSP server  │
│ $(book) Documentation            Open unfault.dev/docs   │
└─────────────────────────────────────────────────────────┘

Names and icons may vary slightly based on your VS Code theme and version, but the items map directly to the Unfault commands listed in the Command Palette.

Configuration

Open Settings and search for “unfault” to see all options:

Setting	Description	Default
`unfault.executablePath`	Path to unfault CLI	`unfault`
`unfault.codeLens.enabled`	Show code lenses above functions	`true`
`unfault.codeLens.clickToOpen`	Click lens to open context sidebar	`true`
`unfault.diagnostics.enabled`	Show inline squiggles	`false`
`unfault.diagnostics.minSeverity`	Minimum severity to show	`high`
`unfault.trace.server`	LSP trace level	`off`
`unfault.verbose`	Enable verbose logging	`false`

Keyboard Shortcuts

Shortcut	Action
Click the Unfault status bar item	Open Unfault menu
Click a code lens	Open context sidebar
`Cmd+Shift+P` → “Unfault”	See all commands

Troubleshooting

”unfault: command not found”

The CLI isn’t in your PATH. Either:

Add the directory containing unfault to your PATH
Set unfault.executablePath in VS Code settings to the full path

The menu item opens https://unfault.dev/docs. For extension-specific docs, see:

Guide: /docs/guides/vscode/
Tutorial: /docs/tutorials/vscode-extension/

No code lenses appearing

Make sure you’re in a supported file (Python, Go, Rust, TypeScript, JavaScript)
Check that unfault.codeLens.enabled is true
Run Unfault: Restart Server from the command palette
Check the Output panel (Unfault: Show Output) for errors

Context sidebar is empty

Ensure you’ve run unfault login in the terminal
Check network connectivity to app.unfault.dev
The first analysis may take a moment as the graph builds

Extension is slow

The first time you open a file, Unfault builds a semantic graph. Subsequent interactions use the cached graph and should be fast.

What You’ve Learned

In this tutorial, you:

Installed the VS Code extension
Understood code lenses and what they show
Used the Context sidebar to explore function impact
Learned about file centrality and dependents
Optionally enabled inline diagnostics
Configured the extension to your preferences