# Vibe Music - Agent Context & Instructions

This document is designed to make Vibe Music easy to control from an agent or automation tool.

## Summary

Vibe Music is a terminal-based vibe engine:

- It plays audio through a detached background `mpv` process
- It searches YouTube via `yt-dlp`
- It supports developer vibes (focus/debug/build/deploy/late-night/hackathon)
- It can auto-pick vibes using time-of-day and git branch naming conventions

## Agent protocol (recommended order)

### 1) Discover capabilities

```bash
vibe commands
```

This outputs JSON describing the supported commands.

### 2) Read current player state

```bash
vibe agent
```

Expected JSON shape:

```json
{
  "status": "playing",
  "track": { "title": "Song Title", "url": "https://..." },
  "position": 125.5,
  "duration": 300.0,
  "volume": 100,
  "loop": false,
  "queue_length": 5
}
```

### 3) Prefer vibe-first control

When the user describes a coding state, prefer `vibe ...` over searching for specific tracks:

```bash
vibe focus
vibe debug
vibe build
vibe deploy --victory
vibe late-night
vibe hackathon
```

Notes:

- Vibe search results are cached (TTL) to keep automation fast and avoid repeated searches.
- Vibe playback is shufflable by default.
- Vibe results are filtered to English-like titles by default. Disable with `--lang any`.

### 4) Optional automation

Auto-pick a vibe (time + git branch) and switch when it changes:

```bash
vibe auto --repo .
```

Install optional git hooks in a repo:

```bash
cd /path/to/repo
vibe hooks install
```

Uninstall:

```bash
vibe hooks uninstall
```

React to errors while running a command:

```bash
vibe watch -- npm test
```

## Git branch mapping (used by `vibe branch` / `vibe auto`)

- `fix/`, `bug/`, `hotfix/` -> `debug`
- `feature/`, `feat/` -> `build`
- `release/`, `deploy/` -> `deploy`

## Classic playback controls

- `vibe pause`, `vibe resume`, `vibe toggle`, `vibe stop`
- `vibe next`, `vibe back`, `vibe replay` (or `vibe 0`)
- `vibe queue`, `vibe clear`

Quick flags (single-arg shortcuts):

- `vibe -n` -> next
- `vibe -b` -> back
- `vibe -q` -> queue
- `vibe -c` -> clear
- `vibe -p` -> pause

## Local state model

Source code:

- `src/yit/__init__.py`: CLI + IPC + vibe engine
- `src/yit/__main__.py`: entrypoint module used by the `vibe` script

Runtime files under `~/.yit/`:

- `results.json`: last search results (used by `play`/`add`)
- `history.json`: persistent history/title cache
- `vibe_cache.json`: cached results per vibe
- `vibe_state.json`: current vibe + timestamp
- `vibe_stats.json`: XP/streak/vibe counts (for `vibe card`)

## Critical rules for agents

1. Prefer `vibe ...` when the user expresses a developer state.
2. Use `vibe agent` before making play/pause decisions if correctness matters.
3. Avoid repeated searches; use caching and existing state when possible.
