Betty

A real-time TUI monitor for Claude Code sessions.

Install

curl -fsSL https://betty4.sh/install.sh | bash

Or directly with uv / pip:

uvx --from betty-cli betty  # run without installing
uv tool install betty-cli   # install permanently
pip install betty-cli       # with pip

Use

# Start betty
betty

# In another terminal, run Claude Code as usual
claude

The companion auto-detects your session. No hooks or configuration needed.

Options

Commands

Keybindings

Navigation

Display

Views

Analysis & Annotations

Agent

Other

Betty Agent

Betty Agent is a continuous session observer that tracks what Claude Code is doing and flags problems in real time. It combines heuristic detectors with optional LLM-powered narrative and drift detection.

Enable

betty config --agent

Or set the environment variable BETTY_AGENT_ENABLED=true.

What it does

• Goal tracking — extracts the session goal and current objective, updating as the user gives new instructions
• Progress assessment — classifies sessions as on_track, stalled, or spinning using error rates, retry patterns, and tool diversity
• Error spike detection — warns when error rate exceeds 40% in recent tool calls
• Retry loop detection — flags when the same tool is called 3+ times consecutively
• Stall detection — notices gaps of 2+ minutes between turns
• File change tracking — logs Read/Write/Edit operations with line counts
• Milestones — marks every 10th tool call and 5th user message
• LLM narrative (optional) — generates a 2-3 sentence situation report describing current activity
• Goal drift detection (optional) — compares recent activity against the session goal and warns if the assistant has gone off track
• Ask Betty — press ? to ask a natural-language question about the session; Betty answers citing turn numbers and file paths

Configuration

The agent uses your existing LLM configuration (set via betty config). LLM features (narrative, drift detection, goal determination, Ask Betty) require a configured LLM provider. Heuristic detectors work without one.

Observations and reports are cached to disk (~/.cache/betty/) and persist across restarts.

License

MIT