lea deck

lea deck

lea opens the deck. Each agent is Claude Code running in the lea container under abduco, so closing the deck, or the terminal, does not stop it: the next lea reattaches.

The mouse works too: click a row to select it, scroll to move, right-click a row for its menu (Split horizontally / Split vertically open a shell beside the agent, as Terminator does; the shell shows with its agent and steps aside while another agent is shown). A right-click anywhere else in the column opens the deck's own menu: new agent, new Control Tower, new agent on another provider, new shell, new folder, sounds, theme, keys, detach; a click on a folder folds or unfolds it; ctrl + right-click makes a folder, holding the agent under the pointer. The pointer over a row shows its whole name (cut in the row when long) with the agent's name, role, profile and state in the bottom border.

States #

A red ● needs you (a permission, or a blocker the agent named with task_update), an orange spinner is working or waiting (its subagents, or a next step it named: CI, a review, a reply), a green ● has finished with nothing pending, an empty ○ has been quiet for 30 minutes, a grey ‖ is paused (p: lea freezes the agent's processes, tool calls included, until you resume it), a lavender ◷ stopped on its usage limit (see below). Agents stay in the order you started them.

Usage limits #

When Claude Code stops on its provider's usage limit, the row shows ◷ and usage limit, resumes 15:02: lea resumes the agent at that time, the limit's reset (from the status line's 5-hour and 7-day windows) plus LEA_RESUME_DELAY seconds (60) and a few seconds of jitter, or after a backoff (5 minutes, doubling, at most an hour) when no reset time is known. Resuming wakes the agent with one fixed line of lea's ("the usage limit … should have reset. Continue your task"); lea never types into its terminal. After 6 resumes without progress, or with LEA_AUTO_RESUME=0, the row says usage limit, resume it and the agent waits for you. A pending resume survives lea stop and the next container: the agent comes back with --resume and lea resumes it at the same time (at least a minute after the restart; given up past 8 days). Codex agents are not detected yet: Codex gives no structured signal for its limit (its failed turn runs no hook, and the error is not kept in its session file).

Messages #

Typing into an agent's pane (enter) talks to it now, in its conversation. m (Send message) instead leaves it a note in its inbox, as another agent would: it reads it on its next turn, or is woken for it once its turn is over. t (Messages) shows everything the agent sent and received: your notes, its reports to you, and its messages with other agents, questions (ask) included; an answer names the message it answers (result to #12). Highlighted in a row's menu, each says what it does. No agent ever asks you a question: it writes to you with msg_send, and you answer with m.

Folders #

Folders come first, in your order, then the agents in no folder. A folder's header sums up its agents, folded or not: how many it holds, then how many need you (red, bold), work, wait on their usage limit and are done (2 ● 1 ✓ 1; !, +, ~ and = in ASCII). Its agents are indented under it, and a blank line sets each folder apart. A folder's colour (c) tints its arrow and its name, never its agents or its summary. An agent a lead starts joins the lead's folder, also when it starts while no deck is attached; once you move it, it stays where you put it. The layout is yours: the deck keeps it on the host (~/.local/share/lea/host/deck/<container>.json), out of every container's reach. Each row shows the agent's context use, its directory and branch, and its own report on its task. The pane that has the keyboard is the bright one: the deck's frame turns blue when it has it; otherwise the terminal on the right shows a blue ▶ <agent> · typing here bar on its top border (grey, with the keys that give it the keyboard, while the deck has it).

Scrolling #

The wheel scrolls an agent's history; the bar then reads history 251/256: type or q to go back, the line at the top of the view out of the history's lines, counting down as you scroll up. Any typed key (q, Escape, Enter, a letter…) goes back to the prompt; that key is not typed, the next ones are.

Sounds #

lea plays a sound only when it needs you, while a deck shows the agent: a permission dialog or an approval card waits, an agent sends you a request (msg_send to user, kind request, or a needs_user reply), or an agent reports it is blocked on a human (task_update whose blocked_on becomes non-empty). A turn that simply ends rings nothing. lea sound on|off and the deck's S switch it at runtime; LEA_SOUND=0 starts with it off; LEA_SOUND_ATTENTION picks the file, or mutes it with 0.

Names #

An agent you have not renamed is named after its first prompt, by a short claude -p run on the host with a small model (LEA_AUTONAME_MODEL, haiku by default; LEA_AUTONAME=0 turns it off). The prompt is not stored. An agent started with a brief (a lead's agents_spawn) is named after its brief instead, unless the lead gave it a label. A row shows the label, then the agent's name dimmed (lea#350 spawn reuse dev-4): the name is never cut, and the tower, lea board and lea agents name the agent the same way, label (name). Labels are unique among the running agents: a clash gets 2, 3…, and a rename to a running agent's label is refused. user, lea and Control Tower… are reserved: only the user gives them, never a lead's label nor the automatic name.

Copy and paste #

Copying is the agent's own: select text in Claude Code's terminal and it copies it to your clipboard, as it does outside lea. lea makes no selection of its own; in a pane whose program does not take the mouse (a split shell, the scrolled-back history), shift+drag lets your terminal select and copy, as in any tmux. ctrl+v pastes your clipboard's text into the pane that has the keyboard (the agent's input, a shell, the deck). lea reads your clipboard only when you press ctrl+v (with wl-paste, xclip or pbpaste); agents never read it.

Permissions #

When an agent asks for a permission, its row shows the request and the deck answers it. Unanswered after LEA_APPROVAL_TIMEOUT seconds (60), Claude asks in its own terminal as usual; LEA_APPROVALS=pane keeps Claude's dialog only.

The deck in your browser: lea web #

lea web, from the lea's projects directory, serves the deck in your browser while it runs (ctrl+c stops it):

lea web            # prints http://127.0.0.1:PORT/?token=…, a link that signs one browser in, once
lea web --open     # also opens it in your browser
lea web --port 8414

The page shows the lea's agents as a tree, each lead with the agents it started, and for each one its state, its own report on its task (status, next step, and in red what blocks it), its branch, context use, cost, unread messages and whether it is paused or its inbox held. It updates live, with no reload. Click an agent (or j/k, then enter) to read its messages and write to it (m; ctrl+enter sends), rename it (e), pause it (p), hold its inbox (h), change its role or stop it (x, confirmed). New agent (n) starts one on a provider, in a repository, with a role, a label and a brief; N starts a Control Tower. Tower (t) opens the control tower's chat: what you write there is a request to it, and its open and queued questions to you show above it. A permission an agent asks for shows at the top of the page with Allow, Deny and, when offered, Always (a, d, A answer the first one). While a browser shows the page, permission prompts wait for it as they do for the deck in tmux; once it is closed, the agent's own dialog asks at once, as without a deck. The page works at phone width, in a light and a dark theme (it follows your system; the ◐ button switches it), and ? lists its keys. See How lea keeps your machine safe for what protects it.