openzellij 1.0.0

package/README.md

@@ -0,0 +1,96 @@
+# 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)
+
+```bash
+# 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`):
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["openzellij"]
+}
+```
+
+**Project configuration** (`opencode.json` in your project root):
+```json
+{
+  "$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`:
+
+```json
+{
+  "autoClosePanes": true,
+  "panePollIntervalMs": 2000,
+  "paneMissingGraceMs": 6000,
+  "paneLayout": "tiled",
+  "enableLogging": true
+}
+```
+
+See [docs/CONFIG.md](docs/CONFIG.md) for full configuration reference.
+
+## Documentation
+
+- [Installation Guide](docs/INSTALL.md) - Detailed installation steps
+- [Configuration Reference](docs/CONFIG.md) - All config options
+
+## Requirements
+
+- Zellij >= 0.30.0
+- OpenCode >= 1.0.0
+- Node.js >= 18 or Bun >= 1.0
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,99 @@
+export type SessionLifecycleEvent =
+  | 'session.created'
+  | 'session.updated'
+  | 'session.idle'
+  | 'session.deleted'
+  | 'session.logs'
+  | 'session.progress'
+
+export interface PluginContext {
+  client: OpencodeClient
+  directory: string
+  serverUrl?: string
+}
+
+export interface OpencodeClient {
+  session: {
+    status(options?: { includeLogs?: boolean }): Promise<SessionStatusResponse>
+    subscribe(listener: SessionSubscriptionHandler): () => void
+  }
+  logger?: {
+    info(message: string, meta?: Record<string, unknown>): void
+    warn(message: string, meta?: Record<string, unknown>): void
+    error(message: string | Error, meta?: Record<string, unknown>): void
+    debug?(message: string, meta?: Record<string, unknown>): void
+  }
+}
+
+export interface SessionStatusResponse {
+  sessions: SessionDescriptor[]
+}
+
+export type SessionSubscriptionHandler = (event: PluginEventInput) => void | Promise<void>
+
+export interface SessionDescriptor {
+  id: string
+  title?: string
+  parentId?: string | null
+  status: SessionState
+  metadata?: Record<string, unknown>
+}
+
+export type SessionState = 'running' | 'idle' | 'completed' | 'failed' | 'unknown'
+
+export interface PluginEventInput {
+  type: SessionLifecycleEvent
+  session: SessionDescriptor
+}
+
+export interface PluginInstance {
+  name: string
+  event: (input: PluginEventInput) => Promise<void>
+  dispose?: () => Promise<void>
+}
+
+export interface TrackedPane {
+  sessionId: string
+  paneId: string
+  processId?: number
+  createdAt: number
+  lastUpdatedAt: number
+  title?: string
+  exitStatus?: number | null
+  missingSince?: number
+}
+
+export interface PaneRegistry {
+  sessions: Map<string, TrackedPane>
+  add(pane: TrackedPane): void
+  remove(sessionId: string): void
+  get(sessionId: string): TrackedPane | undefined
+  getAll(): TrackedPane[]
+  updateLastSeen(sessionId: string): void
+}
+
+export interface PluginConfig {
+  enableLogging: boolean
+  spawnDelayMs: number
+  maxConcurrentSpawns: number
+  paneLayout: 'tiled' | 'vertical' | 'horizontal'
+  zellijBinary: string
+  listIntervalMs: number
+  autoClosePanes: boolean
+  panePollIntervalMs: number
+  paneMissingGraceMs: number
+}
+
+export interface PluginInput {
+  context: PluginContext
+}
+
+export interface PluginOutput {
+  name: string
+  event: SessionEvent
+}
+
+export type SessionEvent = 
+  | { type: 'custom'; payload: Record<string, unknown> }
+  | { type: 'pane.spawned'; sessionId: string; paneId: string }
+  | { type: 'pane.closed'; sessionId: string; paneId: string }