stormlight

README

Stormlight

A workspace-native control surface for coding agents.

stormlight dispatches Claude, Codex, and custom-configured coding agents into isolated windows on a private, Stormlight-owned tmux server. Each agent is one provider conversation. The dashboard organizes them as Workspaces | Agents | Spanreed, showing live process state, recent interaction, and agents that need attention without nesting another tmux instance or owning your terminal. The Spanreed pane is your written link to the selected agent — its transcript, your replies, and its requests — named for the long-distance writing instrument in the books Stormlight itself is named after.

Workspace-aware grouping keeps agents from the same repository together while preserving the checkout or worktree each agent is using.

Design

• tmux owns process and terminal lifetime, and nothing else.
• Stormlight runs tmux as a private appliance: a dedicated server (tmux -L stormlight) with Stormlight's own configuration. User dotfiles, plugins, and session-restore tools never load there, so behavior is identical on every machine.
• Each agent is one tagged tmux window in the stormlight-agents session.
• The dashboard can exit without stopping any agent.
• Metadata is stored as tmux window options, not inferred from window names.
• Provider adapters construct commands; tmux lifecycle is provider-neutral.
• Agent runtimes and dashboard presentation surfaces are separate interfaces.
• Workspace resolvers are provider-neutral and external resolvers are supported.
• Pane messages use tmux buffers, avoiding command interpolation.
• The Spanreed pane combines structured actions with sampled terminal output.
• Custom provider specs give unsupported agent CLIs a fallback.

An outside-tmux launch transparently hosts the dashboard in a temporary session on the Stormlight server; a launch from inside your own tmux uses the current pane directly and reaches agents through a nested client. Selecting an agent switches to its window, and that window's status bar names where you are — workspace › worktree › agent — rather than listing the session's other agents, which the dashboard is already for. A narrow terminal drops the outer segments first; the agent's own name always stays. Press the tmux prefix followed by Q to return to the dashboard. Stormlight installs this binding only when Q is unbound or already owned by Stormlight. While the prefix is active, the managed session highlights the tmux status bar and shows Q for return and ? for the full tmux key list. Closing the dashboard removes only its temporary session; agents keep running on the Stormlight server.

Requirements

