Panes and projects

Move panes and tabs

ActionFunction
swap_left, swap_right, swap_up, swap_downExchanges the focused pane with an adjacent pane
rotate_panes_clockwise (Ctrl+Shift+]), rotate_panes_counterclockwise (Ctrl+Shift+[)Moves every pane in the tab to the next or previous position in reading order
pane_overview (Ctrl+Shift+D)Shows the panes of every tab as live cards to choose from
move_pane_to_tabMoves the pane to a new tab
move_pane_to_windowMoves the pane to a new window
detach_tabMoves the complete tab to a new window

Rotation keeps the layout shape and split ratios. Focus stays with the same pane.

Pane overview

The pane overview shows the panes of every tab in the window as live cards, up to 32. Panes after the 32nd, in tab order, do not appear in the overview. The overview does not open when the focused pane is one of them. Each tab’s cards form a group, in tab order. The focused pane starts highlighted. The default overview shows each tab as a small picture of its panes, each pane in its place. The tabs are in a grid.

KeyFunction
Left, Right, Up, Down, or h, l, k, jHighlights the pane in that direction. At the edge of a tab, the highlight goes on to the tab in that direction. With no pane there, it stays.
Tab, Shift+TabHighlights the next or previous pane in order, and wraps round
Home, EndHighlights the first or last pane
Enter, Space or a left clickFocuses the highlighted pane and closes the overview
1 to 9Focuses that numbered card and closes the overview
Escape, the pane_overview key, or a right or middle clickCloses the overview and keeps the focus

The mouse wheel also moves the highlight, in order. An overview pack that shows the cards in a row or round a ring has other arrow keys. Pane Deck is one example. With such a pack, Right or l and Left or h highlight the next and the previous pane. Down or j and Up or k highlight the first pane of the next and the previous tab. A pack chooses the arrow keys with overviewNavigation in its metadata. A pane in another tab switches to that tab as the overview closes. Keys do not reach the panes while the overview is open. Programs in the panes keep running. A zoomed tab shows all of its panes in the overview, and returns zoomed on the chosen pane. Animation.overviewCurve and Animation.overviewDuration set the motion. Shaders.overview chooses the pack that draws it. See shaders. Use the command palette or a keybinding to run these actions. Drag a tab outside the tab bar and release it to open a new window. Alternatively, right-click the tab and select Detach Tab to New Window. A horizontal drag inside the bar changes tab order. Movement keeps processes, history, graphics and pane IDs. A detached tab also keeps its tab ID and split ratios. An empty source window closes after its last pane moves.

These commands move pane 12 beside pane 34, then detach its tab:

afterglow ctl move-pane 34 right --pane 12
afterglow ctl detach-tab --pane 12

A move can cross tab and window boundaries. Use target 0 with the placement new-tab or new-window, as in afterglow ctl move-pane 0 new-tab --pane 12. With a target pane, new-tab puts the pane in a new tab after the tab of that target, in the window of that target. Afterglow refuses a move to a new tab of its own window for a pane that is alone in its tab. The move_pane_to_tab action then shows a notice, and afterglow ctl action reports an error. A held key tries the move one time. Luau supplies matching move_pane and detach_tab effects. Their results contain the pane snapshot and destination IDs. on_pane_moved reports the new location. A move does not cause creation or closure events.

In the window of a mux session, a pane or a tab that moves to a new window goes to a new session. A new window shows that session, and the programs keep running. The pane gets a new pane ID, and the tab gets a new tab ID. Control clients and scripts get a closure event and then a creation event, not a move event. Afterglow refuses a move of the last panes of a session out of its window to a new window. Afterglow also refuses a move of a session pane into a window that shows no session or a session of another daemon. It refuses a move of another pane into the window of a session too. A pane that moves into the window of another session of the same daemon joins that session (see move a pane to another session).

Save and open projects

  1. Open the command palette.
  2. Select Save Project.
  3. Enter a project name.

A project stores one window’s tabs, split trees, ratios, focus, titles, directories and explicit launch arguments. Replacing an existing project requires confirmation. You can also save the window of a mux session (see projects and mux sessions). Switch Project searches saved names. It focuses an open instance or starts the saved layout in a new window. Other windows remain open. The keybinding action names are save_project and switch_project.

CommandResult
afterglow ctl save-project development --pane 12Saves the window of pane 12 as the project development
afterglow ctl projectsLists the saved projects
afterglow ctl open-project developmentFocuses the open instance, or starts the project
afterglow ctl open-project development --newStarts another instance of the project
afterglow ctl open-project development --into-sessionOpens the project into a mux session, whatever the project says
afterglow ctl open-project development --no-sessionOpens the project into a window outside a session, whatever the project says
afterglow ctl save-project development --pane 12 --overwriteSaves the window of pane 12 in place of the saved project development

Project files

Layouts are in projects/ beside the active configuration file. The usual path is ~/.config/afterglow/projects/. Names contain 1–64 letters, digits, underscores or hyphens. Saves replace files atomically. Symlink files are not permitted.

LimitValue
Format version1
Tabs16
Panes32
Tree depth16
File size1 MiB
Tab and pane IDs1–64 characters
Pane directory4,096 characters, an absolute path or one that starts with ~
Tab and pane titles256 characters
Pane command64 arguments, each of at most 4,096 bytes in UTF-8, with a program name first

Afterglow validates the layout before it creates windows or runs commands. A save or an open that a limit stops names that limit and the count of the layout. A save keeps a pane command that is over the command limits as an empty command, and gives a warning.

  1. Copy development.json into the project directory.
  2. Set the directories and commands for your system.
  3. Open the development project.
ObjectFields
Documentversion, active_tab, tabs, and the optional session (true or false)
Tabid, title, active_pane, tree
Leafpane: {id, cwd, title, command}
Splitdirection, ratio, first, second

Split direction is right or down. The ratio must be greater than zero and less than one. Pane IDs must be unique in the document. Tab IDs must also be unique. Saved IDs are labels. Each launch maps them to new runtime IDs.

Commands and recovery

command is an argument array. An empty array starts the configured shell. Only explicit pane launch commands are saved. Afterglow does not infer commands from foreground processes or shell history. Commands do not use implicit shell expansion. Use an explicit shell with -c when expansion is necessary.

Directories must be absolute or start with ~/. A single ~ means the home directory. A missing directory uses the home directory instead. An unavailable command starts a shell with a warning. Explicit commands remain visible after exit, with their exit status. A restored shell also remains visible after an unsuccessful exit. Press a key to close a held pane.

A project file stores a launch layout, not running programs. It does not save scrollback, environment snapshots, remote sessions or process state. For a project with "session": true, the mux daemon keeps the programs of its session running (see projects and mux sessions). Examine commands in imported layouts before you open them.

Projects and mux sessions

A project with "session": true opens into a session of the mux daemon of this computer. The session has the name of the project. A window keeps its session running when it closes only when it opened from a project into that session, also with --new. For these windows, Mux.onClose does not apply. It decides for the other windows of sessions. A save under a project name does not change what a close does. To end the session, run afterglow mux kill NAME, or end its programs. --into-session and --no-session of afterglow ctl open-project choose for one open. The global --session NAME of afterglow ctl is another option. It names the session that a command acts on. Switch Project and the open_project effect of scripts follow the project.

The session of the projectOpen the project
A window shows itFocuses that window
It runs, and no window shows itA new window shows it again, with its programs as they are
It does not runStarts it with all the panes of the project, and a new window lays them out. A pane whose program ended before the window opened is left out, with a warning.
It runs, with --newStarts another session, whose name the daemon gives

A save writes the kind of the window that it saves. A save of a window that shows a session of this computer sets session to true. A save of any other window removes it, also for a project that you opened with --no-session. Thus a save of the window of a session of another host writes no session, and the project opens into a window of this computer. The daemon keeps the command and the title of each pane, so a window that shows the session again saves them too. Afterglow starts the daemon, the session and the panes of the project in the background, and connects to the session there. The windows go on responding while the session starts. The afterglow ctl open-project call, and the result of the open_project effect, come when the window of the session opens. While the session of a project starts, a second open of the project waits for it, and then focuses its window. A pane of a session closes when its program exits. The project does not hold it, as it holds a pane outside a session. A project whose name starts with - cannot name a session, and opens into a window. With --into-session, its open fails with project NAME cannot name a session: the name of a session must be and the rule for names.

Script and control results

Luau effectResult fields
save_project(pane, name, overwrite?)name, window_id
list_projects()names
open_project(name, newInstance?)name, window_id, reused, and session for a project that opens into a session

Wait for the result with afterglow.await. reused is true when a window of the project, or of its session, was there already and came to the front. A new project instance also returns pane_ids, tab_ids and warnings. A window that shows a session that ran already returns no ID maps. The ID maps connect saved labels to runtime IDs. Project creation uses the structural action budget. Window snapshots contain project. An unnamed window has an empty project name.

The project script shows a native selector. The control socket supplies projects, saveProject and openProject. The CLI prints save and open results as JSON.

open_directory(path, layout?) starts a shell or saved layout in a directory. All template panes use that directory. It opens a window, also for a layout whose project opens into a mux session. An existing window for the canonical directory receives focus without a restart. Results contain window_id, pane_id, cwd and reused. A layout restore also returns ID maps and warnings. Window snapshots contain project_directory.

afterglow ctl open-directory PATH --layout NAME

Integration test

The test checks pane transfers, save, restore and error recovery. To run it, see Projects and the project navigator.

Mirrored from docs/PROJECTS.md in the Afterglow repository.