gwt.toml Reference
gwt reads its configuration from .config/gwt.toml in your project root. All sections are optional — sensible defaults are used for everything.
[project]
[project]
name = "my-app" # Project display name (default: directory name)
[session]
[session]
name = "my-session" # Zellij session name (default: "gwt")
All repos with the same session name share a single Zellij session. Use different names to create logical groups.
[gateway]
[gateway]
port = 54846 # Optional: pin the gateway port. Omit to auto-allocate on first attach.
watch = false # Watch mode (default: false)
Port behaviour: When port is omitted (the default after gwt init), the gateway allocates a free port on first start and persists it to .gwt/gateway.port. Subsequent starts reuse that port while it remains available. Set port explicitly only if you need a stable, pinned port (e.g. for shared team configuration).
Gateway apps
gwt init auto-detects dev apps from package.json scripts, npm/pnpm workspaces, convention directories (apps/*, packages/*, services/*), Cargo workspace members with web-server dependencies, and Python project files. Detected apps are offered as a pre-selected multi-select during init.
You can add or edit apps manually at any time:
[[gateway.apps]]
name = "frontend"
command = "pnpm"
args = ["run", "dev"]
cwd = "apps/web" # Working directory relative to project root (default: ".")
port-env = "PORT" # Environment variable for port assignment
port-arg = "--port" # CLI argument for port (alternative to port-env)
ready-pattern = "localhost" # String to detect in stdout when app is ready
Each app gets a dynamically assigned port and is accessible via http://<name>.localhost:<gateway-port>.
Port assignment: Use either port-env (sets an environment variable) or port-arg (appends a CLI argument). The gateway assigns a random available port.
Ready detection: The gateway watches stdout for the ready-pattern string to determine when the app is serving. For apps that print their bound port in startup output, use ready-regex instead:
| Field | Type | Default | Description |
|---|---|---|---|
ready-regex | string | — | Regex with one capture group to extract the port from stdout/stderr. Overrides ready-pattern for port detection. Example: "localhost:(\\d+)" |
[worktree]
[worktree]
path = ".worktrees" # Directory for worktrees (default: ".worktrees")
auto-create = true # Auto-create on switch (default: true)
[merge]
[merge]
commit-message-command = "your-tool summarize" # Command for AI commit messages (default: none)
When set, gwt squash pipes the diff to this command and uses its stdout as the commit message. The user can accept, reject, or edit the result.
[skills]
[skills]
recommend = ["skill-one", "skill-two"] # Skills to install via `gwt skills install`
[hooks.*]
See Hooks for hook configuration.
Extra sections
Any unrecognized top-level sections are passed through as plugin configuration. Plugins deserialize their own config from these extra sections.