captain-miao: A TUI Fleet Manager for Your AI Coding Sessions

Running multiple AI coding sessions simultaneously is increasingly common, but keeping track of which agent is working, which is waiting for input, and which has finished can quickly become chaotic. A new open-source tool called captain-miao aims to solve this by providing a terminal user interface (TUI) that gives you a bird's-eye view of all your agent sessions.

Unlike other session managers such as herdr or cmux, captain-miao doesn't embed its own terminal. Instead, it leverages the native protocols of the terminal multiplexers you already use—Kitty and zellij—to control sessions as native windows or panes. This keeps the tool lightweight and lets you maintain your existing workflow.

How It Works

When you launch a session via claude or codex, captain-miao wraps it with a launcher process that injects tracking hooks. These hooks report session status, working directory, context usage, and a live preview back to the dashboard. The hooks are torn down on exit, and nothing is written to your global ~/.claude/settings.json.

From the dashboard, you can start new sessions (o / O), resume existing ones (r), or fork, focus, and kill sessions—all without leaving the TUI. The ? key opens a complete keybinding reference, and a which-key strip appears when you press Space to guide you through available actions.

Installation and Setup

You can install captain-miao from source with a Rust toolchain and a C compiler (needed for the bundled SQLite), or use the prebuilt npm package:

bunx @hyperlogue/captain-miao

The npm package downloads a prebuilt binary matching your platform (macOS Intel/Apple silicon, Linux x86-64/arm64) as an optional dependency, so nothing is fetched at runtime. Prebuilt binaries are also attached to GitHub releases if you prefer to download them directly.

A Nix flake is also provided for running directly from GitHub.

Security Considerations

Because captain-miao drives Kitty over its remote-control protocol, that protocol is a real privilege—it can read your terminal and run commands. The tool strongly recommends a secure setup that pairs a password with an allowlist script.

Your kitty.conf should enable remote control with a password and point to an authorization script:

allow_remote_control socket
remote_control_password your-secret
remote_control_authorization_path ~/.config/kitty/captain_miao_rc.py

The script, placed at ~/.config/kitty/captain_miao_rc.py, validates every request against three checks: it must arrive over the socket, carry the correct password, and reference an allowed command. captain-miao's default password is i-am-the-captain-miao, and its default allowed commands are the ones it uses. You can customize these via [kitty] rc_password in its config.

Looser alternatives exist (e.g., allow_remote_control socket-only), but the tightest setup is recommended. captain-miao verifies remote control at startup and exits with a diagnostic if it cannot connect.

Configuration and Customization

Configuration lives in ~/.config/captain-miao/config.toml (or $XDG_CONFIG_HOME). Every key is optional, and an unparseable file falls back to defaults. You can customize colors, default shell, and keybindings.

Keybindings are fully remappable via a [keybinds] table. For example, to remap restart to ctrl+r, add:

[keybinds]
restart = "ctrl+r"

You can also unbind a command with an empty list. The authoritative keymap is in src/app/keymap.rs.

Architecture

captain-miao uses a strict unidirectional data flow. State files are stored under ~/.local/state/captain-miao/ and runtime sockets under $XDG_RUNTIME_DIR/captain-miao/, both with owner-only permissions. These files may contain prompt text, so they are written with mode 0600 inside a 0700 directory. For a deeper dive, see AGENTS.md in the repository.

The project is MIT-licensed and available on GitHub.