https://github.com/maou-shonen/opencode-zellij
OpenCode plugin for Zellij-backed panes and workflow integrations
https://github.com/maou-shonen/opencode-zellij
opencode opencode-plugin
Last synced: 15 days ago
JSON representation
OpenCode plugin for Zellij-backed panes and workflow integrations
- Host: GitHub
- URL: https://github.com/maou-shonen/opencode-zellij
- Owner: maou-shonen
- License: mit
- Created: 2026-05-07T15:51:57.000Z (22 days ago)
- Default Branch: main
- Last Pushed: 2026-05-13T12:12:53.000Z (17 days ago)
- Last Synced: 2026-05-13T14:39:22.631Z (16 days ago)
- Topics: opencode, opencode-plugin
- Language: TypeScript
- Homepage:
- Size: 203 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# opencode-zellij
[](https://www.npmjs.com/package/opencode-zellij)
[](https://github.com/maou-shonen/opencode-zellij/actions/workflows/ci.yml)
[ζ£ι«δΈζ](README.zh.md)
Give OpenCode a way to use visible Zellij panes for work that should not disappear into a one-shot tool call.
Use OpenCode's built-in `bash` for normal commands. Use this plugin when the process should stay alive, remain visible, or need later input.
## Installation
Add the npm package name to your OpenCode config:
```json
{
"$schema": "https://opencode.ai/config.json",
"plugin": [
"opencode-zellij"
]
}
```
OpenCode installs npm plugins automatically at startup. Zellij must also be installed and available on your `PATH`.
## Good fits
- dev servers and watchers
- REPLs and interactive CLIs
- SSH or remote sessions
- commands that ask follow-up questions
- privileged commands that need human review
## Ask OpenCode like this
```text
Start the dev server in a visible Zellij pane and wait until it is ready.
```
```text
Check the server pane for errors.
```
```text
Send Enter to the interactive pane and show me the latest output.
```
```text
Open a human-reviewed pane for the sudo install step.
```
```text
Close the dev server pane.
```
## Tools
| Tool | Use |
| --- | --- |
| `zellij_pty_spawn` | Start a visible Zellij pane. |
| `zellij_pty_read` | Read recent pane output. |
| `zellij_pty_write` | Send input to an interactive pane. |
| `zellij_pty_list` | Show panes known to the plugin. |
| `zellij_pty_kill` | Close a pane created by the plugin. |
| `zellij_pty_request_sudo` | Ask the user to review and run privileged commands in Zellij. |
## Human-only work
`zellij_pty_request_sudo` opens a review pane, shows what will run, and waits for the user to type `YES`. The agent cannot type into that pane, so passwords and credentials stay in Zellij instead of entering prompts or tool arguments.
## Configuration
Optional sidecar config files are loaded from `~/.config/opencode/opencode-zellij.config.jsonc` and from `.opencode/opencode-zellij.config.jsonc` in the current project. Project config overrides user config.
```jsonc
{
"$schema": "https://raw.githubusercontent.com/maou-shonen/opencode-zellij/main/opencode-zellij.schema.json",
"autoUpdate": true,
"pty": {
"enabled": true,
"sudoPane": "allow" // allow, deny, or hide
},
"tabTitle": { "enabled": true }
}
```
Set `autoUpdate`, `pty.enabled`, or `tabTitle.enabled` to `false` to turn those features off.
## Dynamic tab title
When OpenCode runs inside Zellij, the plugin updates the current tab title to show the project, branch, and current OpenCode state:
```text
π’ opencode-zellij π± main # ready
β‘ opencode-zellij π± main # agent running
π¬ opencode-zellij π± main # waiting for user input
```
The title is updated best-effort from OpenCode session, question, permission, and branch events.
## Pane cleanup watchdog
When the plugin creates a pane, it also starts a small detached Node.js watchdog process for that OpenCode plugin instance. The watchdog keeps a per-instance registry under `$XDG_RUNTIME_DIR/opencode-zellij-*` (or the system temp directory), watches the owning OpenCode process, and closes plugin-created panes if OpenCode exits before normal plugin cleanup can run, such as when leaving with Ctrl-D.
The watchdog exits automatically after the owner process exits and cleanup is complete. Registries are isolated per OpenCode process and plugin instance.
## Notes
- This is not a sandbox.
- Session records are in-memory only; restarting OpenCode loses them.
- Output is rendered Zellij output, not raw PTY bytes.
- Exit code capture is best-effort for commands started by the plugin.
- When dynamic tab title is enabled, it may overwrite manual Zellij tab renames on the next OpenCode state change.