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

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":"\x3Cinvoking-channel-id>","relayDir":"\x3Crelay-dir>","pid":\x3CPID>}' > /tmp/codecast-pending-\x3CPID>.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: \x3Cbrief summary>" --mode now

Monitoring

process poll sessionId:\x3Cid>        # Check status
process log sessionId:\x3Cid>         # View recent output
process kill sessionId:\x3Cid>        # Stop session

Agent Support

Session Tracking

• Active sessions: /tmp/dev-relay-sessions/\x3CPID>.json (auto-removed on end)
• Event logs: /tmp/dev-relay.XXXXXX/stream.jsonl (7-day auto-cleanup)
• Interactive input: process submit sessionId:\x3Cid> 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