Breakpoints & Stepping

Setting Breakpoints

CLI

# Simple line breakpoint
krometrail break order.py:147

# Multiple lines in one file
krometrail break order.py:147,150,155

# Conditional breakpoint — only fires when expression is true
krometrail break "order.py:147 when discount < 0"

# Hit count — fires after N hits
krometrail break "order.py:147 hit >=100"

# Logpoint — logs a message instead of stopping
krometrail break "order.py:147 log 'discount={discount}, total={total}'"

# Exception breakpoints
krometrail break --exceptions uncaught
krometrail break --exceptions raised    # Python: all raised exceptions

MCP: debug_set_breakpoints

// Simple
{
	"session_id": "...",
	"file": "order.py",
	"breakpoints": [{ "line": 147 }]
}

// Conditional
{
	"session_id": "...",
	"file": "order.py",
	"breakpoints": [{ "line": 147, "condition": "discount < 0" }]
}

// Hit count
{
	"session_id": "...",
	"file": "order.py",
	"breakpoints": [{ "line": 147, "hit_condition": ">=100" }]
}

// Logpoint
{
	"session_id": "...",
	"file": "order.py",
	"breakpoints": [{ "line": 147, "log_message": "discount={discount}, total={total}" }]
}

DAP semantics

debug_set_breakpoints replaces all existing breakpoints in the specified file. To keep existing breakpoints, include them in the call alongside new ones.

Setting Breakpoints at Launch

Pass initial breakpoints with debug_launch to avoid a separate call:

{
	"command": "python -m pytest tests/test_order.py -x",
	"breakpoints": [
		{ "file": "order.py", "line": 147 },
		{ "file": "discount.py", "line": 23, "condition": "tier == 'gold'" }
	]
}

Listing Breakpoints

# CLI
krometrail breakpoints

# MCP: debug_list_breakpoints
{ "session_id": "..." }

Returns all active breakpoints with current hit counts.

Removing Breakpoints

# Remove all breakpoints in a file
krometrail break --clear order.py

# To remove specific breakpoints, set the file with only the ones you want to keep
krometrail break order.py:150,155
# (line 147 is now removed)

Stepping

CLI

# Step over — execute current line, stay in current function
krometrail step over

# Step into — enter the function being called
krometrail step into

# Step out — run to end of current function, return to caller
krometrail step out

# Step multiple times
krometrail step over --count 5

MCP: debug_step

{ "session_id": "...", "direction": "over" }
{ "session_id": "...", "direction": "into" }
{ "session_id": "...", "direction": "out" }
{ "session_id": "...", "direction": "over", "count": 5 }

Every step returns the viewport snapshot at the new location.

Run to Line

Run to a specific line without setting a permanent breakpoint:

CLI

krometrail run-to order.py:155

MCP: debug_run_to

{ "session_id": "...", "file": "order.py", "line": 155 }

Continue

Resume execution until the next breakpoint or program exit:

CLI

krometrail continue
krometrail continue --timeout 10000

MCP: debug_continue

{ "session_id": "..." }
{ "session_id": "...", "timeout_ms": 10000 }

Exception Breakpoints

CLI

krometrail break --exceptions uncaught    # only uncaught exceptions
krometrail break --exceptions raised      # all raised exceptions (Python)
krometrail break --exceptions all         # all exceptions (JS)

MCP: debug_set_exception_breakpoints

{ "session_id": "...", "filters": ["uncaught"] }
{ "session_id": "...", "filters": ["raised"] }

Tips

• Prefer conditional breakpoints over stepping through loops — when i == 99 is far more efficient than stepping 99 times
• Logpoints as non-intrusive probes — logpoints don't stop execution, making them useful for monitoring without disrupting the control flow
• Re-launch with earlier breakpoints — if you step past the bug site, stop the session and re-launch with an earlier breakpoint rather than trying to navigate backwards