domux

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:

The 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.

The 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 \ + 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:

Variable	Meaning
DOMUX_VERSION=v0.1.0	Install a specific release
DOMUX_INSTALL_DIR=/custom/bin	Install somewhere else
DOMUX_SKIP_BOOTSTRAP=1	Skip setup after download

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:

Binding	Action
<prefix> t	Open todo popup for the current pane path
<prefix> s	Open session switcher
<prefix> u	Open utilities popup
<prefix> v	Toggle server marker for current session
<prefix> N	Set session label
<prefix> n	Clear session label
<prefix> i	Toggle AI state for current pane
<prefix> f	Clear domux state for current session

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.

Key	Action
j / k / arrows	Move cursor
a	Add task
e	Edit task title
Enter	Edit notes in $EDITOR
Space / x	Mark done and archive
i	Toggle in progress
f	Focus task for this session
d	Delete task
J / K	Move task up or down
Tab	Show or hide archive
r	Reload from disk
? / h	Toggle help
q / Esc	Quit

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.

Key	Action
j / k / arrows	Move cursor
Enter	Switch to selected session
/	Filter sessions
+	Create a workspace session in the selected group
n	Name selected session
c	Clear selected session
r	Reset selected branch only
s	Mark selected session as server
Tab	Show or hide task previews
D	Delete workspace sessions or close main sessions
q / Esc	Quit

Commands

Command	Meaning
domux	Open todo TUI
domux todo	Same as domux
domux switcher	Open session switcher
domux sessions	Alias for switcher
domux start [DIR]	Start or resume a pinned tmux session
domux adopt [DIR]	Pin the current tmux session to a directory
domux attach NAME	Attach or switch to a tmux session
domux clear	Reset and free the current workspace
domux reset-branch	Reset only the current git branch
domux clear-state	Clear domux state for current session
domux server	Toggle server marker
domux commands	Open utilities popup
domux doctor	Check integration state
domux migrate	Preview migration from old tmux dotfiles

Script-friendly output:

Command	Meaning
domux --path	Print todo file path for current context
domux --count	Print active task count
domux --status	Print tmux status text
domux --list	Print active tasks
domux --version	Print version

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

## 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