convez.ai
Skill
YuMinHui825

omnibreak-skill

YuMinHui825/omnibreak-skill

Ver no GitHub
BomPluginScore · de 0 a 100

Give Claude a debugger. Deploy, break, inspect, crash — all from CLI.

Instalação

$npx convez-ai YuMinHui825/omnibreak-skill

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
12
Forks
0
Acompanhando
1
Saúde
42%
Último commit
há 2 semanas
Versão
0.9.0
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

OmniBreak Skill

:cn: 中文文档

CLI tool and Claude Code Skill for remote Linux debugging via GDB/gdbserver.
Automate bug investigation — deploy, attach, breakpoints, crash capture.

What is OmniBreak Skill?

A CLI wrapper around GDB/gdbserver that returns structured JSON output. Designed for:

  • Claude Code integration — Claude can deploy, debug, and fix bugs autonomously
  • CI/CD pipelines — capture crash backtraces in automated tests
  • Scripting — shell scripts that need debugger access

Works with the same GDB/MI engine as OmniBreak VSCode Extension.

Architecture

omnibreak daemon &          # Background daemon holds GDB connection (TCP 127.0.0.1:49200)
omnibreak launch ...        # All commands talk to daemon via TCP
omnibreak break ...
omnibreak continue ...      # Returns full status: threads, frames, variables
omnibreak status ...        # Returns JSON: threads, frames, variables
omnibreak stop

Prerequisites

Your Machine

  • Node.js 20+
  • SSH access to remote Linux target

Target Machine

sudo apt install -y gdbserver gdb-multiarch

Install

Standalone CLI

git clone https://github.com/YuMinHui825/omnibreak-skill.git
cd omnibreak-skill
npm install --production && npm link

Pre-compiled JavaScript is included — no TypeScript compilation needed.
Dev setup (only for contributors who modify TypeScript): npm install && npm run compile.

Running Tests

# Unit tests (pure logic, no remote VM needed)
npm run test:unit

# Integration tests (requires remote target + running daemon)
nohup node out/daemon.js > /dev/null 2>&1 &
npm run test:integration      # daemon auto-managed

# All tests
npm test

Integration tests target ubuntu@192.168.64.2:1234 by default.
Override in test/setup.ts.

AI Agent Integration

Easiest way — just paste this to your agent and let it install itself:

Install OmniBreak from https://github.com/YuMinHui825/omnibreak-skill and set it up

The agent will read the repo, run npm install --production && npm link, and configure the skill automatically.

Claude Code

mkdir -p ~/.claude/skills/omnibreak
cp SKILL.md ~/.claude/skills/omnibreak/SKILL.md

Restart Claude Code after first install. Or use /skill add in Claude Code and point to the repo URL.

Codex / Cursor / Other Agents

git clone https://github.com/YuMinHui825/omnibreak-skill.git
cd omnibreak-skill && npm install --production && npm link

Then tell the agent: "Use the omnibreak CLI for remote Linux debugging. Commands: daemon, launch, break, continue, status, stop, trace, coredump, stats, leaks, logs, deploy, watch. All return JSON."

After installation, the agent can autonomously complete the full debug cycle — no manual commands needed:

  1. Asks for missing info — target IP, SSH password, binary path, source location, build command
  2. Compiles + deploys — builds with -g debug symbols, SCPs to target
  3. Breakpoints + watchpoints — sets breakpoints (file:line, conditional) and watchpoints (read/write/access)
  4. Auto state on continue — continue/next/step automatically return threads, frames, and variables
  5. Auto crash analysis — captures full 500-frame backtrace with exact file:line
  6. Memory leak detection — heap tracking with risk escalation, plus Perfetto heapprofd native profiling
  7. Performance monitoring — real-time CPU%, RSS, VSZ, thread count, remote log tailing
  8. System trace capture — Perfetto with CPU sampling (flame graphs), GPU auto-detection, SQL auto-summary
  9. Fixes code — analyzes root cause, edits source, rebuilds, redeploys, re-verifies
  10. Generates diagnostic reports — summarizes problem, fix, and verification results

Quick Start

# 1. Start daemon (once per session)
omnibreak daemon &

