AgentRoom

A desktop app that turns your AI coding agents into animated pixel art characters in a virtual office — with full session search, transcript browsing, and real-time activity monitoring across Claude Code, Codex, and Gemini.

# Prerequisites: Rust (rustup.rs), Node.js 18+, Xcode CLI tools (macOS) or webkit2gtk (Linux)

git clone --recursive https://github.com/liuyixin-louis/agentroom.git
cd agentroom

# Build the CASS search backend (~5 min, one-time)
./scripts/install-cass.sh
source ~/.zshrc

# Index your agent sessions
cass index --full

# Launch the app
npm install
npm run tauri dev

• Real-time agent visualization — each active coding agent gets its own animated character that types when writing code, reads when searching files, and idles when waiting for input
• Multi-agent support — Claude Code, Codex, and Gemini agents displayed simultaneously with distinct visual styles
• Work & idle rooms — active agents sit at desks in the Work Room; idle agents walk to the Break Room and hang out on couches
• Per-project focus — switch the office view to show only agents working on a specific project
• Session search & browsing — search across all agent sessions with full-text search powered by CASS, grouped by project
• Transcript viewer — click any session to read the full conversation in-app
• Open in Terminal — one-click "Open in iTerm2" button to jump straight into a session's working directory and resume the agent
• Sub-agent visualization — Task tool sub-agents spawn as separate characters linked to their parent
• Speech bubbles — visual indicators when an agent is waiting for input or needs permission approval
• Sound notifications — chime when an agent finishes its turn
• Token usage dashboard — real-time spend and rate limit tracking
• AI-powered session tagging — auto-summarize and categorize sessions
• Persistent layouts — office design is saved per project
• Claude Code skill — drop-in searching-agent-sessions skill lets you search past sessions from any Claude Code conversation (just copy to ~/.claude/skills/)

AgentRoom watches the JSONL transcript files that coding agents write to disk. A Rust file watcher (notify crate) detects new lines in real time and emits structured events to the frontend via Tauri's event system. The React frontend drives a Canvas 2D game engine with BFS pathfinding and a character state machine.

JSONL files (Claude/Codex/Gemini)
  -> Rust file watcher (notify + tokio)
    -> AgentStateManager (event dedup + state tracking)
      -> Tauri event bus
        -> React useAgentEvents hook
          -> OfficeState (Canvas 2D game engine)

Complete setup from a fresh machine to a running app.

macOS:

xcode-select --install

Linux (Debian/Ubuntu):

sudo apt update && sudo apt install -y \
  build-essential curl wget git \
  libwebkit2gtk-4.1-dev libgtk-3-dev libappindicator3-dev \
  librsvg2-dev patchelf libssl-dev

Linux (Fedora):

sudo dnf install -y \
  gcc gcc-c++ make curl wget git \
  webkit2gtk4.1-devel gtk3-devel libappindicator-gtk3-devel \
  librsvg2-devel openssl-devel

Skip if cargo --version already works.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"
rustc --version   # 1.85+ required (for Rust edition 2024)

Skip if node --version shows 18+.

# via nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source "$HOME/.nvm/nvm.sh"
nvm install 22

# or download directly from https://nodejs.org/

git clone --recursive https://github.com/liuyixin-louis/agentroom.git
cd agentroom

Already cloned without --recursive? Run git submodule update --init --recursive

CASS indexes and searches your coding agent session histories. It compiles from source into a single binary.

Option A -- Automated install (builds + adds to PATH):

./scripts/install-cass.sh
source ~/.zshrc   # or: source ~/.bashrc

Option B -- Manual build:

cd search-backend/cass
cargo build --release
# Binary: search-backend/cass/target/release/cass

# Install to PATH (pick one):
sudo cp target/release/cass /usr/local/bin/cass   # system-wide
# or: export PATH="$(pwd)/target/release:$PATH"   # session-only
cd ../..

Option C -- System-wide install (uses sudo):

./scripts/install-cass.sh --system

Verify: cass --version

The release build takes 3-8 minutes (LTO enabled). Subsequent builds are fast.

cass index --full       # scans all agent session directories
cass health --json      # verify index health

CASS auto-detects sessions from these agents:

npm install
npm run tauri dev

The pixel office window opens within seconds. Active coding agents appear as animated characters at desks.

npm run tauri build

Output: src-tauri/target/release/bundle/ (.app/.dmg on macOS, .deb/.AppImage on Linux).

Note on submodule access: The search backend submodules are hosted on GitHub. If they are private repos, you'll need SSH access configured. Public repos work with HTTPS out of the box.

