A proof-of-concept workspace built on libghostty-vt and GTK4/libadwaita: vertical tabs, each holding a split tree of terminal and web panes, with saved layouts that open a whole arrangement — directories, scripts and all — in one go, and a startup list that opens the ones you always want.

The sidebar holds the window controls, a new-tab button, one row per tab, and a settings gear at its foot — the layout Zen Browser uses for vertical tabs — with the content inset to its right.

Quick start

nix develop          # Zig 0.16 + GTK4 + libadwaita, no host toolchain needed
zig build run

Everything is pinned by flake.nix; nothing needs to be installed on the host.

Installing

mise run install     # builds release, installs into ~/.local
mise run uninstall

That puts the binary in ~/.local/libexec/playpen, a launcher on ~/.local/bin, a desktop entry in ~/.local/share/applications, and the icon in the hicolor theme, then refreshes the desktop and icon caches. mise tasks lists the rest (build, run, fmt, screenshot).

Two things the installer has to handle that a normal install wouldn't:

A launcher, not a symlink. The binary links against GTK in the Nix store and has an RPATH, so it runs anywhere — but a handful of things are found by path at runtime rather than linked, and they have to be pointed at the Nix copies or the app misbehaves in ways that look nothing like a packaging problem. A desktop launcher starts the app with a minimal environment, so those paths are baked into the launcher script, read out of the dev shell at install time rather than hardcoded so they can't drift from the flake. See Running off-NixOS for what each one is.
Nix GC roots. The installed app depends on store paths that nix-collect-garbage would otherwise be free to delete, which would break it later with no obvious connection to the command that did it. Install pins every store path in the binary's RPATH, plus the by-path ones above, which never appear in an RPATH; uninstall releases them.

Running off-NixOS

Everything here is set up by the dev shell and baked into the installed launcher, so it should be invisible — but each one cost a debugging session, so it is written down.

GSettings schemas and icon themes (GSETTINGS_SCHEMA_DIR, XDG_DATA_DIRS). Without them GTK aborts on a missing schema, or renders broken-image icons.
A TLS backend (GIO_EXTRA_MODULES → glib-networking). GIO has none built in; it loads one as a module. Without it every https:// page in a web pane fails with "TLS support is not available", while http:// still works.
One consistent mesa (__EGL_VENDOR_LIBRARY_DIRS, LIBGL_DRIVERS_PATH, GBM_BACKENDS_PATH). This is the subtle one. WebKit's web process is linked against Nix's libgbm, but libglvnd falls back to /usr/share/glvnd/egl_vendor.d and loads the host's mesa as the EGL vendor — and a GBM device created by one mesa is rejected by the other. Nix's libgbm also looks for its backend under /run/opengl-driver, which only exists on NixOS. Either one aborts the web process at startup with Could not create default EGL display: EGL_BAD_PARAMETER, so web panes open fine, begin loading, and then go permanently blank — the terminal side is completely unaffected, which makes it look like an app bug rather than a graphics one. Pointing all three at the Nix mesa fixes it; the real GPU is still used, via /dev/dri.

Which "libghostty" this uses, and why

Ghostty ships two different C APIs, and only one of them is usable here:

	`include/ghostty.h`	`include/ghostty/vt.h`
name	"libghostty-internal"	libghostty-vt
scope	whole terminal incl. renderer	VT core only
platforms	`GHOSTTY_PLATFORM_MACOS`, `GHOSTTY_PLATFORM_IOS`	any
intended for	Ghostty's own macOS app	external embedders

ghostty.h is the one that would hand you a ready-made terminal surface, but it has no Linux platform tag at all — its ghostty_platform_e enum only knows macOS and iOS, and its own header says it is "tailored to the needs of the macOS app". On Linux, Ghostty does not embed itself through that API; it builds its GTK apprt directly into the binary.

So this project uses libghostty-vt, the API Ghostty documents for external embedders. That means we get, for free and battle-tested:

escape sequence parsing and full terminal state
screen, scrollback, line wrapping, and reflow on resize
key and mouse event encoding (including the Kitty keyboard protocol)
paste safety checking and bracketed paste encoding

and we supply everything above it: process management, rendering, and the UI.

We consume it as a Zig module rather than through the C ABI. Ghostty's build.zig detects that it is being used as a dependency and, in that mode, builds only libghostty-vt — no GTK, no executable — so zig build pulls in just the VT core.

Architecture

