opencode-multi-model/.opencode/plans/archive/draft-multi-model.md

llm, status

llm	status
openai/gpt-5.4	done

Multi-model launcher plan

Goal

Create an OpenCode project-local custom tool that:

1. accepts a tmux session name plus one or more model names
2. validates that the required tools and arguments are present
3. validates each requested model against opencode models
4. creates one tmux session and one window per model
5. launches opencode --model <model> in each window
6. prints a reliable attach instruction for the user

The right OpenCode primitive for this is a project-local custom tool in .opencode/tools/, not a slash command. Custom tools support typed argument schemas and programmatic execution, which makes validation sturdier, faster, and less dependent on prompt following.

Recommended implementation shape

• File: .opencode/tools/multi-model.ts
• Tool name: multi-model
• Arguments:
  • sessionName: string
  • models?: string[]

Proposed tool behavior

The tool should do the following in order:

1. Verify sessionName exists and at least one model was supplied.
2. Verify tmux is installed with command -v tmux.
3. Verify opencode is installed with command -v opencode.
4. Run opencode models and build an allowlist of valid model ids.
5. Reject any requested model that is not in the allowlist.
6. Reject duplicate model ids in the same invocation.
7. Check whether tmux session sessionName already exists.
8. If a requested model is invalid, compute close matches from the allowlist and return a error message with instruction to fix the tool call.
9. If no models are provided, return error.
10. Create tmux session detached.
11. Create one window per validated model.
12. In each window, launch opencode --model <model>.
13. Return tmux attach -t <session-name>.
14. If any launch step fails after session creation, return exactly what succeeded and what failed.

Reliability and edge cases

Missing dependencies

• tmux not installed: abort before any work.
• opencode not installed or not on PATH: abort before any work.

Example:

const tmuxExists = await Bun.$`command -v tmux`.quiet().nothrow()

This is non-obvious because the tool should detect the environment first instead of failing halfway through tmux setup.

Suggested implementation notes

• Use shell-safe quoting for all user-provided values.
• Long model names may be truncated by tmux window naming: use a short sanitized label for the window name, but keep the full model id in the command.

Example:

Window name: gpt-5-4
Launch command: opencode --model openai/gpt-5.4

Example tool outline

import { tool } from "@opencode-ai/plugin"

export default tool({
  description: "Launch multiple OpenCode models in tmux",
  args: {
    sessionName: tool.schema.string().min(1),
    models: tool.schema.array(tool.schema.string().min(1)).min(1),
  },
  async execute(args, context) {
    // 1. verify tmux and opencode exist
    // 2. load valid models from `opencode models`
    // 3. reject invalid or duplicate models
    // 4. fail if session already exists
    // 5. create session and windows
    // 6. return structured success payload with attach command
    return "Use `tmux attach -t sessionName` to join session.";
  },
})

This example is intentionally minimal; the real implementation should return structured errors and partial-success details.

Return value

The tool should return freeform text.

For success - "Use tmux attach -t sessionName to join session."

For failures: "Error: Session already exists. Use a different sessionName.",

For invalid model name: "Error: Model name 'openai/gpt5.4' not found. Did you mean 'openai/gpt-5.4' or 'openai/gpt-5.4-mini'?",

For missing models array: "Error: Model names must not be empty."

Future ideas

1. Add a project-local plugin wrapper for logging, richer UI integration, or event hooks while keeping the tool as the execution engine.
2. Package the tool or plugin as an npm-distributed OpenCode plugin for reuse across multiple repositories and machines.