> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperprobe.co/llms.txt
> Use this file to discover all available pages before exploring further.

# VS Code Extension IDE Guide

> Install, connect, configure, and manage real-time probes directly inside your IDE.

The HyperProbe VS Code extension brings the entire production debugging workflow straight into your code editor. Insert snapshot points, inject logs, and track performance counters directly on your source code—without switching windows or opening dashboards.

***

## 🔌 1. Installation

You can install the HyperProbe extension using either the visual Extensions Marketplace or keyboard-only Quick Open (works in VS Code, VSCodium, and Gitpod via the Open VSX Registry):

<Tabs>
  <Tab title="Extensions Panel (UI)">
    1. Open VS Code and navigate to the Extensions panel (`Cmd+Shift+X` on macOS / `Ctrl+Shift+X` on Windows/Linux).
    2. Search for **HyperProbe** and click **Install**.
  </Tab>

  <Tab title="Quick Open (Keyboard-Only)">
    1. Launch VS Code Quick Open by pressing **`Cmd+P`** (macOS) or **`Ctrl+P`** (Windows/Linux).
    2. Paste the following command and press **Enter**:
       ```text theme={null}
       ext install hyperprobe.hyperprobe-extension
       ```
  </Tab>
</Tabs>

Once installed, a new **HyperProbe Debugger** icon will appear inside your side Activity Bar instantly without requiring an editor restart!

***

## ⚙️ 2. Connection & Configuration

The extension must know where your HyperProbe Server is hosted.

### Setting the Server URL

By default, the **`hyperprobe.serverUrl`** setting is configured to point to:

```text theme={null}
https://app.hyperprobe.co
```

This is correct for general cloud usage. If you are self-hosting or testing locally:

1. Open VS Code Settings (`Cmd+,` / `Ctrl+,`).
2. Search for `hyperprobe.serverUrl`.
3. Set your server URL, for example: `https://app.hyperprobe.co`.

```json .vscode/settings.json theme={null}
{
  "hyperprobe.serverUrl": "https://app.hyperprobe.co"
}
```

<Tip>
  **Pro-Tip:** Commit a workspace-level `.vscode/settings.json` file to your git repository. This automatically aligns the server URL for your entire engineering team when they clone the codebase!
</Tip>

***

## 🎯 3. Inserting and Managing Probes

Once configured, placing a probe on any line is as simple as a right-click.

<Steps>
  <Step title="Map your workspace with .hprc">
    The extension discovers active running services by reading a `.hprc` file placed at the root of your local repository. Create a `.hprc` file containing your Service UUID from the dashboard:

    ```json .hprc theme={null}
    {
      "serviceId": "<service-uuid-from-dashboard>"
    }
    ```
  </Step>

  <Step title="Select a Line & Insert">
    Right-click any executable statement in your editor and choose **Insert a Snapshot** (or Dynamic Log, Counter, etc.).
  </Step>

  <Step title="Configure Your Probe Options">
    The probe creation drawer will slide open with context-aware parameters:

    * **Watch Expressions:** Enter custom code expressions to evaluate live (e.g., `user.cart.total` or `isNewCustomer()`).
    * **Condition:** Filter execution paths. The probe will only capture data when the boolean expression evaluates to true (e.g., `req.headers['x-user-id'] === 'user_1029'`).
    * **Hit Limit:** Set how many times the probe fires before self-destructing in-process (snapshots default to `1` for safety, logs default to `100`).
  </Step>
</Steps>

***

## 🔍 4. Inspecting Captured Telemetry

Click any completed or active probe in your side panel to open the **Snapshot Inspector**:

```text theme={null}
┌────────────────────────────────────────────────────────┐
│ 🟢 HIT 1 OF 3 (Captured 2:14:10 PM)                   │
├────────────────────────────────────────────────────────┤
│ ├─ ▼ WATCH EXPRESSIONS                                 │
│ │    └─ user.cart.total: 104.99                        │
│ │                                                      │
│ ├─ ▼ LOCAL VARIABLES                                   │
│ │  ├─ req: { method: 'POST', path: '/checkout' }       │
│ │  ├─ session: { active: true, claims: [...] }         │
│ │  └─ address: "123 Main St, New York"                 │
│ │                                                      │
│ ├─ ▼ CALL STACK                                        │
│ │  ├─ 0: CheckoutController.ts:line 45                 │
│ │  ├─ 1: Router.ts:line 102                            │
│ │  └─ 2: Server.ts:line 12                             │
└────────────────────────────────────────────────────────┘
```

* **Interactive Call Stack:** Click on any stack frame in the Call Stack block to dynamically switch the Variables panel to inspect the exact heap state of that specific scope level!
* **Text Filters:** Type into the Variables panel search bar to instantly isolate deep keys on heavy payloads (like Express request headers).