opencode-multi-model/.opencode/plans/1773495986494-brave-wizard.md

---
model: minimax-m2.5-free
---

# Plan: Package multi-model tool as npm OpenCode Plugin

## Overview

Convert the existing `.opencode/tools/multi-model.ts` into a sharable npm package that users can install and configure. The tool will be packaged as an **OpenCode Plugin** that exposes the multi-model tool functionality.

## Key Requirements

1. **Package as OpenCode Plugin** - Users install via `"plugin"` field in config
2. **Custom npm scope** - Package name will be user-defined (e.g., `@username/opencode-multi-model`)
3. **Configurable binary** - Support both `opencode` and `kilo` binaries via environment variable/config

## Architecture

### Current State
- Tool lives in `.opencode/tools/multi-model.ts`
- Uses `@opencode-ai/plugin` to define custom tool
- Already has comprehensive tests in `.opencode/multi-model.test.ts`

### Target State
```
├── src/
│   ├── index.ts               # Plugin entry point
│   └── multi-model.ts         # Tool definition (refactored)
├── tests/
│   └── multi-model.test.ts    # Tests (refactored from existing)
├── package.json               # NPM package config
├── tsconfig.json              # TypeScript config
├── README.md                  # Documentation
└── LICENSE                    # License
```

## Implementation Steps

### 1. Create Plugin Structure

Create new package with proper TypeScript configuration:

```json
// package.json
{
  "name": "@username/opencode-multi-model",
  "version": "1.0.0",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  },
  "dependencies": {
    "@opencode-ai/plugin": "^1.2.26",
  },
  "devDependencies": {
    "bun-types": "^1.0.0",
    "typescript": "^5.0.0"
  }
}
```

### 2. Refactor Tool for Plugin Export

The tool definition stays similar but needs env-based binary configuration:

```typescript
// src/multi-model.ts
import { tool, type ToolContext } from "@opencode-ai/plugin"

// Make binary name configurable via environment variable
function getBinaryName(context: ToolContext): string {
  // Users set OPENCODE_MULTI_MODEL_BINARY=kilo or OPENCODE_MULTI_MODEL_BINARY=opencode
  return process.env.OPENCODE_MULTI_MODEL_BINARY || "opencode"
}

export const multiModelTool = tool({
  description: "Launch multiple OpenCode models in tmux",
  args: {
    sessionName: tool.schema.string().min(1).describe("tmux session name to create"),
    models: tool.schema
      .array(tool.schema.string().min(1))
      .min(1)
      .describe("one or more OpenCode model ids to launch"),
  },
  async execute(args, context) {
    const binaryName = getBinaryName(context)
    // ... use binaryName instead of hardcoded "opencode"
  }
})
```

### 3. Create Plugin Entry Point

```typescript
// src/index.ts
import type { Plugin } from "@opencode-ai/plugin"
import { multiModelTool } from "./multi-model"

export const OpenCodeMultiModelPlugin: Plugin = async (ctx) => {
  return {
    tool: {
      "multi-model": multiModelTool,
    },
  }
}

export default OpenCodeMultiModelPlugin
export { multiModelTool }
```

### 4. Add Build Configuration

```json
// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "declaration": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "skipLibCheck": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
```

### 5. Add Build Script and Tests

```json
// package.json scripts
{
  "scripts": {
    "build": "bun build src/index.ts --outdir dist --target bun --format esm",
    "test": "bun test",
    "prepublishOnly": "bun run build"
  }
}
```

**Tests**: Copy `.opencode/multi-model.test.ts` to `tests/multi-model.test.ts` and update imports:
- Change `import multiModelTool, { __testing_helpers } from "./tools/multi-model"` 
- To `import multiModelTool, { __testing_helpers } from "../src/multi-model"`

The existing tests should work with minimal changes since the tool API remains the same.

### 6. Create README with Usage Instructions

```markdown
# opencode-multi-model

Plugin for OpenCode that enables launching multiple AI models in tmux sessions.

## Installation

Add to your OpenCode config (`opencode.json`):

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

## Usage

```
Use multi-model tool to launch multiple models:
sessionName: my-session, models: ["openai/gpt-4o", "anthropic/claude-3-5-sonnet"]
```

## Configuration

### Custom Binary

By default uses `opencode`. To use `kilo` instead, set environment variable:

```json
{
  "plugin": ["@username/opencode-multi-model"],
  "env": {
    "OPENCODE_MULTI_MODEL_BINARY": "kilo"
  }
}
```

## Requirements

- tmux
- git
- opencode or kilo binary


## Files to Create/Modify

### New Files
- `package.json` - NPM package configuration
- `tsconfig.json` - TypeScript configuration
- `src/index.ts` - Plugin entry point
- `src/multi-model.ts` - Refactored tool with configurable binary
- `tests/multi-model.test.ts` - Tests (copy from `.opencode/multi-model.test.ts`)
- `README.md` - Installation and usage docs
- `LICENSE` - License file

### Delete
- Delete `.opencode/tools/multi-model.ts` after refactoring to new package
- Delete `.opencode/multi-model.test.ts` after copying to new package


## Verification

1. **Build**: Run `bun run build` to compile TypeScript
2. **Test**: Run `bun test` in the new package directory
3. **Local Test**: 
   - Link package locally with `bun link`
   - Add to test project config
   - Verify tool works
4. **Publish**: Run `npm publish --access public` (or `bun publish`)

## Usage for End Users

After publishing, users will:

1. Install package:
```bash
npm install -D @username/opencode-multi-model
```

2. Add to config:
```json
{
  "plugin": ["@username/opencode-multi-model"]
}
```

3. Use the tool:
```
Use tool multi-model with sessionName "testing" with models opencode/mimo-v2-flash-free and opencode/minimax-m2.5-free
```