openzellij

OpenCode plugin for Zellij integration - automatically manages background agent panes in Zellij terminal sessions.

Features

• Auto-spawning panes: Background OpenCode agents automatically open in Zellij floating panes
• Auto-close on completion: Panes automatically close when agents finish (configurable)
• Agent visibility: Track all active agent panes with logging
• Configurable behavior: Fine-tune polling intervals, grace periods, and pane layout
• Cross-platform: Works on Linux, macOS, Windows via npm

Installation

For LLMs

Paste this into opencode:

follow the steps written in this markdown file and execute them in order : https://raw.githubusercontent.com/cernoh/openzellij/refs/heads/main/docs/LLM_SETUP_SCRIPT.md

npm (Recommended)

# Global installation (recommended)
npm install -g openzellij

# Project-local
npm install openzellij

Adding to OpenCode Config

After installing via npm, add openzellij to your OpenCode configuration:

Global configuration (~/.config/opencode/opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["openzellij"]
}

Project configuration (opencode.json in your project root):

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["openzellij"]
}

OpenCode will automatically install and load the plugin at startup. The plugin will activate when you launch background agents in a Zellij session.

Quick Start

1. Install the plugin (see Installation above)
2. Ensure Zellij is installed and in your PATH
3. Start a Zellij session: zellij
4. Launch OpenCode with background agents
5. Agent panes will automatically appear in Zellij
6. Panes auto-close when agents complete (default behavior)

Configuration

Create ~/.config/opencode/openzellij.json:

{
  "autoClosePanes": true,
  "panePollIntervalMs": 2000,
  "paneMissingGraceMs": 6000,
  "paneLayout": "tiled",
  "enableLogging": true
}

See docs/CONFIG.md for full configuration reference.

Documentation

• Installation Guide - Detailed installation steps
• Configuration Reference - All config options

Requirements

• Zellij >= 0.30.0
• OpenCode >= 1.0.0
• Node.js >= 18 or Bun >= 1.0

License

MIT