manage-layout

name	manage-layout
description	Use when you want to rearrange the workspace dock tabs (open, split, move, focus, close, maximize, reload, rename, delete, stop or start an instance) or inspect the live layout.
metadata	{"author":"imbue","crystallized":true}

Managing the workspace dock layout

The user interacts with you (and the apps you build) through a tabbed dock defined in system/apps/system_interface. Your chat is one such tab; every other tab is an instance of some app: a terminal, a browser, a files page, another agent's chat, an app you built.

system/scripts/layout.py is the agent-facing helper. Use it whenever you want to surface, inspect, or rearrange tabs. Do not hand-edit the dock's saved layouts.

Where the script lives: layout.py is at the repo root, at system/scripts/layout.py (i.e. /home/user/workspace/system/scripts/layout.py, the container WORKDIR). It is NOT inside this skill's folder. Every command below is written as python3 system/scripts/layout.py ..., a path relative to the repo root, which is the cwd for all commands in this repo.

Addresses (read this first)

Every tab is named by one address:

Form	Meaning	Example
app:<name>?instance=<key>	One instance of an app.	app:chat?instance=agent-3f2a... (a chat, keyed by its agent id), app:terminal?instance=terminal-2 (a terminal, keyed by its tmux session name), app:browser?instance=riley (a browser, keyed by its name)
app:<name>	A single-instance app's one tab (an app built without instances = true); or, as an open / split target for an app with instances, "a fresh instance of this app".	app:docs (a single-instance app you built), open app:terminal

A bare word is shorthand for app:<word> (open files). The literal self resolves to your own chat panel; most useful as --relative-to=self on split / move. Your own chat's address is app:chat?instance=$MNGR_AGENT_ID.

layout.py list prints every address on the machine, with each instance's title and status, so you never have to guess: find the row whose title the user said, and use its address.

A bare https:// URL is also an open target: open https://example.com starts a new browser on that page (the browser app's new action with the URL as its url param) and prints the new browser's address.

Clients and views

The workspace shows one view at a time: a project (a shared set of tabs plus its own arrangement) or Everything (every instance on the machine). Every browser client (one per browser; its windows share it) has one active view and its own arrangement of every view, kept in a file on the shell. That file is the truth: the browser saves the user's own gestures into it, and the shell edits it for your ops, so an op lands whether or not a browser is connected and a connected window shows it within a redraw.

