OpenCode Side Panel Sessions

A TUI plugin for OpenCode that displays parallel and background agent sessions directly in the sidebar. Provides live status updates, session pinning with persistent storage, and one-click navigation — so you never lose track of what your agents are doing.

Quick Start

Option 1: Install via npm (recommended)

cd ~/.config/opencode
npm install opencode-side-panel-sessions

That's it — restart OpenCode and the sessions panel will appear in the sidebar.

Note: The installation script automatically registers the plugin in your tui.json. No manual config editing needed.

Option 2: Local Development Setup

1. Clone the repository:

   git clone https://github.com/j-marcon/opencode-side-panel-sessions.git ~/src/opencode-side-panel-sessions

2. Install dependencies:

   cd ~/src/opencode-side-panel-sessions
   bun install

3. Register the plugin in ~/.config/opencode/tui.json:

   {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": ["../../src/opencode-side-panel-sessions/src/tui.tsx"]
   }

   The path is relative to the ~/.config/opencode/ directory. Adjust if your project lives elsewhere.

4. Restart OpenCode. The sessions panel will appear in the sidebar automatically.

Features

Session List

Displays all top-level (non-subagent) sessions in the sidebar. Each entry shows a status symbol, truncated title (25 characters max), and a pin toggle.

Three Sections: Current Session, Pinned + All Sessions

• Current Session — The session you're currently viewing (auto-detected), shown at the very top with live status and pin toggle.
• Pinned — Your starred sessions, always visible below the current session.
• All Sessions — All unpinned sessions, collapsed by default (click ▶ to expand). Sessions are grouped by date: Today, Yesterday, This Week, This Month, and Older.

Sections are hidden when they have no sessions to show. The current session is excluded from Pinned and All Sessions to avoid duplication.

Status Symbols

• Working sessions display an animated spinner (◐◓◑◒) that rotates every 200ms.
• All other states show a static symbol with distinct colors for quick visual scanning.

Live Updates

The panel stays up to date via two mechanisms:

1. Event bus — Listens for session.status, session.created, session.updated, and session.deleted events from OpenCode.
2. Polling fallback — Refreshes every 10 seconds to catch any missed events.

Collapsible

Click the ▼ Sessions header to collapse the entire panel. Click again (▶ Sessions) to expand. The All Sessions section has its own toggle (▶/▼) and starts collapsed to keep the panel compact.

Pin / Unpin

Click the star icon next to any session to pin it (☆ → ★). Pinned sessions survive restarts — they are persisted in OpenCode's key-value store under the sidebar-sessions-pinned key. If the KV write fails, the pin change is reverted and an error is logged.

One-Click Navigation

Click any session title to jump directly to that session. Navigation failures are caught and logged to OpenCode's app log.

Status Symbol Reference

Status	Symbol	Color	Meaning
Working	◐◓◑◒ (animated)	Green	Session is actively processing
Idle	●	Yellow	Session is waiting, no active work
Awaiting Input	◇	Blue	Session is paused, waiting for user input
Complete	✓	Gray	Session finished successfully
Error	✗	Red	Session encountered an error
Stopped	■	Gray	Session was stopped by the user or system

Usage Tips

• Collapse / expand panel: Click the ▼ Sessions or ▶ Sessions header to toggle the entire panel.
• Collapse / expand All Sessions: Click the ▶ or ▼ next to "All Sessions" to toggle date-grouped session list.
• Pin a session: Click the empty star (☆) next to a session title. The star fills in (★) to confirm.
• Unpin a session: Click the filled star (★) again to remove the pin.
• Pins are persistent: Pins are stored in OpenCode's key-value store and survive restarts. If a KV write fails, the pin reverts to its previous state automatically.
• Truncation: Session titles longer than 25 characters are truncated with an ellipsis (…) for a clean list.
• Subagent filtering: Sessions with a parent ID are excluded — only top-level user sessions are shown.

Development

# Install dependencies
bun install

# Type-check the project
bun run typecheck

# Build for publishing
bun run build

Project Structure

opencode-side-panel-sessions/
├── .github/
│   └── workflows/
│       ├── ci.yml                        # CI: typecheck + build on push/PR
│       └── publish.yml                   # CD: auto-publish to npm on version tags
├── src/
│   ├── tui.tsx                           # Plugin entrypoint — registers the sidebar slot
│   ├── types.ts                          # Shared types: SessionInfo, SessionStatus, SessionsStore
│   └── components/
│       ├── SessionPanel.tsx              # Main panel: Current Session, Pinned, date-grouped All Sessions
│       ├── SessionItem.tsx               # Individual session row with title, status, pin toggle
│       └── StatusBadge.tsx               # Animated/static status symbol renderer
├── scripts/
│   ├── build.ts                          # Build script (Bun.build() + tsc declarations)
│   └── register-tui.mjs                  # Postinstall: auto-registers in tui.json
├── dist/                                 # Compiled output (generated by build)
├── package.json
├── tsconfig.json
├── tsconfig.build.json
├── CHANGELOG.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── SECURITY.md
├── LICENSE
├── .gitignore
└── README.md

Publishing

Automated Release (recommended)

The repository includes a GitHub Actions workflow that automatically publishes to npm when a version tag is pushed.

1. Bump the version:

   npm version patch   # bug fixes
   npm version minor   # new features, backwards compatible
   npm version major   # breaking changes

   This creates a commit and a v* tag (e.g., v0.1.1).

2. Push the tag:

   git push --follow-tags

   The publish workflow will run typecheck, build, and publish to npm automatically.

Manual Release (if needed)

bun run build
npm publish
git push --tags

Prerequisite

The publish workflow requires an NPM_TOKEN secret in your GitHub repository settings. Create an npm automation token with publish access to the opencode-side-panel-sessions package and add it to repository secrets.

Contributing

Please see CONTRIBUTING.md for full details on how to contribute, including development setup, code style, and pull request process.

Philosophy

This project adheres to the 5 Laws of Elegant Defense (code-philosophy):

• Early Exit — Guard clauses at top of functions (e.g., SessionItem returns null for missing session, loadPinnedIds returns [] on failure).
• Parse Don't Validate — Data is parsed at boundaries (mapSessionStatus normalizes SDK types; loadPinnedIds coerces KV storage).
• Atomic Predictability — Pure functions where possible (toSessionInfo, truncateTitle, getStatusDisplay); side effects isolated in handlers.
• Fail Fast — Descriptive error messages propagated to the UI; attempt-pin failures revert and log.
• Intentional Naming — Function and variable names read like English (togglePin, fetchSessions, displayTitle, pinnedSessions).

Links

• GitHub: https://github.com/j-marcon/opencode-side-panel-sessions
• npm: https://www.npmjs.com/package/opencode-side-panel-sessions
• OpenCode Plugins: https://opencode.ai/docs/plugins

License

MIT — see LICENSE for details.