Add IPC protocol layer for clean separation of core and integration concerns

AGENTS.md

@@ -1,23 +1,59 @@
 ---
 created: 2025-12-07T13:45:00-0800
-updated: 2025-12-08T00:50:00-0800
+updated: 2026-01-09T23:50:00-0800
 slug: zellij-pane-tracker
-keywords: zellij, pane, tracker, plugin, terminal, mcp, ai-assistant
+keywords: zellij, pane, tracker, plugin, terminal, mcp, ai-assistant, ipc, canvas
 ---
 # Zellij Pane Tracker Plugin
 
-A Zellij plugin + MCP server that gives AI assistants visibility into all terminal panes.
+A Zellij plugin + **IPC protocol** + Canvas API that gives AI assistants visibility into all terminal panes.
 
 ## Quick Context
 
-**What it does:** Exports pane metadata to JSON + MCP server for AI assistants to read/interact with panes
+**What it does:** Exports pane metadata to JSON + IPC server + Canvas API for AI assistants to interact with panes
 
-**Why:** Lets AI coding assistants (OpenCode, etc.) "see" and interact with other terminal panes
+**Why:** Lets AI coding assistants (OpenCode, etc.) "see" and interact with other terminal panes with **clean separation of concerns**
 
-**Status:** ✅ **FULLY WORKING** - Plugin, companion script, and MCP server all operational
+**Status:** ✅ **FULLY WORKING** - Plugin, Canvas API, IPC protocol, and reference MCP server all operational
+
+**New in v1.0:** IPC protocol inspired by [claude-canvas](https://github.com/dvdsgl/claude-canvas) for clean separation between core functionality and AI integrations
 
 ## Architecture
 
+### New: IPC Protocol Architecture (v1.0+)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Zellij Session                          │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────────┐ │
+│  │terminal_1│  │terminal_2│  │terminal_3│  │pane-tracker │ │
+│  │(opencode)│  │IPC Server│  │(Pane #2) │  │  (plugin)   │ │
+│  └────┬─────┘  └─────┬────┘  └──────────┘  └──────┬──────┘ │
+└───────┼──────────────┼───────────────────────────┼────────┘
+        │              │                           │
+        │ MCP          │ IPC (Unix socket)         │ writes
+        │              │                           ▼
+        │              │              /tmp/zj-pane-names.json
+        │              │
+        │              ▼
+        │     ┌────────────────────┐
+        │     │  IPC Server        │
+        │     │  - Canvas API      │
+        │     │  - Pane operations │
+        │     └────────────────────┘
+        │              ▲
+        │              │ IPC client library
+        ▼              │
+┌──────────────────────┴────┐
+│  OpenCode Integration     │
+│  (separate repo)           │
+│  - MCP server using IPC   │
+│  - OpenCode-specific code │
+└────────────────────────────┘
+```
+
+### Legacy: Direct MCP Architecture (reference)
+
 ```
 ┌─────────────────────────────────────────────────────────────┐
 │                     Zellij Session                          │
@@ -43,7 +79,17 @@ A Zellij plugin + MCP server that gives AI assistants visibility into all termin
 | File | Purpose |
 |------|---------|
 | `src/main.rs` | Plugin source (Rust, compiles to WASM) |
-| `mcp-server/index.ts` | MCP server (TypeScript/Bun) - needs fixes |
+| **IPC Layer** | |
+| `ipc/types.ts` | IPC message protocol definitions |
+| `ipc/server.ts` | IPC server implementation (Unix sockets) |
+| `ipc/client.ts` | IPC client implementation |
+| `ipc/ipc-server-standalone.ts` | Standalone IPC server binary |
+| `ipc/ipc-client-cli.ts` | Example CLI client for testing |
+| **Canvas API** | |
+| `api/canvas-api.ts` | High-level abstraction for Zellij operations |
+| **Legacy/Reference** | |
+| `mcp-server/index.ts` | Reference MCP server (direct implementation) |
+| **Other** | |
 | `~/.config/zellij/plugins/zellij-pane-tracker.wasm` | Installed plugin |
 | `/tmp/zj-pane-names.json` | Output file (pane metadata) |
 | `~/zjdump` | **Primary tool** - dump any pane content with full scrollback |
@@ -97,6 +143,41 @@ OpenCode runs: ~/zjdump 2
 
 **Updated by:** The Zellij plugin continuously on pane events
 
+## IPC Protocol (NEW in v1.0)
+
+The IPC protocol enables clean separation of concerns between core functionality and AI integrations.
+
+**Socket Location:** `/tmp/zellij-pane-{session}.sock`
+
+**Benefits:**
+- **Separation of concerns** - Core repo vs integration repos
+- **Language agnostic** - Any language can implement a client
+- **Multiple clients** - Multiple AI assistants can connect simultaneously
+- **Clean testing** - Test protocol independently
+
+**Starting the IPC Server:**
+```bash
+bun run ipc/ipc-server-standalone.ts
+```
+
+**Client Example:**
+```typescript
+import { connectWithRetry, getSocketPath } from "zellij-pane-tracker/ipc";
+
+const client = await connectWithRetry({
+  socketPath: getSocketPath(),
+  onMessage: (msg) => console.log(msg),
+  onDisconnect: () => console.log("Disconnected")
+});
+
+client.send({ type: "getPanes" });
+client.send({ type: "dumpPane", paneId: "terminal_2", options: { lines: 50 } });
+```
+
+**See:** 
+- [ipc/README.md](ipc/README.md) - Full IPC protocol documentation
+- [docs/OPENCODE_INTEGRATION.md](docs/OPENCODE_INTEGRATION.md) - Guide for creating separate integration repo
+
 ## MCP Server (WORKING)
 
 The MCP server provides AI assistants with full Zellij integration via OpenCode's native tools.

README.md

@@ -1,17 +1,21 @@
 # zellij-pane-tracker
 
-A Zellij plugin + MCP server that lets AI assistants see and interact with your terminal panes.
+A Zellij plugin + IPC protocol that lets AI assistants see and interact with your terminal panes.
 
 ## The Problem
 
 AI coding assistants (Claude, GPT, Cursor, etc.) running in a terminal pane are blind to other panes. They can't see your build output, test results, or what's running in your file manager.
 
 ## The Solution
 
-This project has two components:
+This project provides **core infrastructure** with clean separation of concerns:
 
-1. **Zellij Plugin** - Exports pane metadata to JSON (`/tmp/zj-pane-names.json`)
-2. **MCP Server** - Exposes pane operations to AI assistants via [Model Context Protocol](https://modelcontextprotocol.io/)
+1. **Zellij Plugin** (Rust/WASM) - Exports pane metadata to JSON (`/tmp/zj-pane-names.json`)
+2. **Canvas API** (TypeScript) - High-level abstraction for pane operations
+3. **IPC Protocol** (Unix sockets) - Language-agnostic communication layer
+4. **Reference MCP Server** - Example integration (see also: separate OpenCode integration)
+
+**Architecture inspired by:** [claude-canvas](https://github.com/dvdsgl/claude-canvas)
 
 Together, they let your AI assistant:
 - Know what panes exist and what they're named
@@ -20,6 +24,14 @@ Together, they let your AI assistant:
 - Create new panes
 - Rename sessions
 
+## New: IPC Protocol
+
+This repo now includes an **IPC (Inter-Process Communication) protocol** for clean separation between:
+- **Core functionality** (this repo) - Plugin, Canvas API, IPC server
+- **AI integrations** (separate repos) - OpenCode, Claude Desktop, etc.
+
+See [IPC Documentation](ipc/README.md) and [OpenCode Integration Guide](docs/OPENCODE_INTEGRATION.md)
+
 ## Quick Start
 
 ### 1. Build and Install the Plugin
@@ -109,6 +121,43 @@ zellij_dump_pane("4", lines=50)    # Last 50 lines
 
 ## How It Works
 
+### New Architecture (with IPC)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Zellij Session                          │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
+│  │ terminal_1  │  │ terminal_2  │  │ terminal_3  │         │
+│  │  opencode   │  │  IPC Server │  │    nvim     │         │
+│  └──────┬──────┘  └──────┬──────┘  └─────────────┘         │
+└─────────┼─────────────────┼────────────────────────────────┘
+          │                 │
+          │ MCP             │ IPC (Unix socket)
+          │                 │
+┌─────────▼────────┐  ┌─────▼──────────────────────────────┐
+│  OpenCode MCP    │  │  IPC Server                        │
+│  (separate repo) │◄─┤  - Canvas API                      │
+│                  │  │  - Reads /tmp/zj-pane-names.json   │
+│                  │  │  - Executes Zellij actions         │
+└──────────────────┘  └────────────────────────────────────┘
+                                  │
+                                  │ reads
+                                  ▼
+                      ┌──────────────────────────┐
+                      │  pane-tracker plugin     │
+                      │  (writes pane metadata)  │
+                      └──────────────────────────┘
+                                  │
+                                  │ writes
+                                  ▼
+                      ┌──────────────────────────┐
+                      │ /tmp/zj-pane-names.json  │
+                      │   { panes: {...} }       │
+                      └──────────────────────────┘
+```
+
+### Traditional Architecture (reference MCP server)
+
 ```
 ┌─────────────────────────────────────────────────────────────┐
 │                     Zellij Session                          │
@@ -135,8 +184,8 @@ zellij_dump_pane("4", lines=50)    # Last 50 lines
 
 1. **Plugin** subscribes to Zellij's `PaneUpdate` events
 2. On each update, writes pane metadata to `/tmp/zj-pane-names.json`
-3. **MCP Server** reads this JSON to answer `get_panes` requests
-4. **zjdump** script navigates to a pane, captures content, returns to origin
+3. **IPC Server** (or MCP Server) reads this JSON and executes Zellij actions
+4. **AI Integrations** connect via IPC protocol for clean separation
 
 ## Usage Without MCP
 
@@ -177,16 +226,99 @@ cat /tmp/zj-pane-names.json
 
 ```
 zellij-pane-tracker/
-├── src/main.rs          # Zellij plugin (Rust/WASM)
+├── src/main.rs              # Zellij plugin (Rust/WASM)
+├── ipc/
+│   ├── types.ts            # IPC message protocol definitions
+│   ├── server.ts           # IPC server implementation
+│   ├── client.ts           # IPC client implementation
+│   ├── ipc-server-standalone.ts  # Standalone IPC server binary
+│   ├── ipc-client-cli.ts   # Example CLI client for testing
+│   └── README.md           # IPC protocol documentation
+├── api/
+│   └── canvas-api.ts       # High-level Zellij operations API
 ├── mcp-server/
-│   ├── index.ts         # MCP server (TypeScript/Bun)
-│   └── package.json
+│   └── index.ts            # Reference MCP server (legacy)
 ├── scripts/
-│   └── zjdump           # Pane content dumper (zsh)
+│   └── zjdump              # Pane content dumper (zsh)
+├── docs/
+│   └── OPENCODE_INTEGRATION.md  # Guide for separate OpenCode repo
 ├── Cargo.toml
+├── package.json
 └── README.md
 ```
 
+## Using the IPC Protocol
+
+### Start IPC Server
+
+```bash
+# In a Zellij pane
+bun run ipc/ipc-server-standalone.ts
+```
+
+The server listens on `/tmp/zellij-pane-{session}.sock` and responds to client requests.
+
+### Connect a Client
+
+```typescript
+import { connectWithRetry, getSocketPath } from "zellij-pane-tracker/ipc";
+
+const client = await connectWithRetry({
+  socketPath: getSocketPath(),
+  onMessage: (msg) => console.log("Received:", msg),
+  onDisconnect: () => console.log("Disconnected")
+});
+
+// Get panes
+client.send({ type: "getPanes" });
+
+// Dump pane content
+client.send({ 
+  type: "dumpPane", 
+  paneId: "terminal_2",
+  options: { lines: 50 }
+});
+
+// Run command
+client.send({
+  type: "runInPane",
+  paneId: "terminal_3",
+  command: "npm test"
+});
+```
+
+### Test with CLI
+
+```bash
+# List all panes
+bun run ipc/ipc-client-cli.ts getPanes
+
+# Dump pane content
+bun run ipc/ipc-client-cli.ts dumpPane terminal_2
+
+# Run command in pane
+bun run ipc/ipc-client-cli.ts runInPane terminal_2 "echo hello"
+```
+
+See [IPC Documentation](ipc/README.md) for full protocol specification.
+
+## Creating an OpenCode Integration
+
+For AI assistant integrations (OpenCode, Claude Desktop, etc.), create a **separate repository** that uses the IPC protocol:
+
+1. Create new repo `zellij-pane-opencode`
+2. Add dependency: `"zellij-pane-tracker": "github:theslyprofessor/zellij-pane-tracker"`
+3. Implement MCP server using IPC client
+4. Add assistant-specific features
+
+See [OpenCode Integration Guide](docs/OPENCODE_INTEGRATION.md) for complete walkthrough.
+
+### Benefits of Separation
+- **Focused repos** - Core vs integration concerns
+- **Independent versioning** - Update either without touching the other
+- **Multiple integrations** - Each AI assistant can have its own repo
+- **Language agnostic** - IPC works with any language
+
 ## License
 
 MIT