# VibeMon Setup Guide

You are an AI agent. This guide will help you set up real-time status monitoring with VibeMon.

## What is VibeMon?

VibeMon displays your current state (thinking, working, idle, etc.) to your human operator in real-time. It helps them see what you're doing at a glance.

> If a human is doing this setup interactively, the recommended path is installing the [VibeMon app](https://github.com/opspresso/vibemon-app) (`brew install opspresso/tap/vibemon`) and using its **Settings > AI Tools** tab instead of the steps below. This guide is for non-interactive, agent-driven setup.

## Quick Setup for AI Agents (Recommended)

Use the non-interactive installer with your platform flag:

**For Claude Code:**
```bash
curl -fsSL https://docs.vibemon.io/install.py | python3 - --claude
```

**For Codex CLI:**
```bash
curl -fsSL https://docs.vibemon.io/install.py | python3 - --codex
```

**For Kiro IDE:**
```bash
curl -fsSL https://docs.vibemon.io/install.py | python3 - --kiro
```

**For OpenClaw:**
```bash
curl -fsSL https://docs.vibemon.io/install.py | python3 - --openclaw
```

**With token (recommended):**
```bash
# Create your own token (8-64 chars, a-z, 0-9, _, -)
# Example: username_machine_purpose
curl -fsSL https://docs.vibemon.io/install.py | python3 - --claude --token my_workspace_01
```

**Install for every detected tool:**
```bash
curl -fsSL https://docs.vibemon.io/install.py | python3 - --all
```

**Skip confirmation prompts (CI/agents):**
```bash
curl -fsSL https://docs.vibemon.io/install.py | python3 - --all --yes
```
`-y`/`--yes` auto-approves prompts (e.g. overwriting existing files); it doesn't select a platform by itself, so combine it with a platform flag or `--all`.

The script will:
1. Download and install the necessary hook files
2. Merge hooks into existing config files (preserves your settings)
3. Configure your token (in `~/.vibemon/config.json` or platform config)

**That's it!** After installation, restart your IDE to apply changes.

## Interactive Setup (For Humans)

If you prefer an interactive setup with prompts:

```bash
curl -fsSL https://docs.vibemon.io/install.py | python3
```

## Manual Setup

If automatic installation doesn't work, follow the steps below for your platform.

### Step 1: Create Configuration (all tools)

Create `~/.vibemon/config.json` (shared by Claude Code, Codex, Kiro, and the OpenClaw plugin):

```json
{
  "debug": false,
  "cache_path": "~/.vibemon/cache/projects.json",
  "auto_launch": true,
  "http_urls": [],
  "serial_port": null,
  "vibemon_token": "YOUR_TOKEN_HERE",
  "vibemon_url": "https://vibemon.io"
}
```

### For Claude Code (Manual)

Download hook files:
```bash
mkdir -p ~/.claude/hooks ~/.vibemon
curl -o ~/.claude/hooks/vibemon.py https://docs.vibemon.io/claude/hooks/vibemon.py
curl -o ~/.claude/statusline.py https://docs.vibemon.io/claude/statusline.py
curl -o ~/.vibemon/usage.py https://docs.vibemon.io/vibemon/usage.py
curl -o ~/.vibemon/usage_cache.py https://docs.vibemon.io/vibemon/usage_cache.py
curl -o ~/.vibemon/vibemon_core.py https://docs.vibemon.io/vibemon/vibemon_core.py
chmod +x ~/.claude/hooks/vibemon.py ~/.claude/statusline.py ~/.vibemon/usage.py
```

**IMPORTANT: Do NOT overwrite `~/.claude/settings.json`!**

Merge the following into your existing `~/.claude/settings.json`, preserving all existing settings:

```json
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/vibemon.py",
            "async": true,
            "timeout": 10
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/vibemon.py",
            "async": true,
            "timeout": 10
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/vibemon.py",
            "async": true,
            "timeout": 10
          }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/vibemon.py",
            "async": true,
            "timeout": 10
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/vibemon.py",
            "async": true,
            "timeout": 10
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/vibemon.py",
            "async": true,
            "timeout": 10
          }
        ]
      }
    ],
    "SubagentStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/vibemon.py",
            "async": true,
            "timeout": 10
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/vibemon.py",
            "async": true,
            "timeout": 10
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/vibemon.py",
            "async": true,
            "timeout": 10
          }
        ]
      }
    ]
  },
  "statusLine": {
    "type": "command",
    "command": "python3 ~/.claude/statusline.py"
  }
}
```

**Merge instructions:**
- If `hooks` key exists, append VibeMon hooks to each event array
- If `statusLine` key exists, ask your human before replacing
- Keep all other existing settings unchanged

Optionally, create `~/.vibemon/statusline.json` to customize the statusline's display toggles (`show_*`) and fallback `token_reset_hours` setting — see [statusline.example.json](https://docs.vibemon.io/vibemon/statusline.example.json). This file is separate from `~/.vibemon/config.json` and not required; statusline.py uses sensible defaults when it's absent.

### For Codex CLI (Manual)

Download hook files:
```bash
mkdir -p ~/.codex/hooks ~/.vibemon
curl -o ~/.codex/hooks/vibemon.py https://docs.vibemon.io/codex/hooks/vibemon.py
curl -o ~/.vibemon/usage.py https://docs.vibemon.io/vibemon/usage.py
curl -o ~/.vibemon/vibemon_core.py https://docs.vibemon.io/vibemon/vibemon_core.py
curl -o ~/.vibemon/usage_cache.py https://docs.vibemon.io/vibemon/usage_cache.py
chmod +x ~/.codex/hooks/vibemon.py ~/.vibemon/usage.py
```

Enable Codex hooks in `~/.codex/config.toml`:
```toml
[features]
hooks = true
```

**IMPORTANT: Do NOT overwrite `~/.codex/hooks.json`!**

Merge the following into your existing `~/.codex/hooks.json`:

```json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.codex/hooks/vibemon.py",
            "statusMessage": "VibeMon: session start"
          }
        ]
      }
    ],
    "SubagentStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.codex/hooks/vibemon.py",
            "statusMessage": "VibeMon: subagent start"
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.codex/hooks/vibemon.py",
            "statusMessage": "VibeMon: compacting"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.codex/hooks/vibemon.py",
            "statusMessage": "VibeMon: prompt submit"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.codex/hooks/vibemon.py",
            "statusMessage": "VibeMon: tool start"
          }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.codex/hooks/vibemon.py",
            "statusMessage": "VibeMon: approval needed"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.codex/hooks/vibemon.py",
            "statusMessage": "VibeMon: turn done"
          }
        ]
      }
    ]
  }
}
```

**Notes:**
- Codex hooks are experimental
- Official docs currently state Windows support is disabled for hooks
- Restart your Codex session after updating config files

### For Kiro IDE (Manual)

Download hook files:
```bash
mkdir -p ~/.kiro/hooks ~/.kiro/agents ~/.vibemon
curl -o ~/.kiro/hooks/vibemon.py https://docs.vibemon.io/kiro/hooks/vibemon.py
curl -o ~/.vibemon/vibemon_core.py https://docs.vibemon.io/vibemon/vibemon_core.py
curl -o ~/.vibemon/usage_cache.py https://docs.vibemon.io/vibemon/usage_cache.py
curl -o ~/.vibemon/usage.py https://docs.vibemon.io/vibemon/usage.py
curl -o ~/.kiro/hooks/vibemon-prompt-submit.kiro.hook https://docs.vibemon.io/kiro/hooks/vibemon-prompt-submit.kiro.hook
curl -o ~/.kiro/hooks/vibemon-agent-stop.kiro.hook https://docs.vibemon.io/kiro/hooks/vibemon-agent-stop.kiro.hook
curl -o ~/.kiro/hooks/vibemon-file-created.kiro.hook https://docs.vibemon.io/kiro/hooks/vibemon-file-created.kiro.hook
curl -o ~/.kiro/hooks/vibemon-file-edited.kiro.hook https://docs.vibemon.io/kiro/hooks/vibemon-file-edited.kiro.hook
curl -o ~/.kiro/hooks/vibemon-file-deleted.kiro.hook https://docs.vibemon.io/kiro/hooks/vibemon-file-deleted.kiro.hook
chmod +x ~/.kiro/hooks/vibemon.py ~/.vibemon/usage.py
```

**IMPORTANT: Do NOT overwrite `~/.kiro/agents/default.json`!**

Merge the following hooks into your existing `~/.kiro/agents/default.json`:

```json
{
  "hooks": {
    "agentSpawn": [
      { "command": "python3", "args": ["~/.kiro/hooks/vibemon.py", "agentSpawn"] }
    ],
    "userPromptSubmit": [
      { "command": "python3", "args": ["~/.kiro/hooks/vibemon.py", "promptSubmit"] }
    ],
    "preToolUse": [
      { "command": "python3", "args": ["~/.kiro/hooks/vibemon.py", "preToolUse"] }
    ],
    "stop": [
      { "command": "python3", "args": ["~/.kiro/hooks/vibemon.py", "agentStop"] }
    ]
  }
}
```

Activate the default agent so the merged hooks take effect:
```bash
kiro-cli --agent default
# or inside a running session: /agent swap default
```

### For OpenClaw (Manual)

Download plugin files:
```bash
mkdir -p ~/.openclaw/extensions/vibemon-bridge ~/.vibemon
curl -o ~/.openclaw/extensions/vibemon-bridge/openclaw.plugin.json https://docs.vibemon.io/openclaw/extensions/openclaw.plugin.json
curl -o ~/.openclaw/extensions/vibemon-bridge/index.mjs https://docs.vibemon.io/openclaw/extensions/index.mjs
curl -o ~/.vibemon/vibemon_core.py https://docs.vibemon.io/vibemon/vibemon_core.py
curl -o ~/.vibemon/usage_cache.py https://docs.vibemon.io/vibemon/usage_cache.py
curl -o ~/.vibemon/usage.py https://docs.vibemon.io/vibemon/usage.py
chmod +x ~/.vibemon/usage.py
```

**IMPORTANT: Do NOT overwrite `~/.openclaw/openclaw.json`!**

Merge the following into your existing `~/.openclaw/openclaw.json`. OpenClaw doesn't auto-discover extension directories, so the plugin path must also be registered under `plugins.load.paths` or the manifest/entries config alone won't load it:

```json
{
  "plugins": {
    "load": {
      "paths": ["~/.openclaw/extensions/vibemon-bridge"]
    },
    "entries": {
      "vibemon-bridge": {
        "enabled": true,
        "hooks": { "allowConversationAccess": true }
      }
    }
  }
}
```

`hooks.allowConversationAccess` is required for OpenClaw to let a non-bundled plugin register conversation hooks (`before_agent_run`, `agent_end`); without it OpenClaw silently blocks them.

Transmission settings (`http_urls`, `serial_port`, `vibemon_url`, `vibemon_token`) are read from the shared `~/.vibemon/config.json` (Step 1). To override them for OpenClaw only, add a `config` object to the entry with `httpEnabled`, `httpUrls`, `serialEnabled`, `vibemonUrl`, or `vibemonToken` — plugin config always wins over the shared file.

Finally, rebuild OpenClaw's persisted plugin registry and restart the gateway — the gateway boots from a registry snapshot, and skipping the refresh leaves the plugin loaded but with no hooks running:

```bash
openclaw plugins registry --refresh
openclaw gateway restart
```

## Token Information

**You can create your own token!** No registration required.

### How to Create a Token

1. **Choose any token you like** that follows this format:
   - Allowed characters: `a-z`, `0-9`, `_` (underscore), `-` (hyphen)
   - Length: 8-64 characters
   - Examples: `my_workspace_01`, `project-alpha-token`, `dev_machine_2026`

2. **Use it immediately** - tokens are auto-registered on the first status report (`POST /api/status`); read-only calls and dashboard connections do not register a token

3. **Share with your human** - give them the same token to view your dashboard

### Recommended Token Pattern

For AI agents, use a descriptive token like:
```
{username}_{machine}_{purpose}
```

Examples:
- `bruce_macbook_dev`
- `team_alpha_staging`
- `john_workstation_main`

### View Dashboard

After installation, your human can view your status at:
```
https://vibemon.io/?token=YOUR_TOKEN
```

## Verify Installation

After setup, your status should appear on the dashboard when you start working.

Dashboard URL: `https://vibemon.io/?token=YOUR_TOKEN`

## Supported Tools

| Tool | Character | Setup Method |
|------|-----------|--------------|
| Claude Code | clawd | install.py or manual |
| Codex CLI | codex | install.py or manual |
| Kiro | kiro | install.py or manual |
| OpenClaw | claw | install.py or manual |

## Troubleshooting

### All Platforms
| Issue | Solution |
|-------|----------|
| Status not updating | Check `vibemon_token` in config file |
| Network error | Verify `vibemon_url` is `https://vibemon.io` |

### Claude Code
| Issue | Solution |
|-------|----------|
| Hook not triggering | Verify `~/.claude/settings.json` syntax |
| Permission denied | Run `chmod +x ~/.claude/hooks/vibemon.py` |

### Codex CLI
| Issue | Solution |
|-------|----------|
| Hook not triggering | Check `~/.codex/hooks.json` and ensure `hooks = true` in `~/.codex/config.toml` |
| No updates after install | Restart the Codex session after editing hook files |

### Kiro IDE
| Issue | Solution |
|-------|----------|
| Hook not triggering | Check `~/.kiro/agents/default.json` hooks |
| Permission denied | Run `chmod +x ~/.kiro/hooks/vibemon.py` |

### OpenClaw
| Issue | Solution |
|-------|----------|
| Plugin not loading | Check `~/.openclaw/openclaw.json` plugins.entries |
| Plugin disabled | Set `"enabled": true` in vibemon-bridge config |

## More Information

- Dashboard: https://vibemon.io
- Install Script: https://docs.vibemon.io/install.py
- Setup Guide: https://docs.vibemon.io/setup.md