Create, don't correct; preserve, don't prune.
Layouter turns a TOML or React/TSX workflow into a running Linux development workspace. Declare your editor, browser, terminal tabs, and panes; Layouter inspects i3 or Sway and kitty, then creates whatever is missing. Run it again to restore a closed test pane while your editor and development server keep running.
You need Linux, Python 3.11+, i3 or Sway, and kitty 0.40.0+ for Layouter's full feature suite. React/TSX workflows also need Node.js 22+. Release executables bundle the React runtime; npm is only a build dependency.
The kitty minimum is required for pane placement with after, which uses
launch --next-to, introduced in kitty 0.40.0.
Check your installed version with kitty --version.
Install a release executable:
install -Dm755 layouter ~/.local/bin/layouterOr build and install from a checkout with Python, Node.js 22+, and npm available:
make installThis downloads the locked npm dependencies, builds the full executable, and
installs it in ~/.local/bin. Ensure that directory is on your PATH.
Override the destination with make install PREFIX=/your/prefix.
Select Python 3.11+ with make install PYTHON=/path/to/python3.11. The installed
launcher uses that interpreter even if python3 on PATH is an older version.
Keep the selected interpreter (and its virtual environment, if used) available.
See packaging for wheels, Debian packages, and release builds.
Save this as .dev/morning.toml in your project:
session = "morning-{project}-{microfrontend}"
focus = "code"
[args]
microfrontend = { position = 0, required = true }
[[workspace]]
name = "code"
layout = "splith"
[[workspace.window]]
name = "editor"
command = ["zed", "."]
[[workspace.kitty]]
name = "tools"
layout = "tall"
[[workspace.kitty.pane]]
title = "server"
command = ["npm", "run", "dev", "--", "--mf", "{microfrontend}"]
[[workspace.kitty.pane]]
title = "tests"
command = ["npm", "test", "--", "--watch"]
[[workspace]]
name = "browser"
[[workspace.window]]
name = "browser"
command = ["firefox", "--new-window", "http://{microfrontend}.localhost:5173"]Adapt the commands to your project, then validate and launch:
layouter --check morning garden
layouter morning gardenHere, morning is the workflow filename and garden is the value of its
microfrontend argument. These are names you choose for your work.
One command opens your tools, arranges the workspaces, and focuses your editor.
Kitty remote control is configured automatically. Repeating the command fills
in missing pieces without moving existing windows or restarting processes.
Use layouter --sync morning garden when you want to restore the declared arrangement too.
- Share a setup across projects. Put workflows in
~/.config/layouter/and launch withlayouter -C ~/src/garden morning garden. Project-local.dev/files take precedence. Name a workflowdefaultto launch it with justlayouter. - Parameterize your environment. Declare workflow arguments for a service,
branch, or environment, then launch with a command such as
layouter morning garden. See the complete example. - Compose layouts with React. Reuse components and choose layouts from arguments and connected displays. TSX compiles to the same desired state as TOML and uses the same reconciliation engine.
- Manage Firefox windows and declared tabs. Use
FirefoxWindow/FirefoxTabor TOMLworkspace.firefoxdeclarations with the optional companion. Recover browser-restored windows and recreate missing declared tabs while preserving user tabs. See companion setup and compatibility. Local builds produce an unsigned archive; tagged CI releases sign it when AMO credentials are configured. - Keep a layout you arranged by hand. Use
layouter --save-layout morning gardento save a TOML workflow's current arrangement, orlayouter --captureto draft a new workflow from your desktop.
A React workflow can adapt its layout to the current display. Save as
.dev/evening.tsx, then run layouter evening:
import {
defineWorkflow, Workflow, Workspace, Window, Kitty, Pane, useScreen,
} from '@layouter/react';
export default defineWorkflow({
component() {
const { width } = useScreen();
return <Workflow session="evening-{project}">
<Workspace name="code" layout={width >= 1920 ? 'splith' : 'splitv'}>
<Window name="editor" command={['zed', '.']} />
<Kitty name="tools">
<Pane name="server" command={['npm', 'run', 'dev']} />
<Pane name="shell" />
</Kitty>
</Workspace>
</Workflow>;
},
});For launcher integrations, use --list --json, --list-args --json morning,
or --describe --json morning to read structured workflow metadata. See the
integration guide.
- Workflow reference: arguments, nested layouts, displays, floating windows, kitty tabs and panes, capture, and CLI options.
- React workflows: components, hooks, editor setup, and executable configuration behavior.
- Firefox companion: installation, managed-tab badges, privacy boundaries, and browser verification results.
- Integrations: build launchers and argument forms using structured metadata and the CLI.
- Design: identity, desired state, and reconciliation.
- Packaging and validation: release artifacts, automated checks, and desktop testing.
make release installs build dependencies in an isolated Python environment,
loads locked npm dependencies, runs the Python and React checks, and builds and
verifies the release artifacts in dist/. It requires Python 3.11+ with venv
support, Node.js 22+, npm, and dpkg-deb.
Use make build for the executable and source archive, make test for Python
tests, and make check to validate the example. Run make help for all targets.
Layouter is available under the MIT License.
