elias/oh-my-opencode
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: regenerate all AGENTS.md files with updated structure

Browse Source
This commit is contained in:
justsisyphus 2026-01-23 02:14:08 +09:00
parent 0e18efc7e4
commit 7de376e24f
9 changed files with 257 additions and 395 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

171
AGENTS.md
View File

@ -1,28 +1,28 @@
# PROJECT KNOWLEDGE BASE # PROJECT KNOWLEDGE BASE
**Generated:** 2026-01-22T22:25:00+09:00 **Generated:** 2026-01-23T02:09:00+09:00
**Commit:** 85bf266f **Commit:** 0e18efc7
**Branch:** dev **Branch:** dev
## OVERVIEW ## OVERVIEW
OpenCode plugin implementing multi-model agent orchestration (Claude Opus 4.5, GPT-5.2, Gemini 3, Grok, GLM-4.7). 31 lifecycle hooks, 20+ tools (LSP, AST-Grep, delegation), 10 specialized agents, Claude Code compatibility layer. "oh-my-zsh" for OpenCode. OpenCode plugin: multi-model agent orchestration (Claude Opus 4.5, GPT-5.2, Gemini 3, Grok, GLM-4.7). 31 lifecycle hooks, 20+ tools (LSP, AST-Grep, delegation), 10 specialized agents, full Claude Code compatibility. "oh-my-zsh" for OpenCode.
## STRUCTURE ## STRUCTURE
``` ```
oh-my-opencode/ oh-my-opencode/
├── src/ ├── src/
│ ├── agents/ # 10 AI agents (Sisyphus, oracle, librarian, explore, etc.) - see src/agents/AGENTS.md │ ├── agents/ # 10 AI agents - see src/agents/AGENTS.md
│ ├── hooks/ # 31 lifecycle hooks (PreToolUse, PostToolUse, Stop, etc.) - see src/hooks/AGENTS.md │ ├── hooks/ # 31 lifecycle hooks - see src/hooks/AGENTS.md
│ ├── tools/ # 20+ tools (LSP, AST-Grep, delegation, session) - see src/tools/AGENTS.md │ ├── tools/ # 20+ tools - see src/tools/AGENTS.md
│ ├── features/ # Background agents, Claude Code compat layer - see src/features/AGENTS.md │ ├── features/ # Background agents, Claude Code compat - see src/features/AGENTS.md
│ ├── shared/ # 50 cross-cutting utilities - see src/shared/AGENTS.md │ ├── shared/ # 50 cross-cutting utilities - see src/shared/AGENTS.md
│ ├── cli/ # CLI installer, doctor, run - see src/cli/AGENTS.md │ ├── cli/ # CLI installer, doctor - see src/cli/AGENTS.md
│ ├── mcp/ # Built-in MCPs: websearch, context7, grep_app - see src/mcp/AGENTS.md │ ├── mcp/ # Built-in MCPs - see src/mcp/AGENTS.md
│ ├── config/ # Zod schema, TypeScript types │ ├── config/ # Zod schema, TypeScript types
│ └── index.ts # Main plugin entry (589 lines) │ └── index.ts # Main plugin entry (590 lines)
├── script/ # build-schema.ts, publish.ts, build-binaries.ts ├── script/ # build-schema.ts, build-binaries.ts
├── packages/ # 7 platform-specific binaries ├── packages/ # 7 platform-specific binaries
└── dist/ # Build output (ESM + .d.ts) └── dist/ # Build output (ESM + .d.ts)
``` ```
@ -31,88 +31,67 @@ oh-my-opencode/
| Task | Location | Notes | | Task | Location | Notes |
|------|----------|-------| |------|----------|-------|
| Add agent | `src/agents/` | Create .ts with factory, add to `builtinAgents` in index.ts | | Add agent | `src/agents/` | Create .ts with factory, add to `agentSources` |
| Add hook | `src/hooks/` | Create dir with `createXXXHook()`, register in index.ts | | Add hook | `src/hooks/` | Create dir with `createXXXHook()`, register in index.ts |
| Add tool | `src/tools/` | Dir with index/types/constants/tools.ts, add to `builtinTools` | | Add tool | `src/tools/` | Dir with index/types/constants/tools.ts |
| Add MCP | `src/mcp/` | Create config, add to index.ts | | Add MCP | `src/mcp/` | Create config, add to index.ts |
| Add skill | `src/features/builtin-skills/` | Create dir with SKILL.md | | Add skill | `src/features/builtin-skills/` | Create dir with SKILL.md |
| LSP behavior | `src/tools/lsp/` | client.ts (connection), tools.ts (handlers) | | Config schema | `src/config/schema.ts` | Zod schema, run `bun run build:schema` |
| AST-Grep | `src/tools/ast-grep/` | napi.ts for @ast-grep/napi binding | | Background agents | `src/features/background-agent/` | manager.ts (1335 lines) |
| Config schema | `src/config/schema.ts` | Zod schema, run `bun run build:schema` after changes | | Orchestrator | `src/hooks/atlas/` | Main orchestration hook (771 lines) |
| Claude Code compat | `src/features/claude-code-*-loader/` | Command, skill, agent, mcp loaders |
| Background agents | `src/features/background-agent/` | manager.ts (1335 lines) for task lifecycle |
| Skill MCP | `src/features/skill-mcp-manager/` | MCP servers embedded in skills |
| CLI installer | `src/cli/install.ts` | Interactive TUI (520 lines) |
| Doctor checks | `src/cli/doctor/checks/` | 14 health checks across 6 categories |
| Orchestrator hook | `src/hooks/atlas/` | Main orchestration hook (771 lines) |
## TDD (Test-Driven Development) ## TDD (Test-Driven Development)
**MANDATORY for new features and bug fixes.** Follow RED-GREEN-REFACTOR: **MANDATORY.** RED-GREEN-REFACTOR:
1. **RED**: Write test → `bun test` → FAIL
| Phase | Action | Verification | 2. **GREEN**: Implement minimum → PASS
|-------|--------|--------------| 3. **REFACTOR**: Clean up → stay GREEN
| **RED** | Write test describing expected behavior | `bun test` → FAIL (expected) |
| **GREEN** | Implement minimum code to pass | `bun test` → PASS |
| **REFACTOR** | Improve code quality, remove duplication | `bun test` → PASS (must stay green) |
**Rules:** **Rules:**
- NEVER write implementation before test - NEVER write implementation before test
- NEVER delete failing tests to "pass" - fix the code - NEVER delete failing tests - fix the code
- Test file naming: `*.test.ts` alongside source - Test file: `*.test.ts` alongside source
- BDD comments: `#given`, `#when`, `#then` (same as AAA) - BDD comments: `#given`, `#when`, `#then`
## CONVENTIONS ## CONVENTIONS
- **Package manager**: Bun only (`bun run`, `bun build`, `bunx`) - **Package manager**: Bun only (`bun run`, `bun build`, `bunx`)
- **Types**: bun-types (not @types/node) - **Types**: bun-types (NEVER @types/node)
- **Build**: `bun build` (ESM) + `tsc --emitDeclarationOnly` - **Build**: `bun build` (ESM) + `tsc --emitDeclarationOnly`
- **Exports**: Barrel pattern in index.ts; explicit named exports - **Exports**: Barrel pattern via index.ts
- **Naming**: kebab-case directories, `createXXXHook`/`createXXXTool` factories - **Naming**: kebab-case dirs, `createXXXHook`/`createXXXTool` factories
- **Testing**: BDD comments `#given/#when/#then`, 83 test files - **Testing**: BDD comments, 90 test files
- **Temperature**: 0.1 for code agents, max 0.3 - **Temperature**: 0.1 for code agents, max 0.3
## ANTI-PATTERNS (THIS PROJECT) ## ANTI-PATTERNS
| Category | Forbidden | | Category | Forbidden |
|----------|-----------| |----------|-----------|
| **Package Manager** | npm, yarn - use Bun exclusively | | Package Manager | npm, yarn - Bun exclusively |
| **Types** | @types/node - use bun-types | | Types | @types/node - use bun-types |
| **File Ops** | mkdir/touch/rm/cp/mv in code - agents use bash tool | | File Ops | mkdir/touch/rm/cp/mv in code - use bash tool |
| **Publishing** | Direct `bun publish` - use GitHub Actions workflow_dispatch | | Publishing | Direct `bun publish` - GitHub Actions only |
| **Versioning** | Local version bump - managed by CI | | Versioning | Local version bump - CI manages |
| **Date References** | Year 2024 - use current year | | Type Safety | `as any`, `@ts-ignore`, `@ts-expect-error` |
| **Type Safety** | `as any`, `@ts-ignore`, `@ts-expect-error` | | Error Handling | Empty catch blocks |
| **Error Handling** | Empty catch blocks `catch(e) {}` | | Testing | Deleting failing tests |
| **Testing** | Deleting failing tests to "pass" | | Agent Calls | Sequential - use `delegate_task` parallel |
| **Agent Calls** | Sequential agent calls - use `delegate_task` for parallel | | Hook Logic | Heavy PreToolUse - slows every call |
| **Tool Access** | Broad tool access - prefer explicit `include` | | Commits | Giant (3+ files), separate test from impl |
| **Hook Logic** | Heavy PreToolUse computation - slows every tool call | | Temperature | >0.3 for code agents |
| **Commits** | Giant commits (3+ files = 2+ commits), separate test from impl | | Trust | Agent self-reports - ALWAYS verify |
| **Temperature** | >0.3 for code agents |
| **Trust** | Trust agent self-reports - ALWAYS verify independently |
## UNIQUE STYLES
- **Platform**: Union type `"darwin" | "linux" | "win32" | "unsupported"`
- **Optional props**: Extensive `?` for optional interface properties
- **Flexible objects**: `Record<string, unknown>` for dynamic configs
- **Agent tools**: `tools: { include: [...] }` or `tools: { exclude: [...] }`
- **Hook naming**: `createXXXHook` function convention
- **Factory pattern**: Components created via `createXXX()` functions
## AGENT MODELS ## AGENT MODELS
| Agent | Default Model | Purpose | | Agent | Model | Purpose |
|-------|---------------|---------| |-------|-------|---------|
| Sisyphus | anthropic/claude-opus-4-5 | Primary orchestrator with extended thinking | | Sisyphus | anthropic/claude-opus-4-5 | Primary orchestrator |
| oracle | openai/gpt-5.2 | Read-only consultation, high-IQ debugging | | Atlas | anthropic/claude-opus-4-5 | Master orchestrator |
| librarian | opencode/glm-4.7-free | Multi-repo analysis, docs, GitHub search | | oracle | openai/gpt-5.2 | Consultation, debugging |
| explore | opencode/grok-code | Fast codebase exploration (contextual grep) | | librarian | opencode/glm-4.7-free | Docs, GitHub search |
| explore | opencode/grok-code | Fast codebase grep |
| multimodal-looker | google/gemini-3-flash | PDF/image analysis | | multimodal-looker | google/gemini-3-flash | PDF/image analysis |
| Prometheus (Planner) | anthropic/claude-opus-4-5 | Strategic planning, interview mode | | Prometheus | anthropic/claude-opus-4-5 | Strategic planning |
| Metis (Plan Consultant) | anthropic/claude-sonnet-4-5 | Pre-planning analysis |
| Momus (Plan Reviewer) | anthropic/claude-sonnet-4-5 | Plan validation |
## COMMANDS ## COMMANDS
@ -120,60 +99,42 @@ oh-my-opencode/
bun run typecheck # Type check bun run typecheck # Type check
bun run build # ESM + declarations + schema bun run build # ESM + declarations + schema
bun run rebuild # Clean + Build bun run rebuild # Clean + Build
bun run build:schema # Schema only bun test # 90 test files
bun test # Run tests (83 test files)
``` ```
## DEPLOYMENT ## DEPLOYMENT
**GitHub Actions workflow_dispatch only** **GitHub Actions workflow_dispatch ONLY**
1. Commit & push changes
1. Never modify package.json version locally 2. Trigger: `gh workflow run publish -f bump=patch`
2. Commit & push changes 3. Never `bun publish` directly, never bump version locally
3. Trigger `publish` workflow: `gh workflow run publish -f bump=patch`
**Critical**: Never `bun publish` directly. Never bump version locally.
## CI PIPELINE
- **ci.yml**: Parallel test/typecheck → build → auto-commit schema on master → rolling `next` draft release
- **publish.yml**: Manual workflow_dispatch → version bump → changelog → 8-package OIDC npm publish → force-push master
## COMPLEXITY HOTSPOTS ## COMPLEXITY HOTSPOTS
| File | Lines | Description | | File | Lines | Description |
|------|-------|-------------| |------|-------|-------------|
| `src/agents/atlas.ts` | 1383 | Orchestrator agent, 7-section delegation, wisdom accumulation | | `src/agents/atlas.ts` | 1383 | Orchestrator, 7-section delegation |
| `src/features/background-agent/manager.ts` | 1335 | Task lifecycle, concurrency, notification batching | | `src/features/background-agent/manager.ts` | 1335 | Task lifecycle, concurrency |
| `src/features/builtin-skills/skills.ts` | 1203 | Skill definitions (playwright, git-master, frontend-ui-ux) | | `src/features/builtin-skills/skills.ts` | 1203 | Skill definitions |
| `src/agents/prometheus-prompt.ts` | 1196 | Planning agent, interview mode, Momus loop | | `src/agents/prometheus-prompt.ts` | 1196 | Planning agent |
| `src/tools/delegate-task/tools.ts` | 1027 | Category-based task delegation | | `src/tools/delegate-task/tools.ts` | 1038 | Category-based delegation |
| `src/hooks/atlas/index.ts` | 771 | Orchestrator hook implementation | | `src/hooks/atlas/index.ts` | 771 | Orchestrator hook |
| `src/cli/config-manager.ts` | 641 | JSONC parsing, multi-level config |
| `src/features/builtin-commands/templates/refactor.ts` | 619 | Refactoring command template |
| `src/agents/sisyphus.ts` | 615 | Main Sisyphus prompt |
| `src/tools/lsp/client.ts` | 596 | LSP protocol, JSON-RPC |
## MCP ARCHITECTURE ## MCP ARCHITECTURE
Three-tier MCP system: Three-tier system:
1. **Built-in**: `websearch` (Exa), `context7` (docs), `grep_app` (GitHub search) 1. **Built-in**: websearch (Exa), context7 (docs), grep_app (GitHub)
2. **Claude Code compatible**: `.mcp.json` files with `${VAR}` expansion 2. **Claude Code compat**: .mcp.json with `${VAR}` expansion
3. **Skill-embedded**: YAML frontmatter in skills (e.g., playwright) 3. **Skill-embedded**: YAML frontmatter in skills
## CONFIG SYSTEM ## CONFIG SYSTEM
- **Zod validation**: `src/config/schema.ts` - **Zod validation**: `src/config/schema.ts`
- **JSONC support**: Comments and trailing commas - **JSONC support**: Comments, trailing commas
- **Multi-level**: Project (`.opencode/`) → User (`~/.config/opencode/`) - **Multi-level**: Project (`.opencode/`) → User (`~/.config/opencode/`)
- **CLI doctor**: Validates config and reports errors
## NOTES ## NOTES
- **Testing**: Bun native test (`bun test`), BDD-style, 83 test files
- **OpenCode**: Requires >= 1.0.150 - **OpenCode**: Requires >= 1.0.150
- **Multi-lang docs**: README.md (EN), README.ko.md (KO), README.ja.md (JA), README.zh-cn.md (ZH-CN) - **Flaky tests**: ralph-loop (CI timeout), session-state (parallel pollution)
- **Config**: `~/.config/opencode/oh-my-opencode.json` (user) or `.opencode/oh-my-opencode.json` (project)
- **Trusted deps**: @ast-grep/cli, @ast-grep/napi, @code-yeongyu/comment-checker - **Trusted deps**: @ast-grep/cli, @ast-grep/napi, @code-yeongyu/comment-checker
- **Claude Code Compat**: Full compatibility layer for settings.json hooks, commands, skills, agents, MCPs
- **Flaky tests**: 2 known flaky tests (ralph-loop CI timeout, session-state parallel pollution)

