Menu
Use when you want to rearrange the workspace dockview tabs (split, move, focus, rename, close, maximize, reload, swap a URL) or inspect the live layout.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Run the background harden pass for one artifact -- crystallize, update, or heal a skill, a service, or the system interface in an isolated worktree, then report back. Invoke when your task file hands you an artifact to harden; it names the operation and artifact to compose.
Promote the just-finished work into a new, reusable, committed, tested skill. Use when that process would recur with new inputs -- especially something you figured out through research or debugging -- or when the user says 'crystallize this'.
Fetch data from somewhere (an external service, an API, a third-party source), process it, and show it to the user -- the "go get all this stuff, do something to it, and put it in front of me" task. Use when the ask is to retrieve real data, transform/summarize/classify it, and surface the result. Validates auth first, confirms a real sample covering every data shape, then crystallizes the pipeline in the background while building surfaces.
Use when writing or reasoning about code that calls Claude -- an AI-driven service, an AI integration, or a skill's scripted model step. Covers the three scenarios (one-shot completion, one-shot agentic task, full agent) and the cost / credentialing model.
Fix an existing artifact that errored or delivered a wrong result. This applies to skills or web services. Invoke at turn-end, after you worked around the failure to satisfy the user's request.
Create a sub-agent to perform a larger task. Use when work is large enough to warrant a separate context, involves multi-file changes, or benefits from isolation.
| name | manage-layout |
| description | Use when you want to rearrange the workspace dockview tabs (split, move, focus, rename, close, maximize, reload, swap a URL) or inspect the live layout. |
| metadata | {"crystallized":true} |
The user interacts with you (and the services you create) through a
tabbed dockview defined in apps/system_interface. Your chat is one
such tab; everything else -- service iframes, terminals, ad-hoc URL
tabs, other agents' chats -- lives alongside it.
scripts/layout.py is the agent-facing helper. Use it whenever you
want to surface, inspect, or rearrange tabs. Do not hand-edit the
dockview layout config.
The workspace has multiple named layouts -- server-persisted dockview
states such as desktop and mobile (users can save more from the
"+" menu). Each connected browser client has exactly one layout
active; every change that client makes auto-persists into that layout.
Consequences for you:
--layout <name> (open, split,
move, focus, close, rename, maximize, restore,
replace-url). The op applies only on connected clients that have
that layout active; with none, it fails fast with a clear error.context. It lists
every known client with its device kind (mobile/desktop), current
layout, connection state, and last few messages -- the client that
most recently messaged you is almost always the requester, and its
current layout is the one to target.load <layout> switches a client onto a layout so you can then
mutate it (e.g. the user is on desktop and asks you to "set up my
mobile layout": load mobile, then run your ops with
--layout mobile). By default it targets the client that most
recently messaged you; pass --client <id> (from context) to pick
explicitly. When the requester can't be determined, every client
switches.inspect with no --layout reads it),
mutate every layout in turn, or ask the user which one they mean.| Goal | Command |
|---|---|
| See which client/layout asked for something | python3 scripts/layout.py context |
| See what's currently open and how it's laid out | python3 scripts/layout.py inspect [--layout <name>] |
| Locate one panel + its tab-mates + cardinal neighbors | python3 scripts/layout.py where <ref> [--layout <name>] |
| List everything addressable (services + agents) with open/running flags | python3 scripts/layout.py list |
| Switch a client onto a named layout | python3 scripts/layout.py load <layout> [--client <id>] |
| Surface a service / URL / terminal / chat alongside your chat | python3 scripts/layout.py open <target> --layout <name> |
| Put a new terminal in the same tab group as your chat | python3 scripts/layout.py split terminal --relative-to=self --direction=within --layout <name> |
| Close a tab | python3 scripts/layout.py close <ref> --layout <name> |
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. This joining-existing-group rule applies uniformly to every
open target -- terminals, service iframes, external URLs, and chats
alike. That can be surprising: open terminal with a service iframe
already to the right of your chat tabs the terminal into that
iframe's group, leaving a terminal nested next to an unrelated
iframe. Pass --new-group to force a fresh column instead.
Targets open accepts:
web) -- creates a new iframe for that
service, or reports a no-op if one is already open (use focus to
bring it to the foreground).terminal -- creates a fresh terminal in the primary agent's
work_dir (each call adds a new one, just like the UI's "New
terminal" button). The new tab's ref (terminal:<hash>) is printed
to stdout so you can capture it for later ops.https://example.com) -- creates a new ad-hoc URL
tab, or reports a no-op if one is already open pointed at that URL.chat:alice) -- opens another mngr-level agent's chat.chat-terminal:<name> ref -- opens (or focuses, if already open)
the terminal attached to that agent's tmux session. Singleton: a
second open chat-terminal:alice focuses the existing panel rather
than creating a duplicate. This is the same terminal the chat
panel's "Open agent terminal" button mounts.Every panel has a stable, type-prefixed ref returned by inspect:
| Prefix | Meaning | Example |
|---|---|---|
service:<name> | The iframe for a registered workspace service. | service:web |
chat:<agent-name> | The chat tab for an mngr-level agent. | chat:alice |
chat-terminal:<agent-name> | The terminal attached to that agent's tmux session. Singleton per agent. | chat-terminal:alice |
terminal:<short-hash> | An anonymous terminal tab (created via open terminal / "New terminal"; each is a fresh instance). | terminal:1a2b3c4d |
url:<short-hash> | An ad-hoc external URL tab. | url:9f8e7d6c |
subagent:<session-id> | A harness-level subagent panel. | subagent:abcd1234 |
When you call open terminal, the new tab's terminal:<hash> ref is
printed to stdout -- capture it if you need to address that specific
terminal later (focus, move, close). Otherwise, run inspect to
recover refs at any time. chat-terminal:<name> is stable by
construction, so you don't need to capture it: the same ref always
addresses the same agent's terminal.
Shorthands accepted anywhere a ref is expected:
web) expands to service:web.https:// URL is accepted as an open / split target
(it creates a new ad-hoc URL tab); the optional url: prefix
(url:https://example.com) works too.self resolves to your own chat panel; most useful as
--relative-to=self on split / move.subagent: and existing terminal:<hash> / url:<hash> refs only
address panels that already exist (created via "New terminal" / "New
URL" in the UI, or by the subagent harness). You can't create those
from open.
When open isn't enough, reach for one of these:
All of these take the same required --layout <name> as open
(except refresh, which reloads iframes on every client):
| Goal | Command |
|---|---|
| Place a new panel with explicit positioning | python3 scripts/layout.py split <target> --relative-to=<ref> --direction=<left|right|above|below|within> [--ratio=0.4] [--new-group] --layout <name> |
| Focus an existing tab | python3 scripts/layout.py focus <ref> --layout <name> |
| Move an open tab next to / into another's group | python3 scripts/layout.py move <ref> --relative-to=<ref> --direction=<dir> [--new-group] --layout <name> |
| Rename a tab's label | python3 scripts/layout.py rename <ref> "<title>" --layout <name> |
| Maximize / restore a group | python3 scripts/layout.py maximize <ref> --layout <name> / python3 scripts/layout.py restore --layout <name> |
| Point an iframe at a new URL | python3 scripts/layout.py replace-url <ref> service:<name>[/path] --layout <name> |
| Reload one tab (or every iframe for a service) | python3 scripts/layout.py refresh <ref> |
split is the customization escape hatch: it accepts the same
targets as open plus full control over the anchor (--relative-to),
direction, size ratio, and whether to share an existing group or
carve a new one. Use it when open's "to the right of your chat,
joining adjacent groups" default isn't what you want.
split and move--direction takes five values:
left / right / above / below describe the adjacent group
in that cardinal direction relative to the anchor. By default, the
new (or moved) panel tabs into a group that already lives there;
pass --new-group to carve a fresh column / row instead so both
panels are visible simultaneously.within describes the anchor's own group. The panel becomes a
tab inside that group, alongside whatever is already there. This is
the single-call form of "put X in the same group as Y". --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 (targeting the requester's layout, here
desktop):
python3 scripts/layout.py split terminal --relative-to=self --direction=within --layout desktop
This creates the terminal and drops it as a tab inside the chat's group, regardless of what else is to the right.
inspect defaults to a compact, one-line-per-group rendering:
active_panel: 1
row size=1.0
[chat:alice* terminal:a1b2c3d4] size=0.4
[service:web*] size=0.6
The * marks the active tab in each group. The header line names
the arrangement of each branch: row means children sit side by
side (left to right), column means they stack top to bottom.
Pass --verbose for the full YAML tree (including panel_id,
iframe URLs, and per-panel details) or --json for the structured
object (machine-readable, always full detail).
where <ref> zeros in on one panel. Compact default:
ref: chat:alice
title: alice
group: [chat:alice* terminal:a1b2c3d4]
left -
right [service:web*]
above -
below -
where --verbose adds the full inspect tree under full_layout.
list outputs YAML by default; pass --json for programmatic
consumption.
Run python3 scripts/layout.py --help (or <subcommand> --help) for
the full surface.
Every mutating op (open, split, move, focus, close,
rename, maximize, restore, replace-url, refresh) waits for
the resulting state to be observable via inspect before returning.
On success it prints a concise one-line diff on stderr:
opened service:web in tabs=[chat:alice*, service:web*]moved terminal:abc into tabs=[chat:alice*, terminal:abc]renamed chat:alice: 'alice' -> 'alice (lead)'On a no-op (the requested end state already holds), it prints
no change: <ref> is already ... to stderr and exits 0. This lets
you tell genuine success from "already done" without re-running
inspect.
maximize, restore, and refresh do not affect any
inspect-observable state, so they print
(broadcast sent; no observable layout-state change to confirm) on
stderr to make explicit that the op was sent without per-op
confirmation.
stdout is reserved for machine-readable output: the
server-allocated ref for open terminal / split terminal (so
wrapper scripts can capture it), and otherwise empty. Diffs and
no-op messages always go to stderr.
layout.py uses three exit codes:
0 ok (including no-op successes)1 error (anything failed -- the specific reason is in stderr,
including the wait-stable timeout and the "no connected client has
that layout active" rejection; for the latter, load the layout
first or ask the user to switch)3 mutex conflict -- another agent's layout op is in flight (retry
after a short backoff; the stderr message includes the in-flight
holder's agent_id, op, args, started_at, and a suggested
retry_after_ms)build-web-service to
scaffold the service first; it ends with a layout.py open <name>
call to surface the new tab.