Summon your Ghostty workspace!

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

Install

npm i -g summon-ws

Requires Node >= 18, 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% ---------------------+------ 25% ------+
|                    |                          |                 |
|                    |    editor (2)            |                 |
|    editor (1)      |                          |    sidebar      |
|                    +--------------------------+                 |
|                    |                          |                 |
|                    |    shell                 |                 |
|                    |                          |                 |
+--------------------+--------------------------+-----------------+
      left col             right col                sidebar

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 | | 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 completions <shell> | Generate shell completion script (zsh, bash) |

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 | | --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 | | starship-preset | | Starship prompt theme preset (per-workspace) | | font-size | | Font size for workspace panes (points) | | on-start | | Command to run before workspace creation | | 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 env.API_KEY sk-123          # per-workspace environment variable

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. | | 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.

When a .summon file contains command values with shell metacharacters (;, |, &, `, $(, ${, <, >), summon displays the commands and prompts for confirmation before executing (confirmDangerousCommands). 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