38
src/agents/AGENTS.md
View File

@ -8,17 +8,17 @@
``` ```
agents/ agents/
├── atlas.ts # Master Orchestrator (1383 lines) - 7-phase delegation ├── atlas.ts # Master Orchestrator (1383 lines)
├── sisyphus.ts # Main prompt (615 lines) ├── sisyphus.ts # Main prompt (615 lines)
├── sisyphus-junior.ts # Delegated task executor (136 lines) ├── sisyphus-junior.ts # Delegated task executor
├── dynamic-agent-prompt-builder.ts # Dynamic prompt generation (360 lines) ├── dynamic-agent-prompt-builder.ts # Dynamic prompt generation
├── oracle.ts # Strategic advisor (GPT-5.2) ├── oracle.ts # Strategic advisor (GPT-5.2)
├── librarian.ts # Multi-repo research (GLM-4.7-free) ├── librarian.ts # Multi-repo research (GLM-4.7-free)
├── explore.ts # Fast grep (Grok Code) ├── explore.ts # Fast grep (Grok Code)
├── multimodal-looker.ts # Media analyzer (Gemini 3 Flash) ├── multimodal-looker.ts # Media analyzer (Gemini 3 Flash)
├── prometheus-prompt.ts # Planning (1196 lines) - interview mode ├── prometheus-prompt.ts # Planning (1196 lines)
├── metis.ts # Plan consultant - pre-planning analysis ├── metis.ts # Plan consultant
├── momus.ts # Plan reviewer - validation ├── momus.ts # Plan reviewer
├── types.ts # AgentModelConfig, AgentPromptMetadata ├── types.ts # AgentModelConfig, AgentPromptMetadata
├── utils.ts # createBuiltinAgents(), resolveModelWithFallback() ├── utils.ts # createBuiltinAgents(), resolveModelWithFallback()
└── index.ts # builtinAgents export └── index.ts # builtinAgents export
@ -26,16 +26,16 @@ agents/
## AGENT MODELS ## AGENT MODELS
| Agent | Model | Temperature | Purpose | | Agent | Model | Temp | Purpose |
|-------|-------|-------------|---------| |-------|-------|------|---------|
| Sisyphus | anthropic/claude-opus-4-5 | 0.1 | Primary orchestrator, todo-driven | | Sisyphus | anthropic/claude-opus-4-5 | 0.1 | Primary orchestrator |
| Atlas | anthropic/claude-opus-4-5 | 0.1 | Master orchestrator, delegate_task | | Atlas | anthropic/claude-opus-4-5 | 0.1 | Master orchestrator |
| oracle | openai/gpt-5.2 | 0.1 | Read-only consultation, debugging | | oracle | openai/gpt-5.2 | 0.1 | Consultation, debugging |
| librarian | opencode/glm-4.7-free | 0.1 | Docs, GitHub search, OSS examples | | librarian | opencode/glm-4.7-free | 0.1 | Docs, GitHub search |
| explore | opencode/grok-code | 0.1 | Fast contextual grep | | explore | opencode/grok-code | 0.1 | Fast contextual grep |
| multimodal-looker | google/gemini-3-flash | 0.1 | PDF/image analysis | | multimodal-looker | google/gemini-3-flash | 0.1 | PDF/image analysis |
| Prometheus | anthropic/claude-opus-4-5 | 0.1 | Strategic planning, interview mode | | Prometheus | anthropic/claude-opus-4-5 | 0.1 | Strategic planning |
| Metis | anthropic/claude-sonnet-4-5 | 0.3 | Pre-planning gap analysis | | Metis | anthropic/claude-sonnet-4-5 | 0.3 | Pre-planning analysis |
| Momus | anthropic/claude-sonnet-4-5 | 0.1 | Plan validation | | Momus | anthropic/claude-sonnet-4-5 | 0.1 | Plan validation |
| Sisyphus-Junior | anthropic/claude-sonnet-4-5 | 0.1 | Category-spawned executor | | Sisyphus-Junior | anthropic/claude-sonnet-4-5 | 0.1 | Category-spawned executor |
@ -54,19 +54,17 @@ agents/
| librarian | write, edit, task, delegate_task, call_omo_agent | | librarian | write, edit, task, delegate_task, call_omo_agent |
| explore | write, edit, task, delegate_task, call_omo_agent | | explore | write, edit, task, delegate_task, call_omo_agent |
| multimodal-looker | Allowlist: read only | | multimodal-looker | Allowlist: read only |
| Sisyphus-Junior | task, delegate_task (cannot spawn implementation agents) | | Sisyphus-Junior | task, delegate_task |
## KEY PATTERNS ## PATTERNS
- **Factory**: `createXXXAgent(model?: string): AgentConfig` - **Factory**: `createXXXAgent(model?: string): AgentConfig`
- **Metadata**: `XXX_PROMPT_METADATA: AgentPromptMetadata` with category, cost, triggers - **Metadata**: `XXX_PROMPT_METADATA` with category, cost, triggers
- **Tool restrictions**: `createAgentToolRestrictions(tools)` or `createAgentToolAllowlist(tools)` - **Tool restrictions**: `createAgentToolRestrictions(tools)` or `createAgentToolAllowlist(tools)`
- **Thinking**: 32k budget tokens for Sisyphus, Oracle, Prometheus, Atlas - **Thinking**: 32k budget tokens for Sisyphus, Oracle, Prometheus, Atlas
- **Model-specific**: GPT uses `reasoningEffort`, Anthropic uses `thinking` budget
## ANTI-PATTERNS ## ANTI-PATTERNS
- **Trust reports**: NEVER trust subagent "I'm done" - verify outputs - **Trust reports**: NEVER trust "I'm done" - verify outputs
- **High temp**: Don't use >0.3 for code agents - **High temp**: Don't use >0.3 for code agents
- **Sequential calls**: Use `delegate_task` with `run_in_background` - **Sequential calls**: Use `delegate_task` with `run_in_background`
- **Missing metadata**: Every agent needs `XXX_PROMPT_METADATA` export

