ocmux - Opencode Multiplexer

A terminal multiplexer for managing OpenCode sessions.

opencode-multiplexer-2026-04-12_21.17.32.mp4

Feature Showcase

Diff View

Screen.Recording.2026-04-30.at.6.50.43.PM.mov

Visual Mode

visual.mov

Sidebar Layouts

width.mov

Mermaid Diagrams

Screen.Recording.2026-08-04.at.5.45.21.PM.mov

Table of Contents

• Install
• Usage
• Keybindings
  • Sidebar navigation
  • Session actions
  • Session picker
  • Message history picker
  • Conversation view
  • Diff view
  • Agents view
  • Visual mode
  • Shell mode
  • Sidebar layout
• Advanced workflows
• System behaviors
• Configuration
• Notes
• License

Install

Cargo:

cargo install opencode-multiplexer

Homebrew:

brew tap joeyism/ocmux
brew install ocmux

Shell (macOS / Linux):

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/joeyism/ocmux-rs/releases/latest/download/ocmux-rs-installer.sh | sh

Optional: Mermaid diagrams in conversation view

Conversation view can render fenced ```mermaid blocks as images. This requires the Mermaid CLI (mmdc) on your PATH:

npm install -g @mermaid-js/mermaid-cli

Pixel graphics work best in Kitty (and other terminals that speak the Kitty graphics protocol). Without mmdc, mermaid fences fall back to normal syntax-highlighted code blocks.

Usage

Run ocmux in your terminal. The sidebar lists active OpenCode sessions sorted by most recently updated. The main pane shows the attached session's terminal output.

• Press Enter to attach to a top-level session
• Press Tab to expand/collapse child sessions
• Press v to open a read-only conversation view (see below)
• Press s to open the session manager
• Click a sidebar row to select it

Keybindings

Sidebar navigation

Key	Action
j / Down	Move down
k / Up	Move up
Enter	Attach to session
Tab	Expand/collapse children
s	Open session manager
Ctrl-h	Hide/show sidebar panel
/	Open session picker
r	Refresh active session
?	Show help overlay
q	Quit (confirm with y)
Ctrl-4	Toggle focus sidebar/main

Session actions

Key	Action
n	Spawn new session
t	Create git worktree + spawn
a	Open Agents relationship view
v	Open read-only conversation view
d	Open diff view for session
f	Show files modified by session
!	Drop into shell in session directory
c	Commit/push modified files
h	Open message history picker
s	Open session manager (delete junk)
x	Kill session (y confirm, n/Esc cancel)

Status icons

Icon	Meaning
● (green)	Agent is working (including normal tool startup)
◐ (yellow)	Session is blocked waiting for your input or tool permission
● (cyan)	Subagents are active
✖ (red)	Session encountered an error
○ (gray)	Session is idle

Session picker

Press / to search and attach to any opencode session. The picker uses fuzzy search across repo, title, and directory fields. Live sessions (currently running) are marked with a green dot (●).

Key	Action
↑ / ↓	Move through list
Enter	Attach to selected
Backspace	Delete last character
any key	Filter by fuzzy match
Esc	Cancel picker

The footer shows matched/total counts. Results are sorted by live status first, then fuzzy match score, then recency.

Session manager

Press s to manage your opencode sessions and delete junk that pollutes your message history. You can fuzzy search, select multiple sessions, and hard-delete them (cascading to all their messages, parts, and subagent children).

Key	Action
↑ / ↓	Move through list
Tab	Toggle selection
Ctrl-a	Select all matched
Ctrl-u	Clear selection
Ctrl-d	Delete selected (or current)
y	Confirm hard-delete
Backspace	Delete last character
any key	Filter by fuzzy match
Esc	Cancel / close

Warning

Deletion is permanent and writes directly to the OpenCode database. It is recommended to back up ~/.local/share/opencode/opencode.db before bulk cleanup.

Message history picker

Press h to search past user messages and paste one into the active terminal session. The picker uses fuzzy search across session title and message text. The top table shows session name and message preview; selecting a row shows the full message below.

Key	Action
↑ / ↓	Move through list
Enter	Paste selected message
Backspace	Delete last character
any key	Filter by fuzzy match
Esc	Cancel picker

The footer shows matched/total counts. Results are sorted by fuzzy match score, then recency.

Conversation view

Screen.Recording.2026-08-04.at.5.45.21.PM.mov

Press v from the sidebar to open a read-only view of the session's conversation history. The view polls the opencode database every second and renders messages, markdown, syntax-highlighted code blocks, and tool call status.

Turns are visually separated with a role-colored left gutter (│). User turns use cyan (YOU); assistant turns use green (agent name). Reasoning is dim italic; tool calls are indented and muted under the gutter.

Mermaid diagrams: Fenced ```mermaid blocks are rendered as images when mmdc is installed (see Optional: Mermaid diagrams). In Kitty and compatible terminals, diagrams use pixel graphics and scroll with the conversation; otherwise they fall back to half-block rendering. Without mmdc, the fence is shown as a normal code block.

