Codecast

Live-stream coding agent sessions to Discord. Zero AI tokens burned.

Setup

First-time setup: see 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.

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.

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:

   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 — first-time install, webhook, bot token
• Advanced modes — PR review, parallel tasks, Discord bridge, Codex
• Discord output — message formats, architecture, env vars, troubleshooting