main.zig       AdwApplication startup
appearance.zig the colour scheme: preference -> libadwaita, CSS, palette
Window.zig     sidebar + GtkStack of views, tab management, shortcuts
View.zig       one tab's content: its panes, their layout, and drag handling
Layout.zig     the split tree: nodes, rearranging, GtkPaned materialization
Pane.zig       content plus its header, drag source, and drop target
Terminal.zig   GtkDrawingArea: Cairo/Pango renderer, keyboard, mouse, selection
Browser.zig    WebKitWebView plus a nav/address bar and a find bar
webkit.zig     hand-written bindings for the WebKitGTK calls we make
Layouts.zig    saved tab templates: model, JSON on disk, {{substitution}}
OpenLayoutDialog.zig  prompts for a layout's parameters
SaveLayoutDialog.zig  turns the current tab into a saved layout
Session.zig    libghostty-vt Terminal + parser, fed by the PTY
Pty.zig        openpt/fork/exec, controlling terminal setup
script.zig     runs a command for `$(...)` in a layout's directory
key.zig        GDK keyval -> libghostty-vt key mapping
palette.zig    every colour by name, its default per scheme, and the CSS for it
theme.zig      the palette resolved for the terminal renderer, which reads numbers
Settings.zig   preferences: theme, palette overrides, startup tabs, JSON on disk
SettingsDialog.zig    the settings page, including the startup list editor
PaletteEditor.zig     the colour editor inside it: a swatch per palette entry
TabSettingsDialog.zig one tab's own settings, and the emoji picker
emoji.zig      generated: every emoji the picker offers, and the search over them

A tab is a view, and a view holds one or more panes arranged in a binary split tree: every interior node is a split with an orientation, every leaf is a pane. That is what allows the layouts a single shared orientation can't express — three panes in a row, drag the rightmost to the bottom, and you get two on top with one spanning the full width beneath them.

A pane holds either a terminal or a web view, behind a Pane.Content union. Both kinds expose the same three operations (widget, focus, destroy) and report back through the same three callbacks (title, exit, focus), so the split tree, drag and drop, and focus tracking are written once and never branch on which kind of pane they are moving. A web pane carries its own navigation bar rather than putting an address entry in the pane header, because the header is the drag handle and a text entry there would swallow the drags that rearrange the view.

Each split node owns a GtkPaned, so dividers are draggable and every split remembers its position as a ratio rather than a pixel count. The ratio is the source of truth: it is re-applied whenever the available space changes, so proportions survive window resizes, and only user drags update it.

Where a drop lands depends on how close it is to the view's own border. Near an edge of the window the pane is placed against the whole layout and spans it; anywhere else it splits just the pane under the pointer. That single rule gives both "put this across the bottom" and "split this one in half".

Panes and split nodes each hold a strong reference to their own widget, so detaching and reattaching during a rearrangement never finalizes anything. Running terminals keep their scrollback and processes straight through a move.

Drags rearrange live. Each time the drop target changes, the move is applied for real, so the layout under the cursor is always the layout you will get — there is no separate drop indicator because the view itself is the preview. Cancelling a drag puts the pane back: only the dragged pane ever moves, so the rest of the tree is unchanged and re-inserting it beside its original sibling restores the original shape.

Layouts

A layout is a saved tab: an arrangement of panes, each with a directory and a script, that opens in one go. Layouts take parameters, so one layout serves any number of projects.

The layout button in the sidebar lists them. Picking one asks for its parameters — prefilled with their defaults — and opens a new tab. A layout with no parameters skips the prompt. The plain new-tab button is untouched: it still opens one shell, immediately.

You author layouts by arranging a tab. Split it, drag panes around, drag the dividers, then Save tab as layout…. That captures the tree, the split orientations and the ratios exactly as they are on screen, and asks only for what it can't infer: a name, the parameters, and each pane's script. There is deliberately no separate layout builder — the split tree already is one.

The save dialog prefills what it can read off the live tab: each terminal's current directory, straight out of /proc/<pid>/cwd, and each web pane's current page. So the usual flow is to get a tab set up the way you like, save it, and replace the literal paths with {{parameters}}.

Editing a saved layout opens the same dialog on the stored one, so its name, parameters and per-pane scripts can be changed without opening it. Renaming moves the layout rather than copying it, and renaming onto a name another layout already has is refused instead of quietly replacing it. Nothing is written until you confirm, so cancelling leaves the layout untouched. To change the shape of a layout, open it, rearrange the tab, and save over it under the same name — the same tools you used to build it in the first place.

Every cwd, command and url goes through {{name}} substitution, and a leading ~ is expanded afterwards. An unknown {{name}} is left as written rather than blanked, so a typo shows up in the pane instead of silently producing an empty path.