Key	Action
j / Down	Scroll down
k / Up	Scroll up
G	Jump to end
g	Jump to top
Ctrl-u	Page up
Ctrl-d	Page down
/	Search conversation
n	Next search match
N	Previous search match
q / v / Esc	Close view

Auto-follow: By default, the view stays at the bottom and scrolls automatically as new messages arrive. Scrolling up manually disengages follow mode. Jump to end (G) or page down at the bottom (Ctrl-d) to resume following.

Search: Search is case-insensitive and incremental — type to filter, Enter to confirm. The search bar shows current match position (1/5). Pressing / again or Esc cancels.

Mouse scroll is supported.

Diff view

Screen.Recording.2026-04-30.at.6.50.43.PM.mov

Press d from the sidebar to open a read-only view of the session's git diff. The view shows both tracked and untracked changes, preferring the opencode serve API when available and falling back to git diff otherwise.

The diff view uses a cursor-based navigation model (distinct from the scroll-based conversation view). The cursor determines the position for visual selection. Searching (/, n, N) moves the cursor to the match line, and mouse scrolling keeps the cursor within the visible viewport.

Key	Action
j / Down	Move cursor down
k / Up	Move cursor up
G	Jump to end
g	Jump to top
Ctrl-u	Page up
Ctrl-d	Page down
/	Search diff
n	Next search match
N	Previous search match
v	Toggle visual selection
Enter	Confirm selection & paste
Esc	Cancel selection / close
q / d	Close view

Search: Case-insensitive, incremental. The search bar shows current/total matches. Jumping to matches moves the cursor to the match line. The / key is disabled while visual mode is active — cancel visual mode first to search.

Mouse scroll is supported and keeps the cursor within the viewport (same behavior as Ctrl-y / Ctrl-e).

Agents view

Press a from the sidebar to inspect the selected session's subagent relationships. The view shows a live session tree by default. When the session is the parent of a parallel-builds run, ocmux automatically loads its plan.json and runs.db to show dependency waves, task status, and linked worker sessions.

Select a node with j/k. Press Enter to attach to a linked worker, v to open its conversation, or d to inspect its diff. Press a, q, or Esc to return.

Visual mode

visual.mov

Visual mode lets you select lines from the diff view and paste them as file references into the active terminal session.

Press v from the diff view to enter visual mode. The current cursor line is marked as the anchor. Use j/k to move the cursor and highlight lines. Press Enter to confirm — this closes the diff, returns to the terminal, and pastes the selected lines into the chatbox.

Selection formatting: Lines are grouped by file and formatted as filepath:line or filepath:start-end (e.g., foo.rs:42-58). Deleted files (/dev/null) are skipped. If the selection spans multiple files, each gets its own reference separated by spaces.

Key	Action
v	Toggle visual mode on/off
j / k	Move cursor to expand/contract selection
Enter	Confirm and paste into terminal
Esc	Cancel visual mode (stays in diff view)

• Search (/) is disabled while visual mode is active
• If no valid file references are in the selection, nothing is pasted

Shell mode

Press ! from the sidebar to drop into a shell in the selected session's working directory. The shell inherits the session's environment variables. Exit the shell normally (e.g., exit or Ctrl-D) to return to ocmux.

This works on top-level sessions only — child sessions do not support shell drop.

Sidebar layout

width.mov

The sidebar has two states:

Sidebar and Panel

The sidebar shows your active and discovered opencode sessions. You can hide the panel entirely for more terminal space.

