@grympler/opencode-tmux-handover 1.0.0

package/QUICK_REFERENCE.md

@@ -0,0 +1,320 @@
+# Quick Reference: Distribution & Configuration
+
+Fast lookup guide for common tasks.
+
+---
+
+## Local → NPM: Publishing Checklist
+
+- [ ] Update `package.json` with correct metadata
+- [ ] Add scope if publishing as organization (`@org/name`)
+- [ ] Run `npm test` to verify code quality
+- [ ] Update version: `npm version patch` (or minor/major)
+- [ ] Create npm account: `npm adduser`
+- [ ] Publish: `npm publish`
+- [ ] Verify: `npm view tt-plugin`
+- [ ] Add to OpenCode config: `"plugin": ["tt-plugin"]`
+
+**Time estimate:** 5-10 minutes
+
+---
+
+## Adding Configuration: Quick Steps
+
+### For Developers
+
+1. Create `src/config.ts` with `loadConfig()` function
+2. Update `src/index.ts` to use `config.enabledCommands`
+3. Create `src/scripts/opencode-tt-config.sh` setup script
+4. Add `src/commands/tt-configure.md` command definition
+5. Update `install.sh` to symlink config script
+
+**Files to create/modify:**
+```
+NEW: src/config.ts
+MODIFY: src/index.ts
+NEW: src/scripts/opencode-tt-config.sh
+NEW: src/commands/tt-configure.md
+MODIFY: install.sh
+```
+
+**Time estimate:** 30 minutes implementation + testing
+
+### For Users
+
+1. Run `/tt-configure` to create config file
+2. Edit `~/.config/opencode/tt-plugin-config.json`
+3. Customize `enabledCommands` array
+4. Restart OpenCode
+
+**Time estimate:** 2 minutes
+
+---
+
+## Configuration Options
+
+### Minimal Config
+```json
+{
+  "enabledCommands": ["tmux"]
+}
+```
+
+### All Options
+```json
+{
+  "enabledCommands": ["tmux", "tmux-oc", "tmux-claude", "tmux-copilot"],
+  "defaultTerminal": "alacritty",
+  "sessionPrefix": "dev"
+}
+```
+
+### Location
+```
+~/.config/opencode/tt-plugin-config.json
+```
+
+---
+
+## Installation Methods
+
+### Local (Development)
+```bash
+git clone https://github.com/yourname/tt-plugin.git
+cd tt-plugin
+npm run install
+```
+
+### From npm (Production)
+1. Add to `~/.config/opencode/opencode.json`:
+   ```json
+   {
+     "plugin": ["tt-plugin"]
+   }
+   ```
+2. Restart OpenCode
+3. Done! Auto-installed to `~/.cache/opencode/node_modules/`
+
+### From GitHub Packages (Organization)
+```json
+{
+  "plugin": ["@yourorg/tt-plugin"]
+}
+```
+
+---
+
+## Publishing Versions
+
+| Phase | Version | Command |
+|-------|---------|---------|
+| Beta | 0.1.0 | `npm version prerelease` |
+| Patch Fix | 1.0.1 | `npm version patch` |
+| New Feature | 1.1.0 | `npm version minor` |
+| Breaking Change | 2.0.0 | `npm version major` |
+
+Then: `npm publish`
+
+---
+
+## Plugin Loading Priorities
+
+When OpenCode starts, plugins load in this order:
+
+1. npm plugins in global config
+2. npm plugins in project config
+3. Local plugins in `~/.config/opencode/plugins/`
+4. Local plugins in `.opencode/plugins/`
+
+**Result:** npm plugins can be overridden by local plugins
+
+---
+
+## Environment Variables
+
+### For Users
+```bash
+# Override config via environment
+export TT_PLUGIN_COMMANDS="tmux,tmux-oc"
+export TT_PLUGIN_TERMINAL="kitty"
+export TT_PLUGIN_PREFIX="myprefix"
+```
+
+### For Developers
+```bash
+# Debug plugin loading
+export DEBUG=opencode:*
+
+# Check where plugin is loaded from
+ls -la ~/.cache/opencode/node_modules/tt-plugin/
+
+# Force local plugin
+rm ~/.cache/opencode/node_modules/tt-plugin/
+```
+
+---
+
+## Common Errors & Fixes
+
+### "Plugin not found"
+```bash
+# If using npm package:
+npm install -g tt-plugin  # Local install for testing
+
+# Check OpenCode config
+cat ~/.config/opencode/opencode.json
+
+# Restart OpenCode
+```
+
+### Config file not found
+```bash
+# First run /tt-configure command
+# Or manually create:
+mkdir -p ~/.config/opencode
+touch ~/.config/opencode/tt-plugin-config.json
+```
+
+### Invalid JSON in config
+```bash
+# Validate JSON
+cat ~/.config/opencode/tt-plugin-config.json | jq .
+
+# Fix with online tool
+# https://jsonlint.com/
+```
+
+### Command not working
+```bash
+# Check if enabled in config
+cat ~/.config/opencode/tt-plugin-config.json | grep enabledCommands
+
+# Restart OpenCode for changes to take effect
+```
+
+---
+
+## Key Files
+
+| File | Purpose | Scope |
+|------|---------|-------|
+| `package.json` | Package metadata | Publishing |
+| `src/index.ts` | Plugin entry point | All |
+| `src/config.ts` | Configuration logic | Configuration |
+| `src/commands/*.md` | Command definitions | Plugin |
+| `src/scripts/*.sh` | Implementations | Plugin |
+| `install.sh` | Installation script | Local |
+| `~/.config/opencode/opencode.json` | OpenCode config | User |
+| `~/.config/opencode/tt-plugin-config.json` | Plugin config | User |
+| `~/.cache/opencode/node_modules/tt-plugin/` | npm installed plugin | npm |
+
+---
+
+## Command Structure
+
+### Current Commands
+```
+/tmux          - Simple tmux session
+/tmux-oc       - Tmux + OpenCode split
+/tmux-claude   - Tmux + Claude split
+/tmux-copilot  - Tmux + Copilot split
+```
+
+### With Configuration
+```
+/tt-configure  - NEW: Setup/edit configuration
+/tmux          - Respects config
+/tmux-oc       - Respects config
+/tmux-claude   - Respects config
+/tmux-copilot  - Respects config
+```
+
+---
+
+## Resources
+
+- **OpenCode Docs:** https://opencode.ai/docs
+- **Plugins:** https://opencode.ai/docs/plugins
+- **Commands:** https://opencode.ai/docs/commands
+- **npm Publishing:** https://docs.npmjs.com/packages-and-modules
+- **Ecosystem:** https://opencode.ai/docs/ecosystem
+
+---
+
+## One-Liner Commands
+
+### Publish to npm
+```bash
+npm version patch && npm publish
+```
+
+### Test configuration
+```bash
+cat ~/.config/opencode/tt-plugin-config.json | jq .
+```
+
+### Check installed plugins
+```bash
+cat ~/.config/opencode/opencode.json | jq '.plugin'
+```
+
+### List symlinked commands
+```bash
+ls -la ~/.config/opencode/commands/ | grep tmux
+```
+
+### View npm package info
+```bash
+npm view tt-plugin version
+```
+
+### Check OpenCode version
+```bash
+opencode --version
+```
+
+---
+
+## Decision Tree
+
+**Q: How do I want to distribute?**
+- Local development → Keep as is, use `npm run install`
+- Open source → Publish to npm
+- Organization only → Publish to GitHub Packages
+
+**Q: Do I need configuration?**
+- No, static commands → Don't add config
+- Yes, users choose commands → Add `enabledCommands` setting
+- Yes, complex settings → Use environment variables or config file
+
+**Q: How to let users configure?**
+- Command-driven → Create `/tt-configure` command
+- File-only → Document `~/.config/opencode/tt-plugin-config.json`
+- UI → Build web interface (advanced)
+
+**Q: What's the release process?**
+- Solo project → Semantic versioning + npm
+- Team project → Use `semantic-release` for automation
+- Enterprise → Use GitHub Actions for CI/CD
+
+---
+
+## Next Milestones
+
+| Step | Effort | Impact |
+|------|--------|--------|
+| Add configuration support | 30 min | Medium |
+| Publish to npm | 10 min | High |
+| Add environment variables | 15 min | Low |
+| Create configuration UI | 2 hours | High |
+| Add telemetry | 1 hour | Medium |
+| Automated releases | 1 hour | High |
+
+---
+
+## Support
+
+- **Documentation:** See `DISTRIBUTION_AND_CONFIG.md` and `IMPLEMENTATION_GUIDE.md`
+- **Issues:** https://github.com/yourusername/tt-plugin/issues
+- **OpenCode Help:** https://github.com/anomalyco/opencode/issues
+- **Discord:** https://opencode.ai/discord

