Sidebar

Tmux sidebar launcher for opencode.

Why Does This Exist?

OpenCode is easier to use when the session list, preview pane, and TUI stay together. This launcher keeps them in one tmux session so you can move between the sidebar and OpenCode without losing context.

Features

• Left pane for projects and sessions
• Right pane for the stock OpenCode TUI
• Enter-based session recall into preview
• Background active sessions
• Session deletion from the sidebar
• Sound notifications when OpenCode needs input or finishes work
• Automatic cleanup of parked opencode attach panes

Quick Start

Prerequisites

• Node.js 20+
• tmux
• opencode

Make sure they are installed and available in your PATH.

Package

• npm package: https://www.npmjs.com/package/opencode-sidebar

Install from npm

npm install -g opencode-sidebar
opencode-sidebar

The CLI checks for tmux and opencode at runtime. If either command is missing, it prints a clear error instead of failing silently.

Build & run from source

git clone https://github.com/arnavpisces/opencode-sidebar.git
cd opencode-sidebar
bun install
npm run start

npm run start builds the local dist/ output and launches the same tmux-backed CLI used by the published package.

Usage

opencode-sidebar

Shortcuts

• ↑ / ↓: move
• Enter: load or recall the selected session into preview
• n: new session
• e: rename session
• d: delete session with confirmation
• k: kill a running session window without deleting history
• h: hide the selected project folder from the list
• Ctrl-b then Tab: collapse or expand the sidebar from either pane after opening a session. If you use a different tmux prefix, use that prefix instead of Ctrl-b.
• Tab while browsing the sidebar: collapse it. In the collapsed sidebar, Tab, Enter, or clicking anywhere on the icon rail expands it again.
• /: search
• a: add a project folder
• Space: expand or collapse a project
• Ctrl-b then arrow keys: switch between the sidebar and the OpenCode pane
• q: quit

Status Symbols

The sidebar collapses to a five-column icon rail (plus the tmux divider): › expands it, ≡ indicates sessions, and the status dot is ● while running or ○ while idle. A connection error shows !. Click anywhere on the rail, including its empty space, to expand. Labels, counts, and shortcut hints stay in the expanded view. Collapsing gives focus and extra space to OpenCode; expanding restores your previous sidebar width and focus. Both panes and their sessions keep running. The width adapts to small terminals, and the collapsed state survives session switching. Search text, selection, and open dialogs are preserved when toggling with the tmux shortcut. Option/Alt configuration is not needed.

• ▶ means currently previewed
• ◆ means active in background
• [*] means a session recently completed work and still has unread completion state

Configuration

• OPENCODE_SIDEBAR_DIR: override the local state and log directory
• OPENCODE_SIDEBAR_NOTIFY=0: disable sounds
• OPENCODE_SIDEBAR_NOTIFY_ATTENTION_SOUND: custom sound for questions and approval requests
• OPENCODE_SIDEBAR_NOTIFY_COMPLETE_SOUND: custom sound for completion
• Sound values can be a system sound name like Glass or Ping, or a full path such as ~/Music/done.aiff

Release Checks

• npm run verify: typecheck, unit tests, and build
• npm run verify:tmux: manual tmux integration checks in isolated temp workspaces
• npm run verify:release: full maintainer-only release check

Contribution

Pull requests and opening issues are welcome. For details, see:

• CONTRIBUTING.md
• .github/ISSUE_TEMPLATE/bug_report.md
• .github/pull_request_template.md

License

Apache-2.0 © 2026 Arnav Kumar

If this repo helped you, consider giving it a ⭐. Happy Vibing :)