Opentmux

An OpenCode plugin that provides smart tmux integration for viewing agent execution in real-time. Automatically spawns panes, streams output, and manages your terminal workspace.

• Agent-Agnostic: Works with oh-my-opencode, omoc-slim, or vanilla OpenCode.
• Cross-Platform: Full support for macOS, Linux, and Windows (via PowerShell or WSL).

Note: The demo shows the "sisyphus" agent from oh-my-opencode, but this plugin supports ALL OpenCode subagents.

Installation

🤖 Let an LLM do it (Recommended)

Paste this into any LLM agent (OpenCode, Claude Code, Cursor, etc.):

Install the @jordonbc/opentmux plugin by following: https://raw.githubusercontent.com/Jordonbc/opentmux/main/README.md

Instructions for LLM Agents

To install this plugin, please perform the following steps for the user:

1. Install the NPM package globally:

npm install -g @jordonbc/opentmux ``` Note: This installer automatically configures the user's shell (Bash/Zsh/Fish/PowerShell) to use the smart wrapper.

1. Verify & Finalize:
   • Check if tmux is installed on the system. If not, advise the user to install it (e.g., brew install tmux, sudo apt install tmux, or winget install tmux).
   • Tell the user: "Installation complete! Please restart your terminal and run opencode once. The wrapper will set up the OpenCode integration automatically."
   • If the user wants a local checkout instead of npm, point them to docs/installation.md.

👤 For Humans (Manual)

1. Install via NPM:

npm install -g @jordonbc/opentmux ``` The installer automatically configures your shell to use the smart wrapper.

1. Run OpenCode: Restart your terminal and type opencode once. The wrapper handles the OpenCode integration automatically.

🛠️ Development

For contributors working on this plugin locally, see LOCAL_DEVELOPMENT.md for setup instructions.

✨ Features

• Automatic Tmux Pane Spawning: When any agent starts, automatically spawns a tmux pane
• Live Streaming: Each pane runs opencode attach to show real-time agent output
• Auto-Cleanup: Panes automatically close when agents complete
• Configurable Layout: Support multiple tmux layouts (main-vertical, tiled, etc.)
• Multi-Port Support: Automatically finds available ports (4096-4106) when running multiple instances
• Smart Wrapper: Automatically detects if you are in tmux; if not, launches a session for you.

⚙️ Configuration

You can customize behavior by creating ~/.config/opencode/opentmux.json:

{
  "enabled": true,
  "port": 4096,
  "layout": "main-vertical",
  "main_pane_size": 60,
  "auto_close": true
}

Option	Type	Default	Description
enabled	boolean	true	Enable/disable the plugin
port	number	4096	OpenCode server port
layout	string	"main-vertical"	Tmux layout: main-horizontal, main-vertical, tiled, etc.
main_pane_size	number	60	Size of main pane (20-80%)
auto_close	boolean	true	Auto-close panes when sessions complete

Logging

OpenTmux writes plugin logs to /tmp/opencode-agent-tmux.log.

Set OPENCODE_TMUX_LOG_LEVEL to control verbosity:

• off: disable plugin file logging
• error: only failures and unexpected conditions
• info: lifecycle events and errors (default)
• debug: verbose queue, polling, and tmux command tracing

❓ Troubleshooting

Panes Not Spawning

1. Verify you're inside tmux: echo $TMUX
2. Check tmux is installed: which tmux (or where tmux on Windows)
3. Check logs: cat /tmp/opentmux.log

Server Not Found

Make sure OpenCode is started with the --port flag matching your config (the wrapper does this automatically).

🗺️ Roadmap

The following features are planned for future releases:

• Glow Integration: Support for Glow to render markdown beautifully in spawned panes.
• Neovim Quick-Launch: Direct integration to launch Neovim at the agent's current working directory.
• Enhanced Customization: More options for pane positioning, colors, and persistent layouts.

📄 License

MIT

🙏 Acknowledgements

This project extracts and improves upon the tmux session management from oh-my-opencode-slim by alvinunreal.