package/README.md

@@ -0,0 +1,117 @@
+# OpenCode Tmux Plugin Suite
+
+Launch tmux sessions from OpenCode with various AI assistants in split panes.
+
+## What It Does
+
+This plugin provides multiple commands to open maximized tmux sessions:
+
+- **`/tmux`** - Simple tmux session (single pane)
+- **`/tmux-oc`** - Tmux with horizontal split, OpenCode in right pane
+- **`/tmux-claude`** - Tmux with horizontal split, Claude in right pane
+- **`/tmux-copilot`** - Tmux with horizontal split, GitHub Copilot in right pane
+
+All commands run locally — no LLM calls, no token costs.
+
+## Requirements
+
+- OpenCode Desktop (dev build with `command.execute.before` hook)
+- tmux
+- A terminal emulator (gnome-terminal, terminator, konsole, alacritty, kitty, xterm)
+
+### Optional - For AI Assistant Splits
+
+- **`/tmux-oc`** - OpenCode (included with OpenCode Desktop)
+- **`/tmux-claude`** - [Claude CLI](https://github.com/anthropics/claude-cli) (`claude` command)
+- **`/tmux-copilot`** - [GitHub Copilot CLI](https://github.com/github/copilot-cli) (`copilot` command)
+
+## Install
+
+```bash
+./install.sh
+```
+
+This will:
+1. Register the plugin in `~/.config/opencode/opencode.json`
+2. Symlink command definitions to `~/.config/opencode/commands/`
+
+### Manual Installation
+
+If you prefer to set it up manually, add the plugin path to your `opencode.json`:
+
+```json
+{
+  "plugin": [
+    "/path/to/tt-plugin"
+  ]
+}
+```
+
+And symlink the commands:
+
+```bash
+ln -s $(pwd)/src/commands/tmux.md ~/.config/opencode/commands/
+ln -s $(pwd)/src/commands/tmux-oc.md ~/.config/opencode/commands/
+ln -s $(pwd)/src/commands/tmux-claude.md ~/.config/opencode/commands/
+ln -s $(pwd)/src/commands/tmux-copilot.md ~/.config/opencode/commands/
+```
+
+## Usage
+
+Type any of the commands in OpenCode:
+
+- **`/tmux`** - Simple tmux session
+- **`/tmux-oc`** - Tmux + OpenCode split
+- **`/tmux-claude`** - Tmux + Claude split
+- **`/tmux-copilot`** - Tmux + Copilot split
+
+Each command will:
+- First run: Create a new tmux session
+- Already in tmux: Create a new split in current window
+- Session exists: Attach to existing session
+
+Session names are based on directory names.
+
+## Uninstall
+
+```bash
+./uninstall.sh
+```
+
+This will unregister the plugin from `opencode.json` and remove command symlinks.
+
+## File Structure
+
+```
+src/
+├── index.ts                    # Main plugin entry point
+├── commands/
+│   ├── tmux.md               # /tmux command definition
+│   ├── tmux-oc.md            # /tmux-oc command definition
+│   ├── tmux-claude.md        # /tmux-claude command definition
+│   └── tmux-copilot.md       # /tmux-copilot command definition
+└── scripts/
+    ├── opencode-tmux.sh      # Simple tmux script
+    ├── opencode-tmux-oc.sh   # OpenCode split script
+    ├── opencode-tmux-claude.sh # Claude split script
+    └── opencode-tmux-copilot.sh # Copilot split script
+
+scripts/
+├── register-plugin.js          # Registers plugin in opencode.json
+└── unregister-plugin.js        # Unregisters plugin from opencode.json
+
+install.sh                      # Installation script
+uninstall.sh                    # Uninstallation script
+package.json                    # Plugin manifest
+```
+
+## How It Works
+
+The plugin uses OpenCode's `command.execute.before` hook to intercept commands before they reach the LLM. When a command is detected:
+
+1. The plugin executes the corresponding bash script
+2. The script launches a terminal with tmux
+3. For split commands, the AI assistant launches in the right pane
+4. The command output is cleared (`output.parts = []`) to prevent LLM processing
+
+The plugin is self-contained - bash scripts are referenced using relative paths from the plugin directory, so no global installation of scripts is needed.

package/install.sh

@@ -0,0 +1,157 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Configuration
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+OPENCODE_CONFIG="${HOME}/.config/opencode"
+
+echo -e "${BLUE}=== OpenCode Tmux Plugin Suite Installation ===${NC}\n"
+
+# Ensure directories exist
+echo -e "${YELLOW}Creating directories...${NC}"
+mkdir -p "${OPENCODE_CONFIG}/commands"
+
+# Function to create symlink with backup
+create_symlink() {
+    local src="$1"
+    local dest="$2"
+    local name="$3"
+
+    if [ ! -f "$src" ]; then
+        echo -e "${RED}✗ Source file not found: $src${NC}"
+        return 1
+    fi
+
+    # Backup existing file if it exists and is not already a symlink
+    if [ -e "$dest" ] && [ ! -L "$dest" ]; then
+        echo -e "${YELLOW}  Backing up existing $name to ${dest}.bak${NC}"
+        mv "$dest" "${dest}.bak"
+    fi
+
+    # Remove old symlink if it exists
+    if [ -L "$dest" ]; then
+        rm "$dest"
+    fi
+
+    # Create symlink
+    ln -s "$src" "$dest"
+    echo -e "${GREEN}✓ Symlinked $name${NC}"
+}
+
+# Function to remove old symlink if exists
+remove_old_symlink() {
+    local dest="$1"
+    local name="$2"
+    
+    if [ -L "$dest" ]; then
+        rm "$dest"
+        echo -e "${YELLOW}  Removed old $name symlink${NC}"
+    fi
+}
+
+# Remove old plugin symlinks (cleanup from old install)
+echo -e "${YELLOW}Cleaning up old plugin symlinks...${NC}"
+remove_old_symlink "${OPENCODE_CONFIG}/plugins/tmux-launcher.ts" "tmux-launcher plugin"
+remove_old_symlink "${OPENCODE_CONFIG}/plugins/tmux-oc-launcher.ts" "tmux-oc-launcher plugin"
+remove_old_symlink "${OPENCODE_CONFIG}/plugins/tmux-claude-launcher.ts" "tmux-claude-launcher plugin"
+remove_old_symlink "${OPENCODE_CONFIG}/plugins/tmux-copilot-launcher.ts" "tmux-copilot-launcher plugin"
+
+# Remove old script symlinks (cleanup from old install)
+echo -e "${YELLOW}Cleaning up old script symlinks...${NC}"
+remove_old_symlink "${HOME}/.local/bin/opencode-tmux.sh" "opencode-tmux.sh script"
+remove_old_symlink "${HOME}/.local/bin/opencode-tmux-oc.sh" "opencode-tmux-oc.sh script"
+remove_old_symlink "${HOME}/.local/bin/opencode-tmux-claude.sh" "opencode-tmux-claude.sh script"
+remove_old_symlink "${HOME}/.local/bin/opencode-tmux-copilot.sh" "opencode-tmux-copilot.sh script"
+
+# Install commands
+echo -e "\n${YELLOW}Installing command files...${NC}"
+
+create_symlink \
+    "${SCRIPT_DIR}/src/commands/tmux.md" \
+    "${OPENCODE_CONFIG}/commands/tmux.md" \
+    "tmux command"
+
+create_symlink \
+    "${SCRIPT_DIR}/src/commands/tmux-oc.md" \
+    "${OPENCODE_CONFIG}/commands/tmux-oc.md" \
+    "tmux-oc command"
+
+create_symlink \
+    "${SCRIPT_DIR}/src/commands/tmux-claude.md" \
+    "${OPENCODE_CONFIG}/commands/tmux-claude.md" \
+    "tmux-claude command"
+
+create_symlink \
+    "${SCRIPT_DIR}/src/commands/tmux-copilot.md" \
+    "${OPENCODE_CONFIG}/commands/tmux-copilot.md" \
+    "tmux-copilot command"
+
+create_symlink \
+    "${SCRIPT_DIR}/src/commands/tt-configure.md" \
+    "${OPENCODE_CONFIG}/commands/tt-configure.md" \
+    "tt-configure command"
+
+# Install configuration script
+echo -e "\n${YELLOW}Installing configuration script...${NC}"
+create_symlink \
+    "${SCRIPT_DIR}/src/scripts/opencode-tt-config.sh" \
+    "${OPENCODE_CONFIG}/commands/tt-configure-script.sh" \
+    "configuration helper script"
+
+# Register plugin in opencode.json
+echo -e "\n${YELLOW}Registering plugin in opencode.json...${NC}"
+node "${SCRIPT_DIR}/scripts/register-plugin.js"
+
+# Verification
+echo -e "\n${YELLOW}Verifying installation...${NC}"
+
+errors=0
+
+# Check commands
+for cmd in tmux tmux-oc tmux-claude tmux-copilot tt-configure; do
+    if [ -L "${OPENCODE_CONFIG}/commands/${cmd}.md" ] && [ -f "${OPENCODE_CONFIG}/commands/${cmd}.md" ]; then
+        echo -e "${GREEN}✓ Command ${cmd} symlink verified${NC}"
+    else
+        echo -e "${RED}✗ Command ${cmd} symlink failed${NC}"
+        ((errors++))
+    fi
+done
+
+# Check syntax of bash scripts
+echo -e "\n${YELLOW}Checking script syntax...${NC}"
+for script in opencode-tmux.sh opencode-tmux-oc.sh opencode-tmux-claude.sh opencode-tmux-copilot.sh opencode-tt-config.sh; do
+    if bash -n "${SCRIPT_DIR}/src/scripts/${script}" 2>/dev/null; then
+        echo -e "${GREEN}✓ Shell script ${script} syntax valid${NC}"
+    else
+        echo -e "${RED}✗ Shell script ${script} syntax error${NC}"
+        ((errors++))
+    fi
+done
+
+# Summary
+echo -e "\n${BLUE}=== Installation Summary ===${NC}"
+echo -e "Commands:  ${OPENCODE_CONFIG}/commands/"
+echo -e "Plugin:    ${SCRIPT_DIR} (registered in opencode.json)"
+
+if [ $errors -eq 0 ]; then
+    echo -e "\n${GREEN}✓ Installation successful!${NC}"
+    echo -e "\n${YELLOW}Available commands:${NC}"
+    echo -e "  ${GREEN}/tmux${NC}          - Simple tmux session (maximized)"
+    echo -e "  ${GREEN}/tmux-oc${NC}       - Tmux with OpenCode in split"
+    echo -e "  ${GREEN}/tmux-claude${NC}   - Tmux with Claude in split"
+    echo -e "  ${GREEN}/tmux-copilot${NC}  - Tmux with GitHub Copilot in split"
+    echo -e "  ${GREEN}/tt-configure${NC}  - Configure plugin settings"
+    echo -e "\n${YELLOW}The plugin is now loaded via opencode.json plugin array${NC}"
+    echo -e "${YELLOW}To uninstall, run:${NC} ./uninstall.sh"
+    exit 0
+else
+    echo -e "\n${RED}✗ Installation failed with $errors error(s)${NC}"
+    exit 1
+fi

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@grympler/opencode-tmux-handover",
+  "version": "1.0.0",
+  "description": "OpenCode Desktop plugin for launching tmux with AI assistants (OpenCode, Claude, Copilot) in split panes",
+  "main": "src/index.ts",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "install": "bash install.sh",
+    "uninstall": "bash uninstall.sh",
+    "test": "echo 'See TESTING.md for comprehensive test procedures'"
+  },
+  "keywords": [
+    "opencode",
+    "plugin",
+    "tmux",
+    "terminal",
+    "split-window",
+    "command",
+    "claude",
+    "copilot"
+  ],
+  "author": "Olivier <olivier@example.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/grympler/opencode-tmux-handover"
+  },
+  "bugs": {
+    "url": "https://github.com/grympler/opencode-tmux-handover/issues"
+  },
+  "engines": {
+    "opencode": ">=dev",
+    "tmux": ">=3.0",
+    "bash": ">=4.0"
+  },
+  "files": [
+    "src/",
+    "scripts/",
+    "install.sh",
+    "uninstall.sh",
+    "README.md",
+    "DISTRIBUTION_AND_CONFIG.md",
+    "IMPLEMENTATION_GUIDE.md",
+    "QUICK_REFERENCE.md",
+    "package.json"
+  ]
+}