82
src/cli/AGENTS.md
View File

@ -2,90 +2,70 @@
## OVERVIEW ## OVERVIEW
CLI entry point: `bunx oh-my-opencode`. Interactive installer, doctor diagnostics, session runner. Uses Commander.js + @clack/prompts TUI. CLI entry: `bunx oh-my-opencode`. Interactive installer, doctor diagnostics. Commander.js + @clack/prompts.
## STRUCTURE ## STRUCTURE
``` ```
cli/ cli/
├── index.ts # Commander.js entry, 5 subcommands ├── index.ts # Commander.js entry
├── install.ts # Interactive TUI installer (520 lines) ├── install.ts # Interactive TUI (520 lines)
├── config-manager.ts # JSONC parsing, multi-level merge (641 lines) ├── config-manager.ts # JSONC parsing (641 lines)
├── types.ts # InstallArgs, InstallConfig, DetectedConfig ├── types.ts # InstallArgs, InstallConfig
├── doctor/ ├── doctor/
│ ├── index.ts # Doctor command entry │ ├── index.ts # Doctor entry
│ ├── runner.ts # Check orchestration │ ├── runner.ts # Check orchestration
│ ├── formatter.ts # Colored output, symbols │ ├── formatter.ts # Colored output
│ ├── constants.ts # Check IDs, categories, symbols │ ├── constants.ts # Check IDs, symbols
│ ├── types.ts # CheckResult, CheckDefinition │ ├── types.ts # CheckResult, CheckDefinition
│ └── checks/ # 14 checks across 6 categories (21 files) │ └── checks/ # 14 checks, 21 files
│ ├── version.ts # OpenCode + plugin version │ ├── version.ts # OpenCode + plugin version
│ ├── config.ts # JSONC validity, Zod validation │ ├── config.ts # JSONC validity, Zod
│ ├── auth.ts # Anthropic, OpenAI, Google │ ├── auth.ts # Anthropic, OpenAI, Google
│ ├── dependencies.ts # AST-Grep, Comment Checker │ ├── dependencies.ts # AST-Grep, Comment Checker
│ ├── lsp.ts # LSP server connectivity │ ├── lsp.ts # LSP connectivity
│ ├── mcp.ts # MCP server validation │ ├── mcp.ts # MCP validation
│ └── gh.ts # GitHub CLI availability │ └── gh.ts # GitHub CLI
├── run/ ├── run/
│ ├── index.ts # Run command entry │ └── index.ts # Session launcher
│ └── runner.ts # Session launcher
└── get-local-version/ └── get-local-version/
├── index.ts # Version detection └── index.ts # Version detection
└── formatter.ts # Version output
``` ```
## CLI COMMANDS ## COMMANDS
| Command | Purpose | | Command | Purpose |
|---------|---------| |---------|---------|
| `install` | Interactive setup, subscription detection | | `install` | Interactive setup |
| `doctor` | 14 health checks, `--verbose`, `--json`, `--category` | | `doctor` | 14 health checks |
| `run` | Launch OpenCode session with completion enforcement | | `run` | Launch session |
| `get-local-version` | Version detection, update checking | | `get-local-version` | Version check |
## DOCTOR CHECK CATEGORIES ## DOCTOR CATEGORIES
| Category | Checks | | Category | Checks |
|----------|--------| |----------|--------|
| installation | opencode, plugin registration | | installation | opencode, plugin |
| configuration | config validity, Zod validation | | configuration | config validity, Zod |
| authentication | anthropic, openai, google | | authentication | anthropic, openai, google |
| dependencies | ast-grep CLI/NAPI, comment-checker | | dependencies | ast-grep, comment-checker |
| tools | LSP, MCP connectivity | | tools | LSP, MCP |
| updates | version comparison | | updates | version comparison |
## HOW TO ADD CHECK ## HOW TO ADD CHECK
1. Create `src/cli/doctor/checks/my-check.ts`: 1. Create `src/cli/doctor/checks/my-check.ts`
```typescript
export function getMyCheckDefinition(): CheckDefinition {
return {
id: "my-check",
name: "My Check",
category: "configuration",
check: async () => ({ status: "pass", message: "OK" })
}
}
```
2. Export from `checks/index.ts` 2. Export from `checks/index.ts`
3. Add to `getAllCheckDefinitions()` 3. Add to `getAllCheckDefinitions()`
## TUI FRAMEWORK ## TUI FRAMEWORK
- **@clack/prompts**: `select()`, `spinner()`, `intro()`, `outro()`, `note()` - **@clack/prompts**: `select()`, `spinner()`, `intro()`
- **picocolors**: Colored terminal output - **picocolors**: Terminal colors
- **Symbols**: ✓ (pass), ✗ (fail), ⚠ (warn), ○ (skip) - **Symbols**: ✓ (pass), ✗ (fail), ⚠ (warn)
## CONFIG-MANAGER
- **JSONC**: Comments (`// ...`), block comments, trailing commas
- **Multi-source**: User (`~/.config/opencode/`) + Project (`.opencode/`)
- **Env override**: `OPENCODE_CONFIG_DIR` for profile isolation
- **Validation**: Zod schema with error aggregation
## ANTI-PATTERNS ## ANTI-PATTERNS
- **Blocking in non-TTY**: Check `process.stdout.isTTY` - **Blocking in non-TTY**: Check `process.stdout.isTTY`
- **Direct JSON.parse**: Use `parseJsonc()` for config - **Direct JSON.parse**: Use `parseJsonc()`
- **Silent failures**: Always return warn/fail in doctor - **Silent failures**: Return warn/fail in doctor
- **Hardcoded paths**: Use `ConfigManager`

