kmux

The multi-session terminal workspace for running AI coding agents side-by-side.

A terminal emulator designed for Claude Code, Codex CLI, and Antigravity CLI on macOS and Linux.
Keep track of parallel agent sessions, monitor API usage, and work safely on separate branches via native git worktrees.

English | 日本語 | 简体中文 | 한국어 | Español

macOS
 

Linux
 

Why kmux?

Running CLI-based AI agents like Claude Code, Codex CLI, or Antigravity CLI alongside your development server quickly leads to terminal clutter, fragmented session history, and git conflicts when agents write to the same working directory.

kmux solves this by providing a dedicated terminal workspace built for agent workflows:

• Isolated Parallel Sessions: Run multiple agents simultaneously in split panes or vertical tabs without environment conflicts.
• Attention Notifications: Get native desktop notifications and workspace badges immediately when an agent completes a task or requires human input.
• Unified Usage Dashboard: Monitor API spend, token heatmaps, and session budgets across all agent providers in a single sidebar.
• Instant Session Resume: Browse your indexing history and resume past agent sessions in one click.
• Worktree Workspaces: Spin up isolated git worktree environments automatically, allowing multiple agents to safely modify different branches of the same repository.

Features

Unified Usage Dashboard Track token usage and API spend across Claude Code, Codex CLI, and Antigravity CLI in one sidebar panel — daily heatmap, today's spend, top-spending models, and per-project hotspots.
Cross-Agent Session History kmux indexes sessions from Claude, Codex, and Antigravity into one searchable sidebar — click any session to resume it instantly, in a fresh pane or the tab that's already open.
Worktree Workspaces Right-click any workspace → Convert to Worktree Workspace for an isolated git worktree, so agents can safely edit different branches of the same repo in parallel.
SSH Workspaces Connect any SSH host as a kmux workspace with Convert to SSH Workspace... — split terminals, run agent sessions side by side, and resume right where you left off after reopening the app.

Terminal Power-User Features

• Split Panes & Tabs — Group build servers, logs, and agent shells within a single workspace.
• Smart Sidebar — Automatically detects your active working directory (cwd), git branch, listening ports, and unread status.
• Layout Persistence — Instantly restores your exact workspace layouts, active tabs, and directories when you relaunch the app.
• Vim Copy Mode & Search — Search terminal buffers (⌘ F) and use Vim-like keybindings to select and copy text without touching the mouse.
• Command Palette — Access all actions and custom workspace commands quickly with ⌘ ⇧ P.

Install

macOS

Homebrew (recommended)

brew tap kkd927/kmux
brew install --cask kkd927/kmux/kmux

kmux includes a built-in updater and will let you know when a new version is available.

DMG download

 

1. Click the button that matches your Mac (M1/M2/M3/M4 → Apple Silicon, older Intel Macs → Intel)
2. Open the downloaded .dmg and drag kmux into your Applications folder
3. On first launch, macOS may ask you to confirm — click Open

Linux

 

1. Choose the AppImage for your Linux CPU (x64 → Intel/AMD 64-bit, ARM64 → ARM 64-bit)
2. Make it executable: chmod +x kmux-linux-x64.AppImage or chmod +x kmux-linux-arm64.AppImage
3. Run the matching file: ./kmux-linux-x64.AppImage or ./kmux-linux-arm64.AppImage

Quick Start

1. Launch kmux and create a workspace (⌘ N on macOS).
2. Inside the terminal, run your local agent CLI — claude, codex, or agy.

   💡 Note: kmux runs the agent CLIs already installed on your system. It does not require you to configure any API keys or wrappers.

3. Toggle the sidebar (⌘ B on macOS) to see the Usage and Sessions panels.
4. Create another workspace to run another agent — or right-click a workspace → Convert to Worktree Workspace if both need to touch the same repo.
5. When an agent needs input or finishes, a native desktop notification fires and the workspace picks up an attention badge.

Keyboard Shortcuts

Shortcuts below show the macOS defaults. Linux uses platform-specific text shortcuts, and every action is also reachable from the command palette.

Workspaces

Shortcut	Action
⌘ N	New workspace
⌘ ]	Next workspace
⌘ [	Previous workspace
⌘ 1–9	Switch to workspace by number
⌘ ⇧ R	Rename workspace
⌘ ⇧ W	Close workspace
⌘ B	Toggle sidebar

Panes

Shortcut	Action
⌘ D	Split right (vertical)
⌘ ⇧ D	Split down (horizontal)
⌥ ⌘ ← → ↑ ↓	Focus pane directionally
⌥ ⇧ ⌘ ← → ↑ ↓	Resize pane
⌥ ⌘ K	Close pane

Surface Tabs

Shortcut	Action
⌘ T	New surface tab
⌃ Tab	Next surface
⌃ ⇧ Tab	Previous surface
⌃ 1–9	Switch to surface by number
⌘ W	Close surface
⌃ ⌘ W	Close other surfaces

Terminal & Utilities

Shortcut	Action
⌘ ⇧ P	Command palette
⌘ F	Search in terminal
⌘ G / ⌘ ⇧ G	Find next / previous
⌘ C / ⌘ V	Copy / paste
⌘ ⇧ M	Vim-style copy mode
⌘ I	Toggle notifications
⌘ ⇧ U	Toggle usage dashboard
⌘ ,	Open settings

Resources

📖 Product Spec	docs/product-spec.md — full feature spec, including automation socket & CLI
🏗️ Architecture ADR	docs/adr/0002-electron-xterm-mvp-architecture.md
🛠️ Development Guide	docs/development.md — build from source, dev loop, debugging
🤝 Contributing	CONTRIBUTING.md
📜 Code of Conduct	CODE_OF_CONDUCT.md
🔒 Security Policy	SECURITY.md

---

kmux — your AI coding agents, side-by-side.

_{macOS + Linux · Actively developed}