Kibitz

Kibitz is a VS Code extension + CLI that watches Claude/Codex sessions, generates live commentary, and lets you dispatch prompts to existing or new sessions from one composer.

Install

VS Code Extension — install from the VS Code Marketplace or search Kibitz in the Extensions panel.

CLI — Homebrew (macOS / Linux)

brew install kibitzsh/tap/kibitz

CLI — npm

npm install -g @kibitzsh/kibitz

Compatibility Matrix (Contract)

| Platform | VS Code panel | Terminal CLI | | --- | --- | --- | | macOS | Supported | Supported | | Windows | Supported | Supported | | Linux | Best effort | Best effort |

Core Capabilities

• Live commentary feed for Claude Code and Codex sessions.
• Cross-session prompt dispatch:
  • Existing active sessions.
  • New session on current provider.
• Slash controls in composer:
  • /help, /pause, /resume, /clear, /focus, /model, /preset, /interval, /update
  • session targeting like /1, /2
• Provider-aware model handling.
• Strict dispatch status events: queued, started, sent, failed.

Prompt Dispatching

Kibitz can send prompts to any active watched session (Claude or Codex), or start a new session on the current provider.

VS Code Panel

• Target badges always include:
  • /1 New session (current provider)
  • /2..N existing active sessions from the watcher list
• Starting a new terminal session is one step: select /1 and send your prompt.
• Select a target by:
  • clicking a target badge
  • typing /N (select only)
  • typing /N <prompt> or N/ <prompt> (select + send)
• Plain text (without target token) sends to the currently selected target.
• Each send emits explicit status updates: queued, started, sent, failed.

Terminal CLI

• Use /sessions to list active sessions with numeric indexes.
• Set target with /target <index|agent:sessionId|new-codex|new-claude>.
• Set summary cadence with /interval <15s|30s|1m|5m|15m|1h>.
• Check for updates with /update.
• Starting a new terminal session is one command: /target new-codex (or /target new-claude), then send plain text.
• After target selection, plain text sends to that target.
• Dispatch status is printed for every send: queued, started, sent, failed.

Scope and Limits

• Targeting is limited to active sessions in the watcher window (recent activity).
• Multi-target broadcast in one send is not implemented.

Development Setup

Prerequisites

• Node.js 20+
• npm 10+
• VS Code 1.85+
• At least one provider CLI installed and authenticated:
  • codex / codex.cmd
  • claude / claude.cmd

Build

npm ci
npm run build

Deploy to Local VS Code/Cursor

npm run deploy:vscode

This copies dist/ and package.json into your local extensions directory and replaces older Kibitz extension folders.

Run CLI

npm run build
node dist/cli/index.js

Testing

npm run typecheck
npm run check:compat
npm run test:ui
npm run test:download-digest
npm run test:all

Useful targeted checks:

npm run test:parsers
npm run check:session-names
npm run check:model-persistence

Release Flow

1. Local smoke and package:
   • npm run deploy:vscode (local install to VS Code/Cursor)
   • npm run package (builds .vsix)
2. Full guarded release flow:
   • npm run cr
3. npm run cr performs checks/build, bumps version, publishes VS Code Marketplace + npm, verifies versions, updates Homebrew formula, and pushes tags.
4. For GitHub auto-release on tag push, add repository secrets:
   • VSCE_PAT (VS Marketplace publish PAT)
   • NPM_TOKEN (npm publish token)
   • HOMEBREW_TAP_TOKEN (GitHub token with write access to kibitzsh/homebrew-kibitz)
5. For daily download digest email workflow (.github/workflows/release-download-digest.yml), add:
   • RESEND_API_KEY (Resend API key)
   • HOMEBREW_TAP_TOKEN (GitHub token with read access to kibitzsh/homebrew-kibitz traffic API)
   • sender is fixed to stats@kibitz.sh
   • recipient is fixed to vasilytrofimchuk@gmail.com

Daily Download Digest Emails

• Workflow: .github/workflows/release-download-digest.yml
• Script: scripts/download-digest.js
• Schedule: 9:00 AM PT daily (with UTC cron + PT hour guard)
• Sender: stats@kibitz.sh
• Recipient: vasilytrofimchuk@gmail.com
• Sources:
  • VS Marketplace downloadCount for kibitzsh.kibitz
  • GitHub Releases asset download_count for kibitzsh/kibitz
  • npm range total downloads for @kibitzsh/kibitz
  • Homebrew tap clone traffic proxy from kibitzsh/homebrew-kibitz (/traffic/clones)
• State cache file: .cache/download-digest/state.json
• Behavior:
  • first run initializes baseline (no email),
  • zero-delta days skip email,
  • positive delta sends digest email.
• Manual run:
  • GitHub Actions → Daily Download Digest → Run workflow
• Local smoke test (with real send):

  RESEND_API_KEY=... \
  RESEND_FROM_EMAIL=stats@kibitz.sh \
  ALERT_EMAIL_TO=vasilytrofimchuk@gmail.com \
  HOMEBREW_TAP_TOKEN=... \
  ENFORCE_9AM_PT=0 \
  DOWNLOAD_DIGEST_STATE_FILE=/tmp/kibitz-digest-test-state.json \
  node scripts/download-digest.js
  

Distribution Channels

1) VS Code Extension Marketplace

• Create publisher in VS Marketplace (if not already created).
• Create Azure DevOps PAT with Marketplace publish scopes.
• Publish with npm run publish:vscode (VSCE_PAT required).
• Recommended:
  • publish stable versions to Marketplace,
  • keep .vsix artifacts in GitHub Releases for manual install/rollback.

2) OpenVSX (for Cursor/VSCodium ecosystems)

• Publish the same extension package to OpenVSX.
• Keep version parity with Marketplace.

3) npm (CLI distribution)

• Keep bin.kibitz pointing to dist/cli/index.js.
• Publish package to npm.
• Users can install globally and run kibitz.

4) Homebrew

Two common paths:

• Formula that installs from npm:
  • wraps npm install -g kibitz.
• Tap formula that downloads built tarball/binary and installs launcher.

For VS Code extensions specifically, Homebrew is optional and usually secondary to Marketplace/OpenVSX.

5) GitHub Releases

• Upload .vsix and changelog per version.
• Add quick install instructions:
  • code --install-extension <file>.vsix

Recommended Distribution Stack

For most users, start with:

1. VS Marketplace (primary VS Code install path)
2. OpenVSX (secondary ecosystem coverage)
3. npm (CLI users)
4. GitHub Releases (.vsix artifact + release notes)

Add Homebrew only if your CLI install demand is high and you want one-command setup for macOS/Linux.

Docs

• Support matrix details
• Compatibility release checklist

Legal

• License (MIT)
• Privacy Policy
• Terms of Use

Cross-Platform Notes

Kibitz mirrors proven room patterns:

• Login-shell PATH inheritance on macOS.
• npm global prefix PATH enrichment on Windows.
• Windows .cmd command mapping (claude.cmd, codex.cmd).
• Platform-parameterized compatibility tests.