| name | agent-session-capture-backup |
| displayName | Agent Session Capture Backup |
| description | Verify, repair, backfill, and back up Pi/Claude/Codex session capture across Flagg, Blaine, and Panda. Use when checking whether agent activity is captured, clearing joelclaw outbox backlogs, backing transcripts up to three-body NAS, or scheduling capture verification. |
| version | 0.1.0 |
| author | joel |
| tags | ["joelclaw","sessions","backup","nas","capture"] |
Agent Session Capture Backup
Use this skill when Joel asks whether agent activity is being captured, indexed, or backed up across machines.
Canonical surfaces
Transcript/raw activity sources:
- Pi:
~/.pi/agent/sessions, ~/.pi/agent/run-history.jsonl, ~/.pi/notes-bridge/events.jsonl
- Claude Code:
~/.claude/projects
- Codex:
~/.codex/sessions, ~/.codex/archived_sessions, ~/.codex/session_index.jsonl
- joelclaw run capture:
~/.joelclaw/runs-dev
- failed run-capture posts:
~/.joelclaw/outbox
NAS backup target:
/Volumes/three-body/sessions/<machine>/<source-key>/...- receipts:
/Volumes/three-body/sessions/receipts/*.json
Current live capture endpoint, per 2026-07-09 repair receipt:
http://joels-mac-studio.tail7af24.ts.net:3111/api/runs- health:
http://joels-mac-studio.tail7af24.ts.net:3111/api/runs/health
Important drift note: older system-architecture docs say Panda is Central. Flagg/Mac Studio is the working capture endpoint for Blaine. Capture authentication uses Flagg's persistent local ~/.joelclaw/capture-auth.db; Typesense machines_dev is only its enrollment/migration mirror.
Manual verification / repair
From ~/Code/joelhooks/joelclaw-runtime:
bun scripts/agent-session-audit-backup.ts \
--hosts flagg,blaine,panda \
--central-url http://joels-mac-studio.tail7af24.ts.net:3111 \
--backup-root /Volumes/three-body/sessions \
--repair-env \
--sync=true \
--replay-outbox \
--replay-limit 250 \
--replay-max-bytes 10485760
What it does:
- verifies each host is reachable
- verifies each host can reach the Central run-capture health endpoint
- optionally repairs
JOELCLAW_CENTRAL_URL in .zshrc, .zprofile, and ~/.config/system-bus.env
- rsyncs transcript/run/outbox sources to the NAS without deleting source files
- replays a bounded number of outbox JSON payloads to
/api/runs
- writes a JSON receipt with source counts, backup counts, newest mtimes, byte totals, and outbox before/after
Use --sync=false for read-only audit.
Use a low --replay-limit first when clearing a huge outbox. Do not unleash tens of thousands of run-capture events without checking worker/Inngest health.
Durable scheduled workflow
Host worker function:
system/agent-session.capture-backup.verify- manual event:
system/agent-session.capture-backup.requested
- daily cron:
TZ=America/Los_Angeles 15 5 * * *
Manual trigger:
joelclaw send system/agent-session.capture-backup.requested -d '{
"hosts": "flagg,blaine,panda",
"centralUrl": "http://joels-mac-studio.tail7af24.ts.net:3111",
"repairEnv": true,
"replayLimit": 250,
"replayMaxBytes": 10485760
}'
Green criteria
- Every active machine reports
centralHealthOk=true.
- Every transcript source that exists locally has matching or increasing backup file counts on NAS.
~/.joelclaw/outbox count trends toward zero on each machine.- Receipts are written daily under
/Volumes/three-body/sessions/receipts.
- A recent receipt includes Flagg and Blaine with fresh Pi, Claude, Codex,
runs-dev, and outbox counts.
Gotchas
- Do not use
http://panda:3000; that endpoint is stale and fails.
- Do not use Panda's
/api/runs until its local Typesense auth lookup is healthy again.
- Flagg may have live local capture even when docs still say Panda is Central. Verify
system-architecture and recent receipts before changing authority language.
- Backups must be copies, not rotations. Do not delete or move live transcript files during backup.
- Outbox replay is a repair operation. Keep it bounded and leave receipts.
- Never print auth tokens from
~/.joelclaw/auth.json; the script reads them locally on each host.
