unitmux: A Floating Desktop App for Claude Code and Codex in tmux

Introduction

If you're running Claude Code or Codex in tmux, you've probably experienced this:

You want to give instructions while reading code in your editor, but every time you have to Cmd+Tab back to the terminal.

The AI asks "1. Yes / 2. No" and you have to switch back to the terminal just to type 1.

When running multiple Claude or Codex sessions in parallel, it's hard to keep track of which pane is in what state.

These small context switches add up and repeatedly break your flow of thought. It's surprisingly stressful.

To solve this, I built a desktop app called unitmux.

What is unitmux?

A desktop app that lets you send instructions directly to Claude Code or Codex running in tmux, from a floating window.

It stays always-on-top, auto-detects tmux panes, and eliminates the need to switch focus to the terminal. You can give instructions to your AI without interrupting your editor workflow.

It also detects panes running the ai wrapper command in addition to claude and codex.

Install with one line:

brew install --cask yugo-ibuki/tap/unitmux

Features

One-Click Responses to Choices

When Claude Code or Codex presents numbered choices, unitmux automatically displays clickable buttons.

You can also respond instantly via keyboard with Ctrl+1-Ctrl+9, so you don't even need to reach for the mouse.

That minor annoyance of switching to the terminal just to type a single character is gone.

Update: Choice detection now supports multiple patterns beyond simple numbered lists: marker-prefixed choices (❯, ›, >, ●), colon-separated inline options such as 1: staging 2: production 3: dev, and multi-line labels such as permission prompts with full command text.

It also intelligently filters out session rating feedback such as "How is Claude doing?" and CLI footers to avoid showing false positives.

Codex support has also been improved. unitmux can detect Codex-style letter choices and uses separate heuristics for Codex prompts, including English and Japanese choice context.

Global Shortcut: Access from Anywhere

Press Cmd+Shift+H to bring focus back to unitmux from any app.

Focus lands directly on the text area, so you can start typing right away and send with Cmd+Enter.

Reading docs in Chrome while instructing the AI now takes just a few seconds, practically seamless.

Update: The focus shortcut is now fully customizable from the Sidebar settings. It also auto-expands compact mode when triggered from another app, so you're immediately ready to type.

Session Status at a Glance

Panes are listed as tabs, with a colored dot indicating status:

• Green: Accepting input
• Orange: Processing
• Gray: Waiting for response / choices available

Each pane also shows a small badge for the tool:

• CC: Claude Code
• CX: Codex

When running multiple Claude or Codex sessions in parallel, you no longer have to wonder "how far along is that pane?"

Switch between panes with Cmd+↑ / Cmd+↓ or Ctrl+H / Ctrl+L.

Update: Panes are now grouped by tmux session in the header, making it easier to navigate when you have many panes across different sessions. Cross-session navigation is also available via Ctrl+Cmd+H / Ctrl+Cmd+L.

Status detection has been refined. For Claude Code, unitmux reads the pane title for idle markers and spinner characters, and parses recent pane output for waiting prompts and choices. Codex status detection uses its own heuristics, such as Working, Thinking, Executing, and enter to send.

unitmux also detects panes running the ai wrapper command in addition to claude and codex.

Git Operations in a Popup

Ctrl+G opens a Git operations popup.

It only covers simple operations, but when you want to commit frequently during the early stages of personal development, being able to do it seamlessly is a real advantage.

You can:

• Stage all changes
• Select individual files with Space
• Stage selected files with Enter
• Type a commit message and press Enter
• Push with Ctrl+P

The popup supports vim-style navigation with j / k.

Being able to commit right when the AI finishes a chunk of work, without going back to the terminal, is quietly satisfying.

Update: The Git popup now displays the current branch name in its header and shows detailed Git status: modified files, untracked files, deleted files, and so on. It also auto-refreshes pane detail after each operation and shows success/error feedback that auto-dismisses after 2 seconds.

Git Diff Viewer

Ctrl+F opens a Git diff viewer.

This is separate from the Git operations popup. The Git popup is for staging, committing, and pushing. The diff viewer is for quickly checking what changed.

It supports:

• Unstaged / staged diff switching
• File sidebar
• Directory folding
• Collapsible file sections
• Hunk navigation
• Vim-style scrolling

Useful keys:

