Check the pulse of your OpenCode sessions. A terminal UI that shows which sessions need your input, sorted by urgency — permission requests, questions, errors, retries — so you can jump straight to what matters.

Select a session and pulse attaches you to its tmux pane, then exits.

Requires Bun

Add opencode-pulse to your OpenCode config (~/.config/opencode/opencode.json or ~/.config/opencode/opencode.jsonc):

{
  "plugin": ["opencode-pulse@latest"]
}

Restart OpenCode. The plugin installs automatically and begins tracking sessions.

bunx --bun opencode-pulse

Or install globally for a persistent pulse command:

bun add -g opencode-pulse
pulse

npx opencode-pulse

Bun must be installed — pulse uses bun:sqlite for database access.

pulse [options]

Options:
  -c, --columns <cols>  Comma-separated columns
  -t, --theme <name>    Theme name
      --db-path <path>  Path to SQLite database
  -h, --help            Show help

Navigation wraps — pressing up on the first item selects the last.

Add this to your ~/.tmux.conf to pop up pulse with prefix + P:

bind-key P display-popup -E -w 90% -h 50% 'bunx --bun opencode-pulse'

Select a session and pulse switches you there, closing the popup automatically.

Sessions are sorted by what needs attention most:

Every option can be set three ways: config file, CLI flag, or environment variable. All three use the same set of options. When the same option is set in multiple places, the most specific source wins:

CLI flag > environment variable > config file > default

Create ~/.config/opencode/pulse.jsonc (JSON with comments):

{
  // See available columns below
  "columns": "status,project,title,todo,updated",
  "theme": "catppuccin",
  "debug": true
}

Columns can also be an array:

{
  "columns": ["status", "project", "title", "todo", "updated"]
}

All keys are optional — only set what you want to override. Plain pulse.json is also supported.

pulse                                           # default columns
pulse --columns status,project,title,updated    # compact view
pulse -c status,project,todo,message            # show error/retry messages
pulse -c status,project,pid,version,tmux        # debugging view

Pulse auto-detects your OpenCode theme and matches its colors. To override, set theme in your config file or use any of the three methods:

pulse --theme catppuccin

Available themes: aura, ayu, carbonfox, catppuccin, catppuccin-frappe, catppuccin-macchiato, cobalt2, cursor, dracula, everforest, flexoki, github, gruvbox, kanagawa, lucent-orng, material, matrix, mercury, monokai, nightowl, nord, one-dark, opencode (default), orng, osaka-jade, palenight, rosepine, solarized, synthwave84, tokyonight, vercel, vesper, zenburn

DB location: ~/.local/share/opencode-pulse/status.db (override with dbPath in config, --db-path flag, or PULSE_DB_PATH env var)

Plugin not loading? Check ~/.local/share/opencode/log/ for errors.

No sessions? Ensure plugin is in your opencode.json and OpenCode was restarted.

Stale sessions showing? Pulse automatically cleans up sessions whose OpenCode process has exited. Dead processes are removed on startup and every 60 seconds.

Debug log: Enable debug in your config to have the plugin log all received events to ~/.local/share/opencode-pulse/debug.log. Useful for verifying the plugin is receiving events from OpenCode.

Two components connected by SQLite:

• Plugin (plugin/) — OpenCode plugin that listens for session events (status changes, permissions, questions, errors, todos) and writes to SQLite
• TUI (tui-ts/) — Reads SQLite, displays sessions sorted by attention priority

The plugin tracks each OpenCode process by PID with a 10-second heartbeat. The TUI polls for changes every 500ms, using SQLite's PRAGMA data_version to skip unnecessary re-renders.

Tmux integration detects whether you're inside a tmux session. If so, pulse uses switch-client to jump to the target pane. Outside tmux, it uses attach-session. A warning is shown if tmux is not detected.

git clone https://github.com/fetep/opencode-pulse
cd opencode-pulse
bun install
bun run build

# Register the local plugin in ~/.config/opencode/opencode.json:
#   { "plugin": ["/path/to/opencode-pulse"] }
# Restart OpenCode.

# Run the TUI
./tui-ts/src/cli.tsx

# Or link globally
bun link
pulse

Enable debug logging during development to see every event the plugin receives from OpenCode:

// ~/.config/opencode/pulse.json
{
  "debug": true
}

Events are written to ~/.local/share/opencode-pulse/debug.log with timestamps and PIDs. Rebuild the plugin after any change to plugin/src/:

bun run build