sspm — Stupid Simple Process Manager

A lightweight TUI process manager for local development. Define your services and apps in a TOML file, group them into profiles, and manage them interactively.

Features

• TOML configuration — declare processes and profiles in a single sspm.toml
• Interactive TUI — start, stop, and monitor processes with keyboard shortcuts
• ANSI color support — colored command output renders properly (compiler output, test runners, etc.)
• Profiles — group processes into named sets (default, backend, frontend, ...)
• Graceful shutdown — sends SIGTERM first, tracks the entire process group, force-kills on demand
• Scrollable logs — mouse wheel to scroll, per-process output buffers
• Freeze mode — pause rendering to select and copy text

Install

cargo install --path .

Quick start

Create an sspm.toml in your project root:

[profiles]
default = ["db"]
backend-only = ["api", "db"]
full-party = ["api", "worker", "db"]

[processes.api]
name = "API Server"
command = "cargo run --bin api"

[processes.worker]
name = "Background Worker"
command = "cargo run --bin worker"

[processes.db]
name = "Database"
command = "docker compose up postgres"

Then run:

sspm              # starts the "default" profile
sspm backend-only # starts only the "backend" profile
sspm full-party   # starts everything

Configuration

Processes

Each [processes.<key>] entry defines a process:

Field	Required	Description
command	yes	Shell command to run (sh -c)
name	no	Display name (defaults to the key)

Profiles

Profiles are lists of process keys. Processes in the active profile start automatically. Processes not in the profile are still visible and can be toggled on manually.

[profiles]
default = ["api", "worker", "db"]
light = ["api"]

Keybindings

Key	Action
Up / k	Select previous process
Down / j	Select next process
Space / Enter	Toggle process (start / stop / force-kill)
c	Clear output of selected process
f	Freeze/unfreeze display (for text selection)
z	Zoom: toggle fullscreen on the output pane
Scroll	Scroll log output
q / Ctrl+C	Quit (SIGTERM all, then exit when all stopped)
q / Ctrl+C x2	Force quit (SIGKILL all)

Process states

Icon	Color	State	Meaning
[x]	green	Running	Process is alive
[.]	yellow	Stopping	SIGTERM sent, waiting for process to exit
[-]	red	Failed	Exited with non-zero code
[ ]	gray	Stopped	Not running

Toggling a Stopping process sends SIGKILL (force-kill).

Shutdown behavior

sspm spawns each process in its own process group and tracks the entire group, not just the shell. This means:

• SIGTERM/SIGKILL reaches child processes, not just the sh wrapper
• The yellow [.] indicator stays visible until every process in the group has exited
• On quit, sspm waits for all process groups to terminate before exiting
• A second q / Ctrl+C sends SIGKILL to everything still alive