zen-widget/README.md

Zen Widget

A floating ASCII companion that watches your terminal and comments on your work. Dead simple to install.

Current Status

Working: Terminal-based demo that displays the widget in your terminal.

Planned: Floating window version that stays on top of your terminal.

Installation

# 1. Clone
git clone https://github.com/yourname/zen-widget.git ~/zen-widget
cd ~/zen-widget

# 2. Build (requires Rust)
cargo build --release

# 3. Run
./target/release/zen-widget

Requirements

• macOS (window detection uses CGWindowList APIs)
• tmux (for terminal content analysis)
• Rust (for building)

Quick Demo

cargo run

This displays:

╔══════════════════════════════════════════╗
║          Zen Widget Starting            ║
╚══════════════════════════════════════════╝

  Terminals: ["Ghostty", "iTerm2", "Alacritty", ...]
  Corner: top-right
  Creature: ghost
  Tmux Session: zen
  Size: 200x150

  Press Ctrl+C to exit

Architecture

┌──────────────────────────────────────┐
│        zen-widget (Rust)             │
│  - Monitors tmux session             │
│  - Displays ASCII creature            │
│  - Generates contextual quips         │
└──────────────────────────────────────┘
                    ▲
                    │ capture-pane -p
                    │
┌──────────────────────────────────────┐
│   tmux session "zen"                 │
│   (hidden, for communication)       │
└──────────────────────────────────────┘

Configuration

Edit ~/.config/zen-widget/config.toml:

# Terminals to track
target_terminals = ["Ghostty", "iTerm2", "Alacritty", "Terminal", "Kitty", "WezTerm"]

# Corner: top-left, top-right, bottom-left, bottom-right
corner = "top-right"

# Creature type: ghost, cat, octopus, bean, slime
creature = "ghost"

# tmux session name
tmux_session = "zen"

# Widget size
width = 200
height = 150

# Opacity (0.0 to 1.0)
opacity = 0.85

# Comment update interval (ticks, ~1 tick per second)
comment_interval = 30

# Position refresh interval (ms)
refresh_ms = 10000

How It Works

1. tmux Bridge

• Creates hidden tmux session named zen
• Widget captures pane content: tmux capture-pane -t zen -p
• Parses output, generates appropriate quip

2. Creature Animation

• 5 creature types: ghost, cat, octopus, bean, slime
• Simple walking animation (3 frames)
• Random quips based on detected activity

3. Context-Aware Quips

• Errors: "oof, that doesn't look great"
• Warnings: "just a warning, probably fine"
• Builds: "compiling, make a coffee"
• Git: "making commits, good human"
• Cargo/npm: "downloading the internet"

Future: Floating Window

The plan is to add a floating widget window using standard macOS APIs:

• NSWindow with level = .floating
• Position tracking via CGWindowListCopyWindowInfo
• Semi-transparent background
• ASCII creature + quip display

This avoids yabai/SIP complexity but requires Accessibility permissions.

License

MIT