pi-lazydocker

Open lazydocker inside Pi with one keystroke. Press alt+l and your containers, logs and stats show up in a themed floating window over your session. Press ctrl+q and you're back where you left off, with the agent still running.

Quick start

1. Install lazydocker (any method from its README):

   brew install lazydocker

2. Install the package:

   pi install npm:pi-lazydocker            # Pi
   gentle-shell install npm:pi-lazydocker  # gentle-shell

3. Inside Pi, press alt+l (or run /lazydocker).

Two ways to open it

| Mode | What you get | Open it with | |---|---|---| | Overlay (default) | A rounded, theme-colored window centered over Pi. Pi stays visible and the agent keeps working underneath. | alt+l, /lazydocker, /lazydocker --overlay | | Fullscreen | lazydocker owns the whole terminal; Pi is restored exactly as it was when you quit. | /lazydocker --fullscreen, or ctrl+o from the overlay |

The overlay falls back to fullscreen by itself when it cannot run: if the native PTY module failed to install on your platform, or if the terminal is smaller than 60×15. You always get lazydocker.

Keys

| Where | Key | Action | |---|---|---| | Pi | alt+l | Open lazydocker in your default mode | | Overlay | ctrl+q | Close the overlay | | Overlay | ctrl+o | Reopen in fullscreen ("open full") | | Overlay / fullscreen | q | Quit lazydocker normally |

Every other key goes straight to lazydocker. See lazydocker's keybindings.

Does alt+l clash with anything? No, not in Pi's defaults or in gentle-shell (which uses alt+g, alt+u, alt+a, alt+s and alt+k). If you already use it, change or disable it with PI_LAZYDOCKER_KEY.

Command

/lazydocker [--overlay | --fullscreen] [lazydocker args...]

| Flag | Meaning | |---|---| | -O, --overlay | Open in the floating window | | -F, --fullscreen | Hand the whole terminal to lazydocker | | -h, --help | Show usage | | -- | Pass everything after it to lazydocker unchanged |

Any other argument goes to lazydocker, for example a specific compose file:

/lazydocker -f docker-compose.prod.yml

lazydocker starts in Pi's working directory, so it picks up the Compose project of whatever repo your session is in.

Configuration

Configuration is optional. Set these variables in your shell profile:

| Variable | Default | Description | |---|---|---| | PI_LAZYDOCKER_KEY | alt+l | Shortcut. Set it to off (or empty) to disable it. | | PI_LAZYDOCKER_MODE | overlay | Mode for the shortcut and for a bare /lazydocker: overlay or fullscreen. | | PI_LAZYDOCKER_WIDTH | 92% | Overlay width, in columns (140) or as a percentage (80%). | | PI_LAZYDOCKER_HEIGHT | 90% | Overlay max height, in rows or as a percentage. | | PI_LAZYDOCKER_COMMAND | lazydocker | Binary or wrapper to run, for example an absolute path. |

Invalid values never break the extension. It falls back to the default and shows a warning the first time you open lazydocker.

# fish example
set -Ux PI_LAZYDOCKER_KEY ctrl+alt+d
set -Ux PI_LAZYDOCKER_WIDTH 85%

Requirements

• Pi in interactive (TUI) mode. In print, JSON or RPC mode the command explains why it can't run.
• Node.js ≥ 22.19 (the same minimum as Pi).
• lazydocker on your PATH (or set PI_LAZYDOCKER_COMMAND).
• A reachable Docker (or Docker-compatible) engine. lazydocker reports connection problems itself.

Troubleshooting

| Symptom | Fix | |---|---| | Could not find "lazydocker" on your PATH | Install lazydocker, or set PI_LAZYDOCKER_COMMAND to its absolute path. The message lists the install commands for your OS. | | Overlay unavailable (...); opening lazydocker fullscreen. | The prebuilt PTY binary for your platform didn't load. Fullscreen keeps working. Reinstall the package or open an issue with the message. | | lazydocker exits right away | It usually can't reach the Docker daemon. Fullscreen mode keeps the error on screen until you press a key. On WSL, make sure Docker Desktop's WSL integration (or the Docker service) is running. | | alt+l does nothing | Your terminal may intercept Alt. In Windows Terminal or iTerm2, check that Alt/Option sends Meta/Esc+, or pick another key with PI_LAZYDOCKER_KEY. |

How it works

• Overlay: lazydocker runs in a pseudo-terminal (@lydell/node-pty, prebuilt for Linux, macOS and Windows on x64 and arm64, with no compiler needed). Its output feeds a headless terminal emulator (@xterm/headless), and each frame is drawn into a Pi overlay component. Keystrokes from Pi's enhanced keyboard protocols (kitty, modifyOtherKeys) are translated back to the classic sequences lazydocker understands.
• Fullscreen: Pi's TUI is paused, lazydocker inherits the real terminal, and Pi redraws when it exits. lazydocker runs asynchronously, so the agent isn't blocked.

Development

git clone https://github.com/Rade-Studio/pi-lazydocker.git
cd pi-lazydocker
npm install
npm run check        # typecheck + tests
pi -e .              # try it in Pi without installing

See CONTRIBUTING.md.

Credits

• lazydocker by Jesse Duffield. This package only embeds it.
• Ideas from @joelazar/lazygit and @rexkit/pi-lazygit.

License

MIT © Asdrubal Hernandez