From 3ac3153aa962b7eefa2a04164676eeab6a730f81 Mon Sep 17 00:00:00 2001
From: bendtherules <abhasbhattacharya2@gmail.com>
Date: Mon, 23 Mar 2026 12:01:37 +0530
Subject: [PATCH] docs: add AGENTS.md with project overview, build commands,
 and coding guidelines

---
 AGENTS.md | 152 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 152 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..e0322dc
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,152 @@
+# AGENTS.md
+
+## Project Overview
+
+opencode-multi-model is a Bun/TypeScript project that provides multi-model tmux session management for AI coding assistants. Works as an OpenCode plugin, standalone CLI, and project tool.
+
+Key features:
+- Launch multiple AI models in isolated tmux sessions
+- Git worktree management for each model session
+- Archive tag creation for session state preservation
+- Supports both OpenCode and Kilo binaries
+- Available as CLI tool, OpenCode plugin, or project-level import
+
+## Build, Lint, and Test Commands
+
+```bash
+# Install dependencies
+bun install
+
+# Build for production
+bun run build
+
+# 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
+- Example:
+  ```typescript
+  import * as fs from "node:fs";
+  import chalk from "chalk";
+  import type { MultiModelOptions } from "../types";
+  import { runCommand } from "./utils";
+  ```
+
+### JSDoc Comments
+
+- Use JSDoc for all exported functions
+- Include `@example`, `@param`, and `@returns` descriptions
+- Add inline comments for hard-to-understand code
+
+### Error Handling
+
+- Return result objects (e.g., `MultiModelResult`, `CommandResult`) with `success: boolean`
+- Include descriptive error messages prefixed with `Error:`
+- Provide actionable error messages (e.g., suggest valid models on failure)
+- 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
+- Wrap command execution in `runCommand()` utility
+- Never use single-character variable names
+
+### 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
+├── 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
+└── tools/
+    ├── open.ts       # OpenCode tool definition
+    ├── close.ts      # CloseCode tool definition
+    └── cleanup.ts    # Cleanup tool definition
+tests/
+├── open.test.ts
+├── close.test.ts
+├── cleanup.test.ts
+├── open_error.test.ts
+├── close_error.test.ts
+└── utils.test.ts
+```
+
+### 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
\ No newline at end of file