https://github.com/kibitzsh/kibitz
Real-time decoded feed of AI agent actions — monitor multiple Claude Code & Codex sessions, see exactly what each agent is doing, and coordinate swarms efficiently
https://github.com/kibitzsh/kibitz
claude claudecode cli codex macos vscode-extension windows
Last synced: 25 days ago
JSON representation
Real-time decoded feed of AI agent actions — monitor multiple Claude Code & Codex sessions, see exactly what each agent is doing, and coordinate swarms efficiently
- Host: GitHub
- URL: https://github.com/kibitzsh/kibitz
- Owner: kibitzsh
- License: mit
- Created: 2026-02-26T19:56:53.000Z (about 1 month ago)
- Default Branch: master
- Last Pushed: 2026-03-02T00:41:59.000Z (28 days ago)
- Last Synced: 2026-03-04T10:23:50.510Z (26 days ago)
- Topics: claude, claudecode, cli, codex, macos, vscode-extension, windows
- Language: TypeScript
- Homepage: https://kibitz.sh
- Size: 992 KB
- Stars: 416
- Watchers: 2
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Support: docs/SUPPORT_MATRIX.md
Awesome Lists containing this project
README
# Kibitz
[](LICENSE)
[](https://marketplace.visualstudio.com/items?itemName=kibitzsh.kibitz)
[](https://www.npmjs.com/package/@kibitzsh/kibitz)
[](https://github.com/kibitzsh/kibitz/actions/workflows/pages.yml)
[](https://kibitz.sh)
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](https://marketplace.visualstudio.com/items?itemName=kibitzsh.kibitz) or search `Kibitz` in the Extensions panel.
**CLI — Homebrew (macOS / Linux)**
```bash
brew install kibitzsh/tap/kibitz
```
**CLI — npm**
```bash
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 ` or `N/ ` (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 `.
- 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
```bash
npm ci
npm run build
```
### Deploy to Local VS Code/Cursor
```bash
npm run deploy:vscode
```
This copies `dist/` and `package.json` into your local extensions directory and replaces older Kibitz extension folders.
### Run CLI
```bash
npm run build
node dist/cli/index.js
```
## Testing
```bash
npm run typecheck
npm run check:compat
npm run test:ui
npm run test:download-digest
npm run test:all
```
Useful targeted checks:
```bash
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):
```bash
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 .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](docs/SUPPORT_MATRIX.md)
- [Compatibility release checklist](docs/COMPAT_CHECKLIST.md)
## Legal
- [License (MIT)](LICENSE)
- [Privacy Policy](PRIVACY.md)
- [Terms of Use](TERMS.md)
## 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.