jeff

A desktop companion for Claude Code. Run multiple claude sessions side-by-side as tabs, get notified when one needs your attention, and manage your Claude settings visually.

What it does

• Tabbed sessions — open several claude conversations at once, each in its own PTY terminal
• Attention indicators — colored dots on each tab show what's happening (red = working, blue = needs input, pink = you typed but didn't send)
• OS notifications — get notified when claude finishes or asks a question while you're in another app
• Patrol — background health monitor catches hung sessions, spinning loops, and context exhaustion
• Settings editor — visual UI for indicators, patrol thresholds, roles, cost budgets, and keybinds
• Roles — preset spawn profiles (model, effort, context tier, system prompt, tool restrictions)
• Cost tracking — per-tab token usage and budget enforcement
• Tray icon — shows how many tabs need attention at a glance
• jeff CLI — open a new tab from any terminal with jeff (uses your current directory)

Install

bun install
bun run start

The first launch installs:

• Hook bridge in ~/.claude/settings.json (backs up first)
• jeff CLI binary at ~/.local/bin/jeff
• Desktop entry at ~/.local/share/applications/jeff.desktop

jeff CLI

cd ~/code/my-project
jeff              # open a new claude session here
jeff --resume     # pick a previous session to resume

If jeff is already running, the CLI talks to it over a unix socket. If not, it launches jeff first.

Keyboard shortcuts

Shortcut	Action
Ctrl+N	New session (opens directory picker)
Ctrl+Shift+N	New private session (no file access)
Ctrl+T	Open external terminal at tab's cwd
Ctrl+[ / Ctrl+]	Switch to previous / next tab

All shortcuts are configurable in Settings.

Indicator colors

Color	Meaning
Red (solid)	Idle or focused
Red (pulsing)	Working (claude is responding)
Blue (pulsing)	Needs attention (question or permission prompt)
Pink	You typed something but didn't send it
Yellow	Patrol warning (quiet too long, spinning)
Dark red	Hung (no output for 30s)

Logs

Structured JSONL logs with rotation at ~/.config/jeff/logs/:

• indicator.jsonl — indicator state changes and notification decisions
• crash.jsonl — unhandled exceptions
• server.jsonl — PTY spawn/exit, hook events

Configuration

All config lives at ~/.config/jeff/config.json and is editable through the Settings UI. Indicator events, patrol thresholds, roles, cost budgets, and keybinds are all configurable.

Requirements

• Linux (Wayland or X11)
• Bun 1.3+
• Claude Code CLI installed at ~/.local/bin/claude