docs/installation.mdx at main · withpointbreak/docs

title	Installation
description	Complete installation instructions for all platforms and methods

What You're Installing

Pointbreak has two components that work together:

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

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

Choose Your Path

**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)

**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)

## Easy Setup: VS Code/Cursor **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)

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>

**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)

**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.

## Full Setup: Claude Code/Other AI Assistants **Both pieces required!** Claude Code, Codex, Windsurf, and Goose cannot auto-register MCP servers. You must install both the extension AND the CLI. **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
      code --install-extension path/to/pointbreak-*.vsix
      ```
    </Tab>

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

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

    <Tab title="Windsurf">
      ```bash
      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>

**macOS / Linux:** ```bash curl -fsSL https://withpointbreak.com/install.sh | sh ```

**Windows (PowerShell):**
```powershell
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
pointbreak --version
# Should output: pointbreak X.X.X
```

Now that both pieces are installed, connect them by registering the MCP server with your AI assistant:

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

    Verify with:
    ```bash
    claude mcp list
    # Should show: pointbreak
    ```

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

  <Tab title="Codex">
    ```bash
    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
    {
      "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>

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).

**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.

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:

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:

VS Code/Cursor users: Restart your editor
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:

uname -m
# arm64 = Apple Silicon
# x86_64 = Intel

Linux:

uname -m
# x86_64 = x64
# aarch64 = ARM64

Windows:

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:

# 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:

Go to Extensions
Find Pointbreak
Click the gear icon → Uninstall
Restart VS Code

Via Command Line:

code --uninstall-extension pointbreak.pointbreak

Remove CLI (if installed)

macOS / Linux:

rm ~/.local/bin/pointbreak

Windows:

Remove-Item "$env:LOCALAPPDATA\Pointbreak" -Recurse

Also remove MCP server registration from your AI assistant:

claude mcp remove pointbreak

Next Steps

After installation:

Install a debug adapter for your language (if not already installed)
Try your first debugging session - See Getting Started
Learn effective debugging patterns - See Usage Guide

Questions?

Installation issues: GitHub Issues
General questions: GitHub Discussions
Website: withpointbreak.com

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

What You're Installing

Choose Your Path

System Requirements

Required

Optional

Platform-Specific Notes

Troubleshooting Installation

"Extension won't install"

"pointbreak: command not found"

"AI can't find Pointbreak"

Wrong Architecture Downloaded

Updating

Extension Updates

CLI Updates

Uninstalling

Remove Extension

Remove CLI (if installed)

Next Steps

Questions?

FilesExpand file tree

installation.mdx

Latest commit

History

installation.mdx

File metadata and controls

What You're Installing

Choose Your Path

System Requirements

Required

Optional

Platform-Specific Notes

Troubleshooting Installation

"Extension won't install"

"pointbreak: command not found"

"AI can't find Pointbreak"

Wrong Architecture Downloaded

Updating

Extension Updates

CLI Updates

Uninstalling

Remove Extension

Remove CLI (if installed)

Next Steps

Questions?