• Every op targets exactly one client. With no --client, that is the client that most recently messaged you, else the one connected client. When neither settles it (several clients, an agent nobody messaged), the op is refused with the connected clients listed; pass --client <id> (from context). Ops are never applied to every client at once.
• An op with no --view edits the client's active view. That is what you want nearly always; just run the op.
• Pass --view <name> to edit a different view (a project's name, or Everything). The op edits that view's arrangement and switches the client to it, so the user sees what you arranged.
• views lists the views: every project plus Everything, each with its tab set and which connected clients have it in front.
• context tells you which client asked: every known client with its device kind, active view, connection state, and last few messages. The client that most recently messaged you is almost always the requester.
• load <view> switches a client onto a view without changing any arrangement (load "Research").

Every tab you open in a project is filed into that project's tab set, so it shows in the project's rail and on every device.

The verbs you'll use 95% of the time

Goal	Command
See which client/view asked for something	python3 system/scripts/layout.py context
List every app and instance (address, title, status, where docked)	python3 system/scripts/layout.py list
List the views and who is on each	python3 system/scripts/layout.py views
See what's currently open and how it's laid out	python3 system/scripts/layout.py inspect [--view <name>]
Locate one panel, its tab-mates, and its neighbors	python3 system/scripts/layout.py where <address> [--view <name>]
Switch a client onto a view	python3 system/scripts/layout.py load <view> [--client <id>]
Surface an instance alongside your chat	python3 system/scripts/layout.py open <address>
Open a web page in a new browser	python3 system/scripts/layout.py open https://example.com
Create an instance with arguments	python3 system/scripts/layout.py open terminal --param workdir=/data
Put a new terminal in the same tab group as your chat	python3 system/scripts/layout.py split terminal --relative-to=self --direction=within
Close a tab	python3 system/scripts/layout.py close <address>

open is the opinionated default. It puts the new tab to the right of your chat, joining whatever group already lives there if one is open. Pass --new-group to force a fresh column instead.

What open does with each target:

• open app:docs (a single-instance app, one you built without instances = true): docks its one tab, or brings it to the front if it is already open.
• open app:terminal?instance=terminal-2 (an instance address): docks that instance, or brings it to the front if it is already open.
• open terminal (a bare app that has instances): runs the app's action through the app and creates a fresh instance every time, exactly like the rail's "New Terminal". The new instance's address is printed to stdout so you can capture it for later ops. The same holds for open chat (a new chat), open browser (a new browser), and open files (a new file viewer: the files app has instances too, so app:files never names an open viewer). --action <id> picks another of the app's actions and --param name=value (repeatable) passes the create's params: open terminal --param workdir=/data, open files --param path=/data/notes. An app's refusal (a full browser fleet, no signed-in account) is the op's error, printed as the app spelled it.
• open https://example.com (a URL): a new browser on that page.

Less common operations

All of these take the same --client as open; split, focus, move take --view too. maximize, restore, and refresh change what is on the target client's screen without changing the saved arrangement (a refresh of a whole app reloads its iframes on every client):

Goal	Command
Place a new panel with explicit positioning	python3 system/scripts/layout.py split <address> --relative-to=<address> --direction=<left|right|above|below|within> [--ratio=0.4] [--new-group]
Focus an existing tab	python3 system/scripts/layout.py focus <address>
Move an open tab next to / into another's group	python3 system/scripts/layout.py move <address> --relative-to=<address> --direction=<dir> [--new-group]
Maximize / restore a group	python3 system/scripts/layout.py maximize <address> / python3 system/scripts/layout.py restore
Reload one tab (or every iframe of an app)	python3 system/scripts/layout.py refresh <address>

And five verbs that go through the app that owns the instance rather than the dock (they take an instance address, never a bare app):

Goal	Command
Retitle an instance (the title shows in every view)	python3 system/scripts/layout.py rename <address> "<title>"
Delete an instance (it leaves every view)	python3 system/scripts/layout.py delete <address>
Point an instance at a path under its app, or at a URL for an app that browses to one	python3 system/scripts/layout.py replace-url <address> </path-or-url>
Stop what backs an instance while keeping it (a chat's agent, a browser's Chromium, a terminal's session)	python3 system/scripts/layout.py stop <address>
Start a stopped instance again	python3 system/scripts/layout.py start <address>

Not every app accepts every verb: a browser is not renameable (its title is its name), an app that does not track locations (the terminal, the chat) refuses replace-url, each app takes only the location form that fits it (a path under the app for the file viewer, an absolute http(s) URL for the browser), and only an instance the app lists as stoppable accepts stop and start (a file viewer has nothing to stop). The app's refusal is printed as the error.

Directions on split and move

--direction takes five values:

• left / right / above / below describe the adjacent group in that direction relative to the anchor. By default the panel tabs into a group that already lives there; pass --new-group to carve a fresh column / row instead so both panels are visible at once.
• within describes the anchor's own group: the panel becomes a tab inside it. --new-group is meaningless with within and is rejected.

The most common natural request, "put a new terminal in the same tab group as my chat", is:

python3 system/scripts/layout.py split terminal --relative-to=self --direction=within

Inspecting state

inspect defaults to a compact, one-line-per-group rendering:

active_panel: g1
row size=1.0
  [app:chat?instance=agent-3f2a* app:terminal?instance=terminal-1] size=0.4
  [app:files?instance=files-1*] size=0.6

The * marks the active tab in each group. row means the children sit side by side, column means they stack. Pass --verbose for the full YAML tree (with each panel's tab id and title) or --json for the structured object. where <address> zeros in on one panel: its title, its group's tabs, and the tabs in each cardinal direction.

list prints every app with its instances: each instance's address, title, status (idle, working, attention, stopped, error), and the ids of the clients whose layouts dock it. list and views output YAML by default; pass --json for programmatic consumption.

Run python3 system/scripts/layout.py --help (or <subcommand> --help) for the full surface.

Ops answer at once

The shell edits the client's arrangement itself and answers with the result, so every dock op returns as soon as the file is written. open, split, move, focus, and close print a one-line description on stderr (opened app:terminal?instance=terminal-2 in tabs=[...], moved ... in ...); opening an address that is already open focuses it. maximize, restore, and refresh print (sent <op> to client <id>).

stdout is reserved for machine-readable output: the address of an instance open / split created, and the structured output of the read commands. Descriptions always go to stderr.

Exit codes

• 0 ok (including no-op successes)
• 1 error (the specific reason is in stderr, including "could not tell which client this op is for", for which you pass --client <id> from context, and an address that is not open or that no app lists)
• 3 the app cannot do it right now (a full browser fleet, no signed-in account for a new chat, an app still starting up; its 409 or 503): retry after a short backoff, or tell the user

When NOT to use this skill

• Building a brand-new app. Use build-app to scaffold it first; it ends with a layout.py open call to surface the new tab.
• Projects themselves (what a project shows, its rail shortcuts, adding a tab to a project without opening it): see manage-projects.
• Persisting layout state. The frontend auto-saves on every change.