64
src/features/AGENTS.md
View File

@ -2,32 +2,30 @@
## OVERVIEW ## OVERVIEW
Core feature modules + Claude Code compatibility layer. Background agents, skill MCP, builtin skills/commands, and 5 loaders for Claude Code compat. Core feature modules + Claude Code compatibility layer. Background agents, skill MCP, builtin skills/commands, 5 loaders.
## STRUCTURE ## STRUCTURE
``` ```
features/ features/
├── background-agent/ # Task lifecycle (1335 lines manager.ts) ├── background-agent/ # Task lifecycle (1335 lines)
│ ├── manager.ts # Launch → poll → complete orchestration │ ├── manager.ts # Launch → poll → complete
│ ├── concurrency.ts # Per-provider/model limits │ ├── concurrency.ts # Per-provider limits
│ └── types.ts # BackgroundTask, LaunchInput │ └── types.ts # BackgroundTask, LaunchInput
├── skill-mcp-manager/ # MCP client lifecycle (520 lines) ├── skill-mcp-manager/ # MCP client lifecycle
│ ├── manager.ts # Lazy loading, idle cleanup │ ├── manager.ts # Lazy loading, cleanup
│ └── types.ts # SkillMcpConfig, transports │ └── types.ts # SkillMcpConfig
├── builtin-skills/ # Playwright, git-master, frontend-ui-ux ├── builtin-skills/ # Playwright, git-master, frontend-ui-ux
│ └── skills.ts # 1203 lines of skill definitions │ └── skills.ts # 1203 lines
├── builtin-commands/ # ralph-loop, refactor, init-deep ├── builtin-commands/ # ralph-loop, refactor, init-deep
│ └── templates/ # Command implementations
├── claude-code-agent-loader/ # ~/.claude/agents/*.md ├── claude-code-agent-loader/ # ~/.claude/agents/*.md
├── claude-code-command-loader/ # ~/.claude/commands/*.md ├── claude-code-command-loader/ # ~/.claude/commands/*.md
├── claude-code-mcp-loader/ # .mcp.json with ${VAR} expansion ├── claude-code-mcp-loader/ # .mcp.json
├── claude-code-plugin-loader/ # installed_plugins.json ├── claude-code-plugin-loader/ # installed_plugins.json
├── claude-code-session-state/ # Session state persistence ├── claude-code-session-state/ # Session persistence
├── opencode-skill-loader/ # Skills from 6 directories (12 files) ├── opencode-skill-loader/ # Skills from 6 directories
├── context-injector/ # AGENTS.md/README.md injection ├── context-injector/ # AGENTS.md/README.md injection
├── boulder-state/ # Todo state persistence ├── boulder-state/ # Todo state persistence
├── task-toast-manager/ # Toast notifications
└── hook-message-injector/ # Message injection └── hook-message-injector/ # Message injection
``` ```
@ -35,43 +33,25 @@ features/
| Type | Priority (highest first) | | Type | Priority (highest first) |
|------|--------------------------| |------|--------------------------|
| Commands | `.opencode/command/` > `~/.config/opencode/command/` > `.claude/commands/` > `~/.claude/commands/` | | Commands | `.opencode/command/` > `~/.config/opencode/command/` > `.claude/commands/` |
| Skills | `.opencode/skills/` > `~/.config/opencode/skills/` > `.claude/skills/` > `~/.claude/skills/` | | Skills | `.opencode/skills/` > `~/.config/opencode/skills/` > `.claude/skills/` |
| Agents | `.claude/agents/` > `~/.claude/agents/` |
| MCPs | `.claude/.mcp.json` > `.mcp.json` > `~/.claude/.mcp.json` | | MCPs | `.claude/.mcp.json` > `.mcp.json` > `~/.claude/.mcp.json` |
## BACKGROUND AGENT ## BACKGROUND AGENT
- **Lifecycle**: `launch` → `poll` (2s interval) → `complete` - **Lifecycle**: `launch` → `poll` (2s) → `complete`
- **Stability**: 3 consecutive polls with same message count = idle - **Stability**: 3 consecutive polls = idle
- **Concurrency**: Per-provider/model limits (e.g., max 3 Opus, max 10 Gemini) - **Concurrency**: Per-provider/model limits
- **Notification**: Batched system reminders to parent session - **Cleanup**: 30m TTL, 3m stale timeout
- **Cleanup**: 30m TTL, 3m stale timeout, signal handlers
## SKILL MCP ## SKILL MCP
- **Lazy**: Clients created on first tool call - **Lazy**: Clients created on first call
- **Transports**: stdio (local process), http (SSE/Streamable) - **Transports**: stdio, http (SSE/Streamable)
- **Environment**: `${VAR}` expansion in config - **Lifecycle**: 5m idle cleanup
- **Lifecycle**: 5m idle cleanup, session-scoped
## CONFIG TOGGLES
```jsonc
{
"claude_code": {
"mcp": false, // Skip .mcp.json
"commands": false, // Skip commands/*.md
"skills": false, // Skip skills/*/SKILL.md
"agents": false, // Skip agents/*.md
"hooks": false // Skip settings.json hooks
}
}
```
## ANTI-PATTERNS ## ANTI-PATTERNS
- **Sequential delegation**: Use `delegate_task` for parallel - **Sequential delegation**: Use `delegate_task` parallel
- **Trust self-reports**: ALWAYS verify agent outputs - **Trust self-reports**: ALWAYS verify
- **Main thread blocks**: No heavy I/O in loader init - **Main thread blocks**: No heavy I/O in loader init
- **Manual versioning**: CI manages package.json version

