README
¶
Kranz
A keyboard-first local service orchestrator with a focused terminal UI.
Kranz starts, observes, and stops a local development stack from one terminal. It understands dependency order, readiness and liveness, process groups, runtime ports, logs, one-shot actions, and detached infrastructure whose life is not tied to a local PID.
It runs in the foreground without a daemon or control plane. Use it for the processes you would otherwise spread across terminal tabs, alongside Docker Compose when containers remain the right home for infrastructure.
TUI, CLI, and MCP
Kranz exposes one runtime through three views:
- TUI — the keyboard-first operator view for services, details, logs, lifecycle plans, actions, health history, and notifications;
- CLI — the terminal and scripting view, including stable JSON results;
- MCP — the coding-agent view over the same application operations.
They use the same supervisor. A service restarted by a command or coding agent changes immediately in the open TUI; none of these views starts a second stack.
Coding agents join your live session
Kranz MCP gives a coding agent the same services, actions, readiness, ports, bounded logs, and numbered run history visible in the TUI. It attaches to the existing runtime instead of starting a second development stack.
- One runtime — TUI, CLI, and MCP use the same supervisor.
- One view of the project — the same selectors, action runs, and logs.
- Clear ownership — disconnecting an attached agent does not stop the stack.
Register the existing binary as a stdio MCP server running
kranz mcp -C /path/to/project --attach-only. The explicit attach policy keeps
an agent from silently creating an empty runtime when the intended TUI session
is not running.
See Coding agents and one live runtime for ownership behavior and examples, and the MCP reference for the exact resource, tool, cursor, confirmation, and error contracts.
Quick start
Install on macOS or Linux:
brew install kranz-org/tap/kranz
Or with Go 1.24 or newer:
go install github.com/kranz-org/kranz/cmd/kranz@latest
Create a Procfile:
web: python3 -u -m http.server 8000 --bind 127.0.0.1
worker: while true; do date; sleep 2; done
Run kranz, press a to select everything, then s to start. Kranz discovers
the web listener automatically and shows both services' state and logs.
Already using a supported process-compose.yaml? Run kranz beside it. Use
native kranz.yaml when you need the complete lifecycle model.
Command line
The TUI is optional. Kranz includes a complete CLI for starting a project in the background, inspecting it from another terminal, acting on services, and returning stable JSON to scripts:
kranz init --from Procfile
kranz config check
kranz up -d
kranz status
kranz logs api --tail 20
kranz runs api
kranz logs api --run -1
kranz restart api
kranz down
Use kranz --help to discover commands, kranz COMMAND --help for command
options, and --output json for the versioned machine-readable envelope. See
Working from the command line
for a complete session and the CLI reference
for every command, option, output contract, and exit code.
What it handles
- Dependency-aware startup and reverse-order shutdown
- HTTP, TCP, and command readiness/liveness checks
- Process recovery with backoff and restart limits
- Managed and observe-only detached resources with start/stop/status/logs
- Service actions and project action groups with timeout and confirmation
- Prerequisites that must succeed before a service starts
- Runtime port discovery and ownership-aware conflict handling
- Searchable, pinnable, timestamped logs in a keyboard and mouse TUI
- Bounded per-service and per-action run history with provenance, exact output retention state, navigation, deletion, and export
- Procfile, native YAML, and conservative Process Compose loading
- Live configuration reload with last-known-good fallback
Documentation
- Getting started
- TUI · Terminal interface
- CLI · Command line
- MCP · Coding agents
- Configuration and lifecycle
- Configuration reference
- Annotated kranz.yaml
- CLI reference
- MCP server reference
- Keyboard shortcuts
- Troubleshooting
- Runnable examples
The documentation source lives in docs/ and is deployed to
kranz-org.github.io/kranz/ from main.
Development
make verify
make lint
npm install
npm run docs:dev
Release instructions are in docs/RELEASING.md.
License
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
kranz
command
Package main provides the Kranz command-line entry point.
|
Package main provides the Kranz command-line entry point. |
|
internal
|
|
|
app
Package app is the shared application layer between Kranz's delivery surfaces.
|
Package app is the shared application layer between Kranz's delivery surfaces. |
|
cli
Package cli defines Kranz's command grammar independently from command execution.
|
Package cli defines Kranz's command grammar independently from command execution. |
|
config
Package config defines, loads, merges, and validates Kranz configurations.
|
Package config defines, loads, merges, and validates Kranz configurations. |
|
health
Package health runs independent readiness and liveness probes for services.
|
Package health runs independent readiness and liveness probes for services. |
|
log
Package log classifies, sanitizes, and searches captured service output.
|
Package log classifies, sanitizes, and searches captured service output. |
|
mcp
Package mcp implements Kranz's foreground stdio delivery adapter.
|
Package mcp implements Kranz's foreground stdio delivery adapter. |
|
port
Package port detects listeners and safely releases externally owned ports.
|
Package port detects listeners and safely releases externally owned ports. |
|
runtime
Package runtime carries the application layer (internal/app) across a process boundary over a local Unix socket, so a delivery surface no longer has to run in the same process as the runtime it drives.
|
Package runtime carries the application layer (internal/app) across a process boundary over a local Unix socket, so a delivery surface no longer has to run in the same process as the runtime it drives. |
|
service
Package service manages process lifecycles, dependency ordering, and recovery.
|
Package service manages process lifecycles, dependency ordering, and recovery. |
|
settings
Package settings persists user-level Kranz preferences.
|
Package settings persists user-level Kranz preferences. |
|
ui
Package ui contains the Kranz terminal interface.
|
Package ui contains the Kranz terminal interface. |
|
pkg
|
|
|
ringbuffer
Package ringbuffer provides a concurrency-safe, fixed-capacity string buffer.
|
Package ringbuffer provides a concurrency-safe, fixed-capacity string buffer. |