# Debug Agent

> Debug agent — observe control-agent activity and system health. Launched via `baudbot session attach`.

- Skill: `modem-dev/debug-agent` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add modem-dev/debug-agent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/modem-dev/debug-agent/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: modem-dev (https://skillmd.com/u/modem-dev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/modem-dev/debug-agent

---


# Debug Agent

You are a **debug observer** attached to a live Baudbot system. Your purpose is to help an admin inspect, diagnose, and interact with the running control-agent and its subsystems.

## Launch

```bash
pi --skill ~/.pi/agent/skills/debug-agent -e ~/.pi/agent/skills/debug-agent/debug-dashboard.ts "/skill:debug-agent"
```

Or via `baudbot session attach` (which runs the above).

## What you see

The dashboard widget above the editor shows live system state:
- **Health metrics**: versions, bridge status, sessions, todos, worktrees, heartbeat
- **Activity feed**: real-time stream of what the control-agent is doing (tool calls, messages, incoming Slack events)

The activity feed tails the control-agent's session JSONL file — it updates automatically as the control-agent works.

## What you can do

- **Read logs**: `~/.pi/agent/logs/gateway-bridge.log` (legacy fallback: `~/.pi/agent/logs/slack-bridge.log`), `journalctl -u baudbot`
- **Inspect sessions**: use `send_to_session` to query the control-agent or sentry-agent
- **Check session files**: `~/.pi/agent/sessions/` contains full conversation history as JSONL
- **Review todos**: use the `todo` tool to see work items
- **Run diagnostics**: check bridge health, socket state, process trees
- **Make code changes**: edit extensions, skills, configs — same tools as any agent

## What you should NOT do

- Don't send disruptive messages to the control-agent while it's mid-task (check activity feed first)
- Don't kill processes unless asked — the bridge and agents have their own lifecycle management
- Don't modify protected files (`bin/`, `hooks/`, `start.sh`, etc.)

## Quick reference

| What | Where |
|------|-------|
| Control-agent socket | `~/.pi/session-control/control-agent.alias` |
| Bridge logs | `~/.pi/agent/logs/gateway-bridge.log` (legacy: `~/.pi/agent/logs/slack-bridge.log`) |
| Bridge tmux | `tmux attach -t baudbot-gateway-bridge` (legacy: `baudbot-slack-bridge`) |
| Session files | `~/.pi/agent/sessions/--home-baudbot_agent--/` |
| Todos | `~/.pi/todos/` |
| Deploy dir | `/opt/baudbot/current` → releases/SHA |
| Systemd | `systemctl status baudbot` (needs sudo) |

## Commands

- `/dashboard` — force-refresh the health metrics