Skip to content

quickstart.mdx

Latest commit

 

History

History
379 lines (281 loc) · 9.58 KB

quickstart.mdx

File metadata and controls

379 lines (281 loc) · 9.58 KB
title Getting Started
description Set up Pointbreak and complete your first AI-assisted debugging session in 5 minutes

What You'll Install

Pointbreak needs two pieces to work:

  1. 🔧 IDE Extension - Connects your IDE to the debugger
  2. 🤖 MCP Server - Lets your AI control the debugger
**Good news:** If you use GitHub Copilot or Cursor, the MCP server installs automatically! You only need to install the extension.

Choose your installation path:

**GitHub Copilot or Cursor:** 
1 step - Just install the extension!
**Claude Code, Codex, Windsurf, Goose:** 
2 steps - Extension + CLI

Quick Setup: GitHub Copilot/Cursor

1. Open VS Code or Cursor 2. Go to Extensions (Cmd+Shift+X / Ctrl+Shift+X) 3. Search for "Pointbreak" 4. Click "Install" 
**That's it!** The MCP server auto-registers with GitHub Copilot and Cursor.
Install the debug adapter for your language: 
<Tabs>
  <Tab title="Python">
    Search for "Python" in Extensions and install the official Microsoft Python extension (includes debugpy).
  </Tab>

  <Tab title="JavaScript/TypeScript">
    Built into VS Code - no installation needed!
  </Tab>

  <Tab title="Rust">
    Search for "CodeLLDB" in Extensions and install it (by vadimcn).
  </Tab>

  <Tab title="Go">
    Search for "Go" in Extensions and install the official Go extension (includes Delve).
  </Tab>
</Tabs>
Open the Output panel (View → Output), select "Pointbreak" from dropdown. 
You should see: `Pointbreak debug bridge started successfully`

<Tip>
Check the status bar at the bottom of VS Code - a green Pointbreak indicator means you're ready!
</Tip>
**You're ready to debug!** 
[Skip to Your First Debugging Session](#your-first-debugging-session)

Full Setup: Claude Code/Other AIs

**Both pieces required!** These AI assistants need manual MCP configuration, so you must install the extension AND the CLI. 1. Open VS Code (or compatible editor) 2. Go to Extensions (Cmd+Shift+X / Ctrl+Shift+X) 3. Search for "Pointbreak" 4. Click "Install" 
**Direct link:** [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=pointbreak.pointbreak)
Install the debug adapter for your language: 
<Tabs>
  <Tab title="Python">
    Search for "Python" in Extensions and install the official Microsoft Python extension (includes debugpy).
  </Tab>

  <Tab title="JavaScript/TypeScript">
    Built into VS Code - no installation needed!
  </Tab>

  <Tab title="Rust">
    Search for "CodeLLDB" in Extensions and install it (by vadimcn).
  </Tab>

  <Tab title="Go">
    Search for "Go" in Extensions and install the official Go extension (includes Delve).
  </Tab>
</Tabs>
**macOS / Linux:** ```bash curl -fsSL https://withpointbreak.com/install.sh | sh ``` 
**Windows (PowerShell):**
```powershell
irm https://withpointbreak.com/install.ps1 | iex
```

**Verify it worked:**
```bash
pointbreak --version
# Should output: pointbreak X.X.X
```

<Note>
The script installs to `~/.local/bin` (Unix) or `%LOCALAPPDATA%\Pointbreak\bin` (Windows). Don't use `sudo`!
</Note>
Register 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
    ```

    [Detailed Claude Code Setup →](/ai-assistants#claude-code)
  </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 the binary:
    - **macOS/Linux**: `~/.local/bin/pointbreak`
    - **Windows**: `%LOCALAPPDATA%\Pointbreak\bin\pointbreak.exe`

    [Detailed Windsurf Setup →](/ai-assistants#windsurf)
  </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:
    - **macOS/Linux**: `~/.local/bin/pointbreak`
    - **Windows**: `%LOCALAPPDATA%\Pointbreak\bin\pointbreak.exe`

    [See all AI assistants →](/ai-assistants)
  </Tab>
</Tabs>
1. **Check extension** - Output panel should show: `Pointbreak debug bridge started successfully` 2. **Check CLI** - Run: `pointbreak --version` 3. **Check AI config** - List MCP servers (e.g., `claude mcp list`) 
If something's wrong, see [Troubleshooting](/troubleshooting).

Your First Debugging Session

Let's debug a simple program to verify everything works!

Create Example Code

Create `test.py`: ```python def calculate_average(numbers): total = sum(numbers) count = len(numbers) return total / count 
result = calculate_average([1, 2, 3, 4, 5])
print(f"Average: {result}")
```
Create `test.js`: ```javascript function calculateAverage(numbers) { const total = numbers.reduce((sum, n) => sum + n, 0); const count = numbers.length; return total / count; } 
const result = calculateAverage([1, 2, 3, 4, 5]);
console.log(`Average: ${result}`);
```
Create `test.rs`: ```rust fn calculate_average(numbers: &[i32]) -> f64 { let total: i32 = numbers.iter().sum(); let count = numbers.len() as f64; total as f64 / count } 
fn main() {
    let result = calculate_average(&[1, 2, 3, 4, 5]);
    println!("Average: {}", result);
}
```
Create `test.go`: ```go package main 
import "fmt"

func calculateAverage(numbers []int) float64 {
    total := 0
    for _, n := range numbers {
        total += n
    }
    return float64(total) / float64(len(numbers))
}

func main() {
    result := calculateAverage([]int{1, 2, 3, 4, 5})
    fmt.Printf("Average: %.2f\n", result)
}
```

Ask Your AI Assistant

Try this prompt:

"Set a breakpoint on line 3 and start debugging test.py.
Show me the value of 'numbers' when we hit the breakpoint."

(Adjust line number and filename for your language)

What Should Happen

  1. Breakpoint appears - Red dot on line 3 in VS Code
  2. Debug session starts - Debugger launches automatically
  3. Execution pauses - Code stops at line 3
  4. AI inspects variables - Shows you the value of numbers

Example AI Response

I've set a breakpoint at line 3 and started debugging.
The execution has paused at the breakpoint.

The value of 'numbers' is: [1, 2, 3, 4, 5]

Would you like me to step through the rest of the function?

Common First-Time Issues

"AI can't find Pointbreak"

VS Code/Cursor users: Restart your editor

Claude Code users:

"Breakpoint not hit"

  • Ensure debug adapter is installed for your language
  • Try running debugger manually (F5) first to verify it works
  • Check that file is saved

"No debug adapter available"

Install the debug adapter for your language (see Step 2 above).

Tips for Effective AI Debugging

  1. Be specific - "Set a breakpoint on line 42" > "debug this"
  2. Set breakpoints first - Ask AI to set breakpoints before starting debugger
  3. Ask for context - "Show me the stack trace" or "What are all the local variables?"
  4. Step through interactively - "Step into this function" or "Step over the next line"
  5. Use natural language - No need to memorize commands!

Example Prompts to Try

"Set a breakpoint where the error occurs and start debugging"

"Step through this loop and show me how the counter changes"

"What's the call stack when we hit this breakpoint?"

"Set a conditional breakpoint that only triggers when x > 10"

"Step into this function and inspect all local variables"

Next Steps

Now that you're up and running:

Ready to debug? Try asking your AI assistant to help you debug your code!