State	Key	Behavior
Visible	(default)	Full-width sidebar showing session tree, title, and status
Hidden	Ctrl-h	Sidebar disappears entirely for maximum terminal space

• Toggle hidden with Ctrl-h
• When the sidebar is hidden, Ctrl-4 (focus toggle) will first unhide it before switching focus
• The sidebar width is configurable via sidebar_width in config (default: 30)

Advanced workflows

• Inspect conversation output — press v on any session (including child sessions) to watch the agent's progress in real-time without attaching to the PTY. Mermaid diagrams render as images when mmdc is available (see Optional: Mermaid diagrams).
• Inspect changed files — press d to open a diff view of all changes made by a session (tracked and untracked)
• Inspect changed files (list) — press f to see which files a session has created or modified. Press any key or Esc to close.
• Drop into a shell — press ! to open a shell in the selected session's working directory. The shell inherits the session's environment; exiting the shell returns to ocmux.
• Commit session changes — press c to prompted for a commit message, then commit and push all modified files immediately.
• Search and attach — press / to open the session picker, search across all opencode sessions, and attach to one.
• Reuse an earlier prompt — press h to open the message history picker, search past user messages, and paste one into the active terminal session.
• Create a worktree — press t to pick a repo directory, then enter a branch name (leave empty to spawn in the repo root without a worktree). A new worktree is created and a session is spawned in it.
• Spawn a session — press n to pick a repo from discovered git repositories (see Configuration for search paths and depth), then spawn a new managed session in that directory.

System behaviors

Focus tracking — When the ocmux window loses OS focus, the border dims to dark gray. When focus returns, the border resumes normal styling.

Sidebar sync — When focus is on the terminal (attached session), the sidebar selection automatically tracks the active session. If the attached session exits, focus returns to the sidebar with a "session exited" footer message.

Notifications — When notifications: true in config, ocmux sends desktop alerts on specific session transitions: Working → Idle, Working → NeedsInput, Working → Error. Each session has a 5-second cooldown between notifications. On macOS, notify-rust is used (which respects Do Not Disturb / Focus modes). On Linux, notify-send is used as a fallback. Notifications are suppressed while ocmux is the focused window.

Terminal features — ocmux supports bracketed paste (safe paste of multi-line content), full special-key forwarding (arrows, Home, End, PageUp, PageDown, F-keys, etc.), and proper terminal resize on window changes. Mouse wheel scroll and clicks are forwarded to the active terminal session (SGR), while diff and conversation views scroll locally. Left-drag still selects text for clipboard copy; a click without drag is delivered to the app.

Configuration

Keybindings, sidebar width, desktop notifications, and repo search depth are configurable via ~/.config/ocmux/config.json:

{
  "sidebar_width": 30,
  "notifications": true,
  "spawn_maxdepth": 5,
  "keybindings": {
    "up": "k",
    "down": "j",
    "spawn": "n",
    "kill": "x",
    "help": "?",
    "worktree": "t",
    "quit": "q",
    "view": "v",
    "files": "f",
    "diff": "d",
    "history": "h"
  }
}

Keybinding values are single characters. Default sidebar_width is 30. Only the keys listed above are configurable; other bindings (Enter, Tab, /, s, Ctrl-h, r, !, c, Ctrl-4, arrows) are fixed.

notifications controls desktop alerts. Defaults to true.

spawn_maxdepth controls how deep find searches for git repos when spawning or creating worktrees. It searches ~/Programming, ~/repos, ~/projects, and ~/code (falling back to ~ if none exist). Defaults to 5.

Notes

• Ctrl-4 is the actual focus toggle binding (hold Ctrl and press 4)
• s opens the session manager; Ctrl-h hides the sidebar entirely for maximum terminal space
• q prompts for confirmation before quitting (y confirm, n/Esc cancel)
• Child sessions are expandable and selectable in the sidebar, but Enter attach is not yet supported for child rows — use v to view their conversation instead
• c and ! operate on top-level sessions only
• r refreshes the currently active session's PTY, not the selected sidebar row
• Killing a managed session (x) also terminates its associated opencode serve daemon
• Deleting a session via the session manager (s) is permanent and hard-removes all associated messages and parts from the database

License

Apache-2.0