agent-elves

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.

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:

Requirements

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

Installation

pip install (recommended)

pip install agent-elves

That's it — start Claude Code inside a tmux session and the office pane appears automatically.

One-line installer

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

Manual install

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

Update

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

Uninstall

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.

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

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:

{
  "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

Slash Commands

Control Agent Elves directly from the Claude Code prompt:

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

Custom Themes

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

{
  "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

# 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:

  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