...` | Save a session (named list of registered projects) |\n| `summon session list` | List saved sessions |\n| `summon session show ` | Print a session's project list |\n| `summon session remove ` | Delete a saved session |\n| `summon session --all` | Launch every registered project as tabs |\n| `summon trust ` | Trust a project's `.summon` file (required before first launch in untrusted directories) |\n| `summon completions ` | Generate shell completion script (`zsh`, `bash`, `fish`) |\n\n> **`switch` vs `open`:** Use `summon switch ` to focus an existing workspace window for a running project. Use `summon open ` (or `summon `) to launch a new workspace. When in doubt: `switch` returns you to work already in progress; `open` starts fresh.\n\n## CLI Flags\n\n| Flag | Description |\n|---|---|\n| `-l, --layout ` | Use a layout preset (`minimal`, `full`, `pair`, `cli`, `btop`) |\n| `-e, --editor ` | Override editor command |\n| `-p, --panes ` | Override number of editor panes |\n| `--editor-size ` | Override editor width percentage |\n| `-s, --sidebar ` | Override sidebar command |\n| `--shell ` | Shell pane: `true`, `false`, or a command |\n| `--auto-resize` | Resize sidebar to match editor-size (default: on) |\n| `--no-auto-resize` | Disable auto-resize |\n| `--starship-preset ` | Starship prompt preset name (per-workspace) |\n| `--font-size ` | Override font size for workspace panes |\n| `--env KEY=VALUE` | Set environment variable (repeatable) |\n| `--on-start ` | Run a command before workspace creation |\n| `--new-window` | Open workspace in a new Ghostty window |\n| `--new-tab` | Open workspace in a new Ghostty tab |\n| `--clean` | Auto-close stale panes from prior Ghostty session (default: off) |\n| `--no-clean` | Skip auto-close of restored panes |\n| `--fullscreen` | Start workspace in fullscreen mode |\n| `--maximize` | Start workspace maximized |\n| `--float` | Float workspace window on top |\n| `--no-project-config` | Skip the `.summon` file (do not require trust) |\n| `-n, --dry-run` | Print generated AppleScript without executing |\n| `-h, --help` | Show help message |\n| `-v, --version` | Show version number |\n\n## Config Keys\n\n| Key | Default | Description |\n|---|---|---|\n| `editor` | *(set during setup)* | Command launched in editor panes |\n| `sidebar` | `lazygit` | Command launched in the sidebar pane |\n| `panes` | `2` | Number of editor panes |\n| `editor-size` | `75` | Width percentage for the editor grid |\n| `shell` | `true` | Shell pane: `true` (shell), `false` (none), or a command |\n| `layout` | | Default layout preset |\n| `auto-resize` | `true` | Auto-resize sidebar to match editor-size |\n| `clean` | `false` | Auto-close stale panes from a prior restored Ghostty session |\n| `starship-preset` | | Starship prompt theme preset (per-workspace) |\n| `font-size` | | Font size for workspace panes (points) |\n| `on-start` | | Command to run before workspace creation |\n| `on-stop` | | Command to run after workspace closes |\n| `new-window` | `false` | Open workspace in a new Ghostty window |\n| `fullscreen` | `false` | Start workspace in fullscreen mode |\n| `maximize` | `false` | Start workspace maximized |\n| `float` | `false` | Float workspace window on top |\n\nMachine config is stored at `~/.config/summon/config`:\n\n```bash\nsummon set editor vim # use vim as the editor\nsummon set shell \"npm run dev\" # run a command in the shell pane\nsummon set layout minimal # default to minimal preset\nsummon set starship-preset tokyo-night # per-workspace Starship prompt theme\nsummon set font-size 14 # font size for workspace panes\nsummon set on-start \"npm install\" # run before workspace creation\nsummon set new-window true # always open in a new window\nsummon set clean true # enable auto-clean of restored panes (default off)\nsummon set env.API_KEY sk-123 # per-workspace environment variable\n```\n\n### Auto-clearing restored panes (`--clean` / `--no-clean`)\n\nWhen Ghostty restores panes from a previous session, running `summon` from one\nof those panes would otherwise nest the new layout inside whichever pane happens\nto be first. By default, summon detects this case and closes the extra panes\nbefore laying out the workspace:\n\n```\nClearing 4 stale panes from previous session...\n```\n\nTo skip this behavior for a single run or permanently:\n\n```bash\nsummon --no-clean # one-off opt-out\nsummon set clean false # global opt-out\nsummon --clean # force clean (overrides config)\n```\n\nAuto-clean is skipped when:\n- `SUMMON_WORKSPACE` is set (you're already inside a live summon workspace — the existing nesting warning handles that case).\n- `--new-window` is passed (a fresh window has nothing to clean).\n- The current tab has only one pane.\n- Dry-run mode (`--dry-run`).\n\n> **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.\n\n## Docs\n\n- [Workspace Gallery](https://juan294.github.io/summon/gallery/) -- visual showcase of layout examples\n- [Architecture](docs/architecture.md) -- module map, AppleScript generation, layout algorithm\n- [User Manual](docs/user-manual.md) -- full command reference, walkthrough, troubleshooting\n- [Changelog](CHANGELOG.md) -- release history\n- [Publishing](docs/publishing.md) -- npm publish checklist\n\n## Contributing\n\nContributions are welcome! Please read the [Contributing Guide](CONTRIBUTING.md) for details on the development workflow, commit conventions, and PR guidelines.\n\n## Code of Conduct\n\nThis project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.\n\n## Environment Variables\n\n| Variable | Description |\n|---|---|\n| `SHELL` | Login shell used to execute pane commands. Must be an absolute path. Falls back to `/bin/bash` if unset or invalid. |\n| `NO_COLOR` | When set, disables ANSI colors in the setup wizard. Follows the [NO_COLOR](https://no-color.org) standard. |\n| `COLORTERM` | When set to `truecolor` or `24bit`, the setup wizard shows colored palette swatches for Starship presets. |\n| `STARSHIP_CONFIG` | Set automatically when `starship-preset` is configured. Points each workspace to a cached preset TOML file. Do not set manually. |\n| `SUMMON_WORKSPACE` | Set to `1` inside summon workspaces. Used to detect and warn about nested launches. |\n| `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/`. |\n| `SUMMON_NO_CACHE` | Set to `1` to disable the persistent cross-invocation read cache (`~/.config/summon/cache.json`). Reads always hit disk. |\n| `EDITOR` | Editor used by `summon layout edit`. Falls back to `vi` if unset. |\n\n## Trust Model\n\n`.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`.\n\nSummon 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:\n\n```bash\nsummon trust . # trust the .summon file in the current directory\nsummon trust ~/code/myapp # trust a specific project's .summon file\n```\n\nTrust is revoked automatically if the file content changes. Run `summon trust ` again after any edit.\n\nWhen 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.\n\n**`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.\n\n**Always review `.summon` files before running summon in untrusted repositories, paying particular attention to `on-start` values which execute as shell commands.**\n\n## Security\n\nTo report a vulnerability, please follow the [Security Policy](SECURITY.md). Do not open a public issue.\n\n## License\n\n[MIT](./LICENSE)\n","readmeFilename":"README.md"}
![\"summon](\"assets/setup-wizard.gif\")
\n