compose-pulse

cpulse

cpulse shows why your Docker Compose stack is stuck. A terminal UI that watches every container in real time, renders the depends_on graph as a tree, names the root cause, and lets you probe, restart, and inspect without leaving the TUI.

The problem

docker compose up dumps interleaved logs from every container into one stream. When something won't start, you're left guessing which service is the actual blocker, scrolling through thousands of log lines, and jumping between terminal tabs. cpulse turns that graph into something you can just look at — and tells you what's blocking what.

What it shows you

Every service gets one of these states, derived from its container state, exit code, restart count, and dependency graph — not just raw Docker status:

An init container that finishes with exit 0 looks nothing like one that crashed — that distinction alone used to require reading logs by hand.

Installation

Homebrew (macOS / Linux)

brew tap hyturing/cpulse
brew trust hyturing/cpulse   # required once for third-party taps (Homebrew 4.6+)
brew install cpulse

Verify: cpulse --version

To upgrade later: brew update && brew upgrade cpulse

Download a binary

Grab the latest release for your platform from GitHub Releases.

# macOS (Apple Silicon)
curl -L https://github.com/hyturing/compose-pulse/releases/latest/download/cpulse_darwin_arm64.tar.gz | tar xz
sudo mv cpulse /usr/local/bin/

Build from source

Requires Go 1.25+.

git clone https://github.com/hyturing/compose-pulse.git
cd compose-pulse
make build
# binary at ./bin/cpulse

Usage

Run cpulse anywhere — it auto-discovers every container on your local Docker daemon:

cpulse

Compose-managed containers appear as dependency trees grouped by project. Everything else shows up in a flat OTHER CONTAINERS section below. New stacks and containers appear automatically — no restart needed.

Bring up stacks in other terminals as usual:

docker compose up

Headless doctor

Diagnose without the TUI — prints root cause + findings, exits 1 if any critical finding:

cpulse doctor
cpulse doctor --project myapp

Commands & flags

Interface

Lazydocker-style layout: select on the left, inspect on the right.

• Top bar — live count of services per state, and how long ago the last poll landed.
• Left column — project rows + nested dependency tree. Each service row shows a state glyph, name, state label, short hint (exit 1, ←2 deps, waiting-since), and live CPU/MEM columns.
• Main panel (right) — tabs follow what you selected:
  • Service selected — 1 Logs · 2 Stats (CPU/MEM sparklines) · 3 Deps (waits-on, blocks, restart order) · 4 Health (inspect healthcheck; Enter runs a probe inside the container)
  • Project selected — 1 Doctor (root cause + findings) · 2 Timeline (scaled startup Gantt) · 3 Graph (roomy pstree with edge conditions)
• Enter zooms the main panel (or jumps to a service / runs a health probe, depending on context). Esc always goes back — never quits.

Keyboard shortcuts

Dashboard

Logs

Actions menu (x)

Restart, stop, start, rebuild, cascade a restart to dependents, run a health probe, or drop into an in-TUI exec shell — without leaving cpulse.

Requirements

• Docker Desktop or Docker Engine running locally
• macOS or Linux

Contributing

Pull requests are welcome. See CONTRIBUTING.md for setup instructions and guidelines.

License

MIT — © 2026 hyturing