Summon your Ghostty workspace!

Summon your Ghostty workspace with one command. Native splits, no tmux.

Browse the Layout Gallery

---

Install

npm i -g summon-ws

Requires Node >= 20.19, macOS, and Ghostty 1.3.1+.

Quick Start

summon .                          # launch workspace in current directory

On first run, an interactive setup wizard guides you through choosing your editor, sidebar, layout, shell, and Starship prompt theme. You can re-run it anytime:

summon setup                      # reconfigure workspace defaults

Register projects for quick access:

summon add myapp ~/code/myapp     # register a project
summon myapp                      # launch by project name

How It Works

Summon generates and executes AppleScript that drives Ghostty's native split system. No terminal multiplexer -- just native Ghostty panes with commands running in each one.

Default Layout

summon .    (panes=2, editor=<your editor>, sidebar=<your sidebar>, shell=true)

+------------ 75% (editor grid) ------------+------ 25% ------+
|                                            |                 |
|                                            |                 |
|    editor (1)          editor (2)          |    sidebar      |
|                                            |                 |
+--------------------------------------------+                 |
|                                            |                 |
|                   shell                    |                 |
|                                            |                 |
+--------------------------------------------+-----------------+
               editor grid (75%)                sidebar (25%)

The editor grid (left 75%) splits vertically between the two editor panes; the shell occupies the bottom of the editor grid; the sidebar runs the full height on the right (25%).

Layout Presets

Preset	Panes	Shell	Use case
full	3	yes	Multi-agent coding + shell
pair	2	yes	Two editors + shell
minimal	1	no	Simple editor + sidebar only
cli	1	yes	CLI tool development -- editor + shell
btop	2	yes	System monitoring -- editor + btop + shell

summon . --layout minimal         # 1 editor pane, no shell
summon . -l pair                  # 2 editors + shell

Custom Layouts

Define arbitrary split configurations using a tree DSL:

summon layout create              # interactive layout builder wizard
summon . --layout my-layout       # launch with a custom layout

Custom layouts are saved to ~/.config/summon/layouts/ and can be used anywhere a preset name is accepted.

Per-project Config

Drop a .summon file in your project root to override machine-level config:

# .summon
layout=minimal
editor=vim
shell=npm run dev
env.PORT=3000

Config resolution order: CLI flags > .summon > machine config > preset > defaults

Commands

Command	Description
summon <target>	Launch workspace (project name, path, or .)
summon setup	Interactive setup wizard — choose editor, sidebar, layout, shell, Starship theme
summon add <name> <path>	Register a project name to a directory
summon remove <name>	Remove a registered project
summon list	List all registered projects
summon set <key> [value]	Set a machine-level config value
summon config	Show current machine configuration
summon open	Select and launch a registered project interactively (always opens a new workspace)
summon export [path]	Export resolved config as a .summon file
summon doctor [--fix]	Check Ghostty config for recommended settings (--fix auto-adds missing)
summon freeze <name>	Save current resolved config as a reusable custom layout
summon keybindings [--vim]	Generate Ghostty key table config for pane navigation
summon layout <action>	Manage custom layouts (create, save, list, show, delete, edit)
summon status [--once]	Interactive workspace status dashboard across all projects
summon switch	Focus an existing workspace window (use this to return to a running workspace); falls back to launching if not found
summon briefing	Morning briefing — overnight commits, dirty files, recommendations
summon ports	Detect port assignments across projects, highlight conflicts
summon snapshot <action>	Manage context snapshots (save, show, clear)
summon session <name>	Launch a saved multi-project session — one Ghostty tab per project
summon session add <name> <p>...	Save a session (named list of registered projects)
summon session list	List saved sessions
summon session show <name>	Print a session's project list
summon session remove <name>	Delete a saved session
summon session --all	Launch every registered project as tabs
summon trust <dir>	Trust a project's .summon file (required before first launch in untrusted directories)
summon completions <shell>	Generate shell completion script (zsh, bash, fish)

switch vs open: Use summon switch <name> to focus an existing workspace window for a running project. Use summon open <name> (or summon <name>) to launch a new workspace. When in doubt: switch returns you to work already in progress; open starts fresh.

CLI Flags

Flag	Description
-l, --layout <preset>	Use a layout preset (minimal, full, pair, cli, btop)
-e, --editor <cmd>	Override editor command
-p, --panes <n>	Override number of editor panes
--editor-size <n>	Override editor width percentage
-s, --sidebar <cmd>	Override sidebar command
--shell <value>	Shell pane: true, false, or a command
--auto-resize	Resize sidebar to match editor-size (default: on)
--no-auto-resize	Disable auto-resize
--starship-preset <preset>	Starship prompt preset name (per-workspace)
--font-size <n>	Override font size for workspace panes
--env KEY=VALUE	Set environment variable (repeatable)
--on-start <cmd>	Run a command before workspace creation
--new-window	Open workspace in a new Ghostty window
--clean	Auto-close stale panes from prior Ghostty session (default: on)
--no-clean	Skip auto-close of restored panes
--fullscreen	Start workspace in fullscreen mode
--maximize	Start workspace maximized
--float	Float workspace window on top
-n, --dry-run	Print generated AppleScript without executing
-h, --help	Show help message
-v, --version	Show version number

