dbg-cli 0.2.2

A universal debugger CLI that lets AI agents observe runtime state instead of guessing from source code
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

# Linux perf Adapter

## CLI

`dbg start perf <perf.data>`

## Preconditions

| Requirement | Check | Fix |
|-------------|-------|-----|
| `dbg` | `which dbg` | `cargo install dbg-cli` — ensure `~/.cargo/bin` is in PATH |
| `perf` | `which perf` | `sudo apt install linux-tools-$(uname -r)` |

## Recording Profiles

```bash
# CPU profile with call graphs
perf record -g ./myapp

# CPU profile for 10 seconds of a running PID
perf record -g -p <PID> -- sleep 10

# With specific events
perf record -e cache-misses -g ./myapp

# Stat summary (no recording)
perf stat ./myapp
```

## Key Commands (perf report --stdio)

| Command | What it does |
|---------|-------------|
| `perf report --stdio` | Text-mode overhead report |
| `perf report --stdio --sort=dso` | Group by shared library |
| `perf annotate <func> --stdio` | Instruction-level profile |
| `perf script` | Raw trace (pipe to flamegraph) |
| `perf stat` | Hardware counter summary |

## Flamegraph

```bash
perf script | stackcollapse-perf.pl | flamegraph.pl > flame.svg
```

Or with `inferno`:
```bash
perf script | inferno-collapse-perf | inferno-flamegraph > flame.svg
```

## Common Failures

| Symptom | Fix |
|---------|-----|
| `Permission denied` | `sudo sysctl kernel.perf_event_paranoid=-1` or run as root |
| No symbols | Compile with `-g` or install debug symbols package |
| `perf not found for kernel` | Install matching `linux-tools-$(uname -r)` |
| WSL2 limited | perf requires matching kernel tools — use native Linux or a VM |