Package Exports

@jordonbc/opentmux
@jordonbc/opentmux/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@jordonbc/opentmux) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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).

Opencode Agent Tmux Demo 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:

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.

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)

Install via NPM:

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

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

Verify you're inside tmux: echo $TMUX
Check tmux is installed: which tmux (or where tmux on Windows)
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.