Directories from a script

A directory can also be $(a command), and what the command prints becomes the path. A parameter can say which project; only a command can answer "wherever that branch is checked out":

"cwd": "$(git -C ~/src/{{repo}} worktree list | awk '/{{branch}}/ {print $1}')"

It runs under /bin/sh -c, so pipes and && work as written, and $(...) may appear anywhere in the field — ~/src/$(pick-project)/api is fine, as are several in one path. Its stdout is the value, trimmed of surrounding whitespace; its stderr stays attached to Playpen's own, so a script that complains complains somewhere you can read it.

Parameters reach the script two ways. They are substituted into it first, as {{name}} above, and every one is also in its environment as PLAYPEN_<NAME> — uppercased, with anything that isn't a shell identifier character replaced by _, so repo-path arrives as PLAYPEN_REPO_PATH. Reach for the environment form whenever a value might contain a space: {{name}} splices text straight into the command line, where a path with a space in it silently becomes two arguments, and "$PLAYPEN_NAME" cannot.

Order is {{name}} → $(...) → leading ~, so a script is free to print a ~/... path and land where it meant to.

Two limits worth knowing. A script blocks the window while it runs, because layouts are built by a synchronous walk of the split tree; it is killed after five seconds, so a mistake costs a visible pause and an error rather than a window that never comes back. And a script that fails leaves an empty string rather than aborting the tab — the rest of the layout is usually fine, and a pane that opened in the wrong directory is both obvious and recoverable, which a tab that refused to open is not. Failures are logged with the command that caused them.

This applies to the directory only. A pane's script field is already typed into a shell, which does its own command substitution; running it here first would evaluate it twice, at two different moments.

Scripts are typed into the shell, not run instead of it. A pane starts your login shell as usual, and the script is fed to it once it is ready. The shell is still there when the script finishes, with your environment loaded and the command in history. The wait matters: writing at spawn time loses the input, because shells that set up line editing discard whatever was buffered while they were initializing. The shell's first output is the signal that it is reading, so that is when the script goes in.

Layouts live in ~/.config/playpen/layouts.json (or $XDG_CONFIG_HOME), and the file is meant to be edited by hand as well — Reload from disk picks up changes. It is JSON because the app writes it too, and a format that round-trips without a hand-written emitter is worth more here than a prettier one.

{
  "version": 1,
  "layouts": [
    {
      "name": "Project",
      "parameters": [
        { "name": "path", "description": "Project directory", "default": "~" }
      ],
      "root": {
        "split": "horizontal",
        "ratio": 0.55,
        "first": {
          "kind": "terminal",
          "cwd": "{{path}}",
          "command": "git status"
        },
        "second": {
          "split": "vertical",
          "ratio": 0.5,
          "first": { "kind": "terminal", "cwd": "{{path}}", "command": "nvim ." },
          "second": { "kind": "web", "url": "https://github.com" }
        }
      }
    }
  ]
}

A node is a split if it has a split key and a leaf otherwise. Saves are atomic — written to a temporary and renamed — so an interrupted write leaves the previous layouts intact rather than a file that won't parse.

Startup tabs

Opening the same three layouts against the same three worktrees every morning is the kind of thing the app should be doing for you. Settings → Startup is a list of tabs to open at launch: one row per tab, each naming a saved layout, the values to fill its parameters in with, and optionally a name and an emoji to pin on the row.

The fastest way to fill it in is Use current tabs: arrange the window you want, then say that this is the window you always want. It writes down one entry per open tab, in sidebar order, with whatever each was opened with.

What is saved is the recipe, not the session. An entry is the layout's name and a handful of values, so it is a few lines you can read, edit and keep — and the layout itself stays the thing you maintain. Nothing here restores a scrollback, a running command, or a shell that has since wandered into another directory; launching re-runs the arrangement, and that was the tedious part.

Rows in the list can be reordered, and the first one is the tab you land in. An entry with no layout picked opens a plain shell, which is worth having — a startup list is often two configured tabs and one ordinary shell to work in. An entry naming a layout that has since been renamed or deleted is skipped with a warning rather than silently costing you a tab, and the settings page keeps showing it — with This layout is no longer saved under it — so the values you typed for it survive until you deal with it.

Parameters that the entry doesn't mention open at the layout's own default, which is the same rule the parameter prompt follows. So an entry only has to carry the values that differ from what the layout already suggests.

The list lives in settings.json beside the theme:

{
  "version": 1,
  "theme": "dark",
  "startup": [
    { "layout": "Project", "name": "signal", "emoji": "🚀",
      "parameters": { "path": "~/src/signal" } },
    { "layout": "Project", "parameters": { "path": "~/src/playpen" } },
    { "name": "scratch" }
  ]
}

With no startup list the app opens a single shell, exactly as it did before this existed — and if a list opens nothing at all, that is what you get too, since a window you can't type in is not an outcome worth being faithful for.

Two design choices worth calling out:

No IO thread. The PTY is read on the GLib main loop through a unix fd watch (g_unix_fd_add). Terminal state is therefore only ever touched from the main thread, so the renderer reads the screen with no locking. Ghostty itself uses a dedicated IO thread; that is the right answer for a real terminal, but this is dramatically simpler and is not a bottleneck at interactive speeds.

No GPU renderer. Ghostty rasterizes glyphs into an atlas and draws on the GPU. Here, each frame walks the visible rows, groups cells into runs of identical style, and hands each run to Pango. That is far more work per frame in principle, but a terminal grid is small.

What works

Your login shell (from the passwd database, not $SHELL) on a real PTY, started as a login shell, with a controlling terminal so job control, Ctrl-C and SIGWINCH behave
Full SGR rendering: 16/256/true color, bold, italic, underline, strikethrough, inverse, and the bright-on-bold convention
Block / bar / underline / hollow cursor styles
Scrollback via mouse wheel; typing snaps back to the prompt
Resize reflows the grid and notifies the child
Window title (OSC 0/2) becomes the pane header and tab label; the tab shows its pane count once a view holds more than one
Tabs: create, close, switch; closing the last one closes the window
Multiple panes per tab in an arbitrary split tree, rearranged by keyboard or by dragging a pane's header, with draggable dividers between them; closing the last pane in a view closes its tab
Web panes, on WebKitGTK, sitting in the split tree beside terminals and dragging around exactly like they do: back/forward/reload, an address bar that takes a URL or falls back to a search, a load-progress indicator in the entry, and the page title feeding the pane header and tab label, plus find-in-page on Ctrl+F. See Find in page
Saved layouts: whole tabs — panes, splits, ratios, per-pane directories and scripts — opened in one go, parameterised by {{name}}, authored by arranging a tab and saving it. See Layouts
A startup list: the tabs to open at launch, each a layout with its parameters filled in, fillable from the tabs you have open now. See Startup tabs
Pane status in the tab strip, driven by OSC 9;4, so a tab can say whether it is working, waiting on you, or finished and still unanswered. See Agent status
Renaming a tab: Ctrl+Shift+R, double-click a tab row, or Rename in its right-click menu. A typed name pins the label; clearing it hands the label back to the panes
An emoji in place of a tab's icon, from Settings in the same right-click menu, picked out of the full emoji set with keyword search. See Tab settings
Zooming a pane to fill its tab and back, from the header button or Ctrl+Shift+Z. Nothing closes and nothing moves — hidden panes keep running and the split comes back exactly as it was. See Zoom
Light and dark schemes, following the desktop by default and pinnable from the settings page, applying to open tabs immediately — terminal palette included. See Theme
Every colour in the palette editable, per scheme, from Settings → Appearance → Customise: the surfaces, the text on them, the accents, the status colours, and the terminal's own background, cursor, selection and 16 ANSI colours. Each change repaints as you make it. See Customising the palette

Shortcuts


`Ctrl+Shift+T`	new tab
`Ctrl+Shift+E`	new terminal in the current tab
`Ctrl+Shift+B`	new web view in the current tab
`Ctrl+Shift+W`	close the focused pane (closes the tab with its last one)
`Ctrl+Shift+←/→/↑/↓`	move the focused pane within its view
`Ctrl+Shift+V`	paste into a terminal (bracketed-paste aware, refuses unsafe pastes)
`Ctrl+Shift+C`	copy the terminal selection
`Ctrl+Shift+R`	rename the current tab (empty name = follow the terminal)
`Ctrl+Shift+Z`	zoom the focused pane to fill the tab, and back
`Ctrl+F`	find in the focused web page (web panes only — see Find in page)
`Ctrl+,`	settings
`Ctrl+PageUp/PageDown`	previous / next tab
`Alt+1`..`Alt+8`	jump to tab N, `Alt+9` jumps to the last

Dragging a pane by its header does the same thing as the arrow shortcuts: the edge you drop against decides both the order and the view's orientation. The header is the drag handle rather than the whole pane so that dragging never competes with the content's own mouse handling.

