vibemon-app
VibeMon
Real-time status monitor for AI assistants with pixel art character display.
See at a glance what your AI assistant is doing — thinking, working, or waiting for input. A cute pixel art character visually represents the current state.
Desktop (Electron) app for VibeMon. For the ESP32 hardware display, see vibemon-esp32.
Supported Tools
| Tool | Description |
|---|---|
| Claude Code | Anthropic’s official AI coding assistant |
| Codex | OpenAI’s AI coding agent |
| Kiro | AWS’s AI coding assistant |
| OpenClaw | Open-source computer use agent |
Agent Integration Model
VibeMon does not talk to agent runtimes directly. Each supported agent is bridged into the same status payload and then rendered by the Desktop App (or the ESP32 display).
| Agent | Bridge type | Tool visibility | Notes |
|---|---|---|---|
| Claude Code | Native hooks | Broad | Best documented lifecycle and tool coverage |
| Codex | Native hooks + codex exec --json |
Broad | Interactive hooks cover shell, file edits, MCP, and other local function tools |
| Kiro | Native hooks | Broad | Good tool-level hooks with MCP-aware tool names |
| OpenClaw | Plugin bridge | Plugin-dependent | Uses plugin SDK hooks rather than the simpler internal hook system |
Support Quality
- Claude Code: Richest hook surface. Best fit for real-time state, permissions, compacting, and tool-loop monitoring.
- Codex: Strong native lifecycle and tool coverage in interactive sessions.
codex exec --jsonremains useful for CI and batch automation. - Kiro: Clean hook model for prompt, tool, and stop events. Practical fit for real-time monitoring.
- OpenClaw: Best supported through plugins. Internal hooks are session/message oriented, so plugin SDK integration is the right path for VibeMon.
What It Monitors
| Field | Description | Example |
|---|---|---|
| State | Current activity state | working, idle, notification |
| Project | Active project directory | vibemon-app |
| Tool | Currently executing tool | Bash, Read, Edit |
| Model | Active model | Opus, Sonnet |
| Memory | Context window usage | 45% |
Quick Start
Homebrew (macOS, recommended):
brew tap opspresso/tap
brew install opspresso/tap/vibemon
Or via npm:
npx vibemon
That’s it! The app launches in the system tray and listens on http://127.0.0.1:19280.
vibemon --version prints the installed version, vibemon --help prints usage — both exit without launching the app.
Open Settings > AI Tools from the tray menu and click Install for Claude Code, Codex CLI, Kiro IDE, or OpenClaw — this sets up the hooks and collector config for you, no separate installer needed. See Settings Window for details.
Tool detection and hook paths honor CLAUDE_CONFIG_DIR, CODEX_HOME, and KIRO_HOME. Kiro is detected through either kiro or kiro-cli.
Preview
Documentation
- Features - States, animations, character window behavior
- API Reference - Complete HTTP API documentation
For full documentation, visit vibemon.io/docs.
States
| State | Color | Description |
|---|---|---|
start |
Cyan | Session begins |
idle |
Green | Waiting for input |
thinking |
Purple | Processing prompt |
planning |
Teal | Plan mode active |
working |
Blue | Tool executing |
packing |
Gray | Context compacting |
notification |
Yellow | User input needed |
done |
Green | Tool completed |
sleep |
Navy | After 5min in idle |
alert |
Red | Critical error/failure |
See Features for animations, working state text, and more.
Characters
| Character | Color | Auto-selected for |
|---|---|---|
vibemon |
Purple | Default; any bridge without its own character |
clawd |
Orange | Claude Code |
codex |
Navy | Codex CLI |
kiro |
White | Kiro |
claw |
Red | OpenClaw |
daangni |
Peach/teal | Manual only (Character Lock) |
The Color column is each character’s overall look. This is distinct from the per-character
colorin the registry, which sets the eye/accent overlay drawn on the sprite — white for VibeMon, whose face is white.
Character Lock
Force the character to always be one of the above, regardless of what each project’s status reports. Default is auto (each project shows its own character).
curl -X POST http://127.0.0.1:19280/character-lock \
-H "Content-Type: application/json" \
-d '{"character":"daangni"}'
Switch via system tray menu (Character Lock submenu) or the API above.
HTTP API
Default port: 19280
POST /status
Update monitor status:
curl -X POST http://127.0.0.1:19280/status \
-H "Content-Type: application/json" \
-d '{"state":"working","tool":"Bash","project":"my-project"}'
GET /status
Get every tracked project’s status and which one the character follows:
curl http://127.0.0.1:19280/status
POST /quit
Stop the application:
curl -X POST http://127.0.0.1:19280/quit
See API Reference for all endpoints.
Character Window
One persistent character + following speech bubble, tracking whichever project is active:
- A project in an active state (thinking, working, notification, …) takes focus; otherwise the most recently updated project keeps it
- Updates from other projects are still collected in the background and shown the moment they gain focus
- Drag it anywhere; it remembers its spot across restarts
See Features for details.
Troubleshooting
| Issue | Solution |
|---|---|
| Window not appearing | Check system tray, or run curl -X POST http://127.0.0.1:19280/show |
| Port already in use | Check with lsof -i :19280 |
| Hook not working | Verify Python 3: python3 --version |
See Features for desktop app details.
Related Projects
- vibemon-esp32 - ESP32 hardware display firmware
- vibemon-web - Cloud dashboard & API (vibemon.io)
- vibemon-docs - Agent hook installation & setup guide (vibemon.io/docs)
License
MIT