63
src/hooks/AGENTS.md
View File

@ -8,27 +8,26 @@
``` ```
hooks/ hooks/
├── atlas/ # Main orchestration & delegation (771 lines) ├── atlas/ # Main orchestration (771 lines)
├── anthropic-context-window-limit-recovery/ # Auto-summarize at token limit ├── anthropic-context-window-limit-recovery/ # Auto-summarize
├── todo-continuation-enforcer.ts # Force TODO completion ├── todo-continuation-enforcer.ts # Force TODO completion
├── ralph-loop/ # Self-referential dev loop until done ├── ralph-loop/ # Self-referential dev loop
├── claude-code-hooks/ # settings.json hook compat layer (14 files) - see AGENTS.md ├── claude-code-hooks/ # settings.json compat layer - see AGENTS.md
├── comment-checker/ # Prevents AI slop/excessive comments ├── comment-checker/ # Prevents AI slop
├── auto-slash-command/ # Detects /command patterns ├── auto-slash-command/ # Detects /command patterns
├── rules-injector/ # Conditional rules from .claude/rules/ ├── rules-injector/ # Conditional rules
├── directory-agents-injector/ # Auto-injects AGENTS.md files ├── directory-agents-injector/ # Auto-injects AGENTS.md
├── directory-readme-injector/ # Auto-injects README.md files ├── directory-readme-injector/ # Auto-injects README.md
├── preemptive-compaction/ # Triggers summary at 85% context ├── edit-error-recovery/ # Recovers from failures
├── edit-error-recovery/ # Recovers from tool failures ├── thinking-block-validator/ # Ensures valid <thinking>
├── thinking-block-validator/ # Ensures valid <thinking> format ├── context-window-monitor.ts # Reminds of headroom
├── context-window-monitor.ts # Reminds agents of remaining headroom
├── session-recovery/ # Auto-recovers from crashes ├── session-recovery/ # Auto-recovers from crashes
├── think-mode/ # Dynamic thinking budget ├── think-mode/ # Dynamic thinking budget
├── keyword-detector/ # ultrawork/search/analyze modes ├── keyword-detector/ # ultrawork/search/analyze modes
├── background-notification/ # OS notification on task completion ├── background-notification/ # OS notification
├── prometheus-md-only/ # Enforces planner read-only mode ├── prometheus-md-only/ # Planner read-only mode
├── agent-usage-reminder/ # Reminds to use specialized agents ├── agent-usage-reminder/ # Specialized agent hints
├── auto-update-checker/ # Checks for plugin updates ├── auto-update-checker/ # Plugin update check
└── tool-output-truncator.ts # Prevents context bloat └── tool-output-truncator.ts # Prevents context bloat
``` ```
@ -36,41 +35,37 @@ hooks/
| Event | Timing | Can Block | Use Case | | Event | Timing | Can Block | Use Case |
|-------|--------|-----------|----------| |-------|--------|-----------|----------|
| PreToolUse | Before tool | Yes | Validate/modify inputs, inject context | | PreToolUse | Before tool | Yes | Validate/modify inputs |
| PostToolUse | After tool | No | Append warnings, truncate output | | PostToolUse | After tool | No | Append warnings, truncate |
| UserPromptSubmit | On prompt | Yes | Keyword detection, mode switching | | UserPromptSubmit | On prompt | Yes | Keyword detection |
| Stop | Session idle | No | Auto-continue (todo-continuation, ralph-loop) | | Stop | Session idle | No | Auto-continue |
| onSummarize | Compaction | No | Preserve critical state | | onSummarize | Compaction | No | Preserve state |
## EXECUTION ORDER ## EXECUTION ORDER
**chat.message**: keywordDetector → claudeCodeHooks → autoSlashCommand → startWork → ralphLoop **chat.message**: keywordDetector → claudeCodeHooks → autoSlashCommand → startWork → ralphLoop
**tool.execute.before**: claudeCodeHooks → nonInteractiveEnv → commentChecker → directoryAgentsInjector → directoryReadmeInjector → rulesInjector **tool.execute.before**: claudeCodeHooks → nonInteractiveEnv → commentChecker → directoryAgentsInjector → rulesInjector
**tool.execute.after**: editErrorRecovery → delegateTaskRetry → commentChecker → toolOutputTruncator → emptyTaskResponseDetector → claudeCodeHooks **tool.execute.after**: editErrorRecovery → delegateTaskRetry → commentChecker → toolOutputTruncator → claudeCodeHooks
## HOW TO ADD ## HOW TO ADD
1. Create `src/hooks/name/` with `index.ts` exporting `createMyHook(ctx)` 1. Create `src/hooks/name/` with `index.ts` exporting `createMyHook(ctx)`
2. Implement event handlers: `"tool.execute.before"`, `"tool.execute.after"`, etc. 2. Add hook name to `HookNameSchema` in `src/config/schema.ts`
3. Add hook name to `HookNameSchema` in `src/config/schema.ts` 3. Register in `src/index.ts`:
4. Register in `src/index.ts`:
```typescript ```typescript
const myHook = isHookEnabled("my-hook") ? createMyHook(ctx) : null const myHook = isHookEnabled("my-hook") ? createMyHook(ctx) : null
// Add to event handlers
``` ```
## PATTERNS ## PATTERNS
- **Session-scoped state**: `Map<sessionID, Set<string>>` for tracking per-session - **Session-scoped state**: `Map<sessionID, Set<string>>`
- **Conditional execution**: Check `input.tool` before processing - **Conditional execution**: Check `input.tool` before processing
- **Output modification**: `output.output += "\n${REMINDER}"` to append context - **Output modification**: `output.output += "\n${REMINDER}"`
- **Async state**: Use promises for CLI path resolution, cache results
## ANTI-PATTERNS ## ANTI-PATTERNS
- **Blocking non-critical**: Use PostToolUse warnings instead of PreToolUse blocks - **Blocking non-critical**: Use PostToolUse warnings instead
- **Heavy computation**: Keep PreToolUse light - slows every tool call - **Heavy computation**: Keep PreToolUse light
- **Redundant injection**: Track injected files to prevent duplicates - **Redundant injection**: Track injected files
- **Verbose output**: Keep hook messages technical, brief

