domux

A tmux switcher that shows which of your parallel AI agents is waiting on you.

domux helps me scale multiple sessions in a single project. It's built on top of tmux. I wanted something that extends my current workflow rather learning another tool. I am comfortable working in the terminal, and that's where I wanted this to work. It's simple, and it's not trying to do too much. There are a bunch of alternatives to this of course, but this works best for me, and it's quite scalable, yet simple. The beauty of the world we live in today is building software tailored to you. This is my take on an AI IDE built on top of the terminal. This is currently my daily driver.

There are two main parts to domux, the switcher and the todolist:

Switcher

The switcher <leader> + s is a custom tmux session switcher, but rich with details like the branch a worktree is on, a name for your session, preview of the tasks attached to that session — and shows the status of what AI agent attached to that session is doing, is it working or waiting for your input. It currently works with claude and codex.

Todolist

The todolist <leader> + t, is a simple tracker to remember what you were doing on that workspace.

Commands

There is also a utilities panel <leader> + u, that currently only supports caffeinate on / off (and requires sudo in case you want to keep your mac awake even with the lid closed)

That's it, feedback welcome!

Note: Everything below this point is AI generated to help set up domux on your machine.

Requirements

Release binaries are macOS only, Apple Silicon and Intel. You need tmux for the
session and switcher workflow; the todo TUI on its own is just a terminal program
that runs anywhere.

Install

curl -fsSL https://raw.githubusercontent.com/pranav7/domux/main/install.sh | sh

The installer downloads the latest checksum-verified release binary and runs
domux bootstrap. No Go toolchain is needed.

The script installs to ~/.local/bin by default. If that is not on your PATH,
it prints the line to add to your shell config.

To inspect first and bootstrap later:

curl -fsSL https://raw.githubusercontent.com/pranav7/domux/main/install.sh | DOMUX_SKIP_BOOTSTRAP=1 sh
domux bootstrap

Useful installer variables:

From source:

go install github.com/pranav7/domux@latest
domux bootstrap

Bootstrap

domux bootstrap prints a plan, asks once, then applies the pieces it can use on
your machine:

• installs tmux with Homebrew if tmux is missing and Homebrew exists
• writes ~/.config/domux/domux.tmux
• patches Claude Code hooks if Claude Code is present
• patches Codex hooks if Codex is present
• registers idle-sleep prevention with caffeinate

The tmux config is not automatically sourced. Add this to ~/.tmux.conf:

source-file ~/.config/domux/domux.tmux

Then reload tmux:

tmux source-file ~/.tmux.conf

The generated tmux bindings inherit your existing prefix. domux does not change
your tmux prefix.

Quick Start

Start or resume work in a directory:

domux start ~/code/my-repo

Open the todo TUI for the current context:

domux

Open the session switcher:

domux switcher

Mark the current tmux session as the one running the dev server:

domux server

Give the current session a label:

domux label set "auth cleanup"

Check setup:

domux doctor

Tmux Bindings

After sourcing ~/.config/domux/domux.tmux:

Todo TUI

domux opens the todo list for the current context. Inside a pinned tmux
session, that means the session root. Outside tmux, it uses the current git root
or directory.

Session Switcher

domux switcher shows tmux sessions grouped by project. It can show branch and
PR state, labels, focused tasks, server marker, and Claude/Codex activity when
hooks are installed.

Commands

Script-friendly output:

Optional Claude and Codex Hooks

If you use Claude Code or Codex, domux can install hooks that update tmux and
the switcher when an agent starts working, waits for input, compacts, or exits.

Preview first:

domux install claude
domux install codex

Apply:

domux install claude --apply
domux install codex --apply

The Claude install also writes a /start-task command that tells Claude how to
use domux, tmux sessions, and git worktrees before it starts coding.

There is also an optional Claude Code plugin for an /implement pipeline. See
docs/implement-pipeline.md if you want that. It
is not required for the normal domux workflow.

Caffeinate

domux commands opens a small utilities popup. The first utility is caffeinate.

Partial mode prevents idle sleep and does not require sudo:

domux install caffeinate

Full mode also prevents lid-close sleep. It requires sudo once during install:

domux install caffeinate --full

Storage

Todo files are stored as markdown:

~/.local/share/domux/by-path/<escaped-path>.md

Example:

---
worktree: /Users/alice/code/my-repo
created: 2026-05-18
---

# TODOs

- [ ] Fix login redirect on Safari
  Notes can live under a task.
- [~] Bump react-router
- [x] 2026-05-18 — Verify deploy

## Archive

- [x] 2026-05-17 — Wire up feature flag

Session metadata lives here:

~/.local/share/domux/sessions/<session>.json

Generated integration files live here:

~/.config/domux/

The files are meant to be readable and recoverable. You can edit the markdown
todo files directly; the TUI reloads changes from disk.

Migration

Older tmux dotfile state is still read:

• ~/.tmux-label-*
• ~/.tmux-server-*
• ~/.tmux-claude-*
• ~/.tmux-codex-*
• ~/.tmux-workspace-*

Preview migration:

domux migrate

Apply migration:

domux migrate --apply

Install commands create backups before writing. Migration does not delete the old
dotfiles.

Development

make
make test
make switcher

For local development, make install symlinks ~/bin/domux to the repo build:

make install

Remove that symlink with:

make uninstall