Skip to content

feat: add debug-agent skill for admin observability #165

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
baudbot-agent merged 4 commits into from
Feb 24, 2026
Merged

feat: add debug-agent skill for admin observability #165

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8e3127a
feat: add TUI dashboard extension for at-a-glance system status
Feb 24, 2026
4d1d0cb
fix: track last event via before_agent_start for all message sources
Feb 24, 2026
a7f97c4
feat: add debug-agent skill for admin observability
Feb 24, 2026
68494fa
fix: flaky test cleanup — wait for child exit + retry rmSync
Feb 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 55 additions & 0 deletions pi/skills/debug-agent/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
---
name: debug-agent
description: Debug agent — observe control-agent activity and system health. Launched via `baudbot session attach`.
---

# 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/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/slack-bridge.log` |
| Bridge tmux | `tmux attach -t 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
Loading