vibecheck
A native macOS edge panel that shows live coding-agent sessions.
apps/macos/ Swift package: CompanionCore (agent-neutral) + Vibecheck (app)
integrations/core/ Shared session-status contract + reporter used by every integration
integrations/pi/ pi package (extension) that reports pi sessions
apps/web/ Landing page (Next.js, static export: npm --prefix apps/web run dev)
Data flow: agent integration → integrations/core reporter → status file →
StatusDirectorySource → SessionStore → panel. See integrations/core/README.md
to add another agent.
Install
brew install --cask ikramhasan/tap/vibecheck
Requires macOS 26 on Apple Silicon. Install through Homebrew rather than downloading the
zip by hand: the app isn't notarized, and the cask clears the quarantine flag so it opens
without a Gatekeeper warning.
Release
Push a version tag. .github/workflows/release.yml builds the app, publishes the zip as a
release of ikramhasan/homebrew-tap and updates
the cask's version and sha256 there.
git tag v0.3.0 && git push origin v0.3.0
The workflow needs the HOMEBREW_TAP_TOKEN secret: a fine-grained token with Contents
read/write on homebrew-tap.
Build & run
apps/macos/scripts/bundle.sh [version] # build the .app and zip (version defaults to 0.0.0)
open apps/macos/build/vibecheck.app # live data
Launch options:
open apps/macos/build/vibecheck.app --args --demo # sample sessions
open apps/macos/build/vibecheck.app --args --demo --settings # also open Settings
Without --demo the panel shows running Claude Code, Codex and pi sessions by reading their
own session files; nothing needs to be installed. It stays hidden while none are running.
Hover the tab on the right screen edge to expand it; the gear opens Settings and the
power button quits.
If an older build is still running, quit it first so the new one loads:
pkill -x Vibecheck
Usage stats
vibecheck reads each agent's plan limits itself, using the sign-in the agent already has. Nothing
extra is installed and no credentials are stored or refreshed; when a sign-in expires, run the agent
once to renew it.
| Agent | Sign-in it reads (read-only) | Shows |
|---|
| Claude | ~/.claude/.credentials.json, or the Claude Code-credentials keychain item | 5h, weekly and per-model weekly limits |
| Codex | ~/.codex/auth.json | 5h, weekly (or monthly on free) and per-model limits |
| Kiro | kiro-cli's ~/Library/Application Support/kiro-cli/data.sqlite3 | monthly credits and overage |
In Settings → Agents, add agents and toggle Status (running sessions) and Usage per agent.
With any usage enabled the tab stays visible even when no agent is running. Usage refreshes every
5 minutes, when the panel opens with stale data, and from the refresh button in the Usage header.
The usage clients are ported from CodexBar (MIT). Agent
icons and brand colours also come from CodexBar; refresh them with
apps/macos/scripts/sync-provider-icons.sh. Agents with an official logo use it instead, drawn in
its own colours from Resources/BrandIcons/ (<id>.svg, plus <id>_dark.svg for dark mode): from
svgl (MIT), and from lobe-icons (MIT)
for Claude, Codex and Kiro. Logos remain their owners' trademarks.
pi extension (optional)
pi sessions show up without it. The extension adds what pi's session files don't record:
its confirm/select dialogs (shown as needing attention) and an exact link between the pi
process and its session.
pi install "$PWD/integrations/pi" # uninstall: pi remove "$PWD/integrations/pi"
Remote machines
Settings → Machines adds Linux machines you reach with ssh (an alias from ~/.ssh/config,
user@host, or a Tailscale name). Their Claude, Codex and pi sessions show in the panel
under the machine's name, with diff stats and the diff window. Nothing is installed on the
other machine:
- vibecheck keeps one
ssh -T <host> bash -s connection per machine and sends it a fixed
script (apps/macos/Sources/CompanionCore/Remote/RemoteScript.swift). The script only
reads: agent registries, /proc, new transcript lines, and a fixed set of git queries
(GIT_OPTIONAL_LOCKS=0, no external diff or textconv). It exits when the connection
closes.
- ssh runs with
BatchMode=yes, so key-based login is required, and never shares or
creates a ControlMaster connection. Host keys are checked as usual.
- Only
SSH_CONNECTION and PI_SUBAGENT_CHILD are read from remote process
environments; nothing else leaves the machine except transcripts and diffs.
- Clicking a remote session opens the app on this Mac that runs it: the app whose
ssh -L tunnel reaches the agent's server (T3 Code), or the terminal tab (and tmux
pane) of the ssh session the agent was started from. This needs a direct ssh
connection; through ProxyJump or ProxyCommand there's nothing on this Mac to match.
- Dev servers on the machine show in the Servers tab as
host:port and open at the
machine's address. Servers that only listen on its localhost are listed without a link.
Remote servers can't be stopped from vibecheck.
- The connection reconnects after errors (2 s, doubling to 60 s) and right after the Mac
wakes. macOS machines aren't supported yet.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
