talkatui (pronounced talkative)

WWE-style live commentary for Claude Code and Codex sessions in a terminal UI.

Install globally:

npm install -g talkatui

What it is

talkatui watches active agent sessions, turns low-level events into commentary, and gives you a fun + useful live control room:

• session list and status
• live commentary feed
• session insights (tool calls/errors/recent actions)
• hype/chaos scoreboard
• optional voice playback

It reads session JSONL logs from:

• ~/.claude/projects/*.jsonl
• ~/.codex/sessions/YYYY/MM/DD/*.jsonl

Requirements

• Node.js >=20
• Terminal that supports interactive TUI apps
• At least one active Claude Code or Codex session

Quick start

Run from source:

git clone [email protected]:vignesh07/talkatui.git
cd talkatui
npm install
npm run build
npm start

Run globally (after publish):

npm install -g talkatui
talkatui

Use globally from your local checkout (no publish needed):

npm install
npm run build
npm link
talkatui

Run commands

# default run (provider/model defaults)
talkatui

# watch only codex sessions
talkatui --source codex

# watch only claude sessions
talkatui --source claude

# watch one project
talkatui --project talkatui

# watch specific session(s)
talkatui --session <session-id>
talkatui --session <id-1> --session <id-2>

# pick provider/model explicitly
talkatui --provider openai --model gpt-4o-mini

# faster commentary cycle (seconds)
talkatui --batch 5

# enable voice
talkatui --voice

# free-tier voice preset
talkatui --voice --voice-tier free

# explicit custom voice (overrides voice tier)
talkatui --voice --voice-id <elevenlabs-voice-id>

API keys and auth

Commentary models are resolved through @mariozechner/pi-ai.

Common providers:

• anthropic -> ANTHROPIC_API_KEY
• openai -> OPENAI_API_KEY
• google -> GEMINI_API_KEY
• others -> provider-specific key or OAuth flow supported by pi-ai

Voice:

• Voice is optional, but if you want TTS, --voice requires ELEVENLABS_API_KEY
• --voice-tier paid|free selects default voice preset
• default is paid tier with Phil (best "announcer" effect)
• free tier gives a lower-cost option
• --voice-id overrides the tier preset

Put keys in your shell profile:

# ~/.zshrc or ~/.bashrc
export ANTHROPIC_API_KEY="..."
export OPENAI_API_KEY="..."
export GEMINI_API_KEY="..."
export ELEVENLABS_API_KEY="..."

Reload shell config:

source ~/.zshrc

List providers/models available through pi-ai:

npx @mariozechner/pi-ai list

If provider auth is missing, talkatui stays up, but live commentary generation is skipped until provider auth is fixed.

Voice plans (ElevenLabs)

If you want voice commentary, you need an ElevenLabs account + API key.

• Paid path (default magic):
  • talkatui --voice --voice-tier paid
  • Uses Phil by default.
• Free/lower-cost path:
  • talkatui --voice --voice-tier free
  • Uses a free-tier friendly preset voice.
• Custom voice:
  • talkatui --voice --voice-id <your-voice-id>

TUI anatomy

From top to bottom:

1. Header

• App banner.

2. Model picker (shown when you press m)

• Lists provider/model options.
• Current selection is highlighted.
• Press m again or esc to close.

3. Sessions panel (left)

• Active sessions with source badge ([CC] Claude, [CX] Codex).
• Shows branch, model, and current status/activity.

4. Session insights panel (left, below sessions)

• Per-selected-session summary:
• Tool calls, Errors, Rejected
• Bash ok/fail, Files
• Top tools, Last, and recent actions list

5. Live commentary panel (right)

• Commentary stream for recent session activity.
• Includes timestamp + project tag on each line.

6. Scoreboard

• Two meters plus counters:
• HYPE (momentum meter)
• CHAOS (failure/turbulence meter)
• STREAK, Peak, Edits, Commands, Errors

7. Ticker

• One-line rolling view of current active session activity.

8. Footer

• Key hints, current voice state, pause state, and selected model.

What hype / chaos / streak mean

• HYPE (0-100):

  • goes up on productive events (successful tool results, successful bash, file edits/writes)
  • can also rise from energetic commentary tones
  • decays over time when idle

• CHAOS (0-100):

  • goes up on failures (tool errors, rejected tool calls, non-zero bash exits)
  • can rise from panic/shock commentary tones
  • decays over time when idle

• STREAK:

  • increments on consecutive successful/progressive events
  • resets on failure/rejection
  • Peak is the highest streak seen in the current run

• Commands:

  • count of successful command-like outcomes (tool success and successful bash)

• Errors:

  • count of tool errors, rejections, and failed bash exits

Keybindings

• q: quit
• m: toggle model picker open/close
• p: pause/resume commentary generation
• v: toggle voice (when available)
• tab / down / j: next session
• up / k: previous session
• in model picker:
  • up / down / j / k / tab: move selection
  • enter: select model
  • m or esc: close picker

Startup health checks

On startup, talkatui reports warnings for:

• unknown provider value
• missing provider auth for selected provider
• --voice set without ELEVENLABS_API_KEY
• missing/unreadable session source directories

Warnings do not block startup.

Release (manual)

1. Validate locally:

npm run lint
npm test
npm run build

2. Bump version:

npm version patch

3. Publish:

npm publish --access public

4. Push branch + tags:

git push origin main --follow-tags

License

MIT

Credits

• @mariozechner/pi-ai powers provider/model routing.
• Huge thanks to Mario Zechner (badlogic) for building Pi.