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

# Debug Sessions

> Session lifecycle, file loading, breakpoints, attach flows, and execution control tools.

Most debugger operations are scoped by `session_id`. Create or pick a session first, then load a binary or attach to a running process.

<Info>
  Except for `create_debug_session` and `list_debug_sessions`, the debugger tool family expects an existing session. Use explicit session names for every serious workflow.
</Info>

## Session lifecycle tools

| Tool                   | Use it for                                             | Notes                             |
| ---------------------- | ------------------------------------------------------ | --------------------------------- |
| `create_debug_session` | create or return a session by id                       | safe to call repeatedly           |
| `list_debug_sessions`  | inspect active sessions                                | returns metadata for all sessions |
| `close_debug_session`  | close a session and stop its `pwncli` driver           | releases GDB resources            |
| `get_session_info`     | inspect cached state without issuing a new GDB command | includes `runtime_dir`            |

```json theme={null}
{"tool":"create_debug_session","arguments":{"session_id":"chal-a"}}
{"tool":"list_debug_sessions","arguments":{}}
{"tool":"get_session_info","arguments":{"session_id":"chal-a"}}
```

## Load, attach, and raw command tools

| Tool             | Use it for                                          | Notes                                        |
| ---------------- | --------------------------------------------------- | -------------------------------------------- |
| `set_file`       | load an executable into GDB                         | resolve paths under `/workspace`             |
| `attach`         | attach to an already running PID                    | returns attach result plus context snapshots |
| `set_breakpoint` | insert a symbol, address, or `file:line` breakpoint | optional condition supported                 |
| `execute`        | run raw GDB or pwndbg commands                      | best for low-level escape hatches            |

```json theme={null}
{"tool":"set_file","arguments":{"binary_path":"/workspace/chal","session_id":"chal-a"}}
{"tool":"set_breakpoint","arguments":{"location":"main","condition":"$rax == 0","session_id":"chal-a"}}
{"tool":"execute","arguments":{"command":"info registers","session_id":"chal-a"}}
```

### Common debugger parameters

<ParamField path="session_id" type="string" required>
  Debug session to operate on. Required for nearly every debugger tool on this page.
</ParamField>

<ParamField path="binary_path" type="string">
  Target binary path. Use a path that resolves under `/workspace`.
</ParamField>

<ParamField path="location" type="string">
  Breakpoint or jump target, such as a symbol, `file:line`, or address expression.
</ParamField>

<ParamField path="command" type="string">
  Raw GDB or pwndbg command for `execute`, or a stepping verb such as `c`, `n`, `s`, `ni`, or `si` for `step_control`.
</ParamField>

<ParamField path="args" type="string">
  Argument string passed to the inferior when using `run`.
</ParamField>

<ParamField path="pid" type="number">
  Target process id for `attach`.
</ParamField>

## Execution control tools

| Tool                   | Use it for                                            | Notes                                    |
| ---------------------- | ----------------------------------------------------- | ---------------------------------------- |
| `run`                  | start the loaded inferior                             | supports `args` and `start`              |
| `step_control`         | continue or step execution                            | supports `c`, `n`, `s`, `ni`, `si`       |
| `gdb_poll`             | drain pending async GDB notifications                 | useful after async activity              |
| `gdb_interrupt`        | interrupt a running inferior and wait for stop events | useful when you need control back        |
| `finish`               | run until the current function returns                | wrapper around MI `-exec-finish`         |
| `jump`                 | resume execution at a location                        | supports symbol, `file:line`, or address |
| `return_from_function` | force the current function to return                  | wrapper around MI `-exec-return`         |
| `until`                | run until a location or next source line              | optional `locspec`                       |

```json theme={null}
{"tool":"run","arguments":{"args":"--demo","start":true,"session_id":"chal-a"}}
{"tool":"step_control","arguments":{"command":"ni","session_id":"chal-a"}}
{"tool":"gdb_interrupt","arguments":{"timeout":1.0,"session_id":"chal-a"}}
{"tool":"until","arguments":{"locspec":"main","session_id":"chal-a"}}
```

## Typical flow

<Steps>
  <Step title="Create the session">
    ```json theme={null}
    {"tool":"create_debug_session","arguments":{"session_id":"chal-a"}}
    ```
  </Step>

  <Step title="Load the binary and stop at main">
    ```json theme={null}
    {"tool":"set_file","arguments":{"binary_path":"/workspace/chal","session_id":"chal-a"}}
    {"tool":"set_breakpoint","arguments":{"location":"main","session_id":"chal-a"}}
    {"tool":"run","arguments":{"session_id":"chal-a"}}
    ```
  </Step>

  <Step title="Inspect and continue">
    ```json theme={null}
    {"tool":"execute","arguments":{"command":"info registers","session_id":"chal-a"}}
    {"tool":"step_control","arguments":{"command":"n","session_id":"chal-a"}}
    ```
  </Step>
</Steps>

## Common edge cases

<AccordionGroup>
  <Accordion title="I got 'session_id is required' or 'session not found'">
    Create the session first with `create_debug_session`, then pass the same `session_id` on all later calls.
  </Accordion>

  <Accordion title="I got 'No binary selected' or 'Use set_file first'">
    Load a file with `set_file` before calling `run`, or pass `binary_path` where the tool supports it.
  </Accordion>

  <Accordion title="My attach flow returns more than one thing">
    The MCP `attach` tool returns the attach result plus a context snapshot list. If you want a single wrapper object instead, use the attach sidecar API described in [Attach API](/tool-reference/attach-api).
  </Accordion>
</AccordionGroup>

## Common debugger response fields

<ResponseField name="success" type="boolean" required>
  Whether the tool call succeeded.
</ResponseField>

<ResponseField name="session_id" type="string">
  Session that the tool actually operated on.
</ResponseField>

<ResponseField name="state" type="string">
  Current debugger or inferior state after the operation, when provided by the backend.
</ResponseField>

<ResponseField name="binary_path" type="string">
  Resolved binary path after `set_file` or other file-sensitive operations.
</ResponseField>

<ResponseField name="runtime_dir" type="string">
  Session-specific runtime directory returned by `get_session_info`.
</ResponseField>

<ResponseField name="error" type="string">
  Short actionable error message when the call fails.
</ResponseField>

<ResponseField name="type" type="string">
  Exception type returned by the shared error wrapper on failures.
</ResponseField>