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 + hea...

# Dev Session Relay

Streams coding agent (Claude Code, Codex, Gemini CLI, etc.) sessions to Discord #dev-session, enabling interactive pair programming.

## Phase 1: Nexus-Orchestrated (Current)

Nexus spawns the coding agent via `exec pty:true background:true`, polls output via `process:log`, and relays to #dev-session via `message` tool. Allan's messages in #dev-session are forwarded to the agent via `process:submit`.

### Protocol

1. **Start:** Nexus posts session header to #dev-session (command, workdir, agent)
2. **Stream:** Poll `process:log` every ~10s, post new output chunks (batched, ANSI stripped)
3. **Input:** Allan's messages in #dev-session during active session → `process:submit`
4. **Hang detection:** No output for 120s → post warning
5. **Completion:** Post exit code + summary
6. **Kill:** Allan says `!kill` → `process:kill`

### Commands (Allan types in #dev-session)

- Any text → forwarded to agent stdin
- `!kill` → kill the agent process
- `!status` → show session status (runtime, last output)
- `!log` or `!log 50` → show last N lines of output

## Phase 2: Standalone (Future)

Requires Discord webhook URL. Script spawns agent, tails output, posts via webhook, listens for input via Discord gateway.

## Location

- Protocol docs: this file + TOOLS.md
- Helper: `relay.sh` (ANSI stripping, output batching)
- Project: `~/projects/dev-session-relay/`