Both add-pane shortcuts are also buttons in every pane header, which is how you open a web view without remembering the chord.

The mouse in a terminal

A terminal's pointer has two possible owners, and which one has it depends on what is running.

Ordinarily it is the window's. Dragging selects text, double-click takes a word and triple-click a line, Ctrl while dragging selects a rectangle, and the wheel moves through the scrollback. Selecting fills the primary selection, so middle-click pastes what was last highlighted; Ctrl+Shift+C puts it on the clipboard proper.

But a full-screen program can ask for the mouse itself (DEC modes 1000-1003), and from then on clicks, drags and wheel notches are encoded and handed straight to it. That is what makes a TUI's buttons clickable and what makes Claude Code scroll. While a program holds the pointer the cursor goes back to an arrow, as a reminder that a drag will not select anything. Holding shift takes it back for the length of that drag, so there is always a way to copy text out of a full-screen application.

One case sits between the two. Pagers — less, man, anything built on them — run on the alternate screen, which has no scrollback for the wheel to move through, and most of them never ask for the mouse. There the wheel becomes arrow keys (DEC mode 1007), which is what those programs are waiting for anyway.

Zoom

A split that was the right shape for watching two things at once is usually the wrong shape for actually working in one of them. Ctrl+Shift+Z, or the fullscreen button in a pane's header, gives that pane the whole tab; the same again puts the split back.

This is not the window manager's fullscreen. The window keeps its decorations, the sidebar stays put, and only the tab's own content area is involved.

Nothing closes and nothing is rearranged. The split tree is left exactly as it was and only the rendering changes, which is what lets the restore be exact rather than an approximation — ratios, orientations and ordering all come back untouched, because they were never taken apart. Hidden panes are unparented but still alive: their shells keep running, output produced while they were off screen is waiting when they return, and their grids keep the size they had rather than reflowing to nothing.

The toggle only appears once a tab holds more than one pane, since zooming the only pane in a view would be an invisible state change. Splitting a pane or moving one leaves zoom, because both of those actions are about the arrangement that zoom is hiding. Closing the zoomed pane leaves zoom; a different pane closing — a background shell exiting, say — does not, since what you are looking at is still there.

Find in page

Ctrl+F in a web pane opens a find bar under its address bar. Typing searches as you go — case-insensitively, wrapping at the end of the document — and the bar reports how many matches there are, or says there are none and reddens the box. Enter steps to the next match, Shift+Enter to the previous, and the two arrow buttons do the same. Escape or the × closes the bar, which is also what clears the highlighting.

The chord is the browser one rather than this app's usual Ctrl+Shift, and it is claimed only while a web pane has focus. In a terminal Ctrl+F is an ordinary control character that the program running there is waiting for — forward-a-character in a readline prompt, the prefix key in tmux — so the key is left alone there.

WebKit does the searching, and it will only tell you the total number of matches, not which one you are on; the count stops at a thousand, on the grounds that a page with more matches than that is one where the exact number tells you nothing.

Tab settings

Right-clicking a tab row opens a small menu: Rename, which is the same one-field popover Ctrl+Shift+R opens, and Settings…, which opens a window belonging to that one tab. Double-clicking a row still goes straight to renaming — it is the thing you do far more often than the other.

The window holds one setting today, Emoji Label: a glyph that stands in for the pane icon in that tab's sidebar row. It replaces the icon rather than joining it, since a row has one slot for "what is this tab" and the label needs the rest of the width. Use the pane icon puts the icon back.

Picking one is a search box over a grid of the whole emoji set — 1906 glyphs, in Unicode's own order and grouping, so it reads the way any other emoji keyboard does. A glyph's tooltip is its name, for the ones you can't quite make out at grid size.

Every whitespace-separated word in the query has to match, in any order, so green circle and circle green both land on 🟢 while circle alone brings back the whole family. Keywords are CLDR's, which is where grin finding 😀 comes from, plus the group and subgroup each glyph belongs to — fruit, arrow and flags each bring back a shelf — plus a table of synonyms for the words a terminal user actually types: deploy finds 🚀, hotfix finds 🩹, docker finds 🐳, rust finds 🦀.

src/emoji.zig is generated by tools/gen-emoji.py from Unicode's emoji-test.txt and CLDR's English annotations; run that rather than editing the table, and add to its SYNONYMS when a glyph should answer to a word the data files don't know. Two things it leaves out. Skin-tone variants, because just over half of Unicode's 3944 sequences are the same gesture in five tones and a grid of them is longer to look through rather than more complete — every base glyph is there. And anything newer than emoji 16.0, because colour fonts trail Unicode by a year or two and a glyph the font has never heard of draws as a hex-digit box, which in a picker reads as a bug; --max-version raises the cutoff once fonts have caught up.