Config Keys

Key	Default	Description
editor	(set during setup)	Command launched in editor panes
sidebar	lazygit	Command launched in the sidebar pane
panes	2	Number of editor panes
editor-size	75	Width percentage for the editor grid
shell	true	Shell pane: true (shell), false (none), or a command
layout		Default layout preset
auto-resize	true	Auto-resize sidebar to match editor-size
clean	true	Auto-close stale panes from a prior restored Ghostty session
starship-preset		Starship prompt theme preset (per-workspace)
font-size		Font size for workspace panes (points)
on-start		Command to run before workspace creation
on-stop		Command to run after workspace closes
new-window	false	Open workspace in a new Ghostty window
fullscreen	false	Start workspace in fullscreen mode
maximize	false	Start workspace maximized
float	false	Float workspace window on top

Machine config is stored at ~/.config/summon/config:

summon set editor vim               # use vim as the editor
summon set shell "npm run dev"      # run a command in the shell pane
summon set layout minimal           # default to minimal preset
summon set starship-preset tokyo-night  # per-workspace Starship prompt theme
summon set font-size 14                # font size for workspace panes
summon set on-start "npm install"      # run before workspace creation
summon set new-window true             # always open in a new window
summon set clean false                 # disable auto-clean of restored panes
summon set env.API_KEY sk-123          # per-workspace environment variable

Auto-clearing restored panes (--clean / --no-clean)

When Ghostty restores panes from a previous session, running summon from one of those panes would otherwise nest the new layout inside whichever pane happens to be first. By default, summon detects this case and closes the extra panes before laying out the workspace:

Clearing 4 stale panes from previous session...

To skip this behavior for a single run or permanently:

summon <project> --no-clean         # one-off opt-out
summon set clean false              # global opt-out
summon <project> --clean            # force clean (overrides config)

Auto-clean is skipped when:

• SUMMON_WORKSPACE is set (you're already inside a live summon workspace — the existing nesting warning handles that case).
• --new-window is passed (a fresh window has nothing to clean).
• The current tab has only one pane.
• Dry-run mode (--dry-run).

Note: Any TUI process in a closed pane (LazyGit, vim, etc.) receives SIGHUP. Save your work before running summon from a restored multi-pane tab, or use --no-clean to preserve the panes.

Docs

• Workspace Gallery -- visual showcase of layout examples
• Architecture -- module map, AppleScript generation, layout algorithm
• User Manual -- full command reference, walkthrough, troubleshooting
• Changelog -- release history
• Publishing -- npm publish checklist

Contributing

Contributions are welcome! Please read the Contributing Guide for details on the development workflow, commit conventions, and PR guidelines.

Code of Conduct

This project follows the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

Environment Variables

Variable	Description
SHELL	Login shell used to execute pane commands. Must be an absolute path. Falls back to /bin/bash if unset or invalid.
NO_COLOR	When set, disables ANSI colors in the setup wizard. Follows the NO_COLOR standard.
COLORTERM	When set to truecolor or 24bit, the setup wizard shows colored palette swatches for Starship presets.
STARSHIP_CONFIG	Set automatically when starship-preset is configured. Points each workspace to a cached preset TOML file. Do not set manually.
SUMMON_WORKSPACE	Set to 1 inside summon workspaces. Used to detect and warn about nested launches.
SUMMON_DEBUG	Set to 1 to enable debug output. Each message is written to stderr with an ISO timestamp and also logged to ~/.config/summon/logs/.
EDITOR	Editor used by summon layout edit. Falls back to vi if unset.

Trust Model

.summon files configure commands that summon executes in each pane (editor, sidebar, shell, on-start). Running summon . in a directory will execute whatever commands its .summon file specifies -- this is the same trust model as Makefile, direnv .envrc, or VS Code .vscode/tasks.json.

Summon uses a direnv-style trust gate: before a project's .summon file is acted upon, its SHA-256 hash must be recorded as trusted. The first time you run summon in a directory with a .summon file, it prompts you to trust it. You can also grant trust explicitly:

summon trust .                    # trust the .summon file in the current directory
summon trust ~/code/myapp         # trust a specific project's .summon file

Trust is revoked automatically if the file content changes. Run summon trust <dir> again after any edit.

When a .summon file contains command values with shell metacharacters (;, |, &, `, $(, ${, <, >), summon displays the commands and prompts for confirmation before executing. The prompt offers three choices: y (run all), n (abort), or s (skip that pane). In non-interactive environments (piped input, CI), execution is refused outright. This check is skipped for --dry-run since no commands are executed.

on-start note: The on-start hook executes its value via a shell (execSync) rather than execFileSync. This is intentional -- on-start supports complex shell commands like docker compose up -d && npm install that require shell interpretation. The editor, sidebar, and shell commands are validated against SAFE_COMMAND_RE before execution, but on-start is not, since it is designed to run arbitrary shell snippets. The confirmDangerousCommands safety net still applies: if on-start is set in a .summon file and contains shell metacharacters, the user is prompted before execution.

Always review .summon files before running summon in untrusted repositories, paying particular attention to on-start values which execute as shell commands.

Security

To report a vulnerability, please follow the Security Policy. Do not open a public issue.

License

MIT