69
src/hooks/claude-code-hooks/AGENTS.md
View File

@ -1,37 +1,36 @@
# CLAUDE CODE HOOKS COMPATIBILITY LAYER # CLAUDE CODE HOOKS COMPATIBILITY
## OVERVIEW ## OVERVIEW
Full Claude Code settings.json hook compatibility. Executes user-defined hooks at 5 lifecycle events: PreToolUse, PostToolUse, UserPromptSubmit, Stop, PreCompact. Full Claude Code settings.json hook compatibility. 5 lifecycle events: PreToolUse, PostToolUse, UserPromptSubmit, Stop, PreCompact.
## STRUCTURE ## STRUCTURE
``` ```
claude-code-hooks/ claude-code-hooks/
├── index.ts # Main factory (401 lines) - createClaudeCodeHooksHook() ├── index.ts # Main factory (401 lines)
├── config.ts # Loads ~/.claude/settings.json ├── config.ts # Loads ~/.claude/settings.json
├── config-loader.ts # Extended config from multiple sources ├── config-loader.ts # Extended config
├── pre-tool-use.ts # PreToolUse hook executor (172 lines) ├── pre-tool-use.ts # PreToolUse executor
├── post-tool-use.ts # PostToolUse hook executor (199 lines) ├── post-tool-use.ts # PostToolUse executor
├── user-prompt-submit.ts # UserPromptSubmit hook executor ├── user-prompt-submit.ts # UserPromptSubmit executor
├── stop.ts # Stop hook executor (session idle) ├── stop.ts # Stop hook executor
├── pre-compact.ts # PreCompact hook executor (context compaction) ├── pre-compact.ts # PreCompact executor
├── transcript.ts # Tool use recording (252 lines) ├── transcript.ts # Tool use recording
├── tool-input-cache.ts # Caches tool inputs between pre/post ├── tool-input-cache.ts # Pre→post caching
├── types.ts # Hook types, context interfaces ├── types.ts # Hook types
├── todo.ts # Todo JSON parsing fix └── todo.ts # Todo JSON fix
└── plugin-config.ts # Plugin config access
``` ```
## HOOK LIFECYCLE ## HOOK LIFECYCLE
| Event | When | Can Block | Context Fields | | Event | When | Can Block | Context |
|-------|------|-----------|----------------| |-------|------|-----------|---------|
| **PreToolUse** | Before tool | Yes | sessionId, toolName, toolInput, cwd | | PreToolUse | Before tool | Yes | sessionId, toolName, toolInput |
| **PostToolUse** | After tool | Warn only | + toolOutput, transcriptPath | | PostToolUse | After tool | Warn | + toolOutput, transcriptPath |
| **UserPromptSubmit** | On user message | Yes | sessionId, prompt, parts, cwd | | UserPromptSubmit | On message | Yes | sessionId, prompt, parts |
| **Stop** | Session idle | inject_prompt | sessionId, parentSessionId | | Stop | Session idle | inject | sessionId, parentSessionId |
| **PreCompact** | Before summarize | No | sessionId, cwd | | PreCompact | Before summarize | No | sessionId |
## CONFIG SOURCES ## CONFIG SOURCES
@ -39,32 +38,14 @@ Priority (highest first):
1. `.claude/settings.json` (project) 1. `.claude/settings.json` (project)
2. `~/.claude/settings.json` (user) 2. `~/.claude/settings.json` (user)
```json
{
"hooks": {
"PreToolUse": [{ "matcher": "Edit", "command": "./check.sh" }],
"PostToolUse": [{ "command": "post-hook.sh $TOOL_NAME" }]
}
}
```
## HOOK EXECUTION ## HOOK EXECUTION
1. User-defined hooks loaded from settings.json 1. Hooks loaded from settings.json
2. Matchers filter by tool name (supports wildcards) 2. Matchers filter by tool name
3. Commands executed via subprocess with environment: 3. Commands via subprocess with `$SESSION_ID`, `$TOOL_NAME`
- `$SESSION_ID`, `$TOOL_NAME`, `$TOOL_INPUT`, `$CWD`
4. Exit codes: 0=pass, 1=warn, 2=block 4. Exit codes: 0=pass, 1=warn, 2=block
## KEY PATTERNS
- **Session tracking**: `Map<sessionID, state>` for first-message, error, interrupt
- **Input caching**: Tool inputs cached pre→post via `tool-input-cache.ts`
- **Transcript recording**: All tool uses logged for debugging
- **Todowrite fix**: Parses string todos to array (line 174-196)
## ANTI-PATTERNS ## ANTI-PATTERNS
- **Heavy PreToolUse logic**: Runs before EVERY tool call - **Heavy PreToolUse**: Runs before EVERY tool call
- **Blocking non-critical**: Use warnings in PostToolUse instead - **Blocking non-critical**: Use PostToolUse warnings
- **Missing error handling**: Always wrap subprocess calls

