ascii-garden

An ambient terminal garden that visualizes Claude Code agents as wandering avatars in a procedurally-generated ASCII world.

    ╭─────────╮    ✿ Sunflower   ❁ Camellia    桜 Sakura
    │ garden  │    Y Tulip       ☘ Clover      菊 Chrysanthemum
    │  ┌───┐  │    % Rose        ⚜ Fleur       竹 Bamboo
    │  │ . │  │    o Daisy       T Mushroom     梅 Plum
    │  └───┘  │    ; Lavender    f Fern         蘭 Orchid
    ╰─────────╯    ^ Carrot      | Cactus       松 Pine

Agents are auto-discovered from running tmux sessions. Walk around the garden, check what each agent is working on, and open a live chat pane to interact with them directly.

Install

Requires Python 3.10+ and uv.

uv sync

Optional: tmux for agent auto-discovery and the embedded chat pane.

Usage

# Launch the garden viewer
garden

# Or run as a module
python -m garden

Controls

Key	Action
WASD / arrow keys	Move around
TAB	Toggle agent roster
ENTER	Chat with nearest agent (or selected in roster)
ESC	Close chat / roster
F2	Cycle chat layout (auto / bottom / side)
Q	Quit

Subcommands

# Register a test agent
garden join -n "Claude" -s "Refactoring auth" -p my-project --color cyan

# List active agents
garden list

How it works

World generation — Each session generates a garden with randomized plots, paths (connected via MST routing), ponds, streams, fences, and buildings. Plants are placed in themed clusters (Flower Garden, Vegetable Patch, Wild Growth, Zen Garden) using flood-fill from seed cells.

Agent discovery — Two sources, merged at render time:

1. tmux — Scans all tmux panes for claude processes. Extracts cwd, session info, and CPU usage. Reads Claude's session logs to display the last user prompt as agent status.
2. File-based — Agents write JSON heartbeat files to ~/.garden/agents/. Stale agents (>30s without heartbeat) are culled. Useful for non-tmux integrations.

Each agent gets a building in the garden keyed to their repo/worktree, a colored 3x2 ASCII sprite, and a speech bubble showing their name, project, and current status.

Chat pane — Pressing ENTER opens a live view of the agent's tmux pane, rendered via pyte (a VT100 terminal emulator). Keystrokes are forwarded through tmux send-keys. Full color and attribute support.

Project structure

garden/
├── app.py        # World generation, rendering, main curses loop
├── agents.py     # Agent presence, tmux discovery, heartbeat files
├── chat.py       # Embedded tmux pane viewer via pyte
├── plants.py     # Plant catalog (ASCII, Unicode, CJK glyphs)
└── __main__.py   # CLI entry point and subcommands

Dependencies

• pyte (>=0.8) — VT100 terminal emulation for the chat pane
• curses — TUI rendering (stdlib)
• tmux — Agent discovery and chat (optional, graceful fallback)