zellij-opencode

Managed OpenCode sessions for Zellij.

This project creates a single managed OpenCode session per Zellij pane and keeps a floating switcher plus tab-name status in sync.

Features

• managed launch flow with explicit OpenCode server ports
• tab names like myproject (3/5)*
• floating session switcher for all tracked sessions
• approval and attention states surfaced as !
• automatic tab-name restore when a managed session stops

Current model

• one managed OpenCode pane = one managed OpenCode session
• the broker polls the local OpenCode server for session, todo, and permission state
• the Zellij plugin handles UI and tab renaming

Install

Build from source:

npm install
npm run build:all

Or install with curl:

curl -fsSL https://raw.githubusercontent.com/navio/zellij-opencode/main/scripts/install.sh | bash

The installer builds the CLI and plugin under ~/.local/share/zellij-opencode/current and creates a ~/.local/bin/zellij-opencode wrapper.

Build

npm install
npm run build:all

This produces:

• CLI: dist/index.js
• plugin: assets/zellij-opencode.wasm

Load the plugin

From inside a Zellij session:

zellij action start-or-reload-plugin "file:$(pwd)/assets/zellij-opencode.wasm"

You only need to do this once per Zellij session.

Suggested keybind

Add this to ~/.config/zellij/config.kdl and adjust the absolute path:

keybinds {
    shared_except "locked" {
        bind "Ctrl Shift o" {
            LaunchOrFocusPlugin "file:/ABSOLUTE/PATH/TO/zellij-opencode/assets/zellij-opencode.wasm" {
                floating true
                move_to_focused_tab true
            }
        }
    }
}

Launch a managed session

From inside Zellij:

node dist/index.js launch --cwd /path/to/project --name myproject

Optional flags:

• --continue
• --session-id <id>
• --model <provider/model>
• --agent <name>

This will:

1. start the local broker if needed
2. create a new Zellij tab in the target directory
3. start OpenCode with an explicit local server port
4. register the pane with the broker
5. begin tab/status updates

Switcher controls

• j / k navigate
• Enter jump to session
• 1-9 quick jump
• c clear selected stopped/attention entry from the switcher
• D clear all stopped/attention entries from the switcher
• Esc close

Notes

• The plugin must be loaded for tab renames and the switcher UI to work.
• The broker only tracks sessions launched through zellij-opencode launch.
• Per-tab color is not implemented; state is shown in tab labels and the switcher.

Test

npm test