package/scripts/register-plugin.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync } from "fs"
+import { dirname, resolve } from "path"
+import { fileURLToPath } from "url"
+import { homedir } from "os"
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+const OPENCODE_CONFIG_PATH = resolve(homedir(), ".config/opencode/opencode.json")
+const PLUGIN_DIR = resolve(__dirname, "..")
+
+function registerPlugin() {
+  try {
+    let config = { plugin: [] }
+    
+    try {
+      const content = readFileSync(OPENCODE_CONFIG_PATH, "utf-8")
+      config = JSON.parse(content)
+    } catch (err) {
+      console.log("Creating new opencode.json...")
+    }
+    
+    if (!Array.isArray(config.plugin)) {
+      config.plugin = []
+    }
+    
+    if (config.plugin.includes(PLUGIN_DIR)) {
+      console.log("Plugin already registered in opencode.json")
+      return
+    }
+    
+    config.plugin.push(PLUGIN_DIR)
+    
+    writeFileSync(OPENCODE_CONFIG_PATH, JSON.stringify(config, null, 2) + "\n")
+    console.log(`✓ Plugin registered: ${PLUGIN_DIR}`)
+    console.log(`✓ Updated: ${OPENCODE_CONFIG_PATH}`)
+  } catch (err) {
+    console.error("Error registering plugin:", err)
+    process.exit(1)
+  }
+}
+
+registerPlugin()