opencode-multi-model

Launch multiple AI models in tmux sessions. Available as:

• OpenCode Plugin
• Standalone CLI
• Project-level tool

Installation

As OpenCode Plugin

Add to your OpenCode config (opencode.json):

{
  "plugin": ["opencode-multi-model"]
}

As Standalone CLI

# Using bunx (no install)
bunx opencode-multi-model open my-session -m openai/gpt-5.2 anthropic/claude-3-5-sonnet

# Or install globally
bun install -g opencode-multi-model
opencode-multi-model open my-session -m openai/gpt-5.2

As Project Tool

If you installed it via bun and want to use it as a project tool, import it from the package:

// .opencode/tools/multi-model.ts
import { openTool as open, closeTool as close } from "opencode-multi-model"
export { open, close }

If you are developing this package locally and want to test it in a project without publishing, import via relative paths:

// .opencode/tools/multi-model.ts
import { openTool } from "../../src/tools/open"
import { closeTool } from "../../src/tools/close"
export { openTool as open, closeTool as close }

Usage

Plugin Usage

Open a session:

Use multi-model-open tool:
sessionName: my-session, models: ["openai/gpt-5.2", "anthropic/claude-3-5-sonnet"]

Close a session (using tool):

call tool multi-model-close with sessionName: my-session

Cleanup archive tags (using tool):

call tool multi-model-cleanup

Close a session (using manual command):

tmux kill-session -t my-session && rm -rf ~/.local/share/opencode/multi-model/my-session && git worktree prune && git branch -D $(git branch --format='%(refname:short)' --list 'opencode/my-session/*')

CLI Usage

Open a session:

# Basic usage
opencode-multi-model open my-session -m openai/gpt-5.2 anthropic/claude-3-5-sonnet

# With custom binary (via flag)
opencode-multi-model open my-session -m openai/gpt-5.2 -b kilo

# With custom binary (via env)
export OPENCODE_MULTI_MODEL_BINARY=kilo
opencode-multi-model open my-session -m openai/gpt-5.2

Close a session (CLI command):

# Close and cleanup worktrees
opencode-multi-model close my-session

Cleanup archive tags (CLI command):

# Delete all archive tags from local and remote repositories
opencode-multi-model cleanup

# Delete all archive tags without confirmation prompts
opencode-multi-model cleanup --force

# Delete only local archive tags, skip remote deletion
opencode-multi-model cleanup --no-remote

# Delete archive tags and push deletions to a specific remote
opencode-multi-model cleanup --remote origin

Close a session (manual command):

tmux kill-session -t my-session && rm -rf ~/.local/share/opencode/multi-model/my-session && git worktree prune && git branch -D $(git branch --format='%(refname:short)' --list 'opencode/my-session/*')

Help:

opencode-multi-model --help
opencode-multi-model open --help
opencode-multi-model close --help
opencode-multi-model cleanup --help

Configuration

Custom Binary

By default uses opencode. To use kilo instead:

Via environment variable:

export OPENCODE_MULTI_MODEL_BINARY=kilo

Via CLI flag:

opencode-multi-model open my-session -m openai/gpt-5.2 -b kilo

Priority: CLI flag > Environment variable > Default ("opencode")

CLI Reference

open - Create a new multi-model tmux session

opencode-multi-model open <session-name> [options]

Arguments:

• <session-name> - Name for the tmux session (required)

Options: | Option | Description | |--------|-------------| | -m, --models <models...> | Model IDs to launch (space-separated) | | -b, --binary <binary> | Binary to use (opencode or kilo). Defaults to env var OPENCODE_MULTI_MODEL_BINARY or 'opencode' |

close - Close a multi-model tmux session

opencode-multi-model close <session-name> [options]

Arguments:

• <session-name> - Name of the tmux session to close (required)

Options: | Option | Description | |--------|-------------| | --keep-worktrees | Do not remove worktrees and delete branches | | --no-tags | Do not create archive tags before deleting branches | | -f, --force | Skip confirmation prompts |

cleanup - Delete all archive tags from local and remote repositories

Archive tags have the format: archive/<branch-name>-<timestamp>. These are created by the close command to preserve branch state before deletion.

opencode-multi-model cleanup [options]

Options: | Option | Description | |--------|-------------| | -f, --force | Skip confirmation prompts | | -r, --remote <remote> | Remote name to push deletions to (default: first remote from git remote -v) | | --no-remote | Only delete local tags, skip remote |

Global Options

| Option | Description | |--------|-------------| | -h, --help | Display help information | | -V, --version | Display version number |

How it works

open command

The open command performs the following steps:

1. Validation: Checks that session name andmodels are provided, no duplicate models exist, and verifies git repo, tmux, and binary are available

2. Model verification: Validates models against opencode models output to ensure only valid model IDs are used

3. Git worktree creation: For each model, creates:

   • A git worktree at ~/.local/share/opencode/multi-model/<session>/<model>/
   • A branch named opencode/<session>/<model>

4. Tmux session: Creates a tmux session with one window per model, each window's working directory set to its corresponding worktree

5. Launch: Sends the launch command to each window to start the binary with the specified model

close command

The close command performs the following steps:

1. Kill tmux session: Terminates the tmux session if it exists

2. Worktree discovery: Finds all worktrees under ~/.local/share/opencode/multi-model/<session>/

3. Worktree cleanup (unless --keep-worktrees):

   • Removes each gitworktree
   • Creates an archive tag (unless --no-tags): archive/<branch>-<timestamp> for recovery
   • Deletes the associated branches

4. Directory cleanup: Removes the base session directory

cleanup command

The cleanup command performs the following steps:

1. Archive tag discovery: Finds all git tags matching the pattern archive/*

2. Local tag deletion: Deletes all archive tags from the local repository

3. Remote tag deletion (unless --no-remote):

   • Determines which remote to use (user-specified, first available, or skip)
   • Pushes tag deletions to the remote repository

4. Summary: Reports the number of tags deleted locally and remotely

Requirements

• tmux
• git
• opencode or kilo binary
• Bun runtime

Development

For local development and testing without publishing:

# Install dependencies
bun install

# Setup git hooks
bun run setup

# Build
bun run build

# Run tests
bun test

# Test CLI locally
bun dist/cli.js open test-session -m openai/gpt-5.2
bun dist/cli.js close test-session

Architecture

├── src/
│   ├── index.ts               # Plugin entry point
│   ├── cli.ts                 # CLI entry point
│   ├── types.ts               # Shared TypeScript types
│   ├── core/
│   │   ├── index.ts           # Core exports
│   │   ├── open.ts            # Launch session logic
│   │   ├── close.ts            # Close session logic
│   │   ├── cleanup.ts         # Cleanup archive tags logic
│   │   └── utils.ts           # Helper functions
│   └── tools/
│       ├── open.ts            # Open tool definition
│       ├── close.ts            # Close tool definition
│       └── cleanup.ts         # Cleanup tool definition
├── tests/
│   └── multi-model.test.ts    # Tests
├── package.json
├── tsconfig.json
└── README.md

Local code coverage

The test suite can generate a coverage report locally.

# Run tests with coverage (HTML report generated in ./coverage)
  npm run coverage   # or: bun run coverage
# Open the HTML report
 open coverage/index.html   # macOS

The coverage directory is ignored by Git but can be inspected to see which lines are exercised.

License

MIT