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 | | OpenCode | Open-source AI coding agent for the terminal |

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 | | OpenCode | Plugin + Python adapter | Broad | Session, tool, permission, and compaction events; no usage metrics |

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 --json remains 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.
• OpenCode: Its auto-discovered plugin sends events through a Python adapter and the shared VibeMon transport. Restart OpenCode after installing or updating the plugin.

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 (Node.js 24):

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, OpenClaw, or OpenCode — this sets up the hooks and collector config for you, no separate installer needed. OpenClaw installation is currently unsupported on Windows. See Settings Window for details.

Tool detection and hook paths honor CLAUDE_CONFIG_DIR, CODEX_HOME, KIRO_HOME, and OPENCODE_CONFIG_DIR. OpenCode defaults to $XDG_CONFIG_HOME/opencode, falling back to ~/.config/opencode. Kiro is detected through either kiro or kiro-cli. Environment overrides must be available to the Desktop App process as well as the tool.

Development

Use Node.js 24 and pnpm. Run nvm use to select the version in .nvmrc before installing dependencies or running project commands.

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) |

OpenCode sends character: "opencode". The current canonical registry has no dedicated OpenCode character, so its status displays as vibemon. Character Lock can select any registered character.

The Color column is each character's overall look. This is distinct from the per-character color in 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