• tmux 3.3 or newer. tmux 3.7+ is strongly recommended: Yazi and Neovim overlays open as tmux popups only on 3.7+, because display-popup in older tmux crashes the whole tmux server when the hosted program queries cursor state (tmux/tmux#4942, fixed in 3.7). Stormlight detects the version and falls back to full-screen takeover on older tmux instead of risking the server.
• yazi for the directory picker (installed automatically by the Homebrew formula). Optional: nvim for task editing.

Install

brew install trentkm/stormlight/stormlight

The formula declares depends_on "tmux", so installs get a popup-safe tmux (>= 3.7) without thinking about any of this.

Build from source

go build -o stormlight .

Install it somewhere on PATH before dispatching agents. Managed tmux windows invoke the same binary to track process lifecycle.

install -m 0755 stormlight ~/.local/bin/stormlight

Use

Open the dashboard:

stormlight

Open it on a directory — the path is added as a workspace (if it isn't one already) and selected, code .-style:

stormlight .
stormlight ~/src/project

The dashboard refreshes all Stormlight-managed windows automatically, including agents started by stormlight dispatch in another shell. It does not adopt Claude or Codex conversations that were started directly outside Stormlight.

Dispatch directly:

stormlight dispatch --provider codex --cwd ~/src/project \
  "Investigate and fix the flaky integration test"

stormlight dispatch --provider claude --cwd ~/src/project \
  "Review the current branch for correctness"

stormlight dispatch --provider claude --mode auto --cwd ~/src/project \
  "Fix every lint warning"

Each agent launches with a permission mode that maps onto the provider's own flags — auto (the default and the recommended way to run: never asks), edits (file edits apply immediately, shell and network still ask), or ask (approvals for consequential actions). In the New Agent form, press m to cycle the mode; auto agents are marked with an AUTO badge in the agent list. When an agent in a prompting mode does need an answer, the dashboard raises attention on it and Enter opens its terminal — prompts are answered in the agent's own pane, where the provider's real UI lives.

Inspect and control agents:

stormlight list
stormlight list --json
stormlight attach <id>
stormlight send <id> "Run the focused test before wrapping up"
stormlight rename <id> "focused test fixer"
stormlight mark <id> attention
stormlight stop <id>
stormlight delete <id>
stormlight logs

Agent renames set the tmux window name, which the dashboard prefers over the generated task title. Workspace renames (press R in the Workspaces pane) are display-name overrides stored in the workspace catalog; the directory on disk is untouched.

IDs may be shortened as long as the prefix remains unambiguous.

Dashboard controls

Key	Action
h / l	Move between Workspaces, Agents, and Spanreed
j / k	Move in the active pane; scroll Spanreed
gg / G	Move to the first or last item
Ctrl-d / Ctrl-u	Move down or up half a page
Ctrl-f / Ctrl-b	Move down or up a full page
< / >	Narrow or widen the focused pane (persists across launches)
z	Toggle compact and expanded list rows
Enter	Enter Agents from Workspaces, or open the selected agent terminal
Ctrl-6	Return from an agent to the dashboard (vim's alternate-buffer toggle; also shown in the agent status bar, which is clickable)
tmux prefix, then Q	Return from an agent to the dashboard (tmux-native fallback)
n	Add a workspace in Workspaces; create an agent in the selected workspace elsewhere
o	Create an agent with an explicit directory picker
i / s	Write a reply in Spanreed
Ctrl-v (while replying)	Paste a clipboard image as a file path
x	Interrupt the selected agent
Ctrl-x, then x / y / Enter	Remove a workspace or delete an agent
Ctrl-x, then X	Delete a workspace and all of its agents
R	Rename the selected workspace or agent
, then a / n / c	Sort by attention, name, or newest (applies to both lists)
m	Mark the selected agent in progress or needs-attention (your own reading, overriding Stormlight's)
M	Mark the selected agent — or workspace — seen
K	Workspace info popup (resolver, roots, metadata)
?	Full keybinding reference
r / Ctrl-l	Refresh
q	Close the dashboard

In Spanreed, press i or s to open the reply box — it wraps and grows with your message, and stays open between messages. Press Enter to send, Ctrl-j for a newline, and Esc — or Backspace once the box is empty — to leave. Press / to search the transcript (n/N between matches). Drag with the mouse to highlight transcript lines — releasing copies them to the tmux paste buffer and the system clipboard. Provider slash commands (/compact, /clear, custom skills) work from the reply box too — a single-line message starting with / is typed into the agent as a command instead of pasted as text. Normal-mode Enter opens the complete provider terminal for controls that cannot be represented inline.

Images paste too: press Ctrl-v while composing and Stormlight saves the clipboard image to a temp file and inserts its path at the cursor — Claude Code and Codex read image files referenced by path. On macOS this uses pngpaste when installed (brew install pngpaste), falling back to AppleScript; on Linux it uses wl-paste or xclip.

Approval and authentication prompts are answered in the agent's own terminal: Stormlight raises attention and points at the pane rather than reimplementing the provider's prompt. While one is pending, the reply box stands down — i / s redirects you to Enter, and a prompt arriving mid-compose closes the composer and parks your draft for when you return. A plain question is different: the agent is idle at its own composer, so a Spanreed reply is the answer.

Pressing n in Agents or Spanreed inherits the current workspace context. The centered form contains a vertical Coding agent picker, an optional name, and a wrapping task composer. Use j / k to choose Codex, Claude, or another configured coding agent, then press Enter to compose and Enter again to launch. Since Enter launches, Ctrl-j is what breaks a line inside the task composer — the same key the Spanreed reply box uses. Shell remains available through stormlight dispatch --provider shell, but is not presented as a conversational coding agent.

Tab reaches the name field, which Enter on the picker skips past. Leave it empty and the agent is named after its task; fill it in and that name is what the agent list and its tmux window carry (the same thing R sets afterward, and what stormlight dispatch --name has always taken). The field drops out of the form in panes too short to hold both it and the task composer.

Press e from the coding-agent picker or Ctrl-o from the task composer to edit the task in Neovim. The saved text returns to the form. Neovim opens in a tmux popup when the current surface supports popups and otherwise temporarily takes over the terminal.

Press o when the agent should run somewhere else. This opens the full directory picker with known workspaces, worktrees, components, Yazi, and interactive path entry. Use j / k or gg / G to select a location. Pressing e on a location edits that path directly. In Yazi, Enter chooses the highlighted directory (or a highlighted file's parent), q chooses Yazi's current directory, and Q cancels. Yazi opens as a tmux popup over the dashboard, including when Stormlight was launched from a regular shell. Direct terminal takeover remains a fallback when the dashboard cannot be hosted in tmux.

Enter a path is an interactive cd from the current directory: type to filter its subdirectories, Tab descends into the best match (arrows pick another, then Enter descends), Backspace on an empty filter goes up, a typed absolute or ~ path jumps there, and Enter with nothing highlighted chooses the directory you are in.

The Spanreed pane retains provider terminal colors while removing startup chrome and the inactive prompt/status area for Claude and Codex. Shell agent output remains unfiltered.

Workspaces

Stormlight resolves working directories automatically. Linked Git worktrees share one workspace group, while each worktree remains a distinct execution root. Independent clones and non-Git directories remain separate. Because a grouped workspace can hold several checkouts, the Spanreed heading names the worktree an agent is working in — worktree fix-auth beside its provider and state — and stays silent for agents in the main checkout.

Press n in the Workspaces pane to open the Add Workspace modal. Yazi and manual path entry are the only actions; current workspaces appear below as read-only context. The catalog is stored at ~/.local/state/stormlight/workspaces.json by default. Workspaces containing active agents remain visible even when they are not in the catalog, so the ordinary confirmation only removes agent-free workspaces. For a workspace that still has agents, the confirmation demands a deliberate capital X, which deletes the workspace and every agent in it.

Compact rows are the default and show the primary workspace or agent line. Press z to reveal the path and resolver or provider details. Narrow terminals show one full-width pane at a time and honor the same row density.

Rows never rearrange on their own: the default order is newest first, and , opens a yazi-style sort chord (a attention, n name, c newest).

Attention has two tiers, and it always outranks the working glow:

Signal	Meaning	Look
working	agent is running	cyan glow sweeping the name
waiting	finished with a result you haven't seen	soft amber ○ marker and count
question / approval / auth	agent is blocked on an explicit decision	loud amber ! — the whole row

Selecting a row never changes what it reports: the cursor row keeps its glow and its amber, painted onto the selection background rather than replaced by it, so moving through the list can't make a working agent read as idle.

Every finished turn is classified from its final message (providers emit the same event for "done" and "asked you something", so the content is the discriminator): a closing question goes loud, anything else is an unseen result. Amber is an inbox — it clears when you engage with the result: replying, interrupting, or opening the terminal clears any tier; paging through the transcript while it is on screen clears unseen; and M marks the selected agent — or every agent in the selected workspace — seen manually. Moving between panes and rows is not engagement — navigation is how you leave a result, so it leaves the amber where it is.

Marking an agent yourself

Stormlight infers all of this from provider hooks and pane state, and it is sometimes wrong: an agent grinding through a long tool call reads as idle, and a result you want to revisit reads as nothing at all. Press m on an agent to say otherwise. The picker offers two marks and a way out:

Mark	Says	Look
w in progress	still going; nothing is pending on you	cyan ● and the working glow, any attention stood down
a needs attention	come back to this one	amber ◆ in the waiting tier
c clear	hand the row back to Stormlight's reading	whatever Stormlight infers

A mark outranks everything Stormlight inferred — in the row, in the workspace counts, and in the header — and rows say marked in progress or marked needs attention outright, so a corrected row never passes for an inference. The ◆ is deliberately not the inferred tiers' ○ or !: at a glance you can tell your own amber from Stormlight's.

The two marks retire differently, because different parties can answer them. In-progress claims the agent is still running, which the agent settles the moment it reports anything — its next hook event retires the mark. Needs- attention claims you have something to come back to, which no provider event can answer, so only you take it down: M, or engaging with the row the same way engagement clears amber. A mark also stops applying when the pane dies, because an exit status is the whole story of a finished agent.

The same override is available outside the dashboard:

stormlight mark 0123abcd working
stormlight mark 0123abcd attention
stormlight mark 0123abcd none

Custom workspace types can override Git by installing executable resolvers in ~/.config/stormlight/resolvers. The protocol is public and does not require Stormlight-specific code. See workspace resolvers.

Provider lifecycle

Stormlight injects agent-scoped lifecycle integration for managed providers:

• Codex uses its external agent-turn-complete notification to become idle and publish the latest response summary.
• Claude uses UserPromptSubmit, Notification, and Stop hooks to report state; the permission notification raises attention on the agent whose terminal is holding the prompt.
• Replies sent from the dashboard mark any provider working immediately.

The runtime also exposes an event command so other provider hooks can report semantic state without screen scraping:

stormlight event --state working --summary "Running focused tests"
stormlight event --state idle
stormlight event --state idle --attention approval \
  --summary "Needs permission to access the network"

Managed processes receive STORMLIGHT_ID, so --id is optional inside a provider hook.

Configuration

Stormlight runs with no configuration. An optional ~/.config/stormlight/config.toml (honoring $XDG_CONFIG_HOME) supplies defaults; precedence is always flags > environment > config file > built-in defaults.

stormlight config init   # write a fully commented template
stormlight config        # print the effective merged configuration

[defaults]
provider = "claude"        # what the New Agent form starts on
mode     = "edits"         # ask | edits | auto

[tmux]
socket      = "stormlight"
return_keys = ["C-6", "C-^"]

[workspaces."~/repos/trusted-project"]
mode = "auto"              # per-directory dispatch defaults (matches subdirs)

A workspace is a directory. How agents behave inside it belongs to the tree itself (CLAUDE.md / AGENTS.md, read natively by the provider CLIs); config only holds preferences about Stormlight's own behavior.

Custom providers

First-class providers (Claude, Codex) keep in-tree adapters that integrate with their extension surfaces — hooks, notifications, permission bridging. Any other agent CLI can be declared in config:

[providers.aider]
label  = "Aider"
binary = "aider"
args   = ["--message", "{task}"]   # exec-style; {task} is replaced verbatim
[providers.aider.mode_args]
auto   = ["--yes-always"]          # prepended per permission mode

Declared providers appear in the New Agent picker and dispatch like any other. Lifecycle integration is the public contract: managed processes receive STORMLIGHT_ID and can report state with stormlight event from any hook mechanism the CLI provides. Stormlight never reimplements an agent.

Diagnostics

Stormlight writes structured JSON Lines diagnostics without prompt text or pane contents. Logs rotate at 5 MiB with one backup.

stormlight logs
stormlight logs --lines 25
stormlight logs --path
stormlight --log-level debug

Override the location with --log-file or STORMLIGHT_LOG_FILE.

The Stormlight tmux server

Stormlight talks to tmux -L stormlight by default and boots that server with its own managed configuration (rewritten at startup at ~/.config/stormlight/tmux.conf). Power users can inspect it directly:

tmux -L stormlight list-sessions
tmux -L stormlight attach -t stormlight-agents

Tests or parallel Stormlight instances can target an alternate server:

STORMLIGHT_TMUX_SOCKET=stormlight-test stormlight list

The value maps to tmux -L <name>. Setting --tmux-socket "" targets the default tmux server with your own configuration; Stormlight never applies its managed config there.