---
name: tmux-screenshot
description: Capture tmux session state into TXT, JSON, and PNG artifacts for operator debugging. Use when publishing or analyzing tmux session state, comparing terminal text against known failure signatures, or generating structured diagnostic captures for the glasspane viewer.
---

# tmux-screenshot

Use this skill for terminal-state capture.

TXT and JSON are the primary diagnostic artifacts. PNG exists for human viewing.

## Scope

This skill covers:

- tmux pane capture
- text-first diagnostic artifacts
- structured JSON metadata
- screenshot publishing for the operator glasspane

## Output priority

1. `txt`
2. `json`
3. `png`

Use TXT for direct comparison and signature matching.

Use JSON for structured automation.

Use PNG for human browsing and visual review.

## Dependencies

Required on FreeBSD host:

- `python312` — system Python (3.12)
- `Pillow` — installed via `sudo uv pip install Pillow --system --python python3.12`
- `dejavu` fonts — `sudo pkg install dejavu`
- `jpeg-turbo`, `freetype2`, `lcms2` — Pillow build deps, `sudo pkg install jpeg-turbo freetype2 lcms2`

## Canonical paths

- Script: `.agent/skills/tmux-screenshot/tmux-screenshot.py`
- Output dir: `/usr/local/www/clawdie/screenshots/`
- Served at: `https://clawdie.si/screenshots/`
- Fonts: `/usr/local/share/fonts/dejavu/DejaVuSansMono.ttf`
- Manifest: `/usr/local/www/clawdie/screenshots/manifest.json`

## Workflow

1. Run `python3 .agent/skills/tmux-screenshot/tmux-screenshot.py --session 0`
2. Read the `.txt` output first
3. Read the `.json` output for structured metadata
4. Use the `.png` output only when a human needs visual context

### Quick capture from host

```sh
python3 /home/clawdie/clawdie-ai/.agent/skills/tmux-screenshot/tmux-screenshot.py --session 0
```

Override output directory with `--outdir /path/to/dir`.

Override session name with `--session <name>`.

## JSON fields

The JSON artifact is the machine-readable state capture.

Current fields include:

- `uuid`
- `session`
- `captured_at`
- `captured_at_display`
- `host`
- `window_index`
- `window_name`
- `pane_id`
- `pane_title`
- `pane_current_command`
- `pane_current_path`
- `text_path`
- `png_path`
- `json_path`
- `line_count`
- `txt_hash`
- `tags`
- `detected_signatures`
- `dimensions`

Use `captured_at_display` for user-facing rendering.

Use `captured_at` for machine comparison and sorting.

## Diagnostic use

This skill is intended to work with troubleshooting skills.

Preferred comparison order:

1. compare `.txt` against known failure and success signatures
2. inspect `.json` for context such as command, path, and pane title
3. check `detected_signatures` in JSON for auto-triage results
4. open `.png` only when human visual review is needed

### Signature detection

The detector runs all captured text against two signature databases:

**Failure signatures** (checked first) — known error patterns that require action:
- Missing warden0 bridge, stale epair interfaces
- PF table missing, NAT rules empty, firewall blocking all
- Host forwarding disabled, Tailscale resolver leak
- Controlplane jail missing, wrong gateway provisioned
- PostgreSQL shmget/initdb failures
- Sanoid config missing, ZFS pool degraded
- Telegram typing with no reply

**Success signatures** — known healthy patterns that confirm working state:
- warden0 bridge at 192.168.100.1
- Host forwarding enabled
- Controlplane at ai.clawdie.si / 192.168.100.100
- Database jail at 192.168.100.2
- PostgreSQL processes running
- ZFS pool ONLINE, clawdie-runtime datasets exist
- Sanoid autosnap active
- PF NAT and pass rules present

### Auto-triage output

The JSON `detected_signatures` field is structured as:

```json
{
  "failures": [{"id": "...", "severity": "error", "invoke": "skill-name", ...}],
  "warnings": [{"id": "...", "severity": "warn", ...}],
  "info": [],
  "healthy": [{"id": "...", "severity": "ok", ...}],
  "all": [...]
}
```

When `invoke` is present on a failure, the agent should run that skill to remediate.

### Signature sources

Failure and success patterns are sourced from real-world observations documented in:

- `freebsd-admin` — host forwarding, resolver baseline
- `bastille-network` — bridge, epair, VNET creation
- `warden-pf` — NAT, PF rules, firewall state
- `warden-bootstrap` — controlplane provisioning, gateway
- `postgres-memory` — shmget, initdb, jail IPC
- `sanoid` — snapshot config, sample dataset warnings
- `warden-zfs` — pool health, dataset layout
- `telegram-admin` — bot response health