38
src/mcp/AGENTS.md
View File

@ -1,8 +1,8 @@
# BUILT-IN MCP CONFIGURATIONS # MCP KNOWLEDGE BASE
## OVERVIEW ## OVERVIEW
3 remote MCP servers for web search, documentation, and code search. All use HTTP/SSE transport, no OAuth. 3 remote MCP servers: web search, documentation, code search. HTTP/SSE transport.
## STRUCTURE ## STRUCTURE
@ -20,20 +20,19 @@ mcp/
| Name | URL | Purpose | Auth | | Name | URL | Purpose | Auth |
|------|-----|---------|------| |------|-----|---------|------|
| **websearch** | `mcp.exa.ai` | Real-time web search | `EXA_API_KEY` header | | websearch | mcp.exa.ai | Real-time web search | EXA_API_KEY |
| **context7** | `mcp.context7.com` | Official library docs | None | | context7 | mcp.context7.com | Library docs | None |
| **grep_app** | `mcp.grep.app` | GitHub code search | None | | grep_app | mcp.grep.app | GitHub code search | None |
## CONFIG PATTERN ## CONFIG PATTERN
All MCPs follow identical structure:
```typescript ```typescript
export const mcp_name = { export const mcp_name = {
type: "remote" as const, type: "remote" as const,
url: "https://...", url: "https://...",
enabled: true, enabled: true,
oauth: false as const, // Explicit disable oauth: false as const,
headers?: { ... }, // Optional auth headers?: { ... },
} }
``` ```
@ -42,29 +41,18 @@ export const mcp_name = {
```typescript ```typescript
import { createBuiltinMcps } from "./mcp" import { createBuiltinMcps } from "./mcp"
// Enable all const mcps = createBuiltinMcps() // Enable all
const mcps = createBuiltinMcps() const mcps = createBuiltinMcps(["websearch"]) // Disable specific
// Disable specific
const mcps = createBuiltinMcps(["websearch"])
``` ```
## HOW TO ADD ## HOW TO ADD
1. Create `src/mcp/my-mcp.ts`: 1. Create `src/mcp/my-mcp.ts`
```typescript
export const my_mcp = {
type: "remote" as const,
url: "https://mcp.example.com",
enabled: true,
oauth: false as const,
}
```
2. Add to `allBuiltinMcps` in `index.ts` 2. Add to `allBuiltinMcps` in `index.ts`
3. Add to `McpNameSchema` in `types.ts` 3. Add to `McpNameSchema` in `types.ts`
## NOTES ## NOTES
- **Remote only**: All built-in MCPs use HTTP/SSE, no stdio - **Remote only**: HTTP/SSE, no stdio
- **Disable config**: User can disable via `disabled_mcps: ["name"]` - **Disable**: User can set `disabled_mcps: ["name"]`
- **Exa requires key**: Set `EXA_API_KEY` env var for websearch - **Exa**: Requires `EXA_API_KEY` env var

77
src/shared/AGENTS.md
View File

@ -2,75 +2,64 @@
## OVERVIEW ## OVERVIEW
50 cross-cutting utilities: path resolution, token truncation, config parsing, model resolution, Claude Code compatibility. 50 cross-cutting utilities: path resolution, token truncation, config parsing, model resolution.
## STRUCTURE ## STRUCTURE
``` ```
shared/ shared/
├── logger.ts # File-based logging (tmpdir/oh-my-opencode.log) ├── logger.ts # File-based logging
├── permission-compat.ts # Agent tool restrictions (ask/allow/deny) ├── permission-compat.ts # Agent tool restrictions
├── dynamic-truncator.ts # Token-aware truncation (50% headroom) ├── dynamic-truncator.ts # Token-aware truncation
├── frontmatter.ts # YAML frontmatter parsing ├── frontmatter.ts # YAML frontmatter
├── jsonc-parser.ts # JSON with Comments support ├── jsonc-parser.ts # JSON with Comments
├── data-path.ts # XDG-compliant storage (~/.local/share) ├── data-path.ts # XDG-compliant storage
├── opencode-config-dir.ts # ~/.config/opencode resolution ├── opencode-config-dir.ts # ~/.config/opencode
├── claude-config-dir.ts # ~/.claude resolution ├── claude-config-dir.ts # ~/.claude
├── migration.ts # Legacy config migration (omo → Sisyphus) ├── migration.ts # Legacy config migration
├── opencode-version.ts # Version comparison (>= 1.0.150) ├── opencode-version.ts # Version comparison
├── external-plugin-detector.ts # OAuth spoofing detection ├── external-plugin-detector.ts # OAuth spoofing detection
├── env-expander.ts # ${VAR} expansion in configs ├── env-expander.ts # ${VAR} expansion
├── system-directive.ts # System directive types ├── model-requirements.ts # Agent/Category requirements
├── hook-utils.ts # Hook helper functions ├── model-availability.ts # Models fetch + fuzzy match
├── model-requirements.ts # Agent/Category model requirements (providers + model) ├── model-resolver.ts # 3-step resolution
├── model-availability.ts # Available models fetch + fuzzy matching ├── shell-env.ts # Cross-platform shell
├── model-resolver.ts # 3-step model resolution (override → provider fallback → default) ├── prompt-parts-helper.ts # Prompt manipulation
├── shell-env.ts # Cross-platform shell environment └── *.test.ts # Colocated tests
├── prompt-parts-helper.ts # Prompt parts manipulation
└── *.test.ts # Test files (colocated)
``` ```
## WHEN TO USE ## WHEN TO USE
| Task | Utility | | Task | Utility |
|------|---------| |------|---------|
| Debug logging | `log(message, data)` in `logger.ts` | | Debug logging | `log(message, data)` |
| Limit context | `dynamicTruncate(ctx, sessionId, output)` | | Limit context | `dynamicTruncate(ctx, sessionId, output)` |
| Parse frontmatter | `parseFrontmatter(content)` | | Parse frontmatter | `parseFrontmatter(content)` |
| Load JSONC config | `parseJsonc(text)` or `readJsoncFile(path)` | | Load JSONC | `parseJsonc(text)` or `readJsoncFile(path)` |
| Restrict agent tools | `createAgentToolAllowlist(tools)` | | Restrict tools | `createAgentToolAllowlist(tools)` |
| Resolve paths | `getOpenCodeConfigDir()`, `getClaudeConfigDir()` | | Resolve paths | `getOpenCodeConfigDir()` |
| Migrate config | `migrateConfigFile(path, rawConfig)` |
| Compare versions | `isOpenCodeVersionAtLeast("1.1.0")` | | Compare versions | `isOpenCodeVersionAtLeast("1.1.0")` |
| Get agent model requirements | `AGENT_MODEL_REQUIREMENTS` in `model-requirements.ts` | | Resolve model | `resolveModelWithFallback()` |
| Get category model requirements | `CATEGORY_MODEL_REQUIREMENTS` in `model-requirements.ts` |
| Resolve model with fallback | `resolveModelWithFallback()` in `model-resolver.ts` |
| Fuzzy match model names | `fuzzyMatchModel()` in `model-availability.ts` |
| Fetch available models | `fetchAvailableModels(client)` in `model-availability.ts` |
## KEY PATTERNS ## PATTERNS
```typescript ```typescript
// Token-aware truncation // Token-aware truncation
const { result } = await dynamicTruncate(ctx, sessionID, largeBuffer) const { result } = await dynamicTruncate(ctx, sessionID, buffer)
// JSONC config loading // JSONC config
const settings = readJsoncFile<Settings>(configPath) const settings = readJsoncFile<Settings>(configPath)
// Version-gated features // Version-gated
if (isOpenCodeVersionAtLeast("1.1.0")) { /* new feature */ } if (isOpenCodeVersionAtLeast("1.1.0")) { /* ... */ }
// Tool permission normalization // Model resolution
const permissions = migrateToolsToPermission(legacyTools)
// Model resolution with fallback chain
const model = await resolveModelWithFallback(client, requirements, override) const model = await resolveModelWithFallback(client, requirements, override)
``` ```
## ANTI-PATTERNS ## ANTI-PATTERNS
- **Raw JSON.parse**: Use `jsonc-parser.ts` for config files - **Raw JSON.parse**: Use `jsonc-parser.ts`
- **Hardcoded paths**: Use `*-config-dir.ts` utilities - **Hardcoded paths**: Use `*-config-dir.ts`
- **console.log**: Use `logger.ts` for background agents - **console.log**: Use `logger.ts` for background
- **Unbounded output**: Always use `dynamic-truncator.ts` - **Unbounded output**: Use `dynamic-truncator.ts`
- **Manual version parse**: Use `opencode-version.ts`

50
src/tools/AGENTS.md
View File

@ -2,7 +2,7 @@
## OVERVIEW ## OVERVIEW
20+ tools: LSP (6), AST-Grep (2), Search (2), Session (4), Agent delegation (4), System (2), Skill (3). High-performance C++ bindings via @ast-grep/napi. 20+ tools: LSP (6), AST-Grep (2), Search (2), Session (4), Agent delegation (4), System (2), Skill (3).
## STRUCTURE ## STRUCTURE
@ -10,17 +10,17 @@
tools/ tools/
├── [tool-name]/ ├── [tool-name]/
│ ├── index.ts # Barrel export │ ├── index.ts # Barrel export
│ ├── tools.ts # Business logic, ToolDefinition │ ├── tools.ts # ToolDefinition
│ ├── types.ts # Zod schemas │ ├── types.ts # Zod schemas
│ └── constants.ts # Fixed values, descriptions │ └── constants.ts # Fixed values
├── lsp/ # 6 tools: goto_definition, references, symbols, diagnostics, prepare_rename, rename ├── lsp/ # 6 tools: definition, references, symbols, diagnostics, rename
├── ast-grep/ # 2 tools: search, replace (25 languages via NAPI) ├── ast-grep/ # 2 tools: search, replace (25 languages)
├── delegate-task/ # Category-based agent routing (1027 lines) ├── delegate-task/ # Category-based routing (1038 lines)
├── session-manager/ # 4 tools: list, read, search, info ├── session-manager/ # 4 tools: list, read, search, info
├── grep/ # Custom grep with timeout/truncation ├── grep/ # Custom grep with timeout
├── glob/ # Custom glob with 60s timeout, 100 file limit ├── glob/ # 60s timeout, 100 file limit
├── interactive-bash/ # Tmux session management ├── interactive-bash/ # Tmux session management
├── look-at/ # Multimodal PDF/image analysis ├── look-at/ # Multimodal PDF/image
├── skill/ # Skill execution ├── skill/ # Skill execution
├── skill-mcp/ # Skill MCP operations ├── skill-mcp/ # Skill MCP operations
├── slashcommand/ # Slash command dispatch ├── slashcommand/ # Slash command dispatch
@ -32,43 +32,33 @@ tools/
| Category | Tools | Purpose | | Category | Tools | Purpose |
|----------|-------|---------| |----------|-------|---------|
| **LSP** | lsp_goto_definition, lsp_find_references, lsp_symbols, lsp_diagnostics, lsp_prepare_rename, lsp_rename | Semantic code intelligence | | LSP | lsp_goto_definition, lsp_find_references, lsp_symbols, lsp_diagnostics, lsp_prepare_rename, lsp_rename | Semantic code intelligence |
| **Search** | ast_grep_search, ast_grep_replace, grep, glob | Pattern discovery | | Search | ast_grep_search, ast_grep_replace, grep, glob | Pattern discovery |
| **Session** | session_list, session_read, session_search, session_info | History navigation | | Session | session_list, session_read, session_search, session_info | History navigation |
| **Agent** | delegate_task, call_omo_agent, background_output, background_cancel | Task orchestration | | Agent | delegate_task, call_omo_agent, background_output, background_cancel | Task orchestration |
| **System** | interactive_bash, look_at | CLI, multimodal | | System | interactive_bash, look_at | CLI, multimodal |
| **Skill** | skill, skill_mcp, slashcommand | Skill execution | | Skill | skill, skill_mcp, slashcommand | Skill execution |
## HOW TO ADD ## HOW TO ADD
1. Create `src/tools/[name]/` with standard files 1. Create `src/tools/[name]/` with standard files
2. Use `tool()` from `@opencode-ai/plugin/tool`: 2. Use `tool()` from `@opencode-ai/plugin/tool`
```typescript
export const myTool: ToolDefinition = tool({
description: "...",
args: { param: tool.schema.string() },
execute: async (args) => { /* ... */ }
})
```
3. Export from `src/tools/index.ts` 3. Export from `src/tools/index.ts`
4. Add to `builtinTools` object 4. Add to `builtinTools` object
## LSP SPECIFICS ## LSP SPECIFICS
- **Client**: `client.ts` manages stdio lifecycle, JSON-RPC - **Client**: `client.ts` manages stdio, JSON-RPC
- **Singleton**: `LSPServerManager` with ref counting - **Singleton**: `LSPServerManager` with ref counting
- **Protocol**: Standard LSP methods mapped to tool responses
- **Capabilities**: definition, references, symbols, diagnostics, rename - **Capabilities**: definition, references, symbols, diagnostics, rename
## AST-GREP SPECIFICS ## AST-GREP SPECIFICS
- **Engine**: `@ast-grep/napi` for 25+ languages - **Engine**: `@ast-grep/napi` for 25+ languages
- **Patterns**: Meta-variables `$VAR` (single), `$$$` (multiple) - **Patterns**: `$VAR` (single), `$$$` (multiple)
- **Performance**: Rust/C++ layer for structural matching
## ANTI-PATTERNS ## ANTI-PATTERNS
- **Sequential bash**: Use `&&` or delegation, not loops - **Sequential bash**: Use `&&` or delegation
- **Raw file ops**: Never mkdir/touch in tool logic - **Raw file ops**: Never mkdir/touch in tool logic
- **Sleep**: Use polling loops, tool-specific wait flags - **Sleep**: Use polling loops
- **Heavy sync**: Keep PreToolUse light, computation in tools.ts