The choice lives on the tab and not on disk, the same as a typed name: it lasts as long as the tab does. Saving the tab as a layout does not carry it, since a layout describes an arrangement of panes rather than what a row looks like.

Agent status

Playpen is mostly used to keep several Claude Code sessions side by side, and the question a sidebar full of them has to answer is "which of these needs me?". So a tab can carry a dot:


purple, pulsing	working
amber	waiting for you — a permission prompt, or a question
green	finished, and you haven't answered it
red	stopped on an error
none	idle

Each colour is carried at three sizes, so it survives being glanced at rather than read: an 11px dot on the row, a bar down the row's leading edge, and a wash behind the whole row. Working gets the bar without the wash — it is the resting state of a busy afternoon, and tinting half the sidebar all day would only teach you to stop looking. Inside a tab, a pane that is asking colours its own frame and header the same way, which is what picks it out of a four-way split.

The green one is the point of the feature. A session that has gone back to idle looks exactly like one that never ran, so a pane that finishes latches green and stays that way until you deal with it. Nothing else tells you a tab is worth going back to.

Opening the tab clears the row. A pane's own dot clears when you go to that pane or type in it. The two answer slightly different questions: the row's is "should I go there?", which visiting settles whether or not you then deal with everything inside, and a pane's is "have you dealt with me?", which only you can answer. In a split that difference is the whole point — you open a flagged tab, the row goes quiet, and the panes you haven't been to yet are still marked.

Work that finishes while you are sitting in the tab flags it too, deliberately. Having a tab on screen when a session stopped says only that the pixels were in front of you; watching it finish and then moving on to something else is the case this is most needed for. It goes quiet as soon as you answer that pane, or the next time you come back to the tab.

Green also outranks purple. A tab holding three sessions goes green as soon as any one of them finishes rather than waiting for the last one to stop, because "one of these is ready for you" is the news. The two states that actually want something from you — amber and red — outrank it in turn.

Panes report this individually and the tab shows the most urgent of them, so a four-pane tab still reduces to one dot. The pane headers carry their own dots, so once the row has brought you to the tab, they say which pane inside it was the one asking; the row stays lit until every finished pane in it has been answered.

How it gets there

Programs report state with OSC 9;4 — the ConEmu progress protocol, the same one Windows Terminal and Ghostty use for taskbar progress — and their title with OSC 0/2. Nothing about this is Claude-specific: a build that reports progress lights the same dot.

Claude Code has no idea about any of this, so a hook tells it:

mise run install-claude-hooks     # merges into ~/.claude/settings.json
mise run uninstall-claude-hooks

That installs hooks/playpen-status.sh into ~/.claude/hooks/ and wires it to five events: UserPromptSubmit → working (and sets the tab title from your prompt), Notification → waiting, Stop / SessionStart / SessionEnd → idle. The red state is deliberately not wired to anything: the obvious candidate, PostToolUseFailure, fires for tool errors Claude then goes on to recover from, so a tab would turn red constantly during ordinary work. The script still accepts error for anything of your own worth flagging that way.

Existing hooks are left alone — every entry is tagged with a marker comment, so re-running replaces Playpen's own entries rather than stacking duplicates, and the previous file is kept at settings.json.playpen-backup. Hooks are read at startup, so open a new session to pick them up.

The hook writes to a pty, not to a socket or a daemon: the bytes land in that pane and no other, with nothing to configure and no way for two concurrent sessions to be mistaken for each other. It writes there rather than to stdout because Claude Code parses hook stdout as the hook's JSON result; an escape sequence written there would corrupt the hook protocol instead of reaching the terminal.

Finding that pty is the one genuinely fiddly part, and /dev/tty — the obvious answer, and what this used to do — is the wrong one. Claude Code starts each hook in its own session, so a hook has no controlling terminal at all and opening /dev/tty fails with ENXIO. It fails invisibly, too: [ -w /dev/tty ] returns true regardless, because it stats a path whose mode is 0666 rather than opening it, so guarding on that reports success and then writes into nothing. Every state change was being dropped on the floor with no error anywhere.

The pty is only one hop away, though — it is on Claude Code's own standard file descriptors. So the script tries its controlling terminal by opening it, and failing that walks up /proc for the nearest ancestor holding a pty, with a ps -o tty= fallback for systems without /proc. The nearest ancestor is the right answer even with something in between: a Claude running inside tmux inside a pane finds tmux's pty, which is where its output actually goes.

