letee

Letee, pronounced luh-tee, is a tmux cockpit for local and remote tmux sessions and coding agents.

It adds a persistent sidebar to an existing terminal. Your sessions remain ordinary tmux sessions, with your terminal, keybindings, plugins, and workflows unchanged. Letee keeps managed sessions on a dedicated inner server named letee.inner on each local or remote host, and does not discover or change sessions on tmux's ordinary default server. By default, letee applies a server-wide tmux configuration overlay to each letee.inner server. It changes styles, mouse, clipboard, passthrough, and bell settings. Set tmux_config_overlay = false to opt out.

Why letee?

• Keep your setup. Letee builds on tmux instead of replacing it. There is no new terminal app or replacement tmux setup.
• See local and remote work together. Sessions and their agents share one sidebar.
• Find work that needs attention. Agent states, alerts, and tmux bells point to sessions that need you.
• Jump to the right pane. Select a session or go directly to an agent's exact tmux window and pane.

Requirements

You need Python 3.11 or newer, tmux and OpenSSH.

Install and launch

pip install letee
letee

Letee opens an outer tmux cockpit with the sidebar on the left and the selected session, or a startup pane, on the right. The default outer prefix is C-s. Your tmux prefix and keybindings stay the same if you have any. Use your mouse if that's what you're most comfortable with.

How it works

Letee creates or attaches to a dedicated outer tmux server. Bare letee uses the letee outer socket; -L NAME uses letee-NAME. Reopening the same name uses attach -d, moving the cockpit to the newest terminal.

Inner local and remote sessions use letee.inner, one shared server per host. Named outer cockpits on the same host share those inner sessions. The ordinary tmux default server is outside letee's scope. Sessions there stay running but are not discovered or changed.

Open or add a local tmux session

1. Use your mouse and click "+ add" or use the keyboard equivalent:
2. Press C-s +, type a session name, and press Enter. Letee searches every discovered session on the chosen host, including tracked sessions. Pressing Enter on a tracked match switches to it, an untracked match tracks and opens it, and a free name creates and tracks it.

Configure agent discovery

Use the local agent discovery guide to install agent-status for Claude Code, Codex, Pi, or OpenCode. It also explains where letee reads status files and how it matches agents to tmux panes.

Open the Agents view and jump to an agent

Start an agent inside a session, then press C-s a. The selector starts on the active agent. Select another with j and k and press Enter to open its exact tmux pane. Agents outside tracked sessions do not appear.

Use C-s Left and C-s Right to jump to the previous or next agent in displayed order across tracked sessions, wrapping at either end. With no active listed agent, Right opens the first and Left the last. C-s s focuses the active session without switching.

Press C-s j to jump to the first agent in the current Agents ordering with a stored bell alert or an input-required, auth-required, failed, or rejected state. With no eligible agent, letee reports no agents need attention. See the agent integration guide for alert states and termination behavior.

Essential controls

Everything in letee aims to support mouse clicks, use this if you're most comfortable with a mouse.

For keyboard enthusiasts, these are the default keys.

Sessions

C-s s focuses Sessions. Use j and k to move, and C-s 1 through C-s 9 to open the first nine tracked sessions. C-s Up and C-s Down switch to the previous or next tracked session in manual order, wrapping at either end without showing a hidden sidebar.

Agents

C-s a focuses Agents. Use j and k to move, then press Enter to open the selected agent's pane.

Find work

C-s f or the sidebar's Find button opens a searchable tree of sessions, windows, and agents. Type to filter, use arrow keys to select, and press Enter to open. Esc cancels without changing your sidebar layout or focus.

Add session

C-s + opens the Add session screen. With one location available it opens the session search directly, otherwise pick a location first. Typing searches every discovered session on that host, including tracked sessions. Press Enter on a tracked match to switch to it, an untracked match to track and open it, or the ＋ row to create and track a new session.

Open selection

Enter opens the selected session or agent pane.

Help

C-s ? opens the built-in help.

Quit or Detach

C-s q quits the outer letee cockpit. Inner tmux sessions keep running.

C-s d detaches the outer letee cockpit. Inner tmux sessions keep running. Returning to a running cockpit skips SSH preparation and keeps its sidebar running.

Looking for more?

See:

• Configuration Guide
• Usage Reference
• Agent Integration Guide
• Development Guide.

License

Licensed under the Apache License 2.0.