• j / k: scroll
• d / u: half-page scroll
• g / G: top / bottom
• ]c / [c: next / previous hunk
• s: toggle staged / unstaged
• q: close

This makes it easier to review AI-generated changes without switching back to the terminal to run git diff.

Semi-Transparent Window to Overlay on Your Editor

You can adjust the window opacity between 50% and 100% with a slider.

Combined with Always on Top, you can see through to your editor's code while giving instructions to the AI.

You can keep an eye on Claude or Codex activity while reading code.

Pair this with Cmd+Shift+H and you can shift focus to the app, write a prompt or pick a choice, all without touching the mouse.

View Current Session Content

Ctrl+P lets you check the session conversation without looking at the terminal.

When you just want to see what question was asked or glance at the last answer, this lets you quickly check and move on to the next prompt.

When the agent runs, it produces a lot of log output, but usually what you actually want to see is the final conclusion. Being able to quickly check just the part you care about and move right into the next prompt is the real benefit.

Update: The preview overlay now has two modes.

The first press of Ctrl+P shows a static snapshot. Pressing Ctrl+P again while the overlay is open switches to live streaming mode, which polls pane content every 500ms and shows a LIVE badge.

Vim-style navigation is available inside the preview:

• j / k: line scroll
• d / u: half-page scroll
• g / G: top / bottom

When available, unitmux also supplements tmux pane output with Claude's JSONL conversation history under ~/.claude, so older conversation context is easier to inspect.

Image Attachment

Images can be attached from the + button or by dragging and dropping them onto the window.

Thumbnails are displayed in unitmux, and the image paths are sent to the AI CLI using bracketed paste so the CLI can detect them as image inputs.

This is useful when you want to ask about screenshots, UI states, diagrams, or local image files without manually typing paths into the terminal.

Compact Mode

Ctrl+W shrinks the window to a minimal bar of about 70px height.

This is useful when you want unitmux to stay visible without taking up screen space.

Expanding back restores the previous window size and position. The shortcut key is customizable.

Session Detail Overlay

Ctrl+D shows detailed information about the selected pane:

• Model name
• Session ID
• Git branch
• Git status
• Working directory
• Pane dimensions
• Start command
• PID / tty

It also includes a close button with a confirmation dialog to terminate the pane.

Create New Session

unitmux can create new Claude or Codex sessions from the UI.

There are two workflows:

• Ctrl+N: quickly add a Claude session to the current tmux session
• Ctrl+Shift+N: open a dialog to create a new tmux session or add a Claude/Codex window to an existing session

In the dialog, you can select the target tmux session and choose between claude and codex.

Shell Mode

Ctrl+B toggles shell mode.

In shell mode, unitmux sends input to a dedicated unitmux-shell tmux window instead of the selected AI pane.

The shell pane is created on demand and uses your default shell. If it is manually closed, unitmux recreates it on the next send or preview.

Preview and live streaming also work for shell output.

This is handy when you want to run quick commands near your AI sessions without switching back to the terminal.

Sidebar Settings Panel

A dedicated settings panel is accessible from the header, offering:

• Always on Top toggle
• Opacity slider
• Theme switch: dark / light
• Send key config: Enter or Cmd+Enter
• Vim mode toggle
• Font size control
• Customizable shortcut keys for compact, preview, detail, Git, diff, and focus
• Choice modifier: Ctrl or Cmd
• Slash command manager

Slash Commands & Skills Integration

Type / in the input area to filter and select from registered commands.

User-defined slash commands can be managed in the Sidebar. You can create, edit, and delete reusable commands such as /fix, /review, or /test.

In addition, unitmux auto-discovers skill commands from:

• ~/.claude/skills/
• .claude/skills/ in the selected project

It parses SKILL.md files for names and descriptions and shows them as read-only slash command candidates.

Input History

The last 10 unique inputs are stored.

Navigate with ↑ / ↓ in the textarea.

Your current draft is preserved when navigating up and restored when you come back down.

Vim Mode

When enabled, unitmux sends Escape followed by i before your text to enter insert mode.

This is useful if you've accidentally left the pane in normal mode while using Claude CLI's vim editor mode.

This is skipped when responding to choices, since single digit choices work directly.

Help Overlay

Ctrl+, opens a quick reference for keyboard shortcuts, organized by category.

It supports the same vim-style scrolling as other overlays.

Installation & First Launch

brew install --cask yugo-ibuki/tap/unitmux

If you'd rather install from DMG, grab it from Releases.

If you see a Gatekeeper warning on first launch, go to:

System Settings → Privacy & Security → Open Anyway

Closing Thoughts

I built this for people who use AI coding assistants in tmux and wanted to simplify the world of "too many terminal windows."

The guiding principle was "simple, then simpler."

No unnecessary mouse operations. Everything is designed to work with Vim-like keybindings so it feels natural to operate.

Rather than trying to replace tmux or become a full terminal manager, unitmux focuses on making prompt input and agent monitoring as low-effort as possible.

tmux is still the base. unitmux just strips away the context switches around it.

Feedback and PRs are very welcome.

👉 https://github.com/yugo-ibuki/unitmux

A star would be really motivating!

Notes

Mac is the primary supported platform.

Linux builds exist, but Linux support has not been verified thoroughly, so please keep that in mind.

Also, since I primarily use Claude Code, there may still be gaps in Codex support.