OpenTmux

The wrapper script ensures that the agent-tmux plugin can always spawn panes by guaranteeing that OpenCode is running inside a tmux environment. It uses the $TMUX environment variable to make this decision:

• If $TMUX is not set: The script executes tmux new-session "opencode --port 4096".
• If $TMUX is set: The script executes opencode --port 4096 directly.

The opencode-agent-tmux plugin provides real-time visibility into OpenCode agent execution by automatically managing tmux panes.

Workflow:

1. Detection: The TmuxSessionManager listens for the session.created event from OpenCode. It identifies agents by checking for a parentID.
2. Spawning: When an agent starts, the plugin automatically spawns a new tmux pane.
3. Streaming: The new pane executes opencode attach to stream the agent's output live.
4. Cleanup: Once the agent session is complete, the plugin automatically closes the associated tmux pane (if autoClose is enabled).

This plugin is agent-agnostic and works with any OpenCode agent (e.g., Sisyphus, Oracle, Explorer, Librarian) and any OpenCode distribution (oh-my-opencode, omoc-slim, or vanilla).

OpenTmux automatically handles multiple OpenCode instances running on different ports to prevent freezing and ensure Tmux panes spawn correctly for each instance's agents.

When you run opencode, the wrapper script performs the following logic:

1. Checks port 4096 (the default port).
2. If 4096 is in use, it sequentially tries ports 4097, 4098, 4099, up to 4106.
3. Finds the first available port and starts OpenCode there.
4. Sets the OPENCODE_PORT environment variable, which the plugin uses to identify the correct instance.

The plugin detects the active port using this priority order:

1. ctx.serverUrl (passed by OpenCode).
2. The OPENCODE_PORT environment variable.
3. The default http://localhost:4096.

The plugin provides real-time tmux integration for viewing OpenCode subagent execution. It operates using the following logic:

1. Initialization: The plugin's init() function loads the configuration and checks if the environment is running inside tmux.
2. Event Monitoring: The TmuxSessionManager subscribes to OpenCode session.created events.
3. Subagent Detection: It filters for sessions that possess a parentID property, identifying them as subagents rather than primary sessions.
4. Pane Spawning: For each detected subagent, it executes a tmux command to split the window and run opencode attach <serverUrl> --session <sessionId> in the new pane.
5. Lifecycle Management: The plugin monitors the session status and automatically closes the corresponding tmux pane when the session becomes idle.

Once installed, running the opencode command automatically manages your tmux environment:

• If you are not currently in a tmux session, it launches a new tmux session and starts OpenCode inside it.
• If you are already in a tmux session, it starts OpenCode normally within your current session.
• It automatically passes --port 4096 to OpenCode and enables the agent-tmux plugin functionality.

Alternatively, you can add the binary directory to your PATH and rename the wrapper to override the original opencode command.

1. Add the directory to your PATH in ~/.zshrc: export PATH="/Users/angansamadder/Code/opencode-agent-tmux/bin:$PATH"
2. Rename the opentmux binary to opencode within that directory to ensure the wrapper is called when you type opencode.

# Add to ~/.zshrc
export PATH="/Users/angansamadder/Code/opencode-agent-tmux/bin:$PATH"

# Rename the wrapper to 'opencode' (this overrides the real opencode command)
mv /Users/angansamadder/Code/opencode-agent-tmux/bin/opentmux \
   /Users/angansamadder/Code/opencode-agent-tmux/bin/opencode

To use OpenTmux, you must install the NPM package globally and then register it as a plugin in your OpenCode configuration. The installer automatically configures your shell (Bash, Zsh, Fish, or PowerShell) to use the smart wrapper.

Prerequisites:

• Ensure tmux is installed on your system (brew install tmux, sudo apt install tmux, or winget install tmux).
• An existing OpenCode installation.

# 1. Install the package globally
npm install -g opentmux

# 2. Add to your OpenCode config (~/.config/opencode/opencode.json)
# Ensure "opentmux" is in the plugin array

To install the plugin, build the project and run the provided installation script. The script builds the TypeScript code, creates the configuration file at ~/.config/opencode/opencode-subagent-tmux.json, and registers the plugin path in your OpenCode configuration (~/.config/opencode/opencode.json).

Prerequisites:

• You must be running inside a tmux session.
• OpenCode must be started with a --port flag that matches your plugin configuration (default is 4096).

Installation Steps:

cd ~/Code/opencode-subagent-tmux
bun install
bun run build
bun run install:plugin

While developing, use the following commands to manage the build and type-checking processes:

• Watch Mode: Automatically rebuilds the project when files change using tsup.
• Manual Build: Performs a standard build of the project.
• Type Checking: Runs TypeScript type checking to ensure code correctness.

# Watch mode
bun run dev

# Manual build
bun run build

# Type checking
bun run typecheck

To confirm that opentmux is correctly installed:

1. Start a new terminal session.
2. Run the opencode command. It should launch tmux automatically.
3. Inside OpenCode, run /help or check the logs to ensure the plugin is active.

The recommended way to install the OpenTmux wrapper is by adding an alias to your ~/.zshrc file. This allows you to use the opencode command to trigger the automatic tmux launching logic.

1. Add the alias to your ~/.zshrc: alias opencode='/Users/angansamadder/Code/opencode-agent-tmux/bin/opentmux'
2. Reload your shell configuration using source ~/.zshrc.

# OpenCode with automatic tmux launching
alias opencode='/Users/angansamadder/Code/opencode-agent-tmux/bin/opentmux'

source ~/.zshrc

To install the tmux integration plugin for OpenCode, follow these steps in order. This assumes you have bun installed on your system.

1. Navigate to the plugin directory.
2. Install the necessary dependencies.
3. Build the plugin from TypeScript.
4. Run the plugin installation script to register it with OpenCode.
5. Start a tmux session and launch OpenCode with the specified port.

# 1. Clone/Navigate to plugin directory
cd ~/Code/opencode-agent-tmux

# 2. Install dependencies
bun install

# 3. Build the plugin
bun run build

# 4. Install to OpenCode
bun run install:plugin

# 5. Start OpenCode with tmux support
tmux
opencode --port 4096