While a configured command is running, a matching on-disk file change triggers its restart. It's useful when your tool doesn't already have a good built-in watch mode.
Configure watch patterns
- Select the command in the sidebar.
- Open the command context menu and choose Edit command....
- Add patterns under File watching.
Patterns are stored as restart_when_changed and are evaluated against paths relative to the project root.
Changing patterns while a command is running does not re-register its watcher. Restart the command for the new pattern list to take effect.
Pattern notes
Solo uses glob matching for restart patterns. In this matcher, * can match across path separators. Prefer explicit patterns like src/**/*.ts, config/**, or **/*.go.
- Patterns must be project-relative. Absolute paths and patterns containing
..components are skipped. - Each pattern-derived watch root must exist when the watcher starts. If a missing root is created later, restart the command to register it.
- A watch root that resolves outside the canonical project root, including through a symlink, is skipped.
- Solo skips unsafe roots, including protected macOS app-data directories and overly broad recursive roots such as your home directory.
Runtime behavior
- Solo watches pattern-derived roots within the project. Wildcard-derived roots are recursive; a literal-file pattern watches its parent directory nonrecursively.
- File events use two fixed 500 ms debounce intervals. The callback forwards the first match and suppresses later matches within its window; independently, the restart processor waits at least 500 ms after that forwarded match. It does not implement a trailing-edge quiet window measured from the last raw event.
- On match, Solo performs a full restart cycle for that command and emits a file-restart event.
- File-watch restarts are command-only and trusted-only.
- An empty list or a list with no usable patterns creates no watcher. In a mixed list, Solo skips unusable entries and keeps usable entries active.
Interaction with crash auto-restart
File-watch restarts and crash auto-restart are separate mechanisms. File-watch restarts are triggered by matching file events; crash auto-restart is triggered by process exits and has its own crash-loop limit.
Operational tips
- Avoid very broad patterns in large repos unless you really need them — they can cause unnecessary restarts.
- Because
*can match path separators in Solo's matcher, use anchored patterns when you only want a narrow part of the repo.