opencode-multi-model/AGENTS.md

# AGENTS.md

## Project Overview

opencode-multi-model is a Bun/TypeScript project that provides multi-model tmux session management for AI coding assistants. It allows running multiple AI models simultaneously in isolated tmux windows with separate git worktrees.

Available as three integration modes:
- **OpenCode Plugin**: Loaded via `opencode.json` plugin array
- **Standalone CLI**: Install globally and run `opencode-multi-model open <session> -m <models...>`
- **Project Tool**: Import core functions from `"opencode-multi-model/core"` for project-level commands (used during development).

Requires: tmux, git, opencode or kilo binary, Bun runtime.

## Build, Lint, and Test Commands

```bash
# Install dependencies
bun install

# Build for production
bun run build

# Run tests
bun test

# Run tests with coverage (HTML report in ./coverage)
bun run coverage
# Run a specific test by name
bun test --test-name-pattern "fails if session name is empty"

# TypeScript type checking
bun run typecheck

# Lint with Biome
bun run lint

# Auto-fix lint issues
bun run lint:fix

# Format code with Biome
bun run format

# Full quality check
bun run typecheck && bun run lint
```

## Code Style Guidelines

### General

- Use **TypeScript** with strict mode
- Use **Bun** as the runtime and package manager
- Use ESM modules (`"type": "module"` in package.json)
- Use `node:` prefix for Node.js built-ins

### Formatting (Biome)

- **Indent**: 2 spaces (not tabs)
- **Quote style**: Double quotes for JS strings
- **Semicolons**: Required
- Run `bun run format` to format files

### TypeScript Conventions

- Use `interface` for object shapes; avoid `type` aliases unless needed
- Use explicit return types on exported functions
- Avoid `any` when possible
- Use `noUncheckedIndexedAccess: true` and `noImplicitOverride: true` in tsconfig
- All types/interfaces go in `src/types.ts`

### Naming Conventions

- **Files**: kebab-case (`multi-model-open.ts`)
- **Functions**: camelCase (`openMultiModel`)
- **Types/Interfaces**: PascalCase (`MultiModelOptions`)
- **Constants**: UPPER_SNAKE_CASE (e.g., `MAX_SUGGESTIONS`)

### Imports

- Use `import type` for type-only imports
- Group imports: external packages, internal modules, types
- Biome automatically organizes imports

### Documentation

- Use JSDoc for all exported functions
- Include `@example`, `@param`, and `@returns` descriptions
- Add inline comments for hard-to-understand code
- Modify Readme.md, if implementation details have changed.

### Error Handling

- Return result objects (e.g., `MultiModelResult`, `CloseSessionResult`, `CleanupResult`) with `success: boolean`
- Include descriptive error messages prefixed with `Error:`
- Provide actionable error messages (e.g., suggest valid models on invalid model name)
- Use `chalk` for colored terminal output (red for errors, dim for secondary info, bold for primary info)

### Shell Commands

- Use `Bun.$` template tag for shell commands
- Always use `quiet().nothrow()` to capture output without throwing
- Wrap command execution in `runCommand()` utility from `core/utils.ts`
- Use `shellQuote()` for user-provided values in shell commands

### Testing

- Use `bun:test` framework
- Mock `Bun.$` using the `mock()` function from `bun:test`
- Use `spyOn()` for fs/os module mocking
- Group tests with `describe()` blocks
- Test file naming: `*.test.ts` in `tests/` directory

## Project Structure

```
src/
├── index.ts          # Plugin entry point (default export)
├── cli.ts            # CLI entry point (commander setup)
├── types.ts          # All TypeScript interfaces/types
├── core/
│   ├── index.ts      # Core exports
│   ├── open.ts       # Session launch logic
│   ├── close.ts      # Session close logic
│   ├── cleanup.ts    # Archive tag cleanup logic
│   └── utils.ts      # Shared utilities (runCommand, shellQuote, etc.)
└── tools/
    ├── open.ts       # OpenCode tool definition
    ├── close.ts      # CloseCode tool definition
    └── cleanup.ts    # Cleanup tool definition
tests/
├── open.test.ts         # Open command tests
├── close.test.ts        # Close command tests
├── cleanup.test.ts      # Cleanup command tests
├── open_error.test.ts   # Open error handling tests
├── close_error.test.ts  # Close error handling tests
└── utils.test.ts        # Utility function tests
```

### Git Branch and Tag Naming

- Session branches: `opencode/<session-name>/<window-name>`
- Archive tags: `archive/<branch-name>-<timestamp>` (created by close command)
- Worktrees: `~/.local/share/opencode/multi-model/<session>/<window>/`

### Common Pitfalls

- Tmux session names use raw input; git branches/paths use sanitized names
- Window names must be unique; collisions get numeric suffixes (e.g., `gpt-5-2`, `gpt-5-2-2`)
- Window names are truncated to 24 characters to fit tmux limits
- Worktree paths are checked for existence before creation to avoid conflicts
- Archive tags preserve branch state before deletion for recovery