CASS (Coding Agent Session Search) is the search engine powering AgentRoom's session search. It's bundled as git submodules under search-backend/.

Sub-10ms interactive search across 11+ coding agent histories via a multi-layer search stack:

search-backend/
|-- cass/                       # Search engine + interactive TUI
|-- asupersync/                 # Async runtime
|-- frankentui/                 # Terminal UI framework
|-- frankensearch/              # Lexical, semantic, and fusion search
|-- franken_agent_detection/    # Agent auto-detection (11 connectors)
+-- toon_rust/                  # Shared utilities

cass index --full                              # rebuild index
cass search "auth error"                       # keyword search
cass search "rate limiting" --mode hybrid      # lexical + semantic
cass timeline --since 7d                       # recent activity
cass tui                                       # interactive TUI
cass health --json                             # index health check

For programmatic / AI agent integration (JSON output):

cass search "query" --json --limit 20 --highlight
cass export "/path/to/session.jsonl" --format markdown

The repo includes a ready-to-use Claude Code skill that lets you search sessions from any Claude Code conversation — no desktop app needed.

# Install the skill (one-time)
cp -r skills/searching-agent-sessions ~/.claude/skills/

# Then in any Claude Code session, just ask:
#   "find my session about authentication"
#   "what did I discuss with gemini about rate limiting?"
#   "show recent codex sessions"

The skill handles cross-agent search, workspace resolution, subagent deduplication, and outputs ready-to-paste resume commands. See skills/searching-agent-sessions/README.md for details.

agentroom-visual/
|-- src/                        # React frontend
|   |-- office/                 # Game engine
|   |   |-- engine/             # Renderer, characters, pathfinding
|   |   |-- tilesets/           # TilesetManager, background gid map
|   |   |-- sprites/            # Character sprite data
|   |   +-- layout/             # Office layout serialization
|   |-- components/             # UI panels (SearchBar, SessionList, etc.)
|   |-- hooks/                  # useAgentEvents (core event bridge)
|   |-- services/               # CASS client, tag service
|   +-- bridge.ts               # Tauri invoke/listen bridge
|-- src-tauri/                  # Rust backend
|   +-- src/
|       |-- file_watcher.rs     # JSONL file watching + initial scan
|       |-- agent_state.rs      # Agent state machine + event emission
|       |-- commands.rs         # Tauri commands (CASS, tags, layout)
|       +-- transcript_parser.rs # JSONL line parsing
|-- search-backend/             # CASS search engine (git submodules)
|   |-- cass/                   # Main search binary + TUI
|   |-- asupersync/             # Async runtime
|   |-- frankentui/             # TUI framework
|   |-- frankensearch/          # Lexical + semantic + fusion search
|   |-- franken_agent_detection/ # Agent connector detection
|   +-- toon_rust/              # Utilities
|-- scripts/
|   |-- build-cass.sh           # Build CASS from source
|   +-- install-cass.sh         # Full install (build + PATH setup)
|-- skills/
|   +-- searching-agent-sessions/  # Claude Code skill (copy to ~/.claude/skills/)
+-- public/assets/              # Tilesets, character sprites

Search & Indexing:

• CASS by Jeffrey Emanuel -- unified search over local coding agent histories, plus the bundled asupersync, frankensearch, frankentui, franken_agent_detection, and toon_rust libraries
• Tantivy -- full-text search engine (BM25 inverted index) powering CASS lexical search
• FastEmbed -- MiniLM-384 embeddings for semantic search

Desktop & Framework:

• Tauri -- desktop app shell with Rust backend and web frontend
• iTerm2 -- "Open in iTerm2" terminal integration via AppleScript

Agent Integrations:

• Claude Code by Anthropic -- primary agent support
• Codex CLI by OpenAI -- Codex agent session support
• Gemini CLI by Google -- Gemini agent session support
• Aider by Paul Gauthier -- Aider session support
• Cline -- VS Code agent extension session support
• CodexBar by Peter Steinberger -- macOS menu bar usage stats for Codex/Claude/Gemini (token panel integration)

Visual Assets:

• Pixel Agents by Pablo de Lucca -- the original pixel art agent visualization (VS Code extension) from which the game engine is ported
• SkyOffice by Kevin Shen -- tileset assets (FloorAndGround, Modern_Office, Generic, Basement)
• LimeZu -- pixel art assets used in SkyOffice's tilesets
• JIK-A-4 (Metro City) -- character sprite base

MIT