A tab's title follows your prompt for as long as Claude holds the foreground. Once it exits, the shell's own prompt sets the title back, which is the right answer — there is no task any more. A name you type yourself outranks both.

Inside a VM

Claude in a microVM (smolvm, krunvm, anything libkrun-based) still works, because the guest console passes these bytes through to the host pty unchanged:

$ # written to the guest's console, observed on the host pty:
b'\x1b]9;4;3\x07'  b'\x1b]0;hello-from-guest\x07'  b'\x1b]9;4;0\x07'

This is the reason for choosing escape sequences over a socket. A unix socket on the host is not reachable from inside a guest, and matching a message to a pane by cwd breaks as soon as guest paths stop corresponding to host ones. A console you already have is the one channel guaranteed to cross that boundary.

The guest has its own $HOME and so its own ~/.claude/settings.json. Install the hook inside the image rather than on the host — the script is dependency-free POSIX sh and behaves identically on both sides:

smolvm machine exec --name NAME -- mkdir -p /root/.claude/hooks
# copy hooks/playpen-status.sh to /root/.claude/hooks/ via a mount or a heredoc,
# then merge the same five events into the guest's settings.json.

jq is used for the title when present and a sed fallback covers a minimal image that has no jq; if the title can't be read the state still reports and the tab simply keeps the name it had.

Theme

Deep navy surfaces with Signal's ultramarine (#3a76f0) as the accent, in a light and a dark scheme. Ctrl+, or the gear at the foot of the sidebar opens Settings, whose Appearance section holds the choice: light, dark, or system, which is the default and follows the desktop.

Every colour it resolves to can be changed — see Customising the palette.

The preference lives in ~/.config/playpen/settings.json (or $XDG_CONFIG_HOME), beside layouts.json, alongside the startup tabs:

{
  "version": 1,
  "theme": "system",
  "colors": {},
  "startup": []
}

Switching applies immediately to every open tab — nothing needs restarting, and a shell that has been running all day repaints along with everything else.

Three separate colour systems have to agree for that to be true, which is what appearance.zig exists to arrange:

libadwaita's style manager colours the stock widgets — popovers, entries, dialog chrome. It is told to force a scheme, or left on default to follow the desktop.
style.css colours everything the app draws itself. It is written entirely against named colours; palette.zig writes the @define-color block that defines them for the scheme in force, and the two are loaded as a single GtkCssProvider. No rule in style.css may hardcode a colour — a literal hex is a rule that looks right in whichever scheme you happened to be testing in, and one the colour editor cannot reach.
theme.zig holds what Cairo draws the terminal grid from: the default background, foreground and cursor, plus the 16 ANSI colours. The style tree is never consulted there, so a CSS reload alone would leave every terminal painted in the scheme it started in. It resolves the same table style.css is fed from, and caches the result — the renderer asks for the background once a frame and for the palette once a cell, and neither should be going through the settings for an answer.

The ANSI palette is the part that is easy to skip and shouldn't be. The standard xterm yellow is #cdcd00, which on a white background is close to invisible — and prompts and build tools use it constantly, so a light scheme without a light palette is a light scheme you can't read. The 240 colours above index 16 are fixed by spec and left alone; only the 16 named ones change.

They are swapped through libghostty-vt's DynamicPalette.changeDefault, which changes what the palette defaults to. Anything a program set for itself with OSC 4 survives the switch, and a later OSC 104 reset returns to the current scheme's palette rather than the one the app happened to start in.

Whether "system" currently means light or dark is libadwaita's answer, not ours: it already watches the desktop for the setting. So the stylesheet follows its dark property rather than the stored preference, and the preference only decides what the style manager is told. A desktop that switches at sunset takes this app with it, with no extra machinery and no second source of truth.

Customising the palette

Settings → Appearance → Customise opens the palette itself: a swatch for every colour named above, in sections — surfaces, text, tab rows, accent, status, then the terminal's own background, foreground, cursor and selection, and the 16 ANSI colours as a strip. Beside each row is the hex it currently resolves to, so a palette can be read off as text rather than only picked at, and a button that puts that one colour back. Each section heading has the same button for the section, and the foot of the list has one for the whole scheme.

Three things about how it behaves, all following from the same decision — that the editor edits the palette you can see:

