Installation

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

✅ Easy Setup

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

📦 Full Setup

Claude Code, Codex, Windsurf, or Goose users:Install extension + CLI (2 steps)Manual MCP server configuration required.Go to Full Setup

Easy Setup: VS Code/Cursor

Install Extension

Via Marketplace (Recommended):

Open VS Code or Cursor
Go to Extensions (Cmd+Shift+X / Ctrl+Shift+X)
Search for “Pointbreak”
Look for publisher: pointbreak
Click “Install”

Direct link: VS Code Marketplace | Open VSX

Verify Installation

Open the Output panel: View → Output
Select “Pointbreak” from the dropdown
You should see: Pointbreak debug bridge started successfully

Look for the Pointbreak status indicator in your VS Code status bar (bottom of window). A green status means you’re ready to go!

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

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.

Install IDE Extension

Via Marketplace (Recommended):

Open VS Code (or compatible editor)
Go to Extensions (Cmd+Shift+X / Ctrl+Shift+X)
Search for “Pointbreak”
Look for publisher: pointbreak
Click “Install”

Direct link: VS Code Marketplace | Open VSX

Alternative: Manual VSIX Installation

Download the platform-specific VSIX:

Platform	Download Link
macOS (Apple Silicon)	pointbreak-darwin-arm64.vsix
macOS (Intel)	pointbreak-darwin-x64.vsix
Linux x64	pointbreak-linux-x64.vsix
Linux ARM64	pointbreak-linux-arm64.vsix
Windows x64	pointbreak-win32-x64.vsix
Windows ARM64	pointbreak-win32-arm64.vsix

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

Then install via command line:

VS Code
VS Code Insiders
Cursor
Windsurf

code --install-extension path/to/pointbreak-*.vsix

code-insiders --install-extension path/to/pointbreak-*.vsix

cursor --install-extension path/to/pointbreak-*.vsix

surf --install-extension path/to/pointbreak-*.vsix

Or install via VS Code UI:

Open your editor
Go to Extensions (Cmd+Shift+X / Ctrl+Shift+X)
Click the ”…” menu (top right)
Select “Install from VSIX…”
Choose the downloaded file

Install MCP Server (CLI)

macOS / Linux:

curl -fsSL https://withpointbreak.com/install.sh | sh

Windows (PowerShell):

irm https://withpointbreak.com/install.ps1 | iex

Do NOT use sudo! The script installs to your user directory (~/.local/bin) which doesn’t require elevated permissions.

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:

pointbreak --version
# Should output: pointbreak X.X.X

Configure Your AI Assistant

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

Claude Code
Codex
Windsurf
Goose
Other

claude mcp add --transport stdio pointbreak -- pointbreak mcp serve

Verify with:

claude mcp list
# Should show: pointbreak

See Claude Code Setup Guide for more details.

codex mcp add pointbreak -- pointbreak mcp serve

Verify with the /mcp command in Codex.

Configure Windsurf’s MCP settings to point to:

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

See Windsurf Setup Guide for details.

Add to your Goose MCP configuration:

{
  "mcpServers": {
    "pointbreak": {
      "command": "pointbreak",
      "args": ["mcp", "serve"]
    }
  }
}

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 for more options.

Verify Everything Works

Check IDE extension - Open Output panel (View → Output), select “Pointbreak”, should see: Pointbreak debug bridge started successfully
Check CLI - Run: pointbreak --version
Test with AI - Ask your AI assistant: "Set a breakpoint on line 10 and start debugging"

If something isn’t working, see 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

Getting Started

Guides

About

Legal

What You’re Installing

Choose Your Path

✅ Easy Setup

📦 Full Setup

Easy Setup: VS Code/Cursor

Full Setup: Claude Code/Other AI Assistants

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?

Getting Started

Guides

About

Legal

​What You’re Installing

​Choose Your Path

✅ Easy Setup

📦 Full Setup

​Easy Setup: VS Code/Cursor

​Full Setup: Claude Code/Other AI Assistants

​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?

What You’re Installing

Choose Your Path

Easy Setup: VS Code/Cursor

Full Setup: Claude Code/Other AI Assistants

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?