codecast

# Codecast Live-stream coding agent sessions to Discord. Zero AI tokens burned. ## Setup First-time setup: see [references/setup.md](references/setup.md) for webhook creation, unbuffer install, bot token, and smoke test. ## Invocation Launch with `exec background:true`. Background exec sessions survive agent turns and OpenClaw fires `notifyOnExit` automatically when the process ends. ```bash exec background:true command:"{baseDir}/scripts/dev-relay.sh -w ~/projects/myapp -- claude -p --dangerously-skip-permissions --output-format stream-json --verbose 'Your task here'" ``` Note the session ID from the response — use it to monitor via `process`. ### Options | Flag | Description | Default | |------|------------|---------| | `-w <dir>` | Working directory | Current dir | | `-t <sec>` | Timeout | 1800 | | `-h <sec>` | Hang threshold | 120 | | `-n <name>` | Agent display name | Auto-detected | | `-r <n>` | Rate limit (posts/60s) | 25 | | `--thread` | Post into a Discord thread | Off | | `--skip-reads` | Hide Read tool events | Off | | `--review <url>` | PR review mode | — | | `--parallel <file>` | Parallel tasks mode | — | | `--resume <dir>` | Replay session | — | For PR review, parallel tasks, Discord bridge, and Codex structured output: see [references/advanced-modes.md](references/advanced-modes.md). ## Agent Launch Checklist 1. **Start background session** → note session ID and PID from response 2. **Post to dev channel** → announce agent name, workdir, task 3. **Write breadcrumb** for completion routing: ```bash echo '{"channel":"<invoking-channel-id>","relayDir":"<relay-dir>","pid":<PID>}' > /tmp/codecast-pending-<PID>.json ``` 4. **Log to daily memory** → session ID, relay dir, invoking channel The breadcrumb file tells the heartbeat precheck where to post results when the session completes. It auto-detects completion by checking if the PID is still alive. That's it. When the process ends, OpenClaw's `notifyOnExit` fires a system event + heartbeat request. The heartbeat handler reads the result from the relay dir's `stream.jsonl` and posts to the invoking channel. ## Completion Detection OpenClaw handles this natively: - `tools.exec.notifyOnExit: true` (default) — system event + heartbeat on process exit - Heartbeat precheck script detects completed sessions via `/tmp/dev-relay-sessions/` - No cron watcher needed **Backup:** Append this to the inner agent's prompt for an additional signal: ``` When completely finished, run: openclaw system event --text "Done: <brief summary>" --mode now ``` ## Monitoring ``` process poll sessionId:<id> # Check status process log sessionId:<id> # View recent output process kill sessionId:<id> # Stop session ``` ## Agent Support | Agent | Output Mode | Status | |-------|------------|--------| | Claude Code | stream-json | Full support | | Codex | --json JSONL | Full support | | Any CLI | Raw ANSI | Basic support | ## Session Tracking - **Active sessions:** `/tmp/dev-relay-sessions/<PID>.json` (auto-removed on end) - **Event logs:** `/tmp/dev-relay.XXXXXX/stream.jsonl` (7-day auto-cleanup) - **Interactive input:** `process submit sessionId:<id> data:"message"` ## Reference Docs - [Setup guide](references/setup.md) — first-time install, webhook, bot token - [Advanced modes](references/advanced-modes.md) — PR review, parallel tasks, Discord bridge, Codex - [Discord output](references/discord-output.md) — message formats, architecture, env vars, troubleshooting