A change applies as you make it. Every colour in the list paints something behind the dialog, so the swatch is its own preview; there is no OK button because there is nothing pending to confirm.
It edits the scheme in force. Which is why the way to edit the other one is the theme picker directly above: switch to light, and the section switches with it. Both palettes are kept, so an afternoon spent pinned to light doesn't cost you the dark palette you built.
The terminal follows the window. Left alone, the terminal's background is the pane surface, its foreground is the body text, and its selection is the muted accent — so recolouring the app recolours the terminal drawn inside it, and the frame around a terminal keeps matching its contents. Setting one of those explicitly breaks the link for that colour and only that colour.

Only what has been changed is stored, per scheme, under colors in settings.json:

{
  "version": 1,
  "theme": "dark",
  "colors": {
    "dark": { "accent": "#ff8800", "sidebar": "#3a0d0d" }
  }
}

That is a deliberate choice over writing whole palettes out. It keeps the file short and hand-editable, it is what lets a row know whether it has been changed, and it means the shipped defaults can be retuned in a later version and still reach everyone who never touched them — rather than only the people who had never opened the editor. A name this build doesn't know, or a value that isn't #rrggbb, costs that one colour and is logged; the rest of the file is read normally.

palette.zig is where the names, the defaults and the grouping live, which is why there is no longer a palette-dark.css. An editor needs to know what the colours are called, what they started as, and which ones belong together, and none of that can be read back out of a stylesheet without parsing it — so the table answers all of it and the CSS is generated from the table.

Not implemented

This is a proof of concept, and the following are deliberately absent:

Mouse selection and copy. libghostty-vt provides the selection and mouse-encoding primitives, but nothing here is wired to them yet, so there is no way to copy text. Paste works.
Ligatures and complex shaping. Each run is drawn independently at a fixed grid offset, so text that needs shaping across cell boundaries won't look right.
Moving panes between tabs. Panes can only be rearranged within their own view.
Browser furniture. Web panes get navigation, an address bar and find-in-page, and nothing else: no bookmarks, history, downloads or devtools, and each pane uses WebKit's default context, so nothing is persisted between runs. Links that ask for a new window are ignored rather than opening a pane.
Restoring a session. Startup tabs reopen the arrangement you asked for, but nothing captures the state a session got itself into: no scrollback, no running commands, no directories a shell wandered off to. A tab comes back as its layout, not as you left it.
Kitty graphics, hyperlinks, tab reordering.
Custom terminfo. TERM is reported as xterm-256color rather than ghostty, since we don't install a terminfo entry.

Development

./b.sh wraps nix develop --command zig build and strips the enormous command line Zig prints on failure.

mise run screenshot out.png "text to type" (or ./shot.sh directly) runs the app inside a throwaway headless Sway and screenshots it. This keeps UI checks entirely out of your real Wayland session — nothing appears on screen, and it works while the session is locked.

One caveat when driving it: wtype loses the first keystroke of every invocation while the compositor adopts its freshly uploaded keymap, so scripted input should begin with a throwaway key. That is a quirk of the injection tool, not of the terminal. Note that this applies per invocation, so a trailing wtype -k Return in its own call is swallowed entirely — pass it as part of the same wtype command as the text it submits.

Modifier chords do work, but only with that same caveat applied to the chord itself. wtype -M ctrl -k comma -m ctrl on its own is unreliable — the dropped first event is the modifier press, leaving a bare comma — so the throwaway key has to go inside the same invocation:

./shot.sh out.png "-k Shift_L -M ctrl -k comma -m ctrl"

Note that shot.sh quotes $KEYS, so a chord needs the quoting relaxed for the words to reach wtype as separate arguments.

Synthetic clicks do not work. swaymsg seat seat0 cursor set/press is accepted and reports success, but the headless backend has no pointer device to emit from and the client never sees it. Anything reachable only by clicking has to be reached another way — a keyboard shortcut, or zig build test if the thing being checked is logic rather than pixels.

zig build test runs the unit tests, which cover layout parsing, the parameter/$(...) substitution pipeline, and the emoji table and its search. They build as two binaries, rooted at Layouts.zig and emoji.zig, so neither links GTK — a test binary has one root, and those are the two files worth testing in isolation that have nothing to do with each other.

tools/gen-emoji.py regenerates src/emoji.zig from Unicode's emoji-test.txt and CLDR's annotations. It is not part of the build — its output is committed, so a build never needs the network — and --check reports whether what is committed is what it would write. See Tab settings.

Web panes need an EGL display and the headless compositor has no GPU, so shot.sh forces the dev shell's mesa down to its software rasterizer. The mesa paths themselves come from the dev shell and are needed on a real session too — see Running off-NixOS.

README.md Unescape Escape

Playpen