# 2. Launch binary on remote target
omnibreak launch --target 192.168.1.100 --binary /app/myapp --user root

# 3. Set breakpoint and run
omnibreak break --file main.c --line 42
omnibreak continue
# → {"ok":true,"status":"stopped","file":"main.c","line":42,"vars":[...]}

# 4. Inspect state
omnibreak status
# → threads, frames, variables

# 5. Cleanup
omnibreak stop

All Commands

CommandDescription
daemonStart background daemon (required before other commands)
launchDeploy + start binary on target via gdbserver
attachAttach to a running process
breakSet breakpoint (--file, --line, --condition)
continue / cResume execution (auto-returns status with threads/frames/vars)
next / nStep over (auto-returns status)
step / sStep into (auto-returns status)
statusFull debug state (threads, frames, vars)
crashCrash backtrace (500 frames)
evalEvaluate C expression
gdbRaw GDB/MI command
watchSet watchpoint (--expr, --type read/write/access)
statsProcess stats — CPU%, RSS, VSZ, thread count, state
leaksMemory leak detection — heap tracking, risk escalation
logsRead remote log file (--path, --lines)
traceCapture Perfetto trace from remote target (system-wide + CPU sampling + auto-summary)
coredumpAnalyze core dump locally with GDB (no daemon needed)
deploySCP file to target (standalone, no session needed)
stopEnd session & cleanup
healthCheck if daemon is running

Launch Options

omnibreak launch --target <IP> --binary <PATH>
  --user <name>          SSH user (default: root)
  --port <n>             gdbserver port (default: 2345)
  --pwd <pass>           SSH password (for scp, gdbserver, and GDB)
  --deploy-source <path> Local binary to SCP before launch
  --source-map <json>    Compile-path → local-path mapping
  --sudo                 Use sudo for gdbserver commands
  --skip-gdbserver       Skip starting gdbserver (if already running)

Attach Options

omnibreak attach --target <IP> --process <name>|--pid <n>
  --binary <path>        .so or binary for debug symbols
  --solib-path <dir>     Remote .so search path
  --source-map <json>    Source path mapping
  --deploy-source <path> Local binary to SCP before attach
  --pwd <pass>           SSH password (for scp, gdbserver, and GDB)
  --sudo                 Use sudo for gdbserver commands

Trace Options

omnibreak trace --target <IP>
  --user <name>           SSH user (default: root)
  --pwd <pass>            SSH password
  --duration <seconds>    Trace duration (default: 10)
  --output <path>         Local output path (default: ./trace.pftrace)
  --events <list>         Ftrace events (default: auto-detect sched + GPU + process events)
  --sudo                  Use sudo for ftrace access (required for kernel events)
  --sudo-pwd <pass>       Sudo password (defaults to SSH password)
  --start-cmd <cmd>       Command to run on remote AFTER trace starts
  --heap-profile <proc>   Enable heapprofd native heap profiling for process name

Uses Perfetto tracebox — deploys automatically on first use (~20MB one-time download).
Returns a .pftrace file openable in ui.perfetto.dev, plus an auto-generated JSON summary:

summary:
  top_cpu_threads     ← top-10 CPU consumers with ms
  thread_states       ← per-thread end_state breakdown
  io_wait             ← threads stuck in D state
  scheduling_latency  ← avg/max scheduling slice duration
  process_rss         ← per-process peak RSS
  perf_top_functions  ← flame graph: top functions by CPU samples

GPU auto-detection: probes /sys/kernel/tracing/events/ for GPU ftrace sources.
CPU sampling: 100Hz linux.perf data source for flame graphs.
Security: passwords passed via SSHPASS env variable, never in ps output.

JSON Output

Every command returns JSON to stdout. Stderr is for human-readable logs.

Success:

{
  "ok": true,
  "status": "stopped",
  "file": "main.c",
  "line": 42,
  "reason": "breakpoint-hit",
  "threads": [{"id":1,"name":"myapp","state":"stopped"}],
  "frames": [{"level":0,"func":"main","file":"main.c","line":42}],
  "vars": [{"name":"x","value":"10"},{"name":"y","value":"20"}]
}

Failure:

{
  "ok": false,
  "error": "Connection refused",
  "code": "CONNECTION",
  "hint": "Check if gdbserver is running on target:2345"
}

