Basic impl with tmux

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

@@ -0,0 +1,119 @@
+---
+llm: openai/gpt-5.4
+status: 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:
+
+```ts
+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:
+
+```text
+Window name: gpt-5-4
+Launch command: opencode --model openai/gpt-5.4
+```
+
+
+## Example tool outline
+
+```ts
+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.