Living Tree

A botanical forest that grows in your terminal as you use Claude Code. Each session sprouts a tree. Every tool call — edits, searches, commits — makes it grow. Flowers bloom, fireflies orbit, and snow falls as your context window fills.

Built for iTerm2. Inspired by 18th-century naturalist lithographs.

Growth Stages

Trees grow through distinct stages based on total tool usage in a session:

Stage	Tool Uses	Appearance
Seed	0	A small seed on bare ground
Sprout	1-10	A tiny shoot
Sapling	10-50	Young trunk with first leaves
Canopy	50-120	Leafy branches, first flowers
Blooming	120-400	Full canopy with roses, sunflowers, peonies
Mature	400-1000	Thick trunk, dense foliage, fireflies
Elder	1000+	Ancient grove with moss, mushrooms, birds

Seasons

The forest changes with your context window. As context fills up, winter arrives — snow accumulates on branches, falls from the sky, and fireflies retreat.

Installation

Quick Install (recommended)

git clone https://github.com/mishkaechoes/livingtree.git
cd livingtree
bash install.sh

This creates a Python virtual environment, installs Pillow, and adds shell aliases.

Manual Install

git clone https://github.com/mishkaechoes/livingtree.git
cd livingtree
python3 -m venv venv
venv/bin/pip install Pillow

# Add to your shell rc:
alias livingtree="$(pwd)/venv/bin/python3 $(pwd)/forest.py"
alias livingtree-ascii="bash $(pwd)/tree-watch.sh"

Requirements

• Python 3.9+ with Pillow
• iTerm2 (for the pixel renderer) or any terminal (for ASCII mode)
• macOS (primary) — Linux support for the pixel renderer requires a Sixel-capable terminal
• jq (for the tracking hook)

Usage

Pixel Forest (iTerm2)

Open a separate iTerm2 pane and run:

livingtree

The forest renders as inline images at ~4 FPS. Trees sway, fireflies orbit, and shooting stars cross the sky.

ASCII Fallback

For terminals without inline image support:

livingtree-ascii

Split-Pane Launcher

Automatically opens Claude Code on the left and the living tree on the right:

bash launch.sh

Claude Code Integration

Living Tree tracks your Claude Code sessions via a PostToolUse hook. Add this to your Claude Code settings (~/.claude/settings.json):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "",
        "command": "bash /path/to/livingtree/hooks/track.sh"
      }
    ]
  }
}

Replace /path/to/livingtree with your actual install path.

What Gets Tracked

Tool	Botanical Element	Symbol
Edit	Roses (pruning)	(@)
Write	Sunflowers (new growth)	{*}
Grep/Glob	Hydrangeas (foraging)	{o}
Read	Ferns (studying)	\|/
Bash	Mushrooms (underground)	,.
Commit	Peonies (harvest)	<@>

Optional: Startup Banner

Add the bloom banner to your Claude Code startup:

{
  "hooks": {
    "PreToolUse": [],
    "PostToolUse": [
      {
        "matcher": "",
        "command": "bash /path/to/livingtree/hooks/track.sh"
      }
    ]
  }
}

Run bash hooks/bloom.sh in your shell profile for the banner on session start.

Optional: Status Line

See statusline.md for Claude Code status line integration.

Configuration

Edit config.json to tune performance and behavior. Changes take effect within 30 seconds (hot-reloaded).

{
  "max_render_width": 800,
  "target_fps": 4,
  "max_trees": 10,
  "max_fireflies_per_cluster": 8,
  "max_firefly_clusters": 4,
  "firefly_enabled": true,
  "shooting_stars_enabled": true,
  "snow_enabled": true
}

Parameter	Default	Description
max_render_width	800	Internal render width in pixels. Most impactful setting. iTerm2 upscales smoothly, so 800 is a good balance. Lower to 400-600 for less CPU.
target_fps	4	Target frames per second. 2-4 is ideal for ambient display.
max_trees	10	Maximum trees rendered regardless of active sessions.
max_firefly_clusters	4	Number of firefly clusters. Total fireflies = clusters x per_cluster.
max_fireflies_per_cluster	8	Fireflies per cluster. Boids algorithm is O(n^2) on total count.
firefly_enabled	true	Disable to save ~5-15ms per frame.
shooting_stars_enabled	true	Disable to save ~2-5ms during shooting star cycles.
snow_enabled	true	Disable to skip all winter/frost effects.

Performance

Frame Timing

Pane Size	Trees	Avg Render	With Fireflies	Notes
800x600	1	40-80ms	50-100ms	Comfortable target
800x600	3	100-200ms	120-240ms	Default config cap
1200x900	5	250-400ms	300-500ms	Retina half-res

Memory

• Base image (800x600 RGBA): ~1.9 MB
• Per tree (moderate depth): +0.5-2 MB transient
• Fireflies (32 boids): negligible
• Steady state for 3 trees: ~8-12 MB RSS

Optimizations

• Adaptive sleep: measures render time, sleeps only the remaining interval
• Frame skipping: reuses the previous frame when data hasn't changed
• Capped resolution: max_render_width limits the render buffer; iTerm2 upscales
• Firefly reinitialization: every 500 frames to prevent drift accumulation
• Session pruning: dead sessions detected via PID checks every 10s

Troubleshooting

High CPU: Lower max_render_width to 400, reduce target_fps to 2, reduce firefly counts.

Memory growth: Should not happen. If RSS exceeds 50 MB, check for orphaned /tmp/claude-garden-* files and restart.

Frame drops: The renderer uses adaptive sleep with a 20ms minimum to avoid busy-looping. Reduce tree count or render width if frames consistently exceed the target interval.

How It Works

1. Tracking hook (hooks/track.sh): A PostToolUse hook writes tool counts to /tmp/claude-garden-<session-id> and session labels to /tmp/claude-meta-<session-id>.

2. Forest renderer (forest.py): Reads all garden files, discovers active sessions, and renders a forest scene using Pillow. Each tree's size/depth/fullness is a function of total tool usage. Output via iTerm2 inline image protocol.

3. ASCII fallback (tree-watch.sh): Pure bash renderer using ANSI escape codes for terminals without inline image support.

4. Seasons: Context window remaining % maps to winter intensity. 90%+ = spring. Below 5% = deep winter with snow, frost, and frozen sway.

5. Health: Tree health degrades with staleness (time since last tool use) and rate limit pressure. Healthy trees are green and lush; dormant trees are skeletal.

License

MIT