Introduction

dux is a terminal UI for running multiple AI coding agents in parallel, one git worktree each. It spawns the real CLI for each agent (Claude Code, Codex, Gemini, OpenCode, or anything else you can run in a terminal) inside an embedded pseudo-terminal. No protocol layer, no adapters, no JSON-RPC. Just the tools you already use, side by side, each in its own branch.

The mental model

dux has three nouns. Once they click, the whole app makes sense.

• Projects are git repositories you’ve added to dux. A project points at a checkout on disk and remembers your preferences for it.
• Agents are sessions running inside a project. Each agent gets its own git worktree on its own branch, so two agents working on the same repo never step on each other.
• Providers are the CLIs that power agents. Claude, Codex, OpenCode, and Gemini ship configured out of the box, and you can wire up any other command yourself.

The flow is: add a project, spin up an agent, pick a provider. dux creates the worktree, launches the CLI in a real terminal, and tracks the session so you can walk away and reconnect later.

The three panes

The window is split into three panes:

• The left pane lists your projects and the agent sessions under each one.
• The center pane shows the focused agent’s live terminal output, or a diff view when you want to review changes.
• The right pane shows the files an agent has changed, with diffs.

Tab and Shift-Tab move between panes, and that’s the primary way you get around. Every pane has its own local key combinations, and the authoritative list of every binding lives in the in-app help overlay (press ?). Everything is rebindable; see Configuration for how.

Where dux keeps its files

dux stores everything in one directory:

• Linux: ~/.config/dux/
• macOS: ~/.dux/

Inside you’ll find config.toml (your settings), sessions.sqlite3 (session state), dux.log (logs, the first place to look when something misbehaves), and a themes/ directory for any themes you write yourself.

Where to go next

• Configuration: the config file, where it lives, and how it expands environment variables.
• Managing Themes: switch the look, or build your own.
• Custom CLI Agents: teach dux to drive any CLI you like.