codecast

name

codecast

description

Stream coding agent sessions (Claude Code, Codex, Gemini CLI, etc.) to a Discord channel in real-time via webhook. Use when invoking coding agents and wanting transparent, observable dev sessions — no black box. Parses Claude Code's stream-json output into clean formatted Discord messages showing tool calls, file writes, bash commands, and results with zero AI token burn. Use when asked to "stream to Discord", "relay agent output", or "make dev sessions visible".

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