{"_id":"@auron-labs/opencode-zellij","_rev":"2-d4d79f3c0b0f9f0e370efa8d925a911a","name":"@auron-labs/opencode-zellij","dist-tags":{"latest":"0.3.0"},"versions":{"0.2.0":{"name":"@auron-labs/opencode-zellij","version":"0.2.0","keywords":["opencode","zellij","plugin","terminal","multiplexer"],"license":"MIT","_id":"@auron-labs/opencode-zellij@0.2.0","maintainers":[{"name":"aflorey","email":"aaron@buckhamduffy.com"}],"homepage":"https://github.com/auron-labs/opencode-plugins/tree/main/packages/opencode-zellij","bugs":{"url":"https://github.com/auron-labs/opencode-plugins/issues"},"dist":{"shasum":"a3d66a17d11b78cfede45992b898a073f79218bf","tarball":"https://registry.npmjs.org/@auron-labs/opencode-zellij/-/opencode-zellij-0.2.0.tgz","fileCount":8,"integrity":"sha512-T9i9S5h60h8BbWAYqY/v7386HEwVBhMULtnfLt8Wx9oocaxYodMYtiBLhEDKuZgeD5MZE478V8sYBMHo/Yw0Kg==","signatures":[{"sig":"MEYCIQDxr2yxHAZAS9iGeeYVVOa5epaGzQcyyVa2IOaiEViYswIhALH0euOKUWAdlAvWdqvwaXjCANthLQgXTlwRwQVHa9s+","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":56075},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"gitHead":"4157a4a6b508679f2448cc3b70fa92f5a82b4cee","scripts":{"test":"bun run build && node --test test/*.test.mjs","build":"tsc -p tsconfig.json","prepublishOnly":"bun run build"},"_npmUser":{"name":"aflorey","email":"aaron@buckhamduffy.com"},"repository":{"url":"git+https://github.com/auron-labs/opencode-plugins.git","type":"git","directory":"packages/opencode-zellij"},"_npmVersion":"11.18.0","description":"OpenCode plugin for managing Zellij panes with event subscriptions, output reading, and lifecycle tracking.","directories":{},"sideEffects":false,"_nodeVersion":"24.16.0","dependencies":{"@opencode-ai/plugin":"^1.17.9"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"bun@1.2.23","devDependencies":{"typescript":"^5.8.3","@types/node":"^22.15.30"},"_npmOperationalInternal":{"tmp":"tmp/opencode-zellij_0.2.0_1782895996246_0.2984620554846975","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@auron-labs/opencode-zellij","version":"0.3.0","description":"OpenCode plugin for managing Zellij panes with event subscriptions, output reading, and lifecycle tracking.","license":"MIT","type":"module","sideEffects":false,"main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"scripts":{"build":"tsc -p tsconfig.json","test":"bun run build && node --test test/*.test.mjs","prepublishOnly":"bun run build"},"packageManager":"bun@1.2.23","publishConfig":{"access":"public"},"dependencies":{"@opencode-ai/plugin":"^1.17.9"},"devDependencies":{"@types/node":"^22.15.30","typescript":"^5.8.3"},"keywords":["opencode","zellij","plugin","terminal","multiplexer"],"repository":{"type":"git","url":"git+https://github.com/auron-labs/opencode-plugins.git","directory":"packages/opencode-zellij"},"bugs":{"url":"https://github.com/auron-labs/opencode-plugins/issues"},"homepage":"https://github.com/auron-labs/opencode-plugins/tree/main/packages/opencode-zellij","_id":"@auron-labs/opencode-zellij@0.3.0","gitHead":"538d706321e071d10773da4c66ac923ad6249ade","_nodeVersion":"22.23.1","_npmVersion":"10.9.8","dist":{"integrity":"sha512-CydbgOGJSU/BgRxliYrUfF07HpcnVKmpzUdJCkUBw4oUzK42XkfBT6Zai2plWWMBiz49eKSlLl1mX2NHwTTK8g==","shasum":"6b415946e54d364c4ad37605eb0334092b76487e","tarball":"https://registry.npmjs.org/@auron-labs/opencode-zellij/-/opencode-zellij-0.3.0.tgz","fileCount":8,"unpackedSize":61269,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFqCTNvnlXraUyq4T1JMhw5t/TPJ8tOwAfQ/t1FHTmX2AiEA+2t1apz0bLG74bcD23S2bvoNUnCxcVLT5KbqRPQS51U="}]},"_npmUser":{"name":"aflorey","email":"aaron@buckhamduffy.com"},"directories":{},"maintainers":[{"name":"aflorey","email":"aaron@buckhamduffy.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/opencode-zellij_0.3.0_1783387217261_0.09056422129529529"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-01T08:53:16.151Z","modified":"2026-07-07T01:20:17.569Z","0.2.0":"2026-07-01T08:53:16.349Z","0.3.0":"2026-07-07T01:20:17.410Z"},"bugs":{"url":"https://github.com/auron-labs/opencode-plugins/issues"},"license":"MIT","homepage":"https://github.com/auron-labs/opencode-plugins/tree/main/packages/opencode-zellij","keywords":["opencode","zellij","plugin","terminal","multiplexer"],"repository":{"type":"git","url":"git+https://github.com/auron-labs/opencode-plugins.git","directory":"packages/opencode-zellij"},"description":"OpenCode plugin for managing Zellij panes with event subscriptions, output reading, and lifecycle tracking.","maintainers":[{"name":"aflorey","email":"aaron@buckhamduffy.com"}],"readme":"# @auron-labs/opencode-zellij\n\nOpenCode plugin for managing Zellij terminal panes. Spawn, read, watch, and control Zellij panes from agent tools with event subscriptions and automatic cleanup.\n\n## Install\n\n```bash\nopencode plugin @auron-labs/opencode-zellij [--global]\n```\n\n## Requirements\n\n- OpenCode installed and loading plugins from your config.\n- Zellij installed and on `PATH` (or set the `binary` option).\n- A running Zellij session (auto-started via a detached session if none exists; `$ZELLIJ_SESSION_NAME` detected automatically, or set `session` in options).\n\n## Usage\n\nAdd to your OpenCode config:\n\n```json\n{\n  \"plugin\": [\n    [\"@auron-labs/opencode-zellij\", {}]\n  ]\n}\n```\n\nWith options:\n\n```json\n{\n  \"plugin\": [\n    [\"@auron-labs/opencode-zellij\", {\n      \"session\": \"my-session\",\n      \"binary\": \"/usr/local/bin/zellij\",\n      \"maxEvents\": 500,\n      \"pollMs\": 2000,\n      \"closeOnExitCleanup\": true,\n      \"stateFile\": \"~/.config/opencode/zellij.json\"\n    }]\n  ]\n}\n```\n\n## Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `session` | string | `$ZELLIJ_SESSION_NAME`, or auto-generated | Zellij session name to target. If no session exists, one is auto-started in detached mode and torn down when OpenCode exits. |\n| `binary` | string | `zellij` | Path to the zellij binary |\n| `maxEvents` | number | `200` | Max events kept in the ring buffer per pane |\n| `pollMs` | number | `3000` | Polling interval (ms) for exit status detection |\n| `closeOnExitCleanup` | boolean | `true` | Close tracked panes when OpenCode exits |\n| `stateFile` | string | `$OPENCODE_CONFIG_DIR/zellij.json`, then `~/.config/opencode/zellij.json` | Path to the persisted state file. `~/` is expanded. |\n\n## Tools\n\n### `zellij_spawn`\n\nSpawn a new Zellij pane, track it, and start a JSON event watcher.\n\n| Arg | Type | Required | Description |\n|-----|------|----------|-------------|\n| `command` | string[] | yes | Command to run |\n| `name` | string | no | Pane name (also used as the ref) |\n| `cwd` | string | no | Working directory |\n| `floating` | boolean | no | Open in floating mode |\n| `direction` | string | no | Direction for tiled panes: `right`, `left`, `up`, `down` |\n| `subscriptions` | array | no | Additional subscriptions |\n\nReturns: `{ ref, paneId, command, subscriptions, exited }`\n\nDefault subscriptions: exit `nonzero`, `closed`.\n\n### `zellij_read`\n\nRead pane output as text.\n\n| Arg | Type | Required | Description |\n|-----|------|----------|-------------|\n| `ref` | string | no | Tracked pane ref |\n| `paneId` | string | no | Zellij pane ID (one of ref/paneId required) |\n| `full` | boolean | no | Include full scrollback |\n| `ansi` | boolean | no | Preserve ANSI escape codes |\n\n### `zellij_events`\n\nReturn buffered events for a tracked pane.\n\n| Arg | Type | Required | Description |\n|-----|------|----------|-------------|\n| `ref` | string | no | Tracked pane ref |\n| `paneId` | string | no | Zellij pane ID |\n| `clear` | boolean | no | Clear buffer after reading |\n| `limit` | number | no | Max events to return |\n\n### `zellij_subscribe`\n\nAdd subscriptions to a tracked pane.\n\n| Arg | Type | Required | Description |\n|-----|------|----------|-------------|\n| `ref` | string | no | Tracked pane ref |\n| `paneId` | string | no | Zellij pane ID |\n| `text` | string | no | Regex pattern to match in output |\n| `exit` | boolean/string/number | no | Subscribe to exit. `true` means `nonzero`; also accepts `any`, `zero`, `nonzero`, or an exact exit code like `1`. |\n| `closed` | boolean | no | Subscribe to pane closed |\n\n### `zellij_wait`\n\nWait for a matching event or timeout.\n\n| Arg | Type | Required | Description |\n|-----|------|----------|-------------|\n| `ref` | string | no | Tracked pane ref |\n| `paneId` | string | no | Zellij pane ID |\n| `timeoutMs` | number | no | Timeout in ms (default 30000) |\n| `text` | string | no | Wait for text matching this regex |\n| `exit` | boolean/string/number | no | Wait for exit. `true` means `nonzero`; also accepts `any`, `zero`, `nonzero`, or an exact exit code like `1`. |\n| `closed` | boolean | no | Wait for pane to close |\n\n### `zellij_stop`\n\nStop the watcher and close a tracked pane.\n\n| Arg | Type | Required | Description |\n|-----|------|----------|-------------|\n| `ref` | string | no | Tracked pane ref |\n| `paneId` | string | no | Zellij pane ID |\n\n### `zellij_restart`\n\nStop and recreate a pane with the same command and options.\n\n| Arg | Type | Required | Description |\n|-----|------|----------|-------------|\n| `ref` | string | yes | Tracked pane ref |\n\n### `zellij_list`\n\nList the target session, Zellij connectivity, live pane count, and tracked pane status. Takes no arguments.\n\nReturns: `{ session, connected, livePanes, error, tracked }`\n\n## Event model\n\nEvents are buffered in a bounded ring buffer per pane (default 200 events). Event types:\n\n| Type | Source | Description |\n|------|--------|-------------|\n| `pane_update` | subscribe | Viewport content changed |\n| `text_match` | subscription | A line matched a text regex |\n| `pane_closed` | subscribe | Pane was closed in Zellij |\n| `pane_exited` | poll | Pane command exited (includes exit code) |\n| `exit_match` | subscription | Pane exit matched a subscribed exit condition |\n| `error` | internal | Watcher or command error |\n\n## Behavior\n\n- **Live output**: uses `zellij subscribe --pane-id <id> --format json` to stream NDJSON events.\n- **Exit detection**: polls `zellij action list-panes --json` at `pollMs` intervals because subscribe does not report exit codes.\n- **Text matching**: rendered viewport updates from subscribe are checked against text regex subscriptions, with duplicate pattern/line matches suppressed while the event remains buffered.\n- **Cleanup**: tracked panes are closed and watcher processes killed on SIGINT, SIGTERM, beforeExit, and exit. Only panes created/tracked by this plugin are closed.\n- **State restore**: on startup, persisted state is loaded and cross-checked against the live session. Still-live tracked panes are restored and watched again; panes that no longer exist are removed from tracking.\n\n## State file\n\nA small JSON file persists tracked pane refs and metadata across restarts. Default location:\n\n1. `stateFile` plugin option, if provided\n2. `$OPENCODE_CONFIG_DIR/zellij.json`\n3. `$HOME/.config/opencode/zellij.json`\n\nThe state file is written on pane changes and loaded on plugin init. It lets refs survive an OpenCode restart and lets the plugin remove stale tracking entries without touching panes it did not create.\n\n## Limitations\n\n- Requires a Zellij session; the plugin will start one in detached mode if none is running.\n- Exit code detection is poll-based, not instant.\n- The `zellij subscribe` stream may have brief gaps during rapid output bursts.\n- Pane IDs are session-scoped; reusing a ref across sessions requires manual coordination.\n- The plugin does not manage Zellij layouts, tabs, or floating window positions.\n","readmeFilename":"README.md"}