🍋🥤 lemonaid

Monitor progress of and switch between lemons (go on... say 'LLMs' three times fast) running in the terminal.

An inbox that stays in view

The inbox can live in a pane that follows you across every window and session switch, so it is ambient rather than something you summon:

lemonaid tmux scratch --follow          # left or top, from config
lemonaid tmux scratch --flip            # move it to the other edge

Above, as a top strip, it draws the columns. On the left it has no room for them, so each session becomes a card instead - name, then time, cwd and branch, then the message wrapped over as many lines as the pane can spare:

The bar above the list turns the unread marker's colour while something is waiting for you. prefix+l toggles focus between the inbox and your work; q parks it until you want it back.

To see it with invented sessions before wiring up your own:

uv run scripts/demo-inbox.py            # a throwaway tmux server, own inbox
uv run scripts/demo-inbox.py --kill

Full setup, keybindings, and behaviour: docs/tmux.md.

How It Works

Lemonaid has two parts: hooks that fire when your lemons need attention, and a TUI (lma) that shows what's going on and lets you jump to sessions.

1. You add hooks to Claude Code, Codex CLI, and/or OpenCode (see Integrations below)
2. When a session stops or needs input, the hook writes a notification to a local SQLite database
3. The lma TUI displays active notifications, watches transcripts for live activity, and auto-archives sessions when they end
4. When you select an active session, you are taken directly to that pane/tab in tmux/WezTerm
5. Over time, archived sessions accumulate into a searchable session history — press h to browse past sessions across all projects and resume them

The TUI doesn't need to be running for notifications to arrive (hooks write directly to the DB), but it does need to run for live activity updates and automatic archiving.

Features

• Notification inbox: Track which Claude Code, Codex CLI, OpenClaw, and OpenCode sessions need your attention, and what they're doing as they do it
• Terminal integration: Hit enter to jump directly to the waiting session's pane (supports tmux and WezTerm). If the session has since died, its pane is recreated in the same directory rather than the jump failing
• Session history & resume: Browse archived sessions across all projects, filter by name/cwd/branch, and resume directly or copy the command
• Places: Spin up a directory and its session in one command, and tear both down in one command. What "spin up a directory" means is a shell command you configure per repo, so worktrees (or whatever else you use) stay out of lemonaid's model
• Snooze: Hold a session that needs attention "but not yet" until a time you pick, with a snoozed list so nothing goes missing
• Undo: Reverse an accidental archive, mark-read, snooze, or rename - multi-level, with a toast naming what changed
• Bootstrap: lemonaid claude bootstrap imports historical Claude sessions from before lemonaid was installed into the archive
• Always-visible sidebar (tmux): Follow mode keeps the inbox in view across every window and session switch, on the left or across the top. Sessions render as cards when the pane is too narrow for columns. Without follow mode it is still a scratch pane you toggle with a keybinding, with no startup delay
• Auto-refresh TUI: See new notifications appear without losing your place

Assorted helpers

• Claude statusline: Colorful statusline showing time, elapsed, git branch, context %, vim mode
• tmux session templates: Spin up new named workspaces with a predefined window layout
• tmux window status formatting: An optional tmux integration to keep your status bar sane

Installation

git clone https://github.com/petergaultney/lemonaid.git
cd lemonaid

# Install globally with uv
uv tool install --editable .

# For development
uv sync
uv run pre-commit install

🍋 Integrations

Claude Code

Add hooks to ~/.claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "lemonaid claude submit" }] }],
    "Stop": [{ "hooks": [{ "type": "command", "command": "lemonaid claude notify" }] }],
    "Notification": [{ "matcher": "permission_prompt", "hooks": [{ "type": "command", "command": "lemonaid claude notify" }] }]
  }
}

Features: sessions appear in the inbox the moment a prompt is submitted (UserPromptSubmit), auto-dismiss via transcript watching, live activity updates, binary patch for faster notifications.

Full documentation: docs/claude.md | Binary patch

Codex CLI

Add to ~/.codex/config.toml at the very top (before any [table] headers):

notify = ["lemonaid", "codex", "notify"]

Features: auto-dismiss via session watching, live activity updates.

Full documentation: docs/codex.md

OpenClaw

Register from within an OpenClaw TUI session:

!lemonaid openclaw register

Features: turn-complete detection, live activity updates, auto-dismiss on user input.

Full documentation: docs/openclaw.md

OpenCode

Add this plugin at ~/.config/opencode/plugins/lemonaid.js (or .opencode/plugins/lemonaid.js in a project):

export const LemonaidPlugin = async ({ $ }) => ({
  event: async ({ event }) => {
    if (event.type === "session.idle" || event.type === "permission.asked") {
      await $`lemonaid opencode notify ${JSON.stringify(event)}`
    }
  },
})

Features: idle/permission notifications via plugin hooks, auto-dismiss via session DB watching, live activity updates.

Full documentation: docs/opencode.md

Terminal Setup

• tmux: See docs/tmux.md for pane switching, back navigation, session templates, and window colors
• WezTerm: See docs/wezterm.md for workspace/pane switching setup

Usage

# Open the inbox TUI
lma

# Or via the full CLI
lemonaid inbox

# List notifications (non-interactive)
lemonaid inbox list

TUI Keybindings

Key	Action
Enter	Open notification (switches to that session)
u	Jump directly to earliest unread session
m / M	Mark as read / unread
a	Archive (remove from list)
s / S	Snooze session / list snoozed
z	Undo the last inbox change
r	Rename session (clear to revert to auto-name)
h	Toggle session history
c	Copy resume command (in history mode)
/	Filter history
f	Move the scratch pane between top and left
H	Save scratch pane size (follow mode, once it has drifted)
g	Refresh
?	Toggle the key hints
q / Escape	Quit

All keybindings are configurable. See docs/keybindings.md.

Programmatic Access

For JSON output and programmatic access (useful for lemons), see docs/for-lemons.md — or run lemonaid for-lemons, which prints the same guide from any install.

Configuration

Config file: ~/.config/lemonaid/config.toml — see docs/config.md for the full reference.

• docs/keybindings.md - Customize TUI keybindings
• docs/tmux.md - tmux integration and session templates
• docs/wezterm.md - WezTerm integration

Architecture

• inbox: SQLite-backed session status storage with Textual TUI
• claude: Claude Code hook integration with transcript watching
• codex: Codex CLI hook integration with session watching
• openclaw: OpenClaw integration with turn-complete detection
• opencode: OpenCode integration with plugin events and live activity watching