opencode-multi-model/README.md

# 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`):

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

### As Standalone CLI

```bash
# 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:

```typescript
// .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:

```typescript
// .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):**
```bash
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:**
```bash
# 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):**
```bash
# Close and cleanup worktrees
opencode-multi-model close my-session
```

**Cleanup archive tags (CLI command):**
```bash
# 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):**
```bash
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:**
```bash
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:**
```bash
export OPENCODE_MULTI_MODEL_BINARY=kilo
```

**Via CLI flag:**
```bash
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

```bash
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

```bash
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.

```bash
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:

```bash
# 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.

```bash
# 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