Metadata-Version: 2.4
Name: agent-elves
Version: 0.1.0
Summary: ASCII art office animation plugin for Claude Code — watch your AI agents work in a tmux pane
Author: Nickdevlab
License-Expression: MIT
Project-URL: Homepage, https://github.com/wongo/agent-elves
Project-URL: Repository, https://github.com/wongo/agent-elves
Keywords: claude-code,plugin,ascii-art,animation,tmux,curses
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: User Interfaces
Classifier: Topic :: Games/Entertainment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Dynamic: license-file

# Agent Elves

```
     _                    _     _____ _
    / \   __ _  ___ _ __ | |_  | ____| |_   _____  ___
   / _ \ / _` |/ _ \ '_ \| __| |  _| | \ \ / / _ \/ __|
  / ___ \ (_| |  __/ | | | |_  | |___| |\ V /  __/\__ \
 /_/   \_\__, |\___|_| |_|\__| |_____|_| \_/ \___||___/
         |___/
```

A Claude Code plugin that spawns an ASCII art animated office in a tmux pane, visualizing your AI agents hard at work in real-time — typing, running around, thinking, and celebrating as they complete tasks.

Pure entertainment. Zero productivity gains. Maximum vibes.

![Agent Elves Demo](demo.gif)

## Features

- Animated ASCII office that reacts to Claude Code activity in real-time
- **10-level office progression** (Game Dev Story inspired): start from a garage with 1 elf, grow to a dream office with 4 elves and full decorations
- **LEVEL UP! animation**: screen flash + ASCII art banner + furniture pop-in reveal (1 new surprise per level)
- **Auto-upgrade**: office evolves as you complete tasks (Lv.10 requires ~220 tasks — a full day of heavy usage)
- **Persistent unlock**: cumulative task count saved across sessions; manually select any unlocked level; reset progress option
- **Protagonist system**: first elf is you — `Nick(Opus)` format with name from git config + current model; role "lead" handles all tools
- **2.5D Y-sort rendering**: painter's algorithm depth sorting — near objects correctly occlude far ones, true perspective feel
- **First-launch welcome**: animated introduction with feature overview
- **Auto/manual startup**: choose whether the office opens automatically or via `/agent-elves-start`
- **Startup intro**: dark office → first elf turns on lights → others arrive and greet
- **Shutdown outro**: elves say goodbye → last one turns off lights → pane closes
- **Plan mode**: protagonist leads whiteboard meeting, regular elves attend, contractors keep working
- Comic-style speech and thought bubbles show current tasks
- **Live task whiteboard**: elf name + mini progress bar + elapsed time, WORKING/DONE split with per-elf colors, adaptive name display
- **Role-based task assignment** with load balancing: protagonist (lead), engineer, researcher, ops, designer specializations
- **Dual-line desk nameplates**: name on top, model/type below — 8-character wide desks
- **Agent Smith contractors**: sub-agents (`Agent`/`TeamCreate`/`SendMessage`) spawn as Matrix-style `_===_ (|■ ■|)` named `Smith(type)` — greet, set up portable desk, work, idle 8s at desk, pack up, leave
- **Super Saiyan Skill animation**: Skill tools trigger a DBZ power-up (protagonist priority) — crouch + `⚡` → "HAAA!!!!" → golden burst with scouter `POWER: 9000+` → persistent `A_BOLD` glow
- **Per-desk monitor states**: screens show typing animation (`▪▫`↔`▫▪`), thinking cursor (`_|`↔`|_`), idle (`▪▪`), or off (`▫▫`)
- **Pomodoro timer**: 25/5-minute work-break cycles with banner animations (FOCUS TIME / BREAK TIME / BACK TO WORK) + terminal bell on transitions
- **Achievement system**: 14 achievements tracking milestones (task counts, all-nighter, power-up master, Smith encounters, and more)
- **7 expression states**: STRETCHING (auto after 45s typing), SLEEPY (night mode 23:00-06:00), EXCITED (3-task streak), FRUSTRATED (tool errors), HIGH_FIVE (dual completion), READING (Read/Grep/Glob), SNACKING (random idle)
- **Elf personality**: each tool action starts with a random reaction line — "收到！", "又來？！", "小事一樁！" etc. (12 reactions × 4 languages = 48 personality lines)
- **Weather system**: live weather API with rain/snow animated inside office windows
- **Dynamic HUD bar**: auto 1-2 row header with 🕐 time, 📅 date, weather, city, ⏱️ elapsed, Pomodoro, ⚡ tasks/hr, 🌟 level
- **Custom theme editor**: press `E` in theme picker to design your own characters — sprite grid editor, live preview, template copy, name/label editing
- **Elf interactions**: coffee chat (stand left of machine, not blocking), return to desk after break
- **Idle chatter**: elves constantly mumble dev jokes — "LGTM", "Ship it!", "Works on my machine", "git push --force"...
- **Matrix easter eggs**: Agent Smith clone attack ("Me, me, me..."), kung fu fight (`━→`), bullet time with slow-mo dodge ("Whoa.") — triggered during Smith's 8s idle window
- **Easter eggs**: pizza delivery, office cat, sleepy elves Zzz, and more
- **Time-of-day atmosphere**: morning / afternoon / evening / night
- **Statistics dashboard** (press `d`): session stats, office level, tasks/hour, Pomodoro status, 14 achievements with lock/unlock display, elf leaderboard with bar charts
- 5 character themes + **custom theme editor**: **Claude**, **Kaomoji**, **Pixel RPG**, **Samurai**, **Space**, or design your own
- 4 display languages: **English**, **Japanese**, **Chinese**, **Korean**
- In-app settings menu with ASCII art logo and animated previews
- Zero dependencies — Python 3.10+ standard library only
- Graceful degradation — silently disabled outside tmux

## Character Themes

Pick a style on first launch or press `s` anytime to change:

### 1. Claude (default)

Rounded, warm design inspired by the Claude.ai avatar.

```
  .---.          .---.          .---.          .---.         .---.
 ( o o )        ( >_< )        ( . . )        ( o o )>     ( ^o^ )
  ( u )          ( u )|         ( ~ )?         ( u )       \( v )/
   /\             ||             /\             />/>         /\
  idle           typing        thinking       walking     celebrating
```

Protagonist: **You(Model)** — colleagues get random names from a pool

### 2. Kaomoji

Lightweight Japanese emoticon style — smallest footprint.

```
 (^_^)         (>_<)         (._.)>        (^_^)>       \(^o^)/
  /|\           /|~           /|\            /|/            |
  / \           ||            / \             >>           / \
  idle         typing       thinking       walking     celebrating
```

Agents: **Mochi** / **Anko** / **Daifuku** / **Kinako** / **Sakura**

### 3. Pixel RPG

Retro 8-bit game character style.

```
 [@@]          [@@]          [@@]          [@@]          *[@@]*
 |oo|          |><|          |..|          |oo|>         +|^^|+
 [==]          [==]~         [==]?         [==]           [==]
  ||            ||            ||            |>            /||\
  /\            ||            /\            /             /  \
  idle         typing       thinking      walking     celebrating
```

Agents: **Player1** / **Player2** / **NPC_A** / **NPC_B** / **Boss**

### 4. Samurai

Japanese warriors — samurai, ninja, and kimono style.

```
  /|\          /|\          /|\          /|\         \|/
 (o_o)        (>.<)        (._.)>      (o_o)>      (^o^)
 /|=|\        /|=|~        /|=|\       /|=|/       \|=|/
  / \          | |          / \         /> />        / \
  idle        typing      thinking    walking    celebrating
```

Agents: **Musashi** / **Hanzo** / **Sakura** / **Kaede** / **Ryu**

### 5. Space

Astronauts, aliens, and robots in outer space.

```
  ,-.          ,-.          ,-.          ,-.        *,-.*
 {o o}        {>_<}        {. .}?      {o o}>     \{^o^}/
 /| |\        /| |~        /| |\       /| |/        | |
  d b          | |          d b         > >          d b
  idle        typing      thinking    walking    celebrating
```

Agents: **Astro** / **Zeta** / **Nova** / **Cosmo** / **Orbit**

## Display Languages

Bubble text and status bar adapt to your chosen language:

| Language | Editing | Done | Status bar |
|---|---|---|---|
| English | Editing app.tsx | Done! | Agents: 3 |
| Japanese | 編集中 app.tsx | 完了！ | エージェント: 3 |
| Chinese | 編輯中 app.tsx | 完成！ | 小精靈: 3 |
| Korean | 편집 중 app.tsx | 완료! | 에이전트: 3 |

## Requirements

- Python 3.10+
- tmux 3.0+
- Claude Code with plugin support

## Installation

### One-line install (recommended)

```bash
curl -fsSL https://raw.githubusercontent.com/wongo/agent-elves/main/install.sh | bash
```

The installer will:
- Clone the repo to `~/.claude/plugins/marketplaces/agent-elves/`
- Register it as a Claude Code marketplace plugin
- Enable the plugin in `settings.json`
- Verify Python and tmux are available

### pip install

```bash
pip install agent-elves
```

### Manual install

```bash
git clone https://github.com/wongo/agent-elves.git ~/.claude/plugins/marketplaces/agent-elves
```

Then start Claude Code inside a tmux session — the office pane appears automatically.

### Update

```bash
cd ~/.claude/plugins/marketplaces/agent-elves && git pull
```

### Uninstall

```bash
bash ~/.claude/plugins/marketplaces/agent-elves/uninstall.sh
```

## Office Levels

The office evolves as you work! Each session starts at Lv.1 and upgrades automatically as tasks are completed. Unlock records persist across sessions.

| Lv | Name | Tasks | Elves | New Furniture |
|----|------|-------|-------|---------------|
| 1 | Garage | 0 | 1 | Door, Coffee machine, Whiteboard |
| 2 | Home Office | 5 | 1 | +Bookshelf |
| 3 | Small Office | 12 | 2 | +Plant |
| 4 | Growing Office | 22 | 2 | +Trophy case |
| 5 | Studio | 35 | 3 | +Sofa |
| 6 | Creative Studio | 55 | 3 | +Arcade |
| 7 | Tech Company | 80 | 3 | +Bar |
| 8 | Big Tech | 115 | 4 | +Spin Bike |
| 9 | Enterprise | 160 | 4 | +Server rack |
| 10 | Dream Office | 220 | 4 | +Gold trophy wall |

Reaching Lv.10 in a single session requires ~220 tool completions — about a full day of heavy Claude Code usage.

Press `s` to manually select any unlocked level, or leave it on **Auto** to let the office grow naturally.

## Configuration

### First launch

On first launch, Agent Elves shows an animated welcome screen introducing the plugin and its features, then walks you through setup:

1. **Theme** — Choose character style (Claude / Kaomoji / Pixel RPG / Samurai / Space / Custom)
2. **Language** — Choose display language (EN / JA / ZH / KO)
3. **Office** — Choose office level (Auto / manually select an unlocked level)
4. **Startup mode** — Choose how the office opens:
   - **Auto-start** — Office opens automatically when Claude Code starts
   - **Manual start** — You open it yourself with `/agent-elves-start`

All choices are saved to `~/.config/agent-elves/config.json` and can be changed anytime.

### Settings menu

Press `s` in the animation pane at any time to open the settings wizard. Navigate with arrow keys + Enter. Auto-selects default after 15s timeout.

### Environment variables

```bash
export CLAUDE_OFFICE_THEME=kaomoji   # claude | kaomoji | pixel
export CLAUDE_OFFICE_LANG=ja         # en | ja | zh | ko
```

### Config file

Settings persist to `~/.config/agent-elves/config.json`:

```json
{
  "theme": "claude",
  "lang": "zh",
  "autostart": "auto",
  "office": "auto",
  "total_tasks": 0,
  "unlocked_offices": ["garage"],
  "user_name": "Nick"
}
```

- `office`: `"auto"` (upgrade as you work) or any level key (e.g. `"studio"`, `"dream_office"`)
- `total_tasks`: cumulative task count across all sessions (used for unlock thresholds)
- `unlocked_offices`: levels permanently unlocked by reaching cumulative task thresholds
- `user_name`: protagonist display name (defaults to `git config user.name` if not set)

### Pane layout

The office auto-adapts to the available pane size. Furniture and elf count are determined by the current office level, with graceful degradation on narrow terminals (some decorations are skipped below 50 columns).

Default split is 40% width. Adjust the `-l 40%` value in `hooks/session_start.py` if needed.

## How It Works

```
┌─────────────────────┐         ┌──────────────────────┐
│  Claude Code         │  Unix   │  Agent Elves          │
│  (main tmux pane)    │  Socket │  (split tmux pane)    │
│                     │  (IPC)  │                        │
│  SessionStart ──────│────────→│  Spawn office          │
│  PreToolUse  ───────│────────→│  Elf walks to desk     │
│  PostToolUse ───────│────────→│  Elf celebrates        │
│  SessionEnd  ───────│────────→│  Shutdown + cleanup    │
└─────────────────────┘         └──────────────────────┘
```

1. **SessionStart** hook opens a new tmux pane and starts the animation engine
2. **PreToolUse** hooks forward tool events (Bash, Edit, Read, Grep...) via a Unix datagram socket
3. The engine maps events to character actions:
   - `Bash` / `Edit` / `Write` — elf runs to desk and types furiously
   - `Read` / `Grep` / `Glob` — elf sits and thinks with a `?` bubble
   - `Agent` — new elf enters through the office door
   - Tool completes — brief celebration hop
4. **SessionEnd** hook sends a shutdown signal and cleans up the pane

All hooks are fire-and-forget. If the animation crashes or isn't running, hooks exit silently with zero impact on Claude Code.

## Agent Behavior

| Event | What the elves do |
|---|---|
| Tool starts (write/execute) | Run to desk, type with focused face `(>_<)`, monitor blinks `▪▫`↔`▫▪` |
| Tool starts (read/search) | Sit down, think with `?` thought bubble, monitor shows cursor `_|`↔`|_` |
| Tool completes | Celebration hop `\(^o^)/` with localized "Done!" bubble |
| Sub-agent spawned | Agent Smith `_===_ (|■ ■|)` enters as `Smith(type)`, sets up portable desk, works, idles 8s at desk, packs up, leaves |
| Team/SendMessage | Also triggers Smith entrance (expanded trigger scope) |
| Skill invoked | Super Saiyan power-up (protagonist priority): crouch + `⚡` → "HAAA!!!!" → scouter → `A_BOLD` glow |
| Smith idle near elf | Random Matrix easter egg: clone attack, kung fu fight `━→`, or bullet time `·` dodge |
| Plan mode enter | Protagonist leads whiteboard, regular elves attend, Smith keeps working |
| Plan mode exit | Elves celebrate and return to desks |
| Task threshold reached | LEVEL UP! animation with screen flash + furniture pop-in |
| Idle > 5 seconds | Wander around the office |
| Idle near another elf | Watercooler chat (then walk back to desk) |
| Coffee break | Grab coffee, then return to assigned desk |

## Slash Commands

Control Agent Elves directly from the Claude Code prompt:

| Command | Description |
|---|---|
| `/agent-elves-start` | Launch the office animation in a tmux pane |
| `/agent-elves-stop` | Shutdown animation and clean up |
| `/agent-elves-status` | Check running state, config, and crash log |
| `/agent-elves-settings` | View or change theme and language |

### Examples

```
/agent-elves-start                  # Launch the animation
/agent-elves-status                 # Check if running
/agent-elves-settings claude zh     # Set Claude theme + Chinese
/agent-elves-settings kaomoji ja    # Set Kaomoji theme + Japanese
/agent-elves-settings pixel en      # Set Pixel RPG theme + English
/agent-elves-stop                   # Shut it down
```

Running `/agent-elves-settings` with no arguments displays current settings and all available options.

## Keyboard Shortcuts

While the animation pane is focused (`Ctrl-b` + arrow key to switch panes):

| Key | Action |
|---|---|
| `s` | Open visual settings wizard (theme + language) |
| `d` | Statistics dashboard (stats, achievements, leaderboard) |
| `p` | Toggle Pomodoro timer (25/5-min cycles) |
| `q` | Trigger shutdown outro animation |
| Arrow keys | Navigate settings menu |
| `1`-`5` | Quick select in settings |
| `E` | Open custom theme editor (in theme picker) |

## Custom Themes

Create `~/.config/agent-elves/custom-theme.json` to define your own characters:

```json
{
  "name": "robots",
  "label": "My Robot Theme",
  "names": ["R2D2", "C3PO", "BB8", "K2SO", "HK47"],
  "sprites": {
    "idle":            [["  [=]  ", "  |o|  ", "  /#\\  "]],
    "typing":          [["  [=]  ", "  |>|~ ", "  |#|  "]],
    "thinking":        [["  [=]? ", "  |.|  ", "  /#\\  "]],
    "walking_right":   [["  [=]> ", "  |o|  ", "   >>  "]],
    "walking_left":    [[" <[=]  ", "  |o|  ", "  <<   "]],
    "celebrating":     [["\\[=]/  ", "  |^|  ", "  /#\\  "]],
    "coffee":          [["  [=]~ ", "  |o|c ", "  /#\\  "]]
  }
}
```

Your custom theme appears as the 6th option in the settings wizard.

### Interactive Editor

Press `E` in the theme picker to open the built-in editor:

- **Arrow keys**: move cursor / switch sprite states
- **Type**: edit ASCII characters directly
- **Tab**: cycle animation frames
- **+/-**: add/remove frames
- **t**: copy a built-in theme as starting point
- **n**: edit character names
- **l**: edit theme label
- **Enter**: save, **Esc**: cancel

## Project Structure

```
agent-elves/
├── .claude-plugin/
│   ├── plugin.json          # Plugin metadata
│   └── marketplace.json     # Marketplace registry
├── skills/                  # Slash commands
│   ├── start/SKILL.md       # /agent-elves-start
│   ├── stop/SKILL.md        # /agent-elves-stop
│   ├── status/SKILL.md      # /agent-elves-status
│   └── settings/SKILL.md    # /agent-elves-settings
├── hooks/
│   ├── hooks.json           # Hook definitions
│   ├── validate.py          # Shared input validation
│   ├── session_start.py     # Spawns tmux pane + animation
│   ├── activity_hook.py     # Forwards tool events via socket
│   └── session_end.py       # Outro animation + cleanup
├── engine/
│   ├── main.py              # Entry point, settings UI, main loop
│   ├── renderer.py          # Y-sorted curses renderer with painter's algorithm (~10fps)
│   ├── scene.py             # Data-driven office layout, task tracking, interactions
│   ├── levels.py            # 10-level office definitions (LevelDef dataclass)
│   ├── characters.py        # Character state machine, roles, movement (7 expression states)
│   ├── animation.py         # Intro/outro/upgrade/plan-mode sequence controllers
│   ├── atmosphere.py        # Time-of-day visual atmosphere
│   ├── sprites.py           # ASCII sprites (5+custom themes + furniture)
│   ├── bubbles.py           # Speech/thought bubbles + i18n (4 languages)
│   ├── pomodoro.py          # Pomodoro timer (25/5-min cycles, phase transitions)
│   ├── achievements.py      # 14 achievements with unlock tracking
│   ├── weather.py           # Live weather API + rain/snow window particles
│   └── ipc.py               # Unix domain socket listener
├── tests/                   # 78 unit tests
│   ├── test_bubbles.py
│   ├── test_characters.py
│   ├── test_scene.py
│   ├── test_atmosphere.py
│   ├── test_ipc.py
│   └── test_sprites.py
├── tools/
│   └── record_demo.py       # Demo recording script
├── pyproject.toml           # pip install support
├── LICENSE                  # MIT
├── install.sh               # One-line installer
├── uninstall.sh             # Uninstaller
└── README.md
```

## Development

```bash
# Run tests
pytest tests/ -v

# Record a demo
python3 tools/record_demo.py

# Play the demo
asciinema play demo.cast
```

## Troubleshooting

**Animation doesn't appear**
- Confirm you're inside tmux: `echo $TMUX` should print a value
- Check the plugin is enabled in `~/.claude/settings.json` under `enabledPlugins`
- Crash log: `cat /tmp/agent-elves-crash.log`

**Characters don't react to tool events**
- Check the socket is alive: `ls /tmp/co-*.sock`
- Send a test event manually:
  ```bash
  echo '{"type":"tool_pre","tool":"Bash","input":{"command":"hello"}}' \
    | python3 ~/.claude/plugins/marketplaces/agent-elves/hooks/activity_hook.py pre
  ```

**Garbled or broken rendering**
- Ensure your terminal supports UTF-8 and box-drawing characters
- Terminals known to work well: kitty, alacritty, iTerm2, Windows Terminal

**Animation pane too small**
- The office auto-switches to compact mode under 40 columns
- Resize the tmux pane: `Ctrl-b` then `:resize-pane -R 20`

## License

MIT

Copyright (c) 2025-2026 Nickdevlab