Typical Workflows

Bug investigation loop

omnibreak daemon &
omnibreak launch --target 192.168.1.100 --binary /app/myapp --user root
omnibreak break --file handler.c --line 342
omnibreak continue
omnibreak status     # check variables
omnibreak next       # step
omnibreak status     # check again
omnibreak stop

Crash capture

omnibreak launch --target 192.168.1.100 --binary /app/myapp --user root
omnibreak break --file handler.c --line 128
omnibreak continue
# ... crash occurs ...
omnibreak crash
# → full 500-frame backtrace with file:line
omnibreak stop

Attach to running service

omnibreak attach --target 192.168.1.100 --process myservice --binary ./libservice.so
omnibreak status
omnibreak stop

Memory leak detection

# Sample every ~5s, watch risk escalate
omnibreak leaks --pid 12345 --target 192.168.1.100 --user root
# → {heapKB:512, heapDeltaKB:384, risk:"high", sampleCount:30}
# risk: none → low → medium → high

Process monitoring

omnibreak stats --pid 12345 --target 192.168.1.100 --user root
# → {cpuPercent:45.2, rssMB:18.5, vszMB:128, threadCount:4, state:"R"}
# state: R=running S=sleeping D=disk-wait T=tracing-stop Z=zombie

System trace capture

# Capture system-wide trace (auto-detects GPU events)
omnibreak trace --target 192.168.1.100 --user root --duration 10 --sudo

# Capture trace and run a specific command during the trace window
omnibreak trace --target 192.168.1.100 --user root --duration 10 --sudo \
  --start-cmd "/app/myapp"

# Custom events override auto-detection
omnibreak trace --target 192.168.1.100 --user root --duration 10 --sudo \
  --events "sched/sched_switch i915/i915_gem_request_submit"

The trace captures CPU scheduling + GPU events (auto-detected) + CPU callstack sampling of ALL processes, plus process snapshots and system info. Use the --start-cmd flag to ensure short-lived programs are captured.

Watchpoint debugging

# Watch when variable 'x' is written to
omnibreak watch --expr "x" --type write

# Watch when expression is accessed (read or write)
omnibreak watch --expr "ptr->data" --type access

# Continue — stops when x changes, returns new value in vars
omnibreak continue
# → {"ok":true,"status":"stopped","file":"main.c","line":42,"vars":[{"name":"x","value":"100"}]}

Remote log inspection

# Read last 100 lines of a remote log file
omnibreak logs --target 192.168.1.100 --path /var/log/myapp.log --lines 100 --user root

# Tail recent activity
omnibreak logs --target 192.168.1.100 --path /tmp/gdbserver-output.log --lines 50
# → {"path":"/var/log/myapp.log","lines":["2024-01-01 INFO ...","..."]}

Native heap profiling (heapprofd)

# Capture trace with native heap profiling for myapp
omnibreak trace --target 192.168.1.100 --user root --duration 10 --sudo \
  --heap-profile "myapp"

# Open trace in ui.perfetto.dev → Heap Dump Explorer → see per-function allocation flame graph

Coredump post-mortem analysis

# Analyze a core dump to find the crash location
omnibreak coredump --binary ./myapp --core ./core.1234
# → {signal:"SIGSEGV", crashingThread:"1",
#    threads:[{id:"1", frames:[{func:"main", file:"main.c", line:42}]}],
#    registers:{pc:"0x...", sp:"0x..."}}

Pure local operation — no daemon, no SSH needed.

Troubleshooting

ProblemSolution
"Daemon not running"omnibreak daemon &
"Connection timed out"Check gdbserver on target, firewall allows port
"Process not found"Process name must match (uses pgrep -f)
"Operation not permitted" (attach)sudo sysctl -w kernel.yama.ptrace_scope=0
No debug symbolsCompile with -g flag
Trace is emptyEnsure --sudo is used (ftrace requires root)
Process not in traceUse --start-cmd so trace starts before the process
No GPU events in traceGPU events only fire when GPU is active (not in headless VMs). Check daemon stderr for Detected GPU: lines

License

MIT

Author

shibu


Ver o original no GitHub

Bom para

Relacionados