docs: add Antigravity and tmux integration docs

README.md

@@ -35,6 +35,10 @@ https://raw.githubusercontent.com/alvinunreal/oh-my-opencode-slim/refs/heads/mas
 
 **Detailed installation guide:** [docs/installation.md](docs/installation.md)
 
+**Additional guides:**
+- **[Antigravity Setup](docs/antigravity.md)** - Complete guide for Antigravity provider configuration  
+- **[Tmux Integration](docs/tmux-integration.md)** - Real-time agent monitoring with tmux
+
 ---
 
 ## 🏛️ Meet the Pantheon
@@ -229,6 +233,8 @@ https://raw.githubusercontent.com/alvinunreal/oh-my-opencode-slim/refs/heads/mas
 
 - **[Quick Reference](docs/quick-reference.md)** - Presets, Skills, MCPs, Tools, Configuration
 - **[Installation Guide](docs/installation.md)** - Detailed installation and troubleshooting
+- **[Antigravity Setup](docs/antigravity.md)** - Complete guide for Antigravity provider configuration
+- **[Tmux Integration](docs/tmux-integration.md)** - Real-time agent monitoring with tmux
 
 ---
 

docs/antigravity.md

@@ -0,0 +1,382 @@
+# Antigravity Provider Setup Guide
+
+Complete guide for configuring Antigravity provider with oh-my-opencode-slim to access Claude and Gemini models through the "google" provider configuration.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Provider Setup](#provider-setup)
+- [Agent Model Assignment](#agent-model-assignment)
+- [Usage Examples](#usage-examples)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Overview
+
+Antigravity provides access to high-quality Claude and Gemini models through a unified interface. This guide shows you how to configure oh-my-opencode-slim to use Antigravity via the "google" provider configuration.
+
+**Benefits:**
+- Access to Claude Opus 4.5 Thinking and Sonnet 4.5 Thinking models
+- Gemini 3 Pro High and Flash models
+- Unified configuration through OpenCode
+- Excellent for complex reasoning tasks (Claude) and fast responses (Gemini)
+
+---
+
+## Installation
+
+### Prerequisites
+
+1. **Install oh-my-opencode-slim:**
+   ```bash
+   bunx oh-my-opencode-slim@latest install
+   ```
+
+2. **Set up Antigravity/LLM-Mux:**
+   Follow the installation guide at https://nghyane.github.io/llm-mux/#/installation
+
+3. **Start the Antigravity service:**
+   Ensure your Antigravity service is running on `http://127.0.0.1:8317`
+
+---
+
+## Configuration
+
+### Step 1: Configure Provider in OpenCode
+
+Edit `~/.config/opencode/opencode.json` and add the "google" provider configuration:
+
+```json
+{
+  "provider": {
+    "google": {
+      "options": {
+        "baseURL": "http://127.0.0.1:8317/v1beta",
+        "apiKey": "sk-dummy"
+      },
+      "models": {
+        "gemini-3-pro-high": {
+          "name": "Gemini 3 Pro High",
+          "attachment": true,
+          "limit": {
+            "context": 1048576,
+            "output": 65535
+          },
+          "modalities": {
+            "input": ["text", "image", "pdf"],
+            "output": ["text"]
+          }
+        },
+        "gemini-3-flash": {
+          "name": "Gemini 3 Flash",
+          "attachment": true,
+          "limit": {
+            "context": 1048576,
+            "output": 65536
+          },
+          "modalities": {
+            "input": ["text", "image", "pdf"],
+            "output": ["text"]
+          }
+        },
+        "claude-opus-4-5-thinking": {
+          "name": "Claude Opus 4.5 Thinking",
+          "attachment": true,
+          "limit": {
+            "context": 200000,
+            "output": 32000
+          },
+          "modalities": {
+            "input": ["text", "image", "pdf"],
+            "output": ["text"]
+          }
+        },
+        "claude-sonnet-4-5-thinking": {
+          "name": "Claude Sonnet 4.5 Thinking",
+          "attachment": true,
+          "limit": {
+            "context": 200000,
+            "output": 32000
+          },
+          "modalities": {
+            "input": ["text", "image", "pdf"],
+            "output": ["text"]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Step 2: Configure Agent Models
+
+Edit `~/.config/opencode/oh-my-opencode-slim.json` and add the Antigravity preset:
+
+```json
+{
+  "preset": "antigravity",
+  "presets": {
+    "antigravity": {
+      "orchestrator": {
+        "model": "google/claude-opus-4-5-thinking",
+        "skills": ["*"],
+        "mcps": ["websearch"]
+      },
+      "oracle": {
+        "model": "google/gemini-3-pro-high",
+        "variant": "high",
+        "skills": [],
+        "mcps": []
+      },
+      "librarian": {
+        "model": "google/gemini-3-flash",
+        "variant": "low",
+        "skills": [],
+        "mcps": ["websearch", "context7", "grep_app"]
+      },
+      "explorer": {
+        "model": "google/gemini-3-flash",
+        "variant": "low",
+        "skills": [],
+        "mcps": []
+      },
+      "designer": {
+        "model": "google/gemini-3-flash",
+        "variant": "medium",
+        "skills": ["agent-browser"],
+        "mcps": []
+      },
+      "fixer": {
+        "model": "google/gemini-3-flash",
+        "variant": "low",
+        "skills": [],
+        "mcps": []
+      }
+    }
+  }
+}
+```
+
+---
+
+## Provider Setup
+
+### Available Models
+
+| Model | Type | Context Window | Output Limit | Best For |
+|-------|------|----------------|--------------|----------|
+| `claude-opus-4-5-thinking` | Claude | 200K tokens | 32K tokens | Complex reasoning, orchestrator |
+| `claude-sonnet-4-5-thinking` | Claude | 200K tokens | 32K tokens | Balanced reasoning and speed |
+| `gemini-3-pro-high` | Gemini | 1M tokens | 65K tokens | High-quality responses |
+| `gemini-3-flash` | Gemini | 1M tokens | 65K tokens | Fast responses, cost-effective |
+
+### Model Recommendations
+
+**For Orchestrator:** Use `claude-opus-4-5-thinking`
+- Best reasoning capabilities for multi-agent coordination
+- Excellent at planning complex workflows
+- Can handle large context windows
+
+**For Oracle:** Use `gemini-3-pro-high`  
+- Strategic thinking and debugging
+- High-quality architectural advice
+
+**For Support Agents:** Use `gemini-3-flash`
+- Fast and cost-effective for routine tasks
+- Good for librarian, explorer, designer, and fixer roles
+
+---
+
+## Agent Model Assignment
+
+### Basic Configuration
+
+The preset assigns models based on their strengths:
+
+```json
+{
+  "presets": {
+    "antigravity": {
+      "orchestrator": { "model": "google/claude-opus-4-5-thinking" },
+      "oracle": { "model": "google/gemini-3-pro-high", "variant": "high" },
+      "librarian": { "model": "google/gemini-3-flash", "variant": "low" },
+      "explorer": { "model": "google/gemini-3-flash", "variant": "low" },
+      "designer": { "model": "google/gemini-3-flash", "variant": "medium" },
+      "fixer": { "model": "google/gemini-3-flash", "variant": "low" }
+    }
+  }
+}
+```
+
+### Custom Assignments
+
+You can customize which model each agent uses:
+
+**Example: All Claude for reasoning-heavy work:**
+```json
+{
+  "presets": {
+    "claude-heavy": {
+      "orchestrator": { "model": "google/claude-opus-4-5-thinking" },
+      "oracle": { "model": "google/claude-sonnet-4-5-thinking", "variant": "high" },
+      "librarian": { "model": "google/claude-sonnet-4-5-thinking", "variant": "low" },
+      "explorer": { "model": "google/claude-sonnet-4-5-thinking", "variant": "low" },
+      "designer": { "model": "google/claude-sonnet-4-5-thinking", "variant": "medium" },
+      "fixer": { "model": "google/claude-sonnet-4-5-thinking", "variant": "low" }
+    }
+  }
+}
+```
+
+**Example: Mixed setup with cost optimization:**
+```json
+{
+  "presets": {
+    "cost-optimized": {
+      "orchestrator": { "model": "google/claude-sonnet-4-5-thinking" },
+      "oracle": { "model": "google/gemini-3-pro-high", "variant": "high" },
+      "librarian": { "model": "google/gemini-3-flash", "variant": "low" },
+      "explorer": { "model": "google/gemini-3-flash", "variant": "low" },
+      "designer": { "model": "google/gemini-3-flash", "variant": "low" },
+      "fixer": { "model": "google/gemini-3-flash", "variant": "low" }
+    }
+  }
+}
+```
+
+---
+
+## Usage Examples
+
+### Switching to Antigravity Preset
+
+```bash
+# Edit the preset in your config
+export OH_MY_OPENCODE_SLIM_PRESET=antigravity
+opencode
+```
+
+### Testing Configuration
+
+1. **Verify provider connection:**
+   ```bash
+   opencode auth status
+   ```
+
+2. **Test agent responses:**
+   ```bash
+   opencode
+   # In OpenCode, run: ping all agents
+   ```
+
+3. **Check logs for any connection issues:**
+   ```bash
+   tail -f ~/.config/opencode/logs/opencode.log
+   ```
+
+### Example Workflow
+
+Once configured, you can ask the orchestrator to handle complex tasks:
+
+```
+Orchestrator, please analyze this codebase and create a comprehensive refactoring plan.
+Use your team to:
+1. Map the current architecture
+2. Identify bottlenecks and issues  
+3. Create a detailed implementation plan
+4. Estimate effort and risks
+```
+
+The orchestrator will delegate to specialists using the configured Antigravity models.
+
+---
+
+## Troubleshooting
+
+### Provider Connection Issues
+
+**Problem:** Agents not responding or showing connection errors
+
+**Solutions:**
+1. Verify Antigravity service is running:
+   ```bash
+   curl http://127.0.0.1:8317/v1beta/models
+   ```
+
+2. Check the baseURL in your config matches your service:
+   ```json
+   {
+     "options": {
+       "baseURL": "http://127.0.0.1:8317/v1beta"
+     }
+   }
+   ```
+
+3. Verify your API key (can be dummy value like "sk-dummy")
+
+### Model Not Found Errors
+
+**Problem:** "Model not found" or similar errors
+
+**Solutions:**
+1. Ensure the model names match exactly:
+   - `claude-opus-4-5-thinking` (not `claude-opus-4.5-thinking`)
+   - `gemini-3-flash` (not `gemini-3-flash-preview`)
+
+2. Check your provider configuration includes all required fields:
+   ```json
+   {
+     "models": {
+       "model-name": {
+         "name": "Display Name",
+         "attachment": true,
+         "limit": { "context": 1048576, "output": 65535 },
+         "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
+       }
+     }
+   }
+   ```
+
+### Authentication Issues
+
+**Problem:** 401 Unauthorized or similar auth errors
+
+**Solutions:**
+1. The `apiKey` can be any dummy value for Antigravity
+2. Ensure the baseURL is correct and accessible
+3. Restart OpenCode after changing configuration
+
+### Performance Issues
+
+**Problem:** Slow responses or timeouts
+
+**Solutions:**
+1. Use `gemini-3-flash` for faster responses on support agents
+2. Check your Antigravity service performance
+3. Consider reducing context sizes for large files
+
+### Switching Between Presets
+
+To test different configurations:
+
+```bash
+# Use environment variable for quick testing
+export OH_MY_OPENCODE_SLIM_PRESET=openai
+opencode
+
+# Or edit ~/.config/opencode/oh-my-opencode-slim.json
+# Change the "preset" field and restart OpenCode
+```
+
+---
+
+## Additional Resources
+
+- **LLM-Mux Installation:** https://nghyane.github.io/llm-mux/#/installation
+- **OpenCode Documentation:** https://opencode.ai/docs
+- **Quick Reference:** [docs/quick-reference.md](quick-reference.md)
+- **Installation Guide:** [docs/installation.md](installation.md)

docs/quick-reference.md

@@ -126,101 +126,6 @@ Routes through Antigravity's CLIProxy for Claude + Gemini models:
 
 </details>
 
-### Antigravity Provider Setup
-
-For using Antigravity with the "google" provider configuration (recommended for Claude + Gemini models):
-
-**Step 1: Configure Provider in OpenCode**
-
-Add to `~/.config/opencode/opencode.json`:
-
-```json
-{
-  "provider": {
-    "google": {
-      "options": {
-        "baseURL": "http://127.0.0.1:8317/v1beta",
-        "apiKey": "sk-dummy"
-      },
-      "models": {
-        "gemini-3-pro-high": {
-          "name": "Gemini 3 Pro High",
-          "attachment": true,
-          "limit": {
-            "context": 1048576,
-            "output": 65535
-          },
-          "modalities": {
-            "input": ["text", "image", "pdf"],
-            "output": ["text"]
-          }
-        },
-        "gemini-3-flash": {
-          "name": "Gemini 3 Flash",
-          "attachment": true,
-          "limit": {
-            "context": 1048576,
-            "output": 65536
-          },
-          "modalities": {
-            "input": ["text", "image", "pdf"],
-            "output": ["text"]
-          }
-        },
-        "claude-opus-4-5-thinking": {
-          "name": "Claude Opus 4.5 Thinking",
-          "attachment": true,
-          "limit": {
-            "context": 200000,
-            "output": 32000
-          },
-          "modalities": {
-            "input": ["text", "image", "pdf"],
-            "output": ["text"]
-          }
-        },
-        "claude-sonnet-4-5-thinking": {
-          "name": "Claude Sonnet 4.5 Thinking",
-          "attachment": true,
-          "limit": {
-            "context": 200000,
-            "output": 32000
-          },
-          "modalities": {
-            "input": ["text", "image", "pdf"],
-            "output": ["text"]
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-**Step 2: Configure Agent Models**
-
-Add preset to `~/.config/opencode/oh-my-opencode-slim.json`:
-
-```json
-{
-  "preset": "antigravity",
-  "presets": {
-    "antigravity": {
-      "orchestrator": { "model": "google/claude-opus-4-5-thinking", "skills": ["*"], "mcps": ["websearch"] },
-      "oracle": { "model": "google/gemini-3-pro-high", "variant": "high", "skills": [], "mcps": [] },
-      "librarian": { "model": "google/gemini-3-flash", "variant": "low", "skills": [], "mcps": ["websearch", "context7", "grep_app"] },
-      "explorer": { "model": "google/gemini-3-flash", "variant": "low", "skills": [], "mcps": [] },
-      "designer": { "model": "google/gemini-3-flash", "variant": "medium", "skills": ["agent-browser"], "mcps": [] },
-      "fixer": { "model": "google/gemini-3-flash", "variant": "low", "skills": [], "mcps": [] }
-    }
-  }
-}
-```
-
-**💡 Recommendation:** Use `claude-opus-4-5-thinking` for the orchestrator as it provides the best reasoning capabilities for multi-agent coordination.
-
-> **Installation Note:** For detailed installation instructions, see https://nghyane.github.io/llm-mux/#/installation
-
 ### Author's Preset
 
 Mixed setup combining multiple providers:
@@ -241,6 +146,8 @@ Mixed setup combining multiple providers:
 }
 ```
 
+> **Antigravity Provider:** For complete Antigravity setup guide, see [Antigravity Setup](antigravity.md)
+
 ---
 
 ## Skills
@@ -435,7 +342,7 @@ You can disable specific MCP servers globally by adding them to the `disabled_mc
 
 #### Quick Setup
 
-1. **Enable tmux integration** in `oh-my-opencode-slim.json` (see [Plugin Config](#plugin-config-oh-my-opencode-slimjson)).
+1. **Enable tmux integration** in `oh-my-opencode-slim.json`:
 
    ```json
    {
@@ -453,15 +360,6 @@ You can disable specific MCP servers globally by adding them to the `disabled_mc
     opencode --port 4096
     ```
 
-   Or use a custom port (must match `OPENCODE_PORT` env var):
-    ```bash
-    tmux
-    export OPENCODE_PORT=5000
-    opencode --port 5000
-    ```
-
-   This allows multiple OpenCode instances on different ports.
-
 #### Layout Options
 
 | Layout | Description |
@@ -472,6 +370,8 @@ You can disable specific MCP servers globally by adding them to the `disabled_mc
 | `even-horizontal` | All panes side by side |
 | `even-vertical` | All panes stacked vertically |
 
+> **Detailed Guide:** For complete tmux integration documentation, troubleshooting, and advanced usage, see [Tmux Integration](tmux-integration.md)
+
 ### Background Tasks
 
 The plugin provides tools to manage asynchronous work:

docs/tmux-integration.md

@@ -0,0 +1,455 @@
+# Tmux Integration Guide
+
+Complete guide for using tmux integration with oh-my-opencode-slim to watch agents work in real-time through automatic pane spawning.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Quick Setup](#quick-setup)
+- [Configuration](#configuration)
+- [Layout Options](#layout-options)
+- [Usage Examples](#usage-examples)
+- [Troubleshooting](#troubleshooting)
+- [Advanced Usage](#advanced-usage)
+
+---
+
+## Overview
+
+**Watch your agents work in real-time.** When the Orchestrator launches sub-agents or initiates background tasks, new tmux panes automatically spawn showing each agent's live progress. No more waiting in the dark.
+
+### Key Benefits
+
+- **Real-time visibility** into agent activities
+- **Automatic pane management** - panes spawn and organize automatically
+- **Interactive debugging** - you can jump into any agent's session
+- **Background task monitoring** - see long-running work as it happens
+- **Multi-session support** - different projects can have separate tmux environments
+
+> ⚠️ **Temporary workaround:** Start OpenCode with `--port` to enable tmux integration. The port must match the `OPENCODE_PORT` environment variable (default: 4096). This is required until the upstream issue is resolved. [opencode#9099](https://github.com/anomalyco/opencode/issues/9099).
+
+---
+
+## Quick Setup
+
+### Step 1: Enable Tmux Integration
+
+Edit `~/.config/opencode/oh-my-opencode-slim.json`:
+
+```json
+{
+  "tmux": {
+    "enabled": true,
+    "layout": "main-vertical",
+    "main_pane_size": 60
+  }
+}
+```
+
+### Step 2: Run OpenCode Inside Tmux
+
+```bash
+# Start a new tmux session
+tmux
+
+# Start OpenCode with the default port (4096)
+opencode --port 4096
+```
+
+That's it! Your agents will now spawn panes automatically.
+
+---
+
+## Configuration
+
+### Tmux Settings
+
+Configure tmux behavior in `~/.config/opencode/oh-my-opencode-slim.json`:
+
+```json
+{
+  "tmux": {
+    "enabled": true,
+    "layout": "main-vertical",
+    "main_pane_size": 60
+  }
+}
+```
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `enabled` | boolean | `false` | Enable/disable tmux pane spawning |
+| `layout` | string | `"main-vertical"` | Layout preset (see [Layout Options](#layout-options)) |
+| `main_pane_size` | number | `60` | Main pane size as percentage (20-80) |
+
+### Layout Options
+
+Choose how panes are arranged:
+
+| Layout | Description |
+|--------|-------------|
+| `main-vertical` | Your session on the left (60%), agents stacked on the right |
+| `main-horizontal` | Your session on top (60%), agents stacked below |
+| `tiled` | All panes in equal-sized grid |
+| `even-horizontal` | All panes side by side |
+| `even-vertical` | All panes stacked vertically |
+
+**Example: Horizontal layout for wide screens:**
+```json
+{
+  "tmux": {
+    "enabled": true,
+    "layout": "main-horizontal",
+    "main_pane_size": 50
+  }
+}
+```
+
+**Example: Tiled layout for maximum parallelism:**
+```json
+{
+  "tmux": {
+    "enabled": true,
+    "layout": "tiled",
+    "main_pane_size": 50
+  }
+}
+```
+
+---
+
+## Usage Examples
+
+### Basic Usage
+
+1. **Start tmux and OpenCode:**
+   ```bash
+   tmux
+   opencode --port 4096
+   ```
+
+2. **Ask the Orchestrator to delegate work:**
+   ```
+   Please analyze this codebase and create a documentation structure.
+   ```
+
+3. **Watch panes spawn automatically:**
+   - The main OpenCode session stays visible
+   - New panes appear showing agent activities
+   - You can switch between panes to monitor progress
+
+### Navigating Panes
+
+```bash
+# List all panes (in another terminal)
+tmux list-panes -a
+
+# Switch to specific pane (in tmux)
+Ctrl+B Arrow Keys    # Navigate between panes
+Ctrl+B %             # Split pane horizontally
+Ctrl+B "             # Split pane vertically
+Ctrl+B z             # Zoom/unzoom pane
+Ctrl+B c             # Create new window
+Ctrl+B n/p           # Next/previous window
+```
+
+### Detaching and Reattaching
+
+```bash
+# Detach from tmux session (keep it running)
+Ctrl+B d
+
+# Reattach to your session later
+tmux attach
+
+# Or specify which session
+tmux attach -t 0
+```
+
+### Monitoring Multiple Projects
+
+For different projects on different ports:
+
+```bash
+# Project 1
+tmux new -s project1
+opencode --port 4096
+
+# Detach and create Project 2
+Ctrl+B d
+tmux new -s project2
+opencode --port 4097
+
+# Switch between projects
+tmux switch -t project1
+tmux switch -t project2
+```
+
+---
+
+## Troubleshooting
+
+### Tmux Integration Not Working
+
+**Problem:** No panes are spawning
+
+**Solutions:**
+1. **Verify tmux integration is enabled:**
+   ```bash
+   cat ~/.config/opencode/oh-my-opencode-slim.json | grep tmux
+   ```
+
+2. **Check port configuration:**
+   ```bash
+   # Ensure port matches
+   echo $OPENCODE_PORT  # Should be 4096 by default
+   opencode --port 4096 # Should match
+   ```
+
+3. **Verify you're running inside tmux:**
+   ```bash
+   echo $TMUX  # Should show something, not empty
+   ```
+
+4. **Check OpenCode logs:**
+   ```bash
+   tail -f ~/.config/opencode/logs/opencode.log
+   ```
+
+### Port Conflicts
+
+**Problem:** "Port already in use" or agents not connecting
+
+**Solutions:**
+1. **Use a different port:**
+   ```bash
+   export OPENCODE_PORT=5000
+   opencode --port 5000
+   ```
+
+2. **Kill existing OpenCode processes:**
+   ```bash
+   pkill -f "opencode"
+   ```
+
+3. **Check for conflicting services:**
+   ```bash
+   netstat -tulpn | grep 4096
+   ```
+
+### Tmux Session Issues
+
+**Problem:** Can't create or attach to tmux sessions
+
+**Solutions:**
+1. **Install tmux:**
+   ```bash
+   # Ubuntu/Debian
+   sudo apt install tmux
+
+   # macOS
+   brew install tmux
+
+   # Or use the package manager that comes with your distribution
+   ```
+
+2. **Check tmux version:**
+   ```bash
+   tmux -V  # Should be 1.8 or higher
+   ```
+
+3. **Reset tmux configuration:**
+   ```bash
+   rm -f ~/.tmux.conf
+   tmux kill-server
+   tmux
+   ```
+
+### Layout Problems
+
+**Problem:** Panes don't arrange as expected
+
+**Solutions:**
+1. **Try different layouts:**
+   ```json
+   {
+     "tmux": {
+       "enabled": true,
+       "layout": "tiled",
+       "main_pane_size": 40
+     }
+   }
+   ```
+
+2. **Manual layout adjustment:**
+   ```bash
+   # In tmux, resize panes
+   Ctrl+B Alt+Arrow Keys
+   ```
+
+3. **Clear all panes and restart:**
+   ```bash
+   tmux kill-pane -a
+   # Restart OpenCode
+   ```
+
+### Performance Issues
+
+**Problem:** Too many panes or slow performance
+
+**Solutions:**
+1. **Reduce pane size for main window:**
+   ```json
+   {
+     "tmux": {
+       "enabled": true,
+       "layout": "main-vertical",
+       "main_pane_size": 40
+     }
+   }
+   ```
+
+2. **Limit background tasks:**
+   ```bash
+   # In OpenCode, use fewer parallel operations
+   # Or configure agents to be more sequential
+   ```
+
+3. **Clean up old panes:**
+   ```bash
+   # Kill all panes except current
+   tmux kill-pane -a
+   ```
+
+---
+
+## Advanced Usage
+
+### Custom Tmux Configuration
+
+Create `~/.tmux.conf` for custom behavior:
+
+```bash
+# Enable mouse support
+set -g mouse on
+
+# Custom key bindings
+bind-key r source-file ~/.tmux.conf
+
+# Better colors
+set -g default-terminal "screen-256color"
+
+# Status bar customization
+set -g status-right "#H %Y-%m-%d %H:%M"
+
+# Pane navigation
+bind h select-pane -L
+bind j select-pane -D
+bind k select-pane -U
+bind l select-pane -R
+```
+
+### Monitoring Multiple Agents
+
+Watch specific agents more closely:
+
+```bash
+# Monitor all agent panes
+watch -n 1 'tmux list-panes -a -F "#{pane_current_command} (#{pane_index})"'
+
+# Watch OpenCode output specifically
+tmux list-panes -a | grep opencode
+
+# Monitor background tasks
+tmux list-panes -a | grep background
+```
+
+### Integration with Background Tasks
+
+The plugin provides background task tools that work seamlessly with tmux:
+
+| Tool | Description | Tmux Integration |
+|------|-------------|------------------|
+| `background_task` | Launch agents asynchronously | Spawns panes for monitoring |
+| `background_output` | Check task results | Output appears in panes |
+| `background_cancel` | Stop running tasks | Cleans up panes |
+
+### Scripting and Automation
+
+```bash
+#!/bin/bash
+# Auto-start script for OpenCode with tmux
+
+# Create dedicated session
+tmux new -d -s opencode
+
+# Start OpenCode in the session
+tmux send-keys -t opencode:0 'opencode --port 4096' Enter
+
+# Wait and attach
+sleep 2
+tmux attach -t opencode
+```
+
+### Log Monitoring
+
+```bash
+# Monitor OpenCode logs in real-time
+tmux split-window -h
+tmux send-keys 'tail -f ~/.config/opencode/logs/opencode.log' Enter
+
+# Switch back to main pane
+tmux select-pane -L
+```
+
+### Custom Layouts
+
+Create custom pane arrangements:
+
+```bash
+# In tmux, create a 3-pane layout
+tmux split-window -h
+tmux split-window -v
+tmux select-pane -L
+
+# Save the layout
+tmux save-buffer ~/my-layout.txt
+
+# Restore later
+tmux load-buffer ~/my-layout.txt
+```
+
+---
+
+## Best Practices
+
+### Session Management
+- Use named sessions for different projects
+- Detach when not actively monitoring
+- Clean up unused sessions periodically
+
+### Performance
+- Use `main-vertical` or `main-horizontal` layouts for better focus
+- Adjust `main_pane_size` based on your screen resolution
+- Limit parallel agent operations for complex tasks
+
+### Development Workflow
+1. Start tmux session for your project
+2. Launch OpenCode with tmux integration enabled
+3. Monitor agent activities as they work
+4. Detach when done, reattach to check progress
+5. Clean up panes after completing work
+
+### Debugging
+- Use `Ctrl+B z` to zoom into specific panes
+- Check logs when agents aren't responding
+- Verify port configuration when switching between projects
+
+---
+
+## Additional Resources
+
+- **Official Tmux Documentation:** https://github.com/tmux/tmux/wiki
+- **Quick Reference:** [docs/quick-reference.md#tmux-integration](quick-reference.md#tmux-integration)
+- **Background Tasks:** [docs/quick-reference.md#background-tasks](quick-reference.md#background-tasks)
+- **OpenCode Documentation:** https://opencode.ai/docs