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

# Installation

> Complete installation instructions for all platforms and methods

## What You're Installing

Pointbreak has **two components** that work together:

1. **🔧 IDE Extension** - Connects your editor to the debugger (always required)
2. **🤖 MCP Server** - Lets your AI assistant control the debugger

<Tip>
  **Good news:** Depending on which AI assistant you use, the MCP server might install automatically!
</Tip>

## Choose Your Path

<CardGroup cols={2}>
  <Card title="✅ Easy Setup" icon="rocket" color="#10b981">
    **VS Code or Cursor users:**

    Just install the extension—you're done!

    MCP server auto-registers with GitHub Copilot and Cursor.

    [Go to Easy Setup](#easy-setup-vs-code-cursor)
  </Card>

  <Card title="📦 Full Setup" icon="wrench" color="#f59e0b">
    **Claude Code, Codex, Windsurf, or Goose users:**

    Install extension + CLI (2 steps)

    Manual MCP server configuration required.

    [Go to Full Setup](#full-setup-claude-code-other-ai-assistants)
  </Card>
</CardGroup>

***

<div id="easy-setup-vs-code-cursor" />

## Easy Setup: VS Code/Cursor

<Steps>
  <Step title="Install Extension">
    **Via Marketplace (Recommended):**

    1. Open VS Code or Cursor
    2. Go to Extensions (Cmd+Shift+X / Ctrl+Shift+X)
    3. Search for "Pointbreak"
    4. Look for publisher: `pointbreak`
    5. Click "Install"

    **Direct link:** [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=pointbreak.pointbreak) | [Open VSX](https://open-vsx.org/extension/pointbreak/pointbreak)
  </Step>

  <Step title="Verify Installation">
    1. Open the Output panel: **View → Output**
    2. Select **"Pointbreak"** from the dropdown
    3. You should see: `Pointbreak debug bridge started successfully`

    <Tip>
      Look for the Pointbreak status indicator in your VS Code status bar (bottom of window). A green status means you're ready to go!
    </Tip>
  </Step>

  <Step title="Start Debugging">
    **You're all set!** The MCP server is automatically registered.

    Try asking your AI assistant:

    ```
    "Set a breakpoint on line 10 and start debugging"
    ```

    Next: [Getting Started Guide](/quickstart)
  </Step>
</Steps>

<Note>
  **Why is this easier?** VS Code and Cursor have an extensions API that allows Pointbreak to auto-register its MCP server. The MCP server binary is included in the extension VSIX package, so there's nothing else to install.
</Note>

***

<div id="full-setup-claude-code-other-ai-assistants" />

## Full Setup: Claude Code/Other AI Assistants

<Warning>
  **Both pieces required!** Claude Code, Codex, Windsurf, and Goose cannot auto-register MCP servers. You must install both the extension AND the CLI.
</Warning>

<Steps>
  <Step title="Install IDE Extension">
    **Via Marketplace (Recommended):**

    1. Open VS Code (or compatible editor)
    2. Go to Extensions (Cmd+Shift+X / Ctrl+Shift+X)
    3. Search for "Pointbreak"
    4. Look for publisher: `pointbreak`
    5. Click "Install"

    **Direct link:** [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=pointbreak.pointbreak) | [Open VSX](https://open-vsx.org/extension/pointbreak/pointbreak)

    <Accordion title="Alternative: Manual VSIX Installation">
      Download the platform-specific VSIX:

      | Platform              | Download Link                                                                                                  |
      | --------------------- | -------------------------------------------------------------------------------------------------------------- |
      | macOS (Apple Silicon) | [pointbreak-darwin-arm64.vsix](https://download.withpointbreak.com/vscode/latest/pointbreak-darwin-arm64.vsix) |
      | macOS (Intel)         | [pointbreak-darwin-x64.vsix](https://download.withpointbreak.com/vscode/latest/pointbreak-darwin-x64.vsix)     |
      | Linux x64             | [pointbreak-linux-x64.vsix](https://download.withpointbreak.com/vscode/latest/pointbreak-linux-x64.vsix)       |
      | Linux ARM64           | [pointbreak-linux-arm64.vsix](https://download.withpointbreak.com/vscode/latest/pointbreak-linux-arm64.vsix)   |
      | Windows x64           | [pointbreak-win32-x64.vsix](https://download.withpointbreak.com/vscode/latest/pointbreak-win32-x64.vsix)       |
      | Windows ARM64         | [pointbreak-win32-arm64.vsix](https://download.withpointbreak.com/vscode/latest/pointbreak-win32-arm64.vsix)   |

      <Note>
        Downloads will include the version number in the filename (e.g., `pointbreak-darwin-arm64-0.2.0.vsix`)
      </Note>

      Then install via command line:

      <Tabs>
        <Tab title="VS Code">
          ```bash theme={null}
          code --install-extension path/to/pointbreak-*.vsix
          ```
        </Tab>

        <Tab title="VS Code Insiders">
          ```bash theme={null}
          code-insiders --install-extension path/to/pointbreak-*.vsix
          ```
        </Tab>

        <Tab title="Cursor">
          ```bash theme={null}
          cursor --install-extension path/to/pointbreak-*.vsix
          ```
        </Tab>

        <Tab title="Windsurf">
          ```bash theme={null}
          surf --install-extension path/to/pointbreak-*.vsix
          ```
        </Tab>
      </Tabs>

      Or install via VS Code UI:

      1. Open your editor
      2. Go to Extensions (Cmd+Shift+X / Ctrl+Shift+X)
      3. Click the "..." menu (top right)
      4. Select "Install from VSIX..."
      5. Choose the downloaded file
    </Accordion>
  </Step>

  <Step title="Install MCP Server (CLI)">
    **macOS / Linux:**

    ```bash theme={null}
    curl -fsSL https://withpointbreak.com/install.sh | sh
    ```

    **Windows (PowerShell):**

    ```powershell theme={null}
    irm https://withpointbreak.com/install.ps1 | iex
    ```

    <Warning>
      **Do NOT use `sudo`!** The script installs to your user directory (`~/.local/bin`) which doesn't require elevated permissions.
    </Warning>

    The install script will:

    * Detect your platform and architecture
    * Download the appropriate binary from GitHub Releases
    * Verify with SHA256 checksums
    * Install to `~/.local/bin/pointbreak` (Unix) or `%LOCALAPPDATA%\Pointbreak\bin\` (Windows)
    * Check your PATH configuration

    **Verify CLI installation:**

    ```bash theme={null}
    pointbreak --version
    # Should output: pointbreak X.X.X
    ```
  </Step>

  <Step title="Configure Your AI Assistant">
    Now that both pieces are installed, connect them by registering the MCP server with your AI assistant:

    <Tabs>
      <Tab title="Claude Code">
        ```bash theme={null}
        claude mcp add --transport stdio pointbreak -- pointbreak mcp serve
        ```

        Verify with:

        ```bash theme={null}
        claude mcp list
        # Should show: pointbreak
        ```

        See [Claude Code Setup Guide](/ai-assistants#claude-code) for more details.
      </Tab>

      <Tab title="Codex">
        ```bash theme={null}
        codex mcp add pointbreak -- pointbreak mcp serve
        ```

        Verify with the `/mcp` command in Codex.
      </Tab>

      <Tab title="Windsurf">
        Configure Windsurf's MCP settings to point to:

        * **macOS/Linux**: `~/.local/bin/pointbreak`
        * **Windows**: `%LOCALAPPDATA%\Pointbreak\bin\pointbreak.exe`

        See [Windsurf Setup Guide](/ai-assistants#windsurf) for details.
      </Tab>

      <Tab title="Goose">
        Add to your Goose MCP configuration:

        ```json theme={null}
        {
          "mcpServers": {
            "pointbreak": {
              "command": "pointbreak",
              "args": ["mcp", "serve"]
            }
          }
        }
        ```
      </Tab>

      <Tab title="Other">
        Configure your MCP client to use the `pointbreak` binary.

        Binary location:

        * **macOS/Linux**: `~/.local/bin/pointbreak`
        * **Windows**: `%LOCALAPPDATA%\Pointbreak\bin\pointbreak.exe`

        See [AI Assistants Guide](/ai-assistants) for more options.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Verify Everything Works">
    1. **Check IDE extension** - Open Output panel (View → Output), select "Pointbreak", should see: `Pointbreak debug bridge started successfully`

    2. **Check CLI** - Run: `pointbreak --version`

    3. **Test with AI** - Ask your AI assistant: `"Set a breakpoint on line 10 and start debugging"`

    If something isn't working, see [Troubleshooting](/troubleshooting).
  </Step>
</Steps>

<Note>
  **Why the extra step?** These AI assistants don't have an MCP installation API, so they can't auto-register the MCP server that's bundled in the extension. You need to install the standalone CLI and manually register it with your AI assistant.
</Note>

***

## System Requirements

### Required

* **Operating Systems**: macOS 10.15+, Windows 10+, or Linux (recent distributions)
* **Editor**: VS Code 1.74.0+ (or compatible: Cursor, Windsurf, VS Codium)
* **Debug Adapter**: Language-specific debugger for your project
  * Python: debugpy (via Python extension)
  * JavaScript/TypeScript: Node Debug (built into VS Code)
  * Rust/C/C++: CodeLLDB
  * Go: Delve (via Go extension)
* **Network**: Internet connection for initial download

### Optional

* **AI Assistant**: MCP-compatible client or built-in (GitHub Copilot, Cursor)
* **Package Manager**: Homebrew (macOS/Linux) or npm for alternative installation methods
* **Node.js**: 18+ (only required for npm installation)

### Platform-Specific Notes

* **macOS**: Both Intel (x64) and Apple Silicon (ARM64) are supported
* **Windows**: Use WSL, PowerShell, or native installation. WSL recommended for best experience.
* **Linux**: Debian/Ubuntu (glibc) and Alpine (musl) distributions supported

***

## Troubleshooting Installation

### "Extension won't install"

**Problem:** "Extension is not compatible with this version of VS Code"

**Solution:** Update VS Code to version 1.74.0 or later.

### "pointbreak: command not found"

**Problem:** CLI installed but not in PATH

**Solution:**

**macOS / Linux** - Add to `~/.bashrc`, `~/.zshrc`, or `~/.profile`:

```bash theme={null}
export PATH="$HOME/.local/bin:$PATH"
```

Then reload: `source ~/.zshrc`

**Windows** - The install script should add to PATH automatically. If not, manually add:
`%LOCALAPPDATA%\Pointbreak\bin` to your System PATH.

### "AI can't find Pointbreak"

**Problem:** AI assistant doesn't see the MCP server

**Solutions:**

1. **VS Code/Cursor users:** Restart your editor
2. **Claude Code users:**
   * Verify CLI: `pointbreak --version`
   * Check MCP config: `claude mcp list`
   * Try removing and re-adding: `claude mcp remove pointbreak && claude mcp add --transport stdio pointbreak -- pointbreak mcp serve`

### Wrong Architecture Downloaded

Check your architecture:

**macOS:**

```bash theme={null}
uname -m
# arm64 = Apple Silicon
# x86_64 = Intel
```

**Linux:**

```bash theme={null}
uname -m
# x86_64 = x64
# aarch64 = ARM64
```

**Windows:**

```powershell theme={null}
echo $env:PROCESSOR_ARCHITECTURE
# AMD64 = x64
# ARM64 = ARM64
```

Download the matching VSIX or let the install script auto-detect.

***

## Updating

### Extension Updates

**Marketplace version:** Updates happen automatically if you have auto-update enabled in VS Code settings.

**Manual VSIX:** Download the latest VSIX and install over the old version.

### CLI Updates

Re-run the install script:

```bash theme={null}
# macOS / Linux
curl -fsSL https://withpointbreak.com/install.sh | sh

# Windows
irm https://withpointbreak.com/install.ps1 | iex
```

***

## Uninstalling

### Remove Extension

**Via VS Code UI:**

1. Go to Extensions
2. Find Pointbreak
3. Click the gear icon → Uninstall
4. Restart VS Code

**Via Command Line:**

```bash theme={null}
code --uninstall-extension pointbreak.pointbreak
```

### Remove CLI (if installed)

**macOS / Linux:**

```bash theme={null}
rm ~/.local/bin/pointbreak
```

**Windows:**

```powershell theme={null}
Remove-Item "$env:LOCALAPPDATA\Pointbreak" -Recurse
```

Also remove MCP server registration from your AI assistant:

```bash theme={null}
claude mcp remove pointbreak
```

***

## Next Steps

After installation:

1. **Install a debug adapter** for your language (if not already installed)
2. **Try your first debugging session** - See [Getting Started](/quickstart)
3. **Learn effective debugging patterns** - See [Usage Guide](/usage)

## Questions?

* **Installation issues:** [GitHub Issues](https://github.com/withpointbreak/pointbreak/issues)
* **General questions:** [GitHub Discussions](https://github.com/withpointbreak/pointbreak/discussions)
* **Website:** [withpointbreak.com](https://withpointbreak.com)