GitHub - AlmogBaku/debug-skill

Let your coding agent debug like a human developer.
Set breakpoints, step through code, evaluate expressions — the way you actually debug.

If this saves you a debugging session, please star the repo — it helps others find it.

AI coding agents (Claude Code, Codex, Opencode, Cursor) are stuck with print statements and guesswork. debug-skill gives them what human developers have: a real debugger they can actually use. It ships two things:

A Claude Code skill — teaches Claude how to debug: when to set breakpoints, how to step through code, how to inspect state
The dap CLI — a stateless CLI wrapper around the Debug Adapter Protocol so any agent can drive a real debugger from Bash

Demo

The Skill

Install the skill, and Claude debugs your code the way you would — not with print statements.

The debugging-code skill gives Claude structured knowledge of the debugging workflow: setting breakpoints, stepping through execution, inspecting locals and the call stack, evaluating expressions mid-run. It uses the dap CLI as its tool.

Install for Claude Code

Via the plugin marketplace — no manual setup needed:

/plugin marketplace add AlmogBaku/debug-skill
/plugin install debugging-code@debug-skill-marketplace

Install for other agents

Via skills.sh — works with Cursor, GitHub Copilot, Windsurf, Cline, and 20+ more agents:

npx skills add AlmogBaku/debug-skill
# or: bunx skills add AlmogBaku/debug-skill

Or manually copy skills/debugging-code/ into your agent's skills.

The `dap` CLI

dap wraps the Debug Adapter Protocol behind simple, stateless CLI commands. A background daemon holds the session; the CLI sends one command and gets back the full context — no interactive terminal required.

Install

# One-liner (Linux & macOS)
bash <(curl -fsSL https://raw.githubusercontent.com/AlmogBaku/debug-skill/master/skills/debugging-code/scripts/install-dap.sh)

Other install methods

From Homebrew (for macOS):

brew install AlmogBaku/tap/dap

From sources:

# Go install
go install github.com/AlmogBaku/debug-skill/cmd/dap@latest

Or download a pre-built binary from the releases page.

Quick Start

dap debug app.py --break app.py:42   # start, stop at breakpoint
dap eval "len(items)"                # inspect a value
dap inspect data --depth 2           # expand nested objects
dap step                             # step over
dap continue                         # next breakpoint
dap continue --to app.py:50          # run to specific line
dap pause                            # interrupt if hanging
dap restart                          # re-run, preserving breakpoint changes
dap stop                             # end session

Execution commands (debug, continue, step) return full context automatically: current location, surrounding source, local variables, call stack, and program output. No follow-up calls needed.

Usage Examples

# Python
dap debug app.py --break app.py:42

# Go
dap debug main.go --break main.go:15

# Node.js / TypeScript
dap debug server.js --break server.js:10

# Rust / C / C++
dap debug hello.rs --break hello.rs:4

# Attach to a remote debugger (e.g. debugpy in a container)
dap debug --attach container:5678 --backend debugpy --break handler.py:20

# Attach to a running process by PID
dap debug --pid 12345 --backend debugpy

# Pass arguments to the program
dap debug app.py --break app.py:10 -- --config prod.yaml --verbose

Commands

Command	Description
`dap debug <script>`	Start debugging (local or `--attach host:port` or `--pid PID`)
`dap stop`	End session
`dap step [in\|out\|over]`	Step (default: over)
`dap continue`	Resume execution (`--to file:line` for temp breakpoint)
`dap context [--frame N]`	Re-fetch current state
`dap eval <expr> [--frame N]`	Evaluate expression in current frame
`dap inspect <var> [--depth N]`	Inspect variable (expand nested objects)
`dap output`	Drain buffered stdout/stderr since last stop
`dap pause`	Pause a running program
`dap restart`	Restart session, preserving breakpoint changes
`dap threads`	List all threads
`dap thread <id>`	Switch to a different thread
`dap break list\|add\|remove\|clear`	Manage breakpoints mid-session

Global flags: --json (machine-readable output), --session <name> (named sessions), --socket <path> (custom socket path), --context-lines <int> (lines of source context)

Supported Languages

Language	Backend	Auto-detected
Python	debugpy	yes
Go	dlv (Delve)	yes
Node.js/TypeScript	js-debug	yes
Rust / C / C++	lldb-dap	yes

Backend is inferred from the file extension. Override with --backend <name>.

How It Works

dap <cmd>  →  Unix socket  →  Daemon  →  DAP protocol  →  debugpy / dlv / js-debug / lldb-dap  →  your program

The daemon starts automatically on dap debug and shuts down on dap stop (or after 10 min idle). It's invisible — you never manage it directly.

Multi-Session

Multiple agents can debug independently with named sessions:

dap debug app.py  --session agent1 --break app.py:10
dap debug main.go --session agent2 --break main.go:8

dap stop --session agent1   # stops agent1 only

Each session has its own daemon and socket. Omit --session to use the default session.

Contributing

PRs and issues welcome. See claudedocs/ for architecture details and CLAUDE.md for code conventions.

Support the Project

If debug-skill saves you from a painful debugging session, consider starring the repo — it helps others find it and keeps the project going.

License

MIT