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

docs: regenerate all AGENTS.md files from comprehensive codebase exploration

Browse Source 
- Fired 33 parallel explore agents across all major directories
- Analyzed 1164 TS files, 133k LOC, 41 hooks, 26 tools, 11 agents, 18 features
- Regenerated 13 AGENTS.md files with 905 total lines
- Root: plugin architecture, initialization flow, 7 OpenCode hook handlers
- src/: entry point orchestration, hook composition pipeline
- agents/: 11 agent inventory with tool restrictions and factory patterns
- hooks/: 41 hooks organized by 5 tiers, key complex hooks documented
- tools/: 26 tools across 14 directories, delegation categories
- features/: 18 modules mapped by complexity (HIGH/MEDIUM/LOW)
- shared/: 101 utilities in 13 categories, model resolution pipeline
- config/: 22 schema files, Zod v4 validation system
- cli/: 5 commands, doctor checks, model fallback system
- mcp/: 3-tier MCP system architecture
- plugin-handlers/: 6-phase config loading pipeline
- claude-code-hooks/: CC settings.json compatibility layer
- claude-tasks/: task schema + file-based persistence

🤖 Generated with assistance of oh-my-opencode
This commit is contained in:
YeonGyu-Kim
2026-02-17 11:17:01 +09:00
parent 5a8e424c8e
commit aac79f03b5
13 changed files with 713 additions and 1015 deletions
Download Patch File Download Diff File Expand all files Collapse all files

361
AGENTS.md
View File

@@ -1,320 +1,119 @@
# PROJECT KNOWLEDGE BASE
# oh-my-opencode — OpenCode Plugin
**Generated:** 2026-02-16T14:58:00+09:00
**Commit:** 28cd34c3
**Branch:** fuck-v1.2
---
## CRITICAL: PULL REQUEST TARGET BRANCH (NEVER DELETE THIS SECTION)
> **THIS SECTION MUST NEVER BE REMOVED OR MODIFIED**
### Git Workflow
```
master (deployed/published)
↑
dev (integration branch)
↑
feature branches (your work)
```
### Rules (MANDATORY)
| Rule | Description |
|------|-------------|
| **ALL PRs → `dev`** | Every pull request MUST target the `dev` branch |
| **NEVER PR → `master`** | PRs to `master` are **automatically rejected** by CI |
| **"Create a PR" = target `dev`** | When asked to create a new PR, it ALWAYS means targeting `dev` |
| **Merge commit ONLY** | Squash merge is **disabled** in this repo. Always use merge commit when merging PRs. |
### Why This Matters
- `master` = production/published npm package
- `dev` = integration branch where features are merged and tested
- Feature branches → `dev` → (after testing) → `master`
- Squash merge is disabled at the repository level — attempting it will fail
**If you create a PR targeting `master`, it WILL be rejected. No exceptions.**
---
## CRITICAL: OPENCODE SOURCE CODE REFERENCE (NEVER DELETE THIS SECTION)
> **THIS SECTION MUST NEVER BE REMOVED OR MODIFIED**
### This is an OpenCode Plugin
Oh-My-OpenCode is a **plugin for OpenCode**. You will frequently need to examine OpenCode's source code to:
- Understand plugin APIs and hooks
- Debug integration issues
- Implement features that interact with OpenCode internals
- Answer questions about how OpenCode works
### How to Access OpenCode Source Code
**When you need to examine OpenCode source:**
1. **Clone to system temp directory:**
```bash
git clone https://github.com/sst/opencode /tmp/opencode-source
```
2. **Explore the codebase** from there (do NOT clone into the project directory)
3. **Clean up** when done (optional, temp dirs are ephemeral)
### Librarian Agent: YOUR PRIMARY TOOL for Plugin Work
**CRITICAL**: When working on plugin-related tasks or answering plugin questions:
| Scenario | Action |
|----------|--------|
| Implementing new hooks | Fire `librarian` to search OpenCode hook implementations |
| Adding new tools | Fire `librarian` to find OpenCode tool patterns |
| Understanding SDK behavior | Fire `librarian` to examine OpenCode SDK source |
| Debugging plugin issues | Fire `librarian` to find relevant OpenCode internals |
| Answering "how does OpenCode do X?" | Fire `librarian` FIRST |
**DO NOT guess or hallucinate about OpenCode internals.** Always verify by examining actual source code via `librarian` or direct clone.
---
## CRITICAL: ENGLISH-ONLY POLICY (NEVER DELETE THIS SECTION)
> **THIS SECTION MUST NEVER BE REMOVED OR MODIFIED**
### All Project Communications MUST Be in English
| Context | Language Requirement |
|---------|---------------------|
| **GitHub Issues** | English ONLY |
| **Pull Requests** | English ONLY (title, description, comments) |
| **Commit Messages** | English ONLY |
| **Code Comments** | English ONLY |
| **Documentation** | English ONLY |
| **AGENTS.md files** | English ONLY |
**If you're not comfortable writing in English, use translation tools. Broken English is fine. Non-English is not acceptable.**
---
**Generated:** 2026-02-17 | **Commit:** 5a8e424c | **Branch:** dev
## OVERVIEW
OpenCode plugin (oh-my-opencode): multi-model agent orchestration with 11 specialized agents, 41 lifecycle hooks across 7 event types, 26 tools (LSP, AST-Grep, delegation, task management), full Claude Code compatibility layer, 4-scope skill loading, background agent concurrency, tmux integration, and 3-tier MCP system. "oh-my-zsh" for OpenCode.
OpenCode plugin (npm: `oh-my-opencode`) that extends Claude Code (OpenCode fork) with multi-agent orchestration, 41 lifecycle hooks, 26 tools, skill/command/MCP systems, and Claude Code compatibility. 1164 TypeScript files, 133k LOC.
## STRUCTURE
```
oh-my-opencode/
├── src/
│ ├── agents/ # 11 AI agents — see src/agents/AGENTS.md
│ ├── hooks/ # 41 lifecycle hooks — see src/hooks/AGENTS.md
│ ├── tools/ # 26 tools — see src/tools/AGENTS.md
│ ├── features/ # Background agents, skills, CC compat — see src/features/AGENTS.md
│ ├── shared/ # Cross-cutting utilities — see src/shared/AGENTS.md
│ ├── cli/ # CLI installer, doctor — see src/cli/AGENTS.md
│ ├── mcp/ # Built-in MCPs — see src/mcp/AGENTS.md
│ ├── config/ # Zod schema — see src/config/AGENTS.md
│ ├── plugin-handlers/ # Config loading pipeline — see src/plugin-handlers/AGENTS.md
│ ├── plugin/ # Plugin interface composition (21 files)
│ ├── index.ts # Main plugin entry (106 lines)
│ ├── create-hooks.ts # Hook creation coordination (62 lines)
│ ├── create-managers.ts # Manager initialization (80 lines)
│ ├── create-tools.ts # Tool registry composition (54 lines)
│ ├── plugin-interface.ts # Plugin interface assembly (66 lines)
│ ├── plugin-config.ts # Config loading orchestration (180 lines)
│ └── plugin-state.ts # Model cache state (12 lines)
├── script/ # build-schema.ts, build-binaries.ts, publish.ts, generate-changelog.ts
├── packages/ # 11 platform-specific binary packages
└── dist/ # Build output (ESM + .d.ts)
│ ├── index.ts # Plugin entry: loadConfig → createManagers → createTools → createHooks → createPluginInterface
│ ├── plugin-config.ts # JSONC multi-level config: project → user → defaults (Zod v4)
│ ├── agents/ # 11 agents (Sisyphus, Hephaestus, Oracle, Librarian, Explore, Atlas, Prometheus, Metis, Momus, Multimodal-Looker, Sisyphus-Junior)
│ ├── hooks/ # 41 hooks across 37 directories + 6 standalone files
│ ├── tools/ # 26 tools across 14 directories
│ ├── features/ # 18 feature modules (background-agent, skill-loader, tmux, MCP-OAuth, etc.)
│ ├── shared/ # 101 utility files in 13 categories
│ ├── config/ # Zod v4 schema system (22 files)
│ ├── cli/ # CLI: install, run, doctor, mcp-oauth (Commander.js)
│ ├── mcp/ # 3 built-in remote MCPs (websearch, context7, grep_app)
│ ├── plugin/ # 7 OpenCode hook handlers + 41 hook composition
│ └── plugin-handlers/ # 6-phase config loading pipeline
├── packages/ # Monorepo: comment-checker, opencode-sdk
└── local-ignore/ # Dev-only test fixtures
```
## INITIALIZATION FLOW
```
OhMyOpenCodePlugin(ctx)
1. injectServerAuthIntoClient(ctx.client)
2. startTmuxCheck()
3. loadPluginConfig(ctx.directory, ctx) → OhMyOpenCodeConfig
4. createFirstMessageVariantGate()
5. createModelCacheState()
6. createManagers(ctx, config, tmux, cache) → TmuxSessionManager, BackgroundManager, SkillMcpManager, ConfigHandler
7. createTools(ctx, config, managers) → filteredTools, mergedSkills, availableSkills, availableCategories
8. createHooks(ctx, config, backgroundMgr) → 41 hooks (core + continuation + skill)
9. createPluginInterface(...) → 7 OpenCode hook handlers
10. Return plugin with experimental.session.compacting
├─→ loadPluginConfig() # JSONC parse → project/user merge → Zod validate → migrate
├─→ createManagers() # TmuxSessionManager, BackgroundManager, SkillMcpManager, ConfigHandler
├─→ createTools() # SkillContext + AvailableCategories + ToolRegistry (26 tools)
├─→ createHooks() # 3-tier: Core(33) + Continuation(7) + Skill(2) = 41 hooks
└─→ createPluginInterface() # 7 OpenCode hook handlers → PluginInterface
```
## 7 OPENCODE HOOK HANDLERS
| Handler | Purpose |
|---------|---------|
| `config` | 6-phase: provider → plugin-components → agents → tools → MCPs → commands |
| `tool` | 26 registered tools |
| `chat.message` | First-message variant, session setup, keyword detection |
| `chat.params` | Anthropic effort level adjustment |
| `event` | Session lifecycle (created, deleted, idle, error) |
| `tool.execute.before` | Pre-tool hooks (file guard, label truncator, rules injector) |
| `tool.execute.after` | Post-tool hooks (output truncation, metadata store) |
| `experimental.chat.messages.transform` | Context injection, thinking block validation |
## WHERE TO LOOK
| Task | Location | Notes |
|------|----------|-------|
| Add agent | `src/agents/` | Create .ts with factory, add to `agentSources` in builtin-agents/ |
| Add hook | `src/hooks/` | Create dir, register in `src/plugin/hooks/create-*-hooks.ts` |
| Add tool | `src/tools/` | Dir with index/types/constants/tools.ts |
| Add MCP | `src/mcp/` | Create config, add to `createBuiltinMcps()` |
| Add skill | `src/features/builtin-skills/` | Create .ts in skills/ |
| Add command | `src/features/builtin-commands/` | Add template + register in commands.ts |
| Config schema | `src/config/schema/` | 21 schema component files, run `bun run build:schema` |
| Plugin config | `src/plugin-handlers/config-handler.ts` | JSONC loading, merging, migration |
| Background agents | `src/features/background-agent/` | manager.ts (1701 lines) |
| Orchestrator | `src/hooks/atlas/` | Main orchestration hook (1976 lines) |
| Delegation | `src/tools/delegate-task/` | Category routing (constants.ts 569 lines) |
| Task system | `src/features/claude-tasks/` | Task schema, storage, todo sync |
| Plugin interface | `src/plugin/` | 21 files composing hooks, handlers, registries |
| Add new agent | `src/agents/` + `src/agents/builtin-agents/` | Follow createXXXAgent factory pattern |
| Add new hook | `src/hooks/{name}/` + register in `src/plugin/hooks/create-*-hooks.ts` | Match event type to tier |
| Add new tool | `src/tools/{name}/` + register in `src/plugin/tool-registry.ts` | Follow createXXXTool factory |
| Add new feature module | `src/features/{name}/` | Standalone module, wire in plugin/ |
| Add new MCP | `src/mcp/` + register in `createBuiltinMcps()` | Remote HTTP only |
| Add new skill | `src/features/builtin-skills/skills/` | Implement BuiltinSkill interface |
| Add new command | `src/features/builtin-commands/` | Template in templates/ |
| Add new CLI command | `src/cli/cli-program.ts` | Commander.js subcommand |
| Add new doctor check | `src/cli/doctor/checks/` | Register in checks/index.ts |
| Modify config schema | `src/config/schema/` + update root schema | Zod v4, add to OhMyOpenCodeConfigSchema |
## TDD (Test-Driven Development)
## MULTI-LEVEL CONFIG
**MANDATORY.** RED-GREEN-REFACTOR:
1. **RED**: Write test → `bun test` → FAIL
2. **GREEN**: Implement minimum → PASS
3. **REFACTOR**: Clean up → stay GREEN
```
Project (.opencode/oh-my-opencode.jsonc) → User (~/.config/opencode/oh-my-opencode.jsonc) → Defaults
```
**Rules:**
- NEVER write implementation before test
- NEVER delete failing tests — fix the code
- Test file: `*.test.ts` alongside source (176 test files)
- BDD comments: `//#given`, `//#when`, `//#then`
Fields: agents (14 overridable), categories (8 built-in + custom), disabled_* arrays, 19 feature-specific configs.
## THREE-TIER MCP SYSTEM
| Tier | Source | Mechanism |
|------|--------|-----------|
| Built-in | `src/mcp/` | 3 remote HTTP: websearch (Exa/Tavily), context7, grep_app |
| Claude Code | `.mcp.json` | `${VAR}` env expansion via claude-code-mcp-loader |
| Skill-embedded | SKILL.md YAML | Managed by SkillMcpManager (stdio + HTTP) |
## CONVENTIONS
- **Package manager**: Bun only (`bun run`, `bun build`, `bunx`)
- **Types**: bun-types (NEVER @types/node)
- **Build**: `bun build` (ESM) + `tsc --emitDeclarationOnly`
- **Exports**: Barrel pattern via index.ts
- **Naming**: kebab-case dirs, `createXXXHook`/`createXXXTool` factories
- **Testing**: BDD comments, 176 test files, 1130 TypeScript files
- **Temperature**: 0.1 for code agents, max 0.3
- **Modular architecture**: 200 LOC hard limit per file (prompt strings exempt)
- **Test pattern**: Vitest, co-located `*.test.ts`, given/when/then style
- **Factory pattern**: `createXXX()` for all tools, hooks, agents
- **Hook tiers**: Session (20) → Tool-Guard (9) → Transform (4) → Continuation (7) → Skill (2)
- **Agent modes**: `primary` (respects UI model) vs `subagent` (own fallback chain) vs `all`
- **Model resolution**: 3-step: override → category-default → provider-fallback → system-default
- **Config format**: JSONC with comments, Zod v4 validation, snake_case keys
## ANTI-PATTERNS
| Category | Forbidden |
|----------|-----------|
| Package Manager | npm, yarn — Bun exclusively |
| Types | @types/node — use bun-types |
| File Ops | mkdir/touch/rm/cp/mv in code — use bash tool |
| Publishing | Direct `bun publish` — GitHub Actions only |
| Versioning | Local version bump — CI manages |
| Type Safety | `as any`, `@ts-ignore`, `@ts-expect-error` |
| Error Handling | Empty catch blocks |
| Testing | Deleting failing tests, writing implementation before test |
| Agent Calls | Sequential — use `task` parallel |
| Hook Logic | Heavy PreToolUse — slows every call |
| Commits | Giant (3+ files), separate test from impl |
| Temperature | >0.3 for code agents |
| Trust | Agent self-reports — ALWAYS verify |
| Git | `git add -i`, `git rebase -i` (no interactive input) |
| Git | Skip hooks (--no-verify), force push without request |
| Bash | `sleep N` — use conditional waits |
| Bash | `cd dir && cmd` — use workdir parameter |
| Files | Catch-all utils.ts/helpers.ts — name by purpose |
## AGENT MODELS
| Agent | Model | Temp | Purpose |
|-------|-------|------|---------|
| Sisyphus | anthropic/claude-opus-4-6 | 0.1 | Primary orchestrator (fallback: kimi-k2.5 → glm-4.7 → gpt-5.3-codex → gemini-3-pro) |
| Hephaestus | openai/gpt-5.3-codex | 0.1 | Autonomous deep worker (NO fallback) |
| Atlas | anthropic/claude-sonnet-4-5 | 0.1 | Master orchestrator (fallback: kimi-k2.5 → gpt-5.2) |
| Prometheus | anthropic/claude-opus-4-6 | 0.1 | Strategic planning (fallback: kimi-k2.5 → gpt-5.2) |
| oracle | openai/gpt-5.2 | 0.1 | Consultation, debugging (fallback: claude-opus-4-6) |
| librarian | zai-coding-plan/glm-4.7 | 0.1 | Docs, GitHub search (fallback: glm-4.7-free) |
| explore | xai/grok-code-fast-1 | 0.1 | Fast codebase grep (fallback: claude-haiku-4-5 → gpt-5-mini → gpt-5-nano) |
| multimodal-looker | google/gemini-3-flash | 0.1 | PDF/image analysis |
| Metis | anthropic/claude-opus-4-6 | 0.3 | Pre-planning analysis (fallback: kimi-k2.5 → gpt-5.2) |
| Momus | openai/gpt-5.2 | 0.1 | Plan validation (fallback: claude-opus-4-6) |
| Sisyphus-Junior | anthropic/claude-sonnet-4-5 | 0.1 | Category-spawned executor |
## OPENCODE PLUGIN API
Plugin SDK from `@opencode-ai/plugin`. Plugin = `async (PluginInput) => Hooks`.
| Hook | Purpose |
|------|---------|
| `tool` | Register custom tools (Record<string, ToolDefinition>) |
| `chat.message` | Intercept user messages (can modify parts) |
| `chat.params` | Modify LLM parameters (temperature, topP, options) |
| `tool.execute.before` | Pre-tool interception (can modify args) |
| `tool.execute.after` | Post-tool processing (can modify output) |
| `event` | Session lifecycle events (session.created, session.stop, etc.) |
| `config` | Config modification (register agents, MCPs, commands) |
| `experimental.chat.messages.transform` | Transform message history |
| `experimental.session.compacting` | Session compaction customization |
## DEPENDENCIES
| Package | Purpose |
|---------|---------|
| `@opencode-ai/plugin` + `sdk` | OpenCode integration SDK |
| `@ast-grep/cli` + `napi` | AST pattern matching (search/replace) |
| `@code-yeongyu/comment-checker` | AI comment detection/prevention |
| `@modelcontextprotocol/sdk` | MCP client for remote HTTP servers |
| `@clack/prompts` | Interactive CLI TUI |
| `commander` | CLI argument parsing |
| `zod` (v4) | Schema validation for config |
| `jsonc-parser` | JSONC config with comments |
| `picocolors` | Terminal colors |
| `picomatch` | Glob pattern matching |
| `vscode-jsonrpc` | LSP communication |
| `js-yaml` | YAML parsing (tasks, skills) |
| `detect-libc` | Platform binary selection |
- Never use `as any`, `@ts-ignore`, `@ts-expect-error`
- Never suppress lint/type errors
- Never add emojis to code/comments unless user explicitly asks
- Never commit unless explicitly requested
- Test: given/when/then — never use Arrange-Act-Assert comments
- Comments: avoid AI-generated comment patterns (enforced by comment-checker hook)
## COMMANDS
```bash
bun run typecheck # Type check
bun run build # ESM + declarations + schema
bun run rebuild # Clean + Build
bun test # 176 test files
bun run build:schema # Regenerate JSON schema
bun test # Vitest test suite
bun run build # Build plugin
bunx oh-my-opencode install # Interactive setup
bunx oh-my-opencode doctor # Health diagnostics
bunx oh-my-opencode run # Non-interactive session
```
## DEPLOYMENT
**GitHub Actions workflow_dispatch ONLY**
1. Commit & push changes
2. Trigger: `gh workflow run publish -f bump=patch`
3. Never `bun publish` directly, never bump version locally
## COMPLEXITY HOTSPOTS
| File | Lines | Description |
|------|-------|-------------|
| `src/features/background-agent/manager.ts` | 1701 | Task lifecycle, concurrency |
| `src/hooks/anthropic-context-window-limit-recovery/` | 2232 | Multi-strategy context recovery |
| `src/hooks/claude-code-hooks/` | 2110 | Claude Code settings.json compat |
| `src/hooks/todo-continuation-enforcer/` | 2061 | Core boulder mechanism |
| `src/hooks/atlas/` | 1976 | Session orchestration |
| `src/hooks/ralph-loop/` | 1687 | Self-referential dev loop |
| `src/hooks/keyword-detector/` | 1665 | Mode detection (ultrawork/search) |
| `src/hooks/rules-injector/` | 1604 | Conditional rules injection |
| `src/hooks/think-mode/` | 1365 | Model/variant switching |
| `src/hooks/session-recovery/` | 1279 | Auto error recovery |
| `src/features/builtin-skills/skills/git-master.ts` | 1112 | Git master skill |
| `src/tools/delegate-task/constants.ts` | 569 | Category routing configs |
## MCP ARCHITECTURE
Three-tier system:
1. **Built-in** (src/mcp/): websearch (Exa/Tavily), context7 (docs), grep_app (GitHub)
2. **Claude Code compat** (features/claude-code-mcp-loader/): .mcp.json with `${VAR}` expansion
3. **Skill-embedded** (features/opencode-skill-loader/): YAML frontmatter in SKILL.md
## CONFIG SYSTEM
- **Zod validation**: 21 schema component files in `src/config/schema/`
- **JSONC support**: Comments, trailing commas
- **Multi-level**: Project (`.opencode/`) → User (`~/.config/opencode/`) → Defaults
- **Migration**: Legacy config auto-migration in `src/shared/migration/`
## NOTES
- **OpenCode**: Requires >= 1.0.150
- **1130 TypeScript files**, 176 test files, 127k+ lines
- **Flaky tests**: ralph-loop (CI timeout), session-state (parallel pollution)
- **Trusted deps**: @ast-grep/cli, @ast-grep/napi, @code-yeongyu/comment-checker
- **No linter/formatter**: No ESLint, Prettier, or Biome configured
- **License**: SUL-1.0 (Sisyphus Use License)
- Logger writes to `/tmp/oh-my-opencode.log` — check there for debugging
- Background tasks: 5 concurrent per model/provider (configurable)
- Plugin load timeout: 10s for Claude Code plugins
- Model fallback priority: Claude > OpenAI > Gemini > Copilot > OpenCode Zen > Z.ai > Kimi
- Config migration runs automatically on legacy keys (agent names, hook names, model versions)

102
src/AGENTS.md
View File

@@ -1,81 +1,41 @@
# SRC KNOWLEDGE BASE
# src/ — Plugin Source
**Generated:** 2026-02-17
## OVERVIEW
Main plugin entry point and orchestration layer. Plugin initialization, hook registration, tool composition, and lifecycle management.
Root source directory. Entry point `index.ts` orchestrates 4-step initialization: config → managers → tools → hooks → plugin interface.
## STRUCTURE
## KEY FILES
| File | Purpose |
|------|---------|
| `index.ts` | Plugin entry, exports `OhMyOpenCodePlugin` |
| `plugin-config.ts` | JSONC parse, multi-level merge (project → user → defaults), Zod validation |
| `create-managers.ts` | TmuxSessionManager, BackgroundManager, SkillMcpManager, ConfigHandler |
| `create-tools.ts` | SkillContext + AvailableCategories + ToolRegistry |
| `create-hooks.ts` | 3-tier hook composition: Core(33) + Continuation(7) + Skill(2) |
| `plugin-interface.ts` | Assembles 7 OpenCode hook handlers into PluginInterface |
## CONFIG LOADING
```
src/
├── index.ts # Main plugin entry (106 lines) — OhMyOpenCodePlugin factory
├── create-hooks.ts # Hook coordination: core, continuation, skill (62 lines)
├── create-managers.ts # Manager initialization: Tmux, Background, SkillMcp, Config (80 lines)
├── create-tools.ts # Tool registry + skill context composition (54 lines)
├── plugin-interface.ts # Plugin interface assembly — 7 OpenCode hooks (66 lines)
├── plugin-config.ts # Config loading orchestration (user + project merge, 180 lines)
├── plugin-state.ts # Model cache state (context limits, anthropic 1M flag, 12 lines)
├── agents/ # 11 AI agents (32 files) — see agents/AGENTS.md
├── cli/ # CLI installer, doctor (107+ files) — see cli/AGENTS.md
├── config/ # Zod schema (21 component files) — see config/AGENTS.md
├── features/ # Background agents, skills, commands (18 dirs) — see features/AGENTS.md
├── hooks/ # 41 lifecycle hooks (36 dirs) — see hooks/AGENTS.md
├── mcp/ # Built-in MCPs (6 files) — see mcp/AGENTS.md
├── plugin/ # Plugin interface composition (21 files)
├── plugin-handlers/ # Config loading, plan inheritance (15 files) — see plugin-handlers/AGENTS.md
├── shared/ # Cross-cutting utilities (96 files) — see shared/AGENTS.md
└── tools/ # 26 tools (14 dirs) — see tools/AGENTS.md
loadPluginConfig(directory, ctx)
1. User: ~/.config/opencode/oh-my-opencode.jsonc
2. Project: .opencode/oh-my-opencode.jsonc
3. mergeConfigs(user, project) → deepMerge for agents/categories, Set union for disabled_*
4. Zod safeParse → defaults for omitted fields
5. migrateConfigFile() → legacy key transformation
```
## PLUGIN INITIALIZATION (10 steps)
## HOOK COMPOSITION
1. `injectServerAuthIntoClient(ctx.client)` — Auth injection
2. `startTmuxCheck()` — Tmux availability
3. `loadPluginConfig(ctx.directory, ctx)` — User + project config merge → Zod validation
4. `createFirstMessageVariantGate()` — First message variant override gate
5. `createModelCacheState()` — Model context limits cache
6. `createManagers(...)` → 4 managers:
- `TmuxSessionManager` — Multi-pane tmux sessions
- `BackgroundManager` — Parallel subagent execution
- `SkillMcpManager` — MCP server lifecycle
- `ConfigHandler` — Plugin config API to OpenCode
7. `createTools(...)` → `createSkillContext()` + `createAvailableCategories()` + `createToolRegistry()`
8. `createHooks(...)` → `createCoreHooks()` + `createContinuationHooks()` + `createSkillHooks()`
9. `createPluginInterface(...)` → 7 OpenCode hook handlers
10. Return plugin with `experimental.session.compacting`
## HOOK REGISTRATION (3 tiers)
**Core Hooks** (`create-core-hooks.ts`):
- Session (20): context-window-monitor, session-recovery, think-mode, ralph-loop, anthropic-effort, ...
- Tool Guard (8): comment-checker, tool-output-truncator, rules-injector, write-existing-file-guard, ...
- Transform (4): claude-code-hooks, keyword-detector, context-injector, thinking-block-validator
**Continuation Hooks** (`create-continuation-hooks.ts`):
- 7 hooks: stop-continuation-guard, compaction-context-injector, todo-continuation-enforcer, atlas, ...
**Skill Hooks** (`create-skill-hooks.ts`):
- 2 hooks: category-skill-reminder, auto-slash-command
## PLUGIN INTERFACE (7 OpenCode handlers)
| Handler | Source | Purpose |
|---------|--------|---------|
| `tool` | filteredTools | All registered tools |
| `chat.params` | createChatParamsHandler | Anthropic effort level |
| `chat.message` | createChatMessageHandler | First message variant, session setup |
| `experimental.chat.messages.transform` | createMessagesTransformHandler | Context injection, keyword detection |
| `config` | configHandler | Agent/MCP/command registration |
| `event` | createEventHandler | Session lifecycle |
| `tool.execute.before` | createToolExecuteBeforeHandler | Pre-tool hooks |
| `tool.execute.after` | createToolExecuteAfterHandler | Post-tool hooks |
## SAFE HOOK CREATION PATTERN
```typescript
const hook = isHookEnabled("hook-name")
? safeCreateHook("hook-name", () => createHookFactory(ctx), { enabled: safeHookEnabled })
: null;
```
All hooks use this pattern for graceful degradation on failure.
createHooks()
├─→ createCoreHooks() # 33 hooks
│ ├─ createSessionHooks() # 20: contextWindowMonitor, thinkMode, ralphLoop, sessionRecovery...
│ ├─ createToolGuardHooks() # 9: commentChecker, rulesInjector, writeExistingFileGuard...
│ └─ createTransformHooks() # 4: claudeCodeHooks, keywordDetector, contextInjector, thinkingBlockValidator
├─→ createContinuationHooks() # 7: todoContinuationEnforcer, atlas, stopContinuationGuard...
└─→ createSkillHooks() # 2: categorySkillReminder, autoSlashCommand
```

134
src/agents/AGENTS.md
View File

@@ -1,85 +1,79 @@
# AGENTS KNOWLEDGE BASE
# src/agents/ — 11 Agent Definitions
**Generated:** 2026-02-17
## OVERVIEW
11 AI agents with factory functions, fallback chains, and model-specific prompt variants. Each agent has metadata (category, cost, triggers) and configurable tool restrictions.
Agent factories following `createXXXAgent(model) → AgentConfig` pattern. Each has static `mode` property. Built via `buildAgent()` compositing factory + categories + skills.
## STRUCTURE
```
agents/
├── sisyphus.ts # Main orchestrator (559 lines)
├── hephaestus.ts # Autonomous deep worker (651 lines)
├── oracle.ts # Strategic advisor (171 lines)
├── librarian.ts # Multi-repo research (329 lines)
├── explore.ts # Fast codebase grep (125 lines)
├── multimodal-looker.ts # Media analyzer (59 lines)
├── metis.ts # Pre-planning analysis (347 lines)
├── momus.ts # Plan validator (244 lines)
├── atlas/ # Master orchestrator (agent.ts + default.ts + gpt.ts)
├── prometheus/ # Planning agent (8 files, plan-template 423 lines)
├── sisyphus-junior/ # Delegated task executor (agent.ts + default.ts + gpt.ts)
├── dynamic-agent-prompt-builder.ts # Dynamic prompt generation (433 lines)
├── builtin-agents/ # Agent registry + model resolution
├── agent-builder.ts # Agent construction with category merging (51 lines)
├── utils.ts # Agent creation, model fallback resolution (571 lines)
├── types.ts # AgentModelConfig, AgentPromptMetadata (106 lines)
└── index.ts # Exports
```
## AGENT INVENTORY
## AGENT MODELS
| Agent | Model | Temp | Fallback Chain | Cost |
|-------|-------|------|----------------|------|
| Sisyphus | claude-opus-4-6 | 0.1 | kimi-k2.5 → glm-4.7 → gpt-5.3-codex → gemini-3-pro | EXPENSIVE |
| Hephaestus | gpt-5.3-codex | 0.1 | NONE (required) | EXPENSIVE |
| Atlas | claude-sonnet-4-5 | 0.1 | kimi-k2.5 → gpt-5.2 | EXPENSIVE |
| Prometheus | claude-opus-4-6 | 0.1 | kimi-k2.5 → gpt-5.2 | EXPENSIVE |
| oracle | gpt-5.2 | 0.1 | claude-opus-4-6 | EXPENSIVE |
| librarian | glm-4.7 | 0.1 | glm-4.7-free | CHEAP |
| explore | grok-code-fast-1 | 0.1 | claude-haiku-4-5 → gpt-5-mini → gpt-5-nano | FREE |
| multimodal-looker | gemini-3-flash | 0.1 | NONE | CHEAP |
| Metis | claude-opus-4-6 | 0.3 | kimi-k2.5 → gpt-5.2 | EXPENSIVE |
| Momus | gpt-5.2 | 0.1 | claude-opus-4-6 | EXPENSIVE |
| Sisyphus-Junior | claude-sonnet-4-5 | 0.1 | (user-configurable) | EXPENSIVE |
| Agent | Model | Temp | Mode | Fallback Chain | Purpose |
|-------|-------|------|------|----------------|---------|
| **Sisyphus** | claude-opus-4-6 | 0.1 | primary | kimi-k2.5 → glm-4.7 → gemini-3-pro | Main orchestrator, plans + delegates |
| **Hephaestus** | gpt-5.3-codex | 0.1 | primary | NONE (required) | Autonomous deep worker |
| **Oracle** | gpt-5.2 | 0.1 | subagent | claude-opus-4-6 → gemini-3-pro | Read-only consultation |
| **Librarian** | glm-4.7 | 0.1 | subagent | glm-4.7-free → claude-sonnet-4-5 | External docs/code search |
| **Explore** | grok-code-fast-1 | 0.1 | subagent | claude-haiku-4-5 → gpt-5-nano | Contextual grep |
| **Multimodal-Looker** | gemini-3-flash | 0.1 | subagent | gpt-5.2 → glm-4.6v → ... (6 deep) | PDF/image analysis |
| **Metis** | claude-opus-4-6 | **0.3** | subagent | kimi-k2.5 → gpt-5.2 → gemini-3-pro | Pre-planning consultant |
| **Momus** | gpt-5.2 | 0.1 | subagent | claude-opus-4-6 → gemini-3-pro | Plan reviewer |
| **Atlas** | claude-sonnet-4-5 | 0.1 | primary | kimi-k2.5 → gpt-5.2 → gemini-3-pro | Todo-list orchestrator |
| **Prometheus** | claude-opus-4-6 | 0.1 | — | kimi-k2.5 → gpt-5.2 → gemini-3-pro | Strategic planner (internal) |
| **Sisyphus-Junior** | claude-sonnet-4-5 | 0.1 | all | user-configurable | Category-spawned executor |
## TOOL RESTRICTIONS
| Agent | Denied | Allowed |
|-------|--------|---------|
| oracle | write, edit, task, call_omo_agent | Read-only consultation |
| librarian | write, edit, task, call_omo_agent | Research tools only |
| explore | write, edit, task, call_omo_agent | Search tools only |
| multimodal-looker | ALL except `read` | Vision-only |
| Sisyphus-Junior | task | No delegation |
| Atlas | task, call_omo_agent | Orchestration only |
| Agent | Denied Tools |
|-------|-------------|
| Oracle | write, edit, task, call_omo_agent |
| Librarian | write, edit, task, call_omo_agent |
| Explore | write, edit, task, call_omo_agent |
| Multimodal-Looker | ALL except read |
| Atlas | task, call_omo_agent |
| Momus | write, edit, task |
## THINKING / REASONING
## STRUCTURE
| Agent | Claude | GPT |
|-------|--------|-----|
| Sisyphus | 32k budget tokens | reasoningEffort: "medium" |
| Hephaestus | — | reasoningEffort: "medium" |
| Oracle | 32k budget tokens | reasoningEffort: "medium" |
| Metis | 32k budget tokens | — |
| Momus | 32k budget tokens | reasoningEffort: "medium" |
| Sisyphus-Junior | 32k budget tokens | reasoningEffort: "medium" |
```
agents/
├── sisyphus.ts # 559 LOC, main orchestrator
├── hephaestus.ts # 507 LOC, autonomous worker
├── oracle.ts # Read-only consultant
├── librarian.ts # External search
├── explore.ts # Codebase grep
├── multimodal-looker.ts # Vision/PDF
├── metis.ts # Pre-planning
├── momus.ts # Plan review
├── atlas/agent.ts # Todo orchestrator
├── types.ts # AgentFactory, AgentMode
├── agent-builder.ts # buildAgent() composition
├── utils.ts # Agent utilities
├── builtin-agents.ts # createBuiltinAgents() registry
└── builtin-agents/ # maybeCreateXXXConfig conditional factories
├── sisyphus-agent.ts
├── hephaestus-agent.ts
├── atlas-agent.ts
├── general-agents.ts # collectPendingBuiltinAgents
└── available-skills.ts
```
## KEY PROMPT PATTERNS
## FACTORY PATTERN
- **Sisyphus/Hephaestus**: Dynamic prompts via `dynamic-agent-prompt-builder.ts` injecting available tools/skills/categories
- **Atlas, Sisyphus-Junior**: Model-specific prompts (Claude vs GPT variants)
- **Prometheus**: 6-section modular prompt (identity → interview → plan-generation → high-accuracy → template → behavioral)
```typescript
const createXXXAgent: AgentFactory = (model: string) => ({
instructions: "...",
model,
temperature: 0.1,
// ...config
})
createXXXAgent.mode = "subagent" // or "primary" or "all"
```
## HOW TO ADD
Model resolution: `AGENT_MODEL_REQUIREMENTS` in `shared/model-requirements.ts` defines fallback chains per agent.
1. Create `src/agents/my-agent.ts` exporting factory + metadata
2. Add to `agentSources` in `src/agents/builtin-agents/`
3. Update `AgentNameSchema` in `src/config/schema/agent-names.ts`
4. Register in `src/plugin-handlers/agent-config-handler.ts`
## MODES
## ANTI-PATTERNS
- **Trust agent self-reports**: NEVER — always verify outputs
- **High temperature**: Don't use >0.3 for code agents
- **Sequential calls**: Use `task` with `run_in_background` for exploration
- **Prometheus writing code**: Planner only — never implements
- **primary**: Respects UI-selected model, uses fallback chain
- **subagent**: Uses own fallback chain, ignores UI selection
- **all**: Available in both contexts (Sisyphus-Junior)

112
src/cli/AGENTS.md
View File

@@ -1,69 +1,71 @@
# CLI KNOWLEDGE BASE
# src/cli/ — CLI: install, run, doctor, mcp-oauth
**Generated:** 2026-02-17
## OVERVIEW
CLI entry: `bunx oh-my-opencode`. 107+ files with Commander.js + @clack/prompts TUI. 5 commands: install, run, doctor, get-local-version, mcp-oauth.
## STRUCTURE
```
cli/
├── index.ts # Entry point (5 lines)
├── cli-program.ts # Commander.js program (150+ lines, 5 commands)
├── install.ts # TTY routing (TUI or CLI installer)
├── cli-installer.ts # Non-interactive installer (164 lines)
├── tui-installer.ts # Interactive TUI with @clack/prompts (140 lines)
├── config-manager/ # 20 config utilities
│ ├── add-plugin-to-opencode-config.ts # Plugin registration
│ ├── add-provider-config.ts # Provider setup (Google/Antigravity)
│ ├── detect-current-config.ts # Installed providers detection
│ ├── write-omo-config.ts # JSONC writing
│ ├── generate-omo-config.ts # Config generation
│ ├── jsonc-provider-editor.ts # JSONC editing
│ └── ... # 14 more utilities
├── doctor/ # 4 check categories, 21 check files
│ ├── runner.ts # Parallel check execution + result aggregation
│ ├── formatter.ts # Colored output (default/status/verbose/JSON)
│ └── checks/ # system (4), config (1), tools (4), models (6 sub-checks)
├── run/ # Session launcher (24 files)
│ ├── runner.ts # Run orchestration (126 lines)
│ ├── agent-resolver.ts # Agent: flag → env → config → Sisyphus
│ ├── session-resolver.ts # Session create or resume with retries
│ ├── event-handlers.ts # Event processing (125 lines)
│ ├── completion.ts # Completion detection
│ └── poll-for-completion.ts # Polling with timeout
├── mcp-oauth/ # OAuth token management (login, logout, status)
├── get-local-version/ # Version detection + update check
├── model-fallback.ts # Model fallback configuration
└── provider-availability.ts # Provider availability checks
```
Commander.js CLI with 5 commands. Entry: `index.ts` → `runCli()` in `cli-program.ts`.
## COMMANDS
| Command | Purpose | Key Logic |
|---------|---------|-----------|
| `install` | Interactive setup | Provider selection → config generation → plugin registration |
| `run` | Session launcher | Agent: flag → env → config → Sisyphus. Enforces todo completion. |
| `doctor` | 4-category health checks | system, config, tools, models (6 sub-checks) |
| `get-local-version` | Version check | Detects installed, compares with npm latest |
| `mcp-oauth` | OAuth tokens | login (PKCE flow), logout, status |
| `install` | Interactive/non-interactive setup | Provider selection → config gen → plugin registration |
| `run <message>` | Non-interactive session launcher | Agent resolution (flag → env → config → Sisyphus) |
| `doctor` | 4-category health checks | System, Config, Tools, Models |
| `get-local-version` | Version detection | Installed vs npm latest |
| `mcp-oauth` | OAuth token management | login (PKCE), logout, status |
## RUN SESSION LIFECYCLE
## STRUCTURE
1. Load config, resolve agent (CLI > env > config > Sisyphus)
2. Create server connection (port/attach), setup cleanup/signal handlers
3. Resolve session (create new or resume with retries)
4. Send prompt, start event processing, poll for completion
5. Execute on-complete hook, output JSON if requested, cleanup
```
cli/
├── index.ts # Entry point → runCli()
├── cli-program.ts # Commander.js program (5 commands)
├── install.ts # Routes to TUI or CLI installer
├── cli-installer.ts # Non-interactive (console output)
├── tui-installer.ts # Interactive (@clack/prompts)
├── model-fallback.ts # Model config gen by provider availability
├── provider-availability.ts # Provider detection
├── fallback-chain-resolution.ts # Fallback chain logic
├── config-manager/ # 20 config utilities
│ ├── plugin registration, provider config
│ ├── JSONC operations, auth plugins
│ └── npm dist-tags, binary detection
├── doctor/
│ ├── runner.ts # Parallel check execution
│ ├── formatter.ts # Output formatting
│ └── checks/ # 15 check files in 4 categories
│ ├── system.ts # Binary, plugin, version
│ ├── config.ts # JSONC validity, Zod schema
│ ├── tools.ts # AST-Grep, LSP, GH CLI, MCP
│ └── model-resolution.ts # Cache, resolution, overrides (6 sub-files)
├── run/ # Session launcher
│ ├── runner.ts # Main orchestration
│ ├── agent-resolver.ts # Flag → env → config → Sisyphus
│ ├── session-resolver.ts # Create/resume sessions
│ ├── event-handlers.ts # Event processing
│ └── poll-for-completion.ts # Wait for todos/background tasks
└── mcp-oauth/ # OAuth token management
```
## HOW TO ADD CHECK
## MODEL FALLBACK SYSTEM
1. Create `src/cli/doctor/checks/my-check.ts`
2. Export `getXXXCheckDefinition()` returning `CheckDefinition`
3. Add to `getAllCheckDefinitions()` in `checks/index.ts`
Priority: Claude > OpenAI > Gemini > Copilot > OpenCode Zen > Z.ai > Kimi > glm-4.7-free
## ANTI-PATTERNS
Agent-specific: librarian→ZAI, explore→Haiku/nano, hephaestus→requires OpenAI/Copilot
- **Blocking in non-TTY**: Check `process.stdout.isTTY`
- **Direct JSON.parse**: Use `parseJsonc()` from shared
- **Silent failures**: Return `warn` or `fail` in doctor, don't throw
- **Hardcoded paths**: Use `getOpenCodeConfigPaths()` from config-manager
## DOCTOR CHECKS
| Category | Validates |
|----------|-----------|
| **System** | Binary found, version >=1.0.150, plugin registered, version match |
| **Config** | JSONC validity, Zod schema, model override syntax |
| **Tools** | AST-Grep, comment-checker, LSP servers, GH CLI, MCP servers |
| **Models** | Cache exists, model resolution, agent/category overrides, availability |
## HOW TO ADD A DOCTOR CHECK
1. Create `src/cli/doctor/checks/{name}.ts`
2. Export check function matching `DoctorCheck` interface
3. Register in `checks/index.ts`

78
src/config/AGENTS.md
View File

@@ -1,52 +1,50 @@
# CONFIG KNOWLEDGE BASE
# src/config/ — Zod v4 Schema System
**Generated:** 2026-02-17
## OVERVIEW
Zod schema definitions for plugin configuration. 21 component files composing `OhMyOpenCodeConfigSchema` with multi-level inheritance and JSONC support.
22 schema files composing `OhMyOpenCodeConfigSchema`. Zod v4 validation with `safeParse()`. All fields optional — omitted fields use plugin defaults.
## SCHEMA TREE
## STRUCTURE
```
config/
├── schema/ # 21 schema component files
│ ├── oh-my-opencode-config.ts # Root schema composition (57 lines)
│ ├── agent-names.ts # BuiltinAgentNameSchema (11 agents), BuiltinSkillNameSchema
│ ├── agent-overrides.ts # AgentOverrideConfigSchema (model, variant, temp, thinking...)
│ ├── categories.ts # 8 categories: visual-engineering, ultrabrain, deep, artistry, quick, ...
│ ├── hooks.ts # HookNameSchema (100+ hook names)
│ ├── commands.ts # BuiltinCommandNameSchema
│ ├── experimental.ts # ExperimentalConfigSchema
│ ├── dynamic-context-pruning.ts # DynamicContextPruningConfigSchema (55 lines)
│ ├── background-task.ts # BackgroundTaskConfigSchema
│ ├── claude-code.ts # ClaudeCodeConfigSchema
│ ├── comment-checker.ts # CommentCheckerConfigSchema
│ ├── notification.ts # NotificationConfigSchema
│ ├── ralph-loop.ts # RalphLoopConfigSchema
│ ├── sisyphus.ts # SisyphusConfigSchema
│ ├── sisyphus-agent.ts # SisyphusAgentConfigSchema
│ ├── skills.ts # SkillsConfigSchema (45 lines)
│ ├── tmux.ts # TmuxConfigSchema, TmuxLayoutSchema
│ ├── websearch.ts # WebsearchConfigSchema
│ ├── browser-automation.ts # BrowserAutomationConfigSchema
│ ├── git-master.ts # GitMasterConfigSchema
│ └── babysitting.ts # BabysittingConfigSchema
├── schema.ts # Barrel export (24 lines)
├── schema.test.ts # Validation tests (735 lines)
├── types.ts # TypeScript types from schemas
└── index.ts # Barrel export (33 lines)
config/schema/
├── oh-my-opencode-config.ts # ROOT: OhMyOpenCodeConfigSchema (composes all below)
├── agent-names.ts # BuiltinAgentNameSchema (11), OverridableAgentNameSchema (14)
├── agent-overrides.ts # AgentOverrideConfigSchema (21 fields per agent)
├── categories.ts # 8 built-in + custom categories
├── hooks.ts # HookNameSchema (46 hooks)
├── skills.ts # SkillsConfigSchema (sources, paths, recursive)
├── commands.ts # BuiltinCommandNameSchema
├── experimental.ts # Feature flags (plugin_load_timeout_ms min 1000, hashline_edit)
├── sisyphus.ts # SisyphusConfigSchema (task system)
├── sisyphus-agent.ts # SisyphusAgentConfigSchema
├── ralph-loop.ts # RalphLoopConfigSchema
├── tmux.ts # TmuxConfigSchema + TmuxLayoutSchema
├── websearch.ts # provider: "exa" | "tavily"
├── claude-code.ts # CC compatibility settings
├── comment-checker.ts # AI comment detection config
├── notification.ts # OS notification settings
├── git-master.ts # commit_footer: boolean | string
├── browser-automation.ts # provider: playwright | agent-browser | playwright-cli
├── background-task.ts # Concurrency limits per model/provider
├── babysitting.ts # Unstable agent monitoring
├── dynamic-context-pruning.ts # Context pruning settings
└── internal/permission.ts # AgentPermissionSchema
```
## ROOT SCHEMA
## ROOT SCHEMA FIELDS (26)
`OhMyOpenCodeConfigSchema` composes: `$schema`, `new_task_system_enabled`, `default_run_agent`, `auto_update`, `disabled_{mcps,agents,skills,hooks,commands,tools}`, `agents` (14 agent keys), `categories` (8 built-in), `claude_code`, `sisyphus_agent`, `comment_checker`, `experimental`, `skills`, `ralph_loop`, `background_task`, `notification`, `babysitting`, `git_master`, `browser_automation_engine`, `websearch`, `tmux`, `sisyphus`
`$schema`, `new_task_system_enabled`, `default_run_agent`, `disabled_mcps`, `disabled_agents`, `disabled_skills`, `disabled_hooks`, `disabled_commands`, `disabled_tools`, `agents`, `categories`, `claude_code`, `sisyphus_agent`, `comment_checker`, `experimental`, `auto_update`, `skills`, `ralph_loop`, `background_task`, `notification`, `babysitting`, `git_master`, `browser_automation_engine`, `websearch`, `tmux`, `sisyphus`, `_migrations`
## CONFIGURATION HIERARCHY
## AGENT OVERRIDE FIELDS (21)
Project (`.opencode/oh-my-opencode.json`) → User (`~/.config/opencode/oh-my-opencode.json`) → Defaults
`model`, `variant`, `category`, `skills`, `temperature`, `top_p`, `prompt`, `prompt_append`, `tools`, `disable`, `description`, `mode`, `color`, `permission`, `maxTokens`, `thinking`, `reasoningEffort`, `textVerbosity`, `providerOptions`
## AGENT OVERRIDE FIELDS
## HOW TO ADD CONFIG
`model`, `variant`, `category`, `skills`, `temperature`, `top_p`, `maxTokens`, `thinking`, `reasoningEffort`, `textVerbosity`, `prompt`, `prompt_append`, `tools`, `permission`, `providerOptions`, `disable`, `description`, `mode`, `color`
## AFTER SCHEMA CHANGES
Run `bun run build:schema` to regenerate `dist/oh-my-opencode.schema.json`
1. Create `src/config/schema/{name}.ts` with Zod schema
2. Add field to `oh-my-opencode-config.ts` root schema
3. Reference via `z.infer<typeof YourSchema>` for TypeScript types
4. Access in handlers via `pluginConfig.{name}`

126
src/features/AGENTS.md
View File

@@ -1,83 +1,69 @@
# FEATURES KNOWLEDGE BASE
# src/features/ — 18 Feature Modules
**Generated:** 2026-02-17
## OVERVIEW
18 feature modules extending plugin capabilities: agent orchestration, skill loading, Claude Code compatibility, MCP management, task storage, and tmux integration.
Standalone feature modules wired into plugin/ layer. Each is self-contained with own types, implementation, and tests.
## STRUCTURE
```
features/
├── background-agent/ # Task lifecycle, concurrency (56 files, 1701-line manager)
│ ├── manager.ts # Main task orchestration (1701 lines)
│ ├── concurrency.ts # Parallel execution limits per provider/model (137 lines)
│ ├── task-history.ts # Task execution history per parent session (76 lines)
│ └── spawner/ # Task spawning: factory, starter, resumer, tmux (8 files)
├── tmux-subagent/ # Tmux integration (28 files, 3303 LOC)
│ └── manager.ts # Pane management, grid planning (350 lines)
├── opencode-skill-loader/ # YAML frontmatter skill loading (28 files, 2967 LOC)
│ ├── loader.ts # Skill discovery (4 scopes)
│ ├── skill-directory-loader.ts # Recursive directory scanning (maxDepth=2)
│ ├── skill-discovery.ts # getAllSkills() with caching + provider gating
│ └── merger/ # Skill merging with scope priority
├── mcp-oauth/ # OAuth 2.0 flow for MCP (18 files, 2164 LOC)
│ ├── provider.ts # McpOAuthProvider class
│ ├── oauth-authorization-flow.ts # PKCE, callback handling
│ └── dcr.ts # Dynamic Client Registration (RFC 7591)
├── skill-mcp-manager/ # MCP client lifecycle per session (12 files, 1769 LOC)
│ └── manager.ts # SkillMcpManager class (150 lines)
├── builtin-skills/ # 5 built-in skills (10 files, 1921 LOC)
│ └── skills/ # git-master (1112), playwright (313), dev-browser (222), frontend-ui-ux (80)
├── builtin-commands/ # 7 command templates (11 files, 1511 LOC)
│ └── templates/ # refactor (620), init-deep (306), handoff (178), start-work, ralph-loop, stop-continuation
├── claude-tasks/ # Task schema + storage (7 files) — see AGENTS.md
├── context-injector/ # AGENTS.md, README.md, rules injection (6 files, 809 LOC)
├── claude-code-plugin-loader/ # Plugin discovery from .opencode/plugins/ (10 files)
├── claude-code-mcp-loader/ # .mcp.json with ${VAR} expansion (6 files)
├── claude-code-command-loader/ # Command loading from .opencode/commands/ (3 files)
├── claude-code-agent-loader/ # Agent loading from .opencode/agents/ (3 files)
├── claude-code-session-state/ # Subagent session state tracking (3 files)
├── hook-message-injector/ # System message injection (4 files)
├── task-toast-manager/ # Task progress notifications (4 files)
├── boulder-state/ # Persistent state for multi-step ops (5 files)
└── tool-metadata-store/ # Tool execution metadata caching (3 files)
```
## MODULE MAP
## KEY PATTERNS
| Module | Files | Complexity | Purpose |
|--------|-------|------------|---------|
| **background-agent** | 49 | HIGH | Task lifecycle, concurrency (5/model), polling, spawner pattern |
| **tmux-subagent** | 27 | HIGH | Tmux pane management, grid planning, session orchestration |
| **opencode-skill-loader** | 25 | HIGH | YAML frontmatter skill loading from 4 scopes |
| **mcp-oauth** | 10 | HIGH | OAuth 2.0 + PKCE + DCR (RFC 7591) for MCP servers |
| **builtin-skills** | 10 | LOW | 6 skills: git-master, playwright, playwright-cli, agent-browser, dev-browser, frontend-ui-ux |
| **skill-mcp-manager** | 10 | MEDIUM | MCP client lifecycle per session (stdio + HTTP) |
| **claude-code-plugin-loader** | 10 | MEDIUM | Unified plugin discovery from .opencode/plugins/ |
| **builtin-commands** | 9 | LOW | Command templates: refactor, init-deep, handoff, etc. |
| **claude-code-mcp-loader** | 5 | MEDIUM | .mcp.json loading with ${VAR} env expansion |
| **context-injector** | 4 | MEDIUM | AGENTS.md/README.md injection into context |
| **boulder-state** | 4 | LOW | Persistent state for multi-step operations |
| **hook-message-injector** | 4 | MEDIUM | System message injection for hooks |
| **claude-tasks** | 4 | MEDIUM | Task schema + file storage + OpenCode todo sync |
| **task-toast-manager** | 3 | MEDIUM | Task progress notifications |
| **claude-code-agent-loader** | 3 | LOW | Load agents from .opencode/agents/ |
| **claude-code-command-loader** | 3 | LOW | Load commands from .opencode/commands/ |
| **claude-code-session-state** | 2 | LOW | Subagent session state tracking |
| **tool-metadata-store** | 2 | LOW | Tool execution metadata cache |
**Background Agent Lifecycle:**
pending → running → completed/error/cancelled/interrupt
- Concurrency: Per provider/model limits (default: 5), queue-based FIFO
- Events: session.idle + session.error drive completion detection
- Key methods: `launch()`, `resume()`, `cancelTask()`, `getTask()`, `getAllDescendantTasks()`
## KEY MODULES
**Skill Loading Pipeline (4-scope priority):**
opencode-project (`.opencode/skills/`) > opencode (`~/.config/opencode/skills/`) > project (`.claude/skills/`) > user (`~/.claude/skills/`)
### background-agent (49 files, ~10k LOC)
**Claude Code Compatibility Layer:**
5 loaders: agent-loader, command-loader, mcp-loader, plugin-loader, session-state
Core orchestration engine. `BackgroundManager` manages task lifecycle:
- States: pending → running → completed/error/cancelled/interrupt
- Concurrency: per-model/provider limits via `ConcurrencyManager` (FIFO queue)
- Polling: 3s interval, completion via idle events + stability detection (10s unchanged)
- spawner/: 8 focused files composing via `SpawnerContext` interface
**SKILL.md Format:**
```yaml
---
name: my-skill
description: "..."
model: "claude-opus-4-6" # optional
agent: "sisyphus" # optional
mcp: # optional embedded MCPs
server-name:
type: http
url: https://...
---
# Skill instruction content
```
### opencode-skill-loader (25 files, ~3.2k LOC)
## HOW TO ADD
4-scope skill discovery (project > opencode > user > global):
- YAML frontmatter parsing from SKILL.md files
- Skill merger with priority deduplication
- Template resolution with variable substitution
- Provider gating for model-specific skills
1. Create directory under `src/features/`
2. Add `index.ts`, `types.ts`, `constants.ts` as needed
3. Export from `index.ts` following barrel pattern
4. Register in main plugin if plugin-level feature
### tmux-subagent (27 files, ~3.6k LOC)
## CHILD DOCUMENTATION
State-first tmux integration:
- `TmuxSessionManager`: pane lifecycle, grid planning
- Spawn action decider + target finder
- Polling manager for session health
- Event handlers for pane creation/destruction
- See `claude-tasks/AGENTS.md` for task schema and storage details
### builtin-skills (6 skill objects)
| Skill | Size | MCP | Tools |
|-------|------|-----|-------|
| git-master | 1111 LOC | — | Bash |
| playwright | 312 LOC | @playwright/mcp | — |
| agent-browser | (in playwright.ts) | — | Bash(agent-browser:*) |
| playwright-cli | 268 LOC | — | Bash(playwright-cli:*) |
| dev-browser | 221 LOC | — | Bash |
| frontend-ui-ux | 79 LOC | — | — |
Browser variant selected by `browserProvider` config: playwright (default) | playwright-cli | agent-browser.

81
src/features/claude-tasks/AGENTS.md
View File

@@ -1,68 +1,43 @@
# CLAUDE TASKS KNOWLEDGE BASE
# src/features/claude-tasks/ — Task Schema + Storage
**Generated:** 2026-02-17
## OVERVIEW
Claude Code compatible task schema and storage. Core task management with file-based persistence, atomic writes, and OpenCode todo sync.
## STRUCTURE
```
claude-tasks/
├── types.ts # Task schema (Zod)
├── types.test.ts # Schema validation tests
├── storage.ts # File operations (atomic write, locking)
├── storage.test.ts # Storage tests (30 tests, 543 lines)
├── session-storage.ts # Session-scoped task storage
├── session-storage.test.ts
└── index.ts # Barrel exports
```
4 non-test files (~622 LOC). File-based task persistence with atomic writes, locking, and OpenCode todo API sync.
## TASK SCHEMA
```typescript
type TaskStatus = "pending" | "in_progress" | "completed" | "deleted"
interface Task {
id: string // T-{uuid}
subject: string // Imperative: "Run tests"
description: string
status: TaskStatus
activeForm?: string // Present continuous: "Running tests"
blocks: string[] // Task IDs this task blocks
blockedBy: string[] // Task IDs blocking this task
owner?: string // Agent name
id: string // T-{uuid} auto-generated
subject: string // Short title
description?: string // Detailed description
status: "pending" | "in_progress" | "completed" | "deleted"
activeForm?: string // Current form/template
blocks?: string[] // Tasks this blocks
blockedBy?: string[] // Tasks blocking this
owner?: string // Agent/session
metadata?: Record<string, unknown>
repoURL?: string
parentID?: string
threadID?: string
repoURL?: string // Associated repository
parentID?: string // Parent task ID
threadID?: string // Session ID (auto-recorded)
}
```
## STORAGE UTILITIES
## FILES
| Function | Purpose |
|----------|---------|
| `getTaskDir(config)` | Task storage directory path |
| `resolveTaskListId(config)` | Task list ID (env → config → cwd) |
| `readJsonSafe(path, schema)` | Parse + validate, null on failure |
| `writeJsonAtomic(path, data)` | Atomic write via temp + rename |
| `acquireLock(dirPath)` | File lock with 30s stale threshold |
| `generateTaskId()` | `T-{uuid}` format |
| `findTaskAcrossSessions(config, taskId)` | Locate task in any session |
| File | Purpose |
|------|---------|
| `types.ts` | Task interface + status types |
| `storage.ts` | `readJsonSafe()`, `writeJsonAtomic()`, `acquireLock()`, `generateTaskId()` |
| `session-storage.ts` | Per-session task storage, threadID auto-recording |
| `index.ts` | Barrel exports |
## TODO SYNC
## STORAGE
Automatic bidirectional sync between tasks and OpenCode's todo system.
| Task Status | Todo Status |
|-------------|-------------|
| `pending` | `pending` |
| `in_progress` | `in_progress` |
| `completed` | `completed` |
| `deleted` | `null` (removed) |
Sync triggers: `task_create`, `task_update`.
## ANTI-PATTERNS
- Direct fs operations (use storage utilities)
- Skipping lock acquisition for writes
- Using old field names (title → subject, dependsOn → blockedBy)
- Location: `.sisyphus/tasks/` directory
- Format: JSON files, one per task
- Atomic writes: temp file → rename
- Locking: file-based lock for concurrent access
- Sync: Changes pushed to OpenCode Todo API after each update

180
src/hooks/AGENTS.md
View File

@@ -1,95 +1,113 @@
# HOOKS KNOWLEDGE BASE
# src/hooks/ — 41 Lifecycle Hooks
**Generated:** 2026-02-17
## OVERVIEW
41 lifecycle hooks intercepting/modifying agent behavior across 7 event types. Three-tier registration: Core (32) → Continuation (7) → Skill (2).
41 hooks across 37 directories + 6 standalone files. Three-tier composition: Core(33) + Continuation(7) + Skill(2). All hooks follow `createXXXHook(deps) → HookFunction` factory pattern.
## STRUCTURE
```
hooks/
├── agent-usage-reminder/ # Specialized agent hints (109 lines)
├── anthropic-context-window-limit-recovery/ # Auto-summarize on limit (2232 lines, 29 files)
├── anthropic-effort/ # Effort=max for Opus max variant (56 lines)
├── atlas/ # Main orchestration hook (1976 lines, 17 files)
├── auto-slash-command/ # Detects /command patterns (1134 lines)
├── auto-update-checker/ # Plugin update check (1140 lines, 20 files)
├── background-notification/ # OS notifications (33 lines)
├── category-skill-reminder/ # Category+skill delegation reminders (597 lines)
├── claude-code-hooks/ # settings.json compat (2110 lines) — see AGENTS.md
├── comment-checker/ # Prevents AI slop comments (710 lines)
├── compaction-context-injector/ # Injects context on compaction (128 lines)
├── compaction-todo-preserver/ # Preserves todos during compaction (203 lines)
├── context-window-monitor.ts # Reminds of headroom at 70% (100 lines)
├── delegate-task-retry/ # Retries failed delegations (266 lines)
├── directory-agents-injector/ # Auto-injects AGENTS.md (195 lines)
├── directory-readme-injector/ # Auto-injects README.md (190 lines)
├── edit-error-recovery/ # Recovers from edit failures (188 lines)
├── empty-task-response-detector.ts # Detects empty responses (27 lines)
├── interactive-bash-session/ # Tmux session management (695 lines)
├── keyword-detector/ # ultrawork/search/analyze modes (1665 lines)
├── non-interactive-env/ # Non-TTY handling (483 lines)
├── preemptive-compaction.ts # Auto-compact at 78% usage (108 lines)
├── prometheus-md-only/ # Planner read-only mode (955 lines)
├── question-label-truncator/ # Truncates labels to 30 chars (199 lines)
├── ralph-loop/ # Self-referential dev loop (1687 lines)
├── rules-injector/ # Conditional .sisyphus/rules injection (1604 lines)
├── session-notification.ts # OS idle notifications (108 lines)
├── session-recovery/ # Auto-recovers from crashes (1279 lines, 14 files)
├── sisyphus-junior-notepad/ # Junior notepad directive (76 lines)
├── start-work/ # Sisyphus work session starter (648 lines)
├── stop-continuation-guard/ # Guards stop continuation (214 lines)
├── subagent-question-blocker/ # Blocks subagent questions (112 lines)
├── task-reminder/ # Task progress reminders (210 lines)
├── task-resume-info/ # Resume info for cancelled tasks (39 lines)
├── tasks-todowrite-disabler/ # Disables TodoWrite when tasks active (202 lines)
├── think-mode/ # Dynamic thinking budget (1365 lines)
├── thinking-block-validator/ # Validates thinking blocks (169 lines)
├── todo-continuation-enforcer/ # Force TODO completion — boulder mechanism (2061 lines)
├── tool-output-truncator.ts # Prevents context bloat (62 lines)
├── unstable-agent-babysitter/ # Monitors unstable behavior (451 lines)
└── write-existing-file-guard/ # Guards against file overwrite (356 lines)
```
## HOOK TIERS
## EVENT TYPES
### Tier 1: Session Hooks (20) — `create-session-hooks.ts`
| Event | Hook Method | Can Block | Count |
|-------|-------------|-----------|-------|
| UserPromptSubmit | `chat.message` | Yes | 4 |
| ChatParams | `chat.params` | No | 2 |
| PreToolUse | `tool.execute.before` | Yes | 13 |
| PostToolUse | `tool.execute.after` | No | 15 |
| SessionEvent | `event` | No | 17 |
| MessagesTransform | `experimental.chat.messages.transform` | No | 1 |
| Compaction | `onSummarize` | No | 2 |
| Hook | Event | Purpose |
|------|-------|---------|
| contextWindowMonitor | session.idle | Track context window usage |
| preemptiveCompaction | session.idle | Trigger compaction before limit |
| sessionRecovery | session.error | Auto-retry on recoverable errors |
| sessionNotification | session.idle | OS notifications on completion |
| thinkMode | chat.params | Model variant switching (extended thinking) |
| anthropicContextWindowLimitRecovery | session.error | Multi-strategy context recovery (truncation, compaction) |
| autoUpdateChecker | session.created | Check npm for plugin updates |
| agentUsageReminder | chat.message | Remind about available agents |
| nonInteractiveEnv | chat.message | Adjust behavior for `run` command |
| interactiveBashSession | tool.execute | Tmux session for interactive tools |
| ralphLoop | event | Self-referential dev loop (boulder continuation) |
| editErrorRecovery | tool.execute.after | Retry failed file edits |
| delegateTaskRetry | tool.execute.after | Retry failed task delegations |
| startWork | chat.message | `/start-work` command handler |
| prometheusMdOnly | tool.execute.before | Enforce .md-only writes for Prometheus |
| sisyphusJuniorNotepad | chat.message | Notepad injection for subagents |
| questionLabelTruncator | tool.execute.before | Truncate long question labels |
| taskResumeInfo | chat.message | Inject task context on resume |
| anthropicEffort | chat.params | Adjust reasoning effort level |
## BLOCKING HOOKS (8)
### Tier 2: Tool Guard Hooks (9) — `create-tool-guard-hooks.ts`
| Hook | Event | Blocks When |
|------|-------|-------------|
| auto-slash-command | chat.message | Command execution fails |
| keyword-detector | chat.message | Keyword injection fails |
| non-interactive-env | tool.execute.before | Interactive command in non-TTY |
| prometheus-md-only | tool.execute.before | Write outside .sisyphus/*.md |
| subagent-question-blocker | tool.execute.before | Question tool in subagent |
| tasks-todowrite-disabler | tool.execute.before | TodoWrite with task system |
| write-existing-file-guard | tool.execute.before | Write to existing file |
| claude-code-hooks | tool.execute.before | Exit code 2 from settings.json hook |
| Hook | Event | Purpose |
|------|-------|---------|
| commentChecker | tool.execute.after | Block AI-generated comment patterns |
| toolOutputTruncator | tool.execute.after | Truncate oversized tool output |
| directoryAgentsInjector | tool.execute.before | Inject dir AGENTS.md into context |
| directoryReadmeInjector | tool.execute.before | Inject dir README.md into context |
| emptyTaskResponseDetector | tool.execute.after | Detect empty task responses |
| rulesInjector | tool.execute.before | Conditional rules injection (AGENTS.md, config) |
| tasksTodowriteDisabler | tool.execute.before | Disable TodoWrite when task system active |
| writeExistingFileGuard | tool.execute.before | Require Read before Write on existing files |
| hashlineReadEnhancer | tool.execute.after | Enhance Read output with line hashes |
## EXECUTION ORDER
### Tier 3: Transform Hooks (4) — `create-transform-hooks.ts`
**UserPromptSubmit**: keywordDetector → claudeCodeHooks → autoSlashCommand → startWork
**PreToolUse**: subagentQuestionBlocker → questionLabelTruncator → claudeCodeHooks → nonInteractiveEnv → commentChecker → directoryAgentsInjector → directoryReadmeInjector → rulesInjector → prometheusMdOnly → sisyphusJuniorNotepad → writeExistingFileGuard → tasksToDoWriteDisabler → atlasHook
**PostToolUse**: claudeCodeHooks → toolOutputTruncator → contextWindowMonitor → commentChecker → directoryAgentsInjector → directoryReadmeInjector → rulesInjector → emptyTaskResponseDetector → agentUsageReminder → interactiveBashSession → editErrorRecovery → delegateTaskRetry → atlasHook → taskResumeInfo → taskReminder
| Hook | Event | Purpose |
|------|-------|---------|
| claudeCodeHooks | messages.transform | Claude Code settings.json compatibility |
| keywordDetector | messages.transform | Detect ultrawork/search/analyze modes |
| contextInjectorMessagesTransform | messages.transform | Inject AGENTS.md/README.md into context |
| thinkingBlockValidator | messages.transform | Validate thinking block structure |
## HOW TO ADD
### Tier 4: Continuation Hooks (7) — `create-continuation-hooks.ts`
1. Create `src/hooks/name/` with `index.ts` exporting `createMyHook(ctx)`
2. Add hook name to `HookNameSchema` in `src/config/schema/hooks.ts`
3. Register in appropriate `src/plugin/hooks/create-*-hooks.ts`
| Hook | Event | Purpose |
|------|-------|---------|
| stopContinuationGuard | chat.message | `/stop-continuation` command handler |
| compactionContextInjector | session.compacted | Re-inject context after compaction |
| compactionTodoPreserver | session.compacted | Preserve todos through compaction |
| todoContinuationEnforcer | session.idle | **Boulder**: force continuation on incomplete todos |
| unstableAgentBabysitter | session.idle | Monitor unstable agent behavior |
| backgroundNotificationHook | event | Background task completion notifications |
| atlasHook | event | Master orchestrator for boulder/background sessions |
## ANTI-PATTERNS
### Tier 5: Skill Hooks (2) — `create-skill-hooks.ts`
- **Heavy PreToolUse**: Runs before EVERY tool — keep light
- **Blocking non-critical**: Use PostToolUse warnings instead
- **Redundant injection**: Track injected files to avoid context bloat
- **Direct state mutation**: Use `output.output +=` instead of replacing
| Hook | Event | Purpose |
|------|-------|---------|
| categorySkillReminder | chat.message | Remind about category+skill delegation |
| autoSlashCommand | chat.message | Auto-detect `/command` in user input |
## KEY HOOKS (COMPLEX)
### anthropic-context-window-limit-recovery (31 files, ~2232 LOC)
Multi-strategy recovery when hitting context limits. Strategies: truncation, compaction, summarization.
### atlas (17 files, ~1976 LOC)
Master orchestrator for boulder sessions. Decision gates: session type → abort check → failure count → background tasks → agent match → plan completeness → cooldown (5s). Injects continuation prompts on session.idle.
### ralph-loop (14 files, ~1687 LOC)
Self-referential dev loop via `/ralph-loop` command. State persisted in `.sisyphus/ralph-loop.local.md`. Detects `<promise>DONE</promise>` in AI output. Max 100 iterations default.
### todo-continuation-enforcer (13 files, ~2061 LOC)
"Boulder" mechanism. Forces agent to continue when todos remain incomplete. 2s countdown toast → continuation injection. Exponential backoff: 30s base, ×2 per failure, max 5 consecutive failures then 5min pause.
### keyword-detector (~1665 LOC)
Detects modes from user input: ultrawork, search, analyze, prove-yourself. Injects mode-specific system prompts.
### rules-injector (19 files, ~1604 LOC)
Conditional rules injection from AGENTS.md, config, skill rules. Evaluates conditions to determine which rules apply.
## STANDALONE HOOKS (in src/hooks/ root)
| File | Purpose |
|------|---------|
| context-window-monitor.ts | Track context window percentage |
| preemptive-compaction.ts | Trigger compaction before hard limit |
| tool-output-truncator.ts | Truncate tool output by token count |
| session-notification.ts + 4 helpers | OS notification on session completion |
| empty-task-response-detector.ts | Detect empty/failed task responses |
| session-todo-status.ts | Todo completion status tracking |
## HOW TO ADD A HOOK
1. Create `src/hooks/{name}/index.ts` with `createXXXHook(deps)` factory
2. Register in appropriate tier file (`src/plugin/hooks/create-{tier}-hooks.ts`)
3. Add hook name to `src/config/schema/hooks.ts` HookNameSchema
4. Hook receives `(event, ctx)` — return value depends on event type

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

@@ -1,55 +1,41 @@
# CLAUDE CODE HOOKS COMPATIBILITY
# src/hooks/claude-code-hooks/ — Claude Code Compatibility
**Generated:** 2026-02-17
## OVERVIEW
Full Claude Code `settings.json` hook compatibility layer. Intercepts OpenCode events to execute external scripts/commands defined in settings.json.
~2110 LOC across 19 files. Provides Claude Code settings.json compatibility layer. Parses CC permission rules and maps CC hooks (PreToolUse, PostToolUse) to OpenCode hooks.
**Config Sources** (priority): `.claude/settings.local.json` > `.claude/settings.json` (project) > `~/.claude/settings.json` (global)
## WHAT IT DOES
## STRUCTURE
```
claude-code-hooks/
├── index.ts # Barrel export
├── claude-code-hooks-hook.ts # Main factory (22 lines)
├── config.ts # Claude settings.json loader (105 lines)
├── config-loader.ts # Extended plugin config (107 lines)
├── pre-tool-use.ts # PreToolUse hook executor (173 lines)
├── post-tool-use.ts # PostToolUse hook executor (200 lines)
├── user-prompt-submit.ts # UserPromptSubmit executor (125 lines)
├── stop.ts # Stop hook executor (122 lines)
├── pre-compact.ts # PreCompact executor (110 lines)
├── transcript.ts # Tool use recording (235 lines)
├── tool-input-cache.ts # Pre→post input caching (51 lines)
├── todo.ts # Todo integration
├── session-hook-state.ts # Active state tracking (11 lines)
├── types.ts # Hook & IO type definitions (204 lines)
├── plugin-config.ts # Default config constants (12 lines)
└── handlers/ # Event handlers (5 files)
├── pre-compact-handler.ts
├── tool-execute-before-handler.ts
├── tool-execute-after-handler.ts
├── chat-message-handler.ts
└── session-event-handler.ts
1. Parses Claude Code `settings.json` permission format
2. Maps CC hook types to OpenCode event types
3. Enforces CC permission rules (allow/deny per tool)
4. Supports CC `.claude/settings.json` and `.claude/settings.local.json`
## CC → OPENCODE HOOK MAPPING
| CC Hook | OpenCode Event |
|---------|---------------|
| PreToolUse | tool.execute.before |
| PostToolUse | tool.execute.after |
| Notification | event (session.idle) |
| Stop | event (session.idle) |
## PERMISSION SYSTEM
CC permissions format:
```json
{
"permissions": {
"allow": ["Edit", "Write"],
"deny": ["Bash(rm:*)"]
}
}
```
## HOOK LIFECYCLE
Translated to OpenCode tool restrictions via permission-compat in shared/.
| Event | Timing | Can Block | Context Provided |
|-------|--------|-----------|------------------|
| PreToolUse | Before exec | Yes (exit 2) | sessionId, toolName, toolInput, cwd |
| PostToolUse | After exec | Warn (exit 1) | + toolOutput, transcriptPath |
| UserPromptSubmit | On message | Yes (exit 2) | sessionId, prompt, parts, cwd |
| Stop | Session end | Inject | sessionId, parentSessionId, cwd |
| PreCompact | Before summarize | No | sessionId, cwd |
## FILES
## EXIT CODES
- `0`: Pass (continue)
- `1`: Warn (continue + system message)
- `2`: Block (abort operation)
## ANTI-PATTERNS
- **Heavy PreToolUse**: Runs before EVERY tool — keep scripts fast
- **Blocking non-critical**: Prefer PostToolUse warnings
- **Ignoring exit codes**: Return `2` to block sensitive tools
Key files: `settings-loader.ts` (parse CC settings), `hook-mapper.ts` (CC→OC mapping), `permission-handler.ts` (rule enforcement), `types.ts` (CC type definitions).

78
src/mcp/AGENTS.md
View File

@@ -1,54 +1,58 @@
# MCP KNOWLEDGE BASE
# src/mcp/ — 3 Built-in Remote MCPs
**Generated:** 2026-02-17
## OVERVIEW
Tier 1 of three-tier MCP system: 3 built-in remote HTTP MCPs.
Tier 1 of the three-tier MCP system. 3 remote HTTP MCPs created via `createBuiltinMcps(disabledMcps, config)`.
**Three-Tier System**:
1. **Built-in** (this directory): websearch, context7, grep_app
2. **Claude Code compat** (`features/claude-code-mcp-loader/`): .mcp.json with `${VAR}` expansion
3. **Skill-embedded** (`features/opencode-skill-loader/`): YAML frontmatter in SKILL.md
## BUILT-IN MCPs
## STRUCTURE
```
mcp/
├── index.ts # createBuiltinMcps() factory
├── index.test.ts # Tests
├── websearch.ts # Exa AI / Tavily web search
├── context7.ts # Library documentation
├── grep-app.ts # GitHub code search
└── types.ts # McpNameSchema
```
| Name | URL | Env Vars | Tools |
|------|-----|----------|-------|
| **websearch** | `mcp.exa.ai` (default) or `mcp.tavily.com` | `EXA_API_KEY` (optional), `TAVILY_API_KEY` (if tavily) | Web search |
| **context7** | `mcp.context7.com/mcp` | `CONTEXT7_API_KEY` (optional) | Library documentation |
| **grep_app** | `mcp.grep.app` | None | GitHub code search |
## MCP SERVERS
| Name | URL | Auth | Purpose |
|------|-----|------|---------|
| websearch | mcp.exa.ai/mcp (default) or mcp.tavily.com/mcp/ | EXA_API_KEY (optional) / TAVILY_API_KEY (required) | Real-time web search |
| context7 | mcp.context7.com/mcp | CONTEXT7_API_KEY (optional) | Library docs lookup |
| grep_app | mcp.grep.app | None | GitHub code search |
## CONFIG PATTERN
## REGISTRATION PATTERN
```typescript
export const mcp_name = {
// Static export (context7, grep_app)
export const context7 = {
type: "remote" as const,
url: "https://...",
url: "https://mcp.context7.com/mcp",
enabled: true,
oauth: false as const,
headers?: { ... },
}
// Factory with config (websearch)
export function createWebsearchConfig(config?: WebsearchConfig): RemoteMcpConfig
```
## HOW TO ADD
## ENABLE/DISABLE
1. Create `src/mcp/my-mcp.ts` with config object
2. Add conditional check in `createBuiltinMcps()` in `index.ts`
3. Add name to `McpNameSchema` in `types.ts`
```jsonc
// Method 1: disabled_mcps array
{ "disabled_mcps": ["websearch", "context7"] }
## NOTES
// Method 2: enabled flag
{ "mcp": { "websearch": { "enabled": false } } }
```
- **Remote only**: HTTP/SSE transport, no stdio
- **Disable**: Set `disabled_mcps: ["name"]` in config
- **Exa**: Default provider, works without API key
- **Tavily**: Requires `TAVILY_API_KEY` env var
## THREE-TIER SYSTEM
| Tier | Source | Mechanism |
|------|--------|-----------|
| 1. Built-in | `src/mcp/` | 3 remote HTTP, created by `createBuiltinMcps()` |
| 2. Claude Code | `.mcp.json` | `${VAR}` expansion via `claude-code-mcp-loader` |
| 3. Skill-embedded | SKILL.md YAML | Managed by `SkillMcpManager` (stdio + HTTP) |
## FILES
| File | Purpose |
|------|---------|
| `index.ts` | `createBuiltinMcps()` factory |
| `types.ts` | `McpNameSchema`: "websearch" \| "context7" \| "grep_app" |
| `websearch.ts` | Exa/Tavily provider with config |
| `context7.ts` | Context7 with optional auth header |
| `grep-app.ts` | Grep.app (no auth) |

99
src/plugin-handlers/AGENTS.md
View File

@@ -1,65 +1,58 @@
# PLUGIN-HANDLERS KNOWLEDGE BASE
# src/plugin-handlers/ — 6-Phase Config Loading Pipeline
**Generated:** 2026-02-17
## OVERVIEW
Configuration orchestration layer. Runs once at plugin init — transforms raw OpenCode config into resolved agent/tool/permission structures via 6-phase sequential loading.
13 non-test files implementing the `ConfigHandler` — the `config` hook handler. Executes 6 sequential phases to register agents, tools, MCPs, and commands with OpenCode.
## STRUCTURE
```
plugin-handlers/
├── config-handler.ts # Main orchestrator (45 lines) — 6-phase loading
├── agent-config-handler.ts # Agent loading pipeline (197 lines)
├── plan-model-inheritance.ts # Plan demotion logic (28 lines)
├── prometheus-agent-config-builder.ts # Prometheus config builder (99 lines)
├── plugin-components-loader.ts # Claude Code plugin discovery (71 lines, 10s timeout)
├── provider-config-handler.ts # Provider config + model context limits cache
├── tool-config-handler.ts # Permission migration (101 lines)
├── mcp-config-handler.ts # Builtin + CC + plugin MCP merge
├── command-config-handler.ts # Command/skill parallel discovery
├── category-config-resolver.ts # Category lookup
├── agent-priority-order.ts # Agent ordering (sisyphus, hephaestus, prometheus, atlas first)
├── plan-model-inheritance.test.ts # 3696 lines of tests
├── config-handler.test.ts # 1061 lines of tests
└── index.ts # Barrel exports
```
## 6-PHASE PIPELINE
## CONFIG LOADING FLOW (6 phases, sequential)
| Phase | Handler | Purpose |
|-------|---------|---------|
| 1 | `applyProviderConfig` | Cache model context limits, detect anthropic-beta headers |
| 2 | `loadPluginComponents` | Discover Claude Code plugins (10s timeout, error isolation) |
| 3 | `applyAgentConfig` | Load agents from 5 sources, skill discovery, plan demotion |
| 4 | `applyToolConfig` | Agent-specific tool permissions |
| 5 | `applyMcpConfig` | Merge builtin + CC + plugin MCPs |
| 6 | `applyCommandConfig` | Merge commands/skills from 9 parallel sources |
1. `applyProviderConfig` → Cache model context limits, detect anthropic-beta headers
2. `loadPluginComponents` → Discover Claude Code plugins (10s timeout, error isolation)
3. `applyAgentConfig` → Load all agents, sisyphus/prometheus/plan demotion
4. `applyToolConfig` → Agent-specific tool permissions (grep_app, task, teammate)
5. `applyMcpConfig` → Merge builtin + Claude Code + plugin MCPs
6. `applyCommandConfig` → Merge builtin + user + project + opencode commands/skills
## FILES
## PLAN MODEL INHERITANCE
When `sisyphus_agent.planner_enabled === true`:
1. Prometheus config → extract model settings (model, variant, temperature, ...)
2. Apply user `agents.plan` overrides (plan override wins)
3. Set `mode: "subagent"` (plan becomes subagent, not primary)
4. Strip prompt/permission/description (only model settings inherited)
## AGENT LOADING ORDER
1. Builtin agents (sisyphus, hephaestus, oracle, ...)
2. Sisyphus-Junior (if sisyphus enabled)
3. OpenCode-Builder (if `default_builder_enabled`)
4. Prometheus (if `planner_enabled`)
5. User agents → Project agents → Plugin agents → Custom agents
**Reordered** by `reorderAgentsByPriority()`: sisyphus, hephaestus, prometheus, atlas first.
| File | Lines | Purpose |
|------|-------|---------|
| `config-handler.ts` | ~200 | Main orchestrator, 6-phase sequential |
| `plugin-components-loader.ts` | ~100 | CC plugin discovery (10s timeout) |
| `agent-config-handler.ts` | ~300 | Agent loading + skill discovery from 5 sources |
| `mcp-config-handler.ts` | ~150 | Builtin + CC + plugin MCP merge |
| `command-config-handler.ts` | ~200 | 9 parallel sources for commands/skills |
| `tool-config-handler.ts` | ~100 | Agent-specific tool grants/denials |
| `provider-config-handler.ts` | ~80 | Provider config + model cache |
| `prometheus-agent-config-builder.ts` | ~100 | Prometheus config with model resolution |
| `plan-model-inheritance.ts` | 28 | Plan demotion logic |
| `agent-priority-order.ts` | ~30 | sisyphus, hephaestus, prometheus, atlas first |
| `agent-key-remapper.ts` | ~30 | Agent key → display name |
| `category-config-resolver.ts` | ~40 | User vs default category lookup |
| `index.ts` | ~10 | Barrel exports |
## TOOL PERMISSIONS
| Agent | Special Permissions |
|-------|---------------------|
| librarian | grep_app_* allowed |
| atlas | task, task_*, teammate allowed |
| sisyphus | task, task_*, teammate, question allowed |
| hephaestus | task, question allowed |
| multimodal-looker | Denies task, look_at |
| Agent | Granted | Denied |
|-------|---------|--------|
| Librarian | grep_app_* | — |
| Atlas, Sisyphus, Prometheus | task, task_*, teammate | — |
| Hephaestus | task | — |
| Default (all others) | — | grep_app_*, task_*, teammate, LSP |
## INTEGRATION
## MULTI-LEVEL CONFIG MERGE
Created in `create-managers.ts`, exposed as `config` hook in `plugin-interface.ts`. OpenCode calls it during session init.
```
User (~/.config/opencode/oh-my-opencode.jsonc)
↓ deepMerge
Project (.opencode/oh-my-opencode.jsonc)
↓ Zod defaults
Final Config
```
- `agents`, `categories`, `claude_code`: deep merged
- `disabled_*` arrays: Set union

133
src/shared/AGENTS.md
View File

@@ -1,97 +1,54 @@
# SHARED UTILITIES KNOWLEDGE BASE
# src/shared/ — 101 Utility Files in 13 Categories
**Generated:** 2026-02-17
## OVERVIEW
96 cross-cutting utilities across 4 subdirectories. Import via barrel: `import { log, deepMerge } from "../../shared"`
Cross-cutting utilities used throughout the plugin. Barrel-exported from `index.ts`. Logger writes to `/tmp/oh-my-opencode.log`.
## CATEGORY MAP
| Category | Files | Key Exports |
|----------|-------|-------------|
| **Model Resolution** | 17 | `resolveModel()`, `checkModelAvailability()`, `AGENT_MODEL_REQUIREMENTS` |
| **Tmux Integration** | 11 | `createTmuxSession()`, `spawnPane()`, `closePane()`, server health |
| **Configuration & Paths** | 10 | `resolveOpenCodeConfigDir()`, `getDataPath()`, `parseJSONC()` |
| **Session Management** | 8 | `SessionCursor`, `trackInjectedPath()`, `SessionToolsStore` |
| **Git Worktree** | 7 | `parseGitStatusPorcelain()`, `collectGitDiffStats()`, `formatFileChanges()` |
| **Command Execution** | 7 | `executeCommand()`, `executeHookCommand()`, embedded command registry |
| **Migration** | 6 | `migrateConfigFile()`, AGENT_NAME_MAP, HOOK_NAME_MAP, MODEL_VERSION_MAP |
| **String & Tool Utils** | 6 | `toSnakeCase()`, `normalizeToolName()`, `parseFrontmatter()` |
| **Agent Configuration** | 5 | `getAgentVariant()`, `AGENT_DISPLAY_NAMES`, `AGENT_TOOL_RESTRICTIONS` |
| **OpenCode Integration** | 5 | `injectServerAuth()`, `detectExternalPlugins()`, client accessors |
| **Type Helpers** | 4 | `deepMerge()`, `DynamicTruncator`, `matchPattern()`, `isRecord()` |
| **Misc** | 8 | `log()`, `readFile()`, `extractZip()`, `downloadBinary()`, `findAvailablePort()` |
## MODEL RESOLUTION PIPELINE
## STRUCTURE
```
shared/
├── logger.ts # File logging (/tmp/oh-my-opencode.log) — 62 imports
├── dynamic-truncator.ts # Token-aware context window management (202 lines)
├── model-resolver.ts # 3-step resolution entry point (65 lines)
├── model-availability.ts # Provider model fetching & fuzzy matching (359 lines)
├── model-requirements.ts # Agent/category fallback chains (161 lines) — 11 imports
├── model-resolution-pipeline.ts # Pipeline orchestration (176 lines)
├── model-resolution-types.ts # Resolution request/provenance types
├── model-sanitizer.ts # Model name sanitization
├── model-name-matcher.ts # Model name matching (91 lines)
├── model-suggestion-retry.ts # Suggest models on failure (144 lines)
├── model-cache-availability.ts # Cache availability checking
├── fallback-model-availability.ts # Fallback model logic (67 lines)
├── available-models-fetcher.ts # Fetch models from providers (114 lines)
├── models-json-cache-reader.ts # Read models.json cache
├── provider-models-cache-model-reader.ts # Provider cache reader
├── connected-providers-cache.ts # Provider caching (196 lines)
├── system-directive.ts # Unified message prefix & types (61 lines) — 11 imports
├── session-utils.ts # Session cursor, orchestrator detection
├── session-cursor.ts # Message cursor tracking (85 lines)
├── session-injected-paths.ts # Injected file path tracking
├── permission-compat.ts # Tool restriction enforcement (87 lines) — 9 imports
├── agent-tool-restrictions.ts # Tool restriction definitions
├── agent-variant.ts # Agent variant from config (91 lines)
├── agent-display-names.ts # Agent display name mapping
├── first-message-variant.ts # First message variant types
├── opencode-config-dir.ts # ~/.config/opencode resolution (138 lines)
├── claude-config-dir.ts # ~/.claude resolution
├── data-path.ts # XDG-compliant storage (47 lines) — 11 imports
├── jsonc-parser.ts # JSONC with comment support (66 lines)
├── frontmatter.ts # YAML frontmatter extraction (31 lines) — 10 imports
├── deep-merge.ts # Recursive merge (proto-pollution safe, MAX_DEPTH=50)
├── shell-env.ts # Cross-platform shell environment (111 lines)
├── opencode-version.ts # Semantic version comparison (80 lines)
├── external-plugin-detector.ts # Plugin conflict detection (137 lines)
├── opencode-server-auth.ts # Authentication utilities (190 lines)
├── safe-create-hook.ts # Hook error wrapper (24 lines)
├── pattern-matcher.ts # Pattern matching (40 lines)
├── file-utils.ts # File operations (34 lines) — 9 imports
├── file-reference-resolver.ts # File reference resolution (85 lines)
├── snake-case.ts # Case conversion (44 lines)
├── tool-name.ts # Tool naming conventions
├── port-utils.ts # Port management (48 lines)
├── zip-extractor.ts # ZIP extraction (83 lines)
├── binary-downloader.ts # Binary download (60 lines)
├── command-executor/ # Shell execution (6 files, 213 lines)
├── git-worktree/ # Git status/diff parsing (8 files, 311 lines)
├── migration/ # Legacy config migration (5 files, 341 lines)
│ ├── config-migration.ts # Migration orchestration (133 lines)
│ ├── agent-names.ts # Agent name mapping (70 lines)
│ ├── hook-names.ts # Hook name mapping (36 lines)
│ └── model-versions.ts # Model version migration (49 lines)
└── tmux/ # Tmux TUI integration (12 files, 427 lines)
└── tmux-utils/ # Pane spawn, close, replace, layout, health
resolveModel(input)
1. Override: UI-selected model (primary agents only)
2. Category default: From category config
3. Provider fallback: AGENT_MODEL_REQUIREMENTS chains
4. System default: Ultimate fallback
```
Key files: `model-resolver.ts` (entry), `model-resolution-pipeline.ts` (orchestration), `model-requirements.ts` (fallback chains), `model-name-matcher.ts` (fuzzy matching).
## MIGRATION SYSTEM
Automatically transforms legacy config on load:
- `agent-names.ts`: Old agent names → new (e.g., `junior` → `sisyphus-junior`)
- `hook-names.ts`: Old hook names → new
- `model-versions.ts`: Old model IDs → current
- `agent-category.ts`: Legacy agent configs → category system
## MOST IMPORTED
| Utility | Imports | Purpose |
|---------|---------|---------|
| logger.ts | 62 | Background task visibility |
| data-path.ts | 11 | XDG storage resolution |
| model-requirements.ts | 11 | Agent fallback chains |
| system-directive.ts | 11 | System message filtering |
| frontmatter.ts | 10 | YAML metadata extraction |
| permission-compat.ts | 9 | Tool restrictions |
| file-utils.ts | 9 | File operations |
| dynamic-truncator.ts | 7 | Token-aware truncation |
## KEY PATTERNS
**3-Step Model Resolution** (Override → Fallback → Default):
1. **Override**: UI-selected or user-configured model
2. **Fallback**: Provider/model chain with availability checking
3. **Default**: System fallback when no matches found
**System Directive Filtering**:
```typescript
if (isSystemDirective(message)) return // Skip system-generated
const directive = createSystemDirective("TODO CONTINUATION")
```
## ANTI-PATTERNS
- **Raw JSON.parse**: Use `jsonc-parser.ts` for comment support
- **Hardcoded paths**: Use `opencode-config-dir.ts` or `data-path.ts`
- **console.log**: Use `logger.ts` for background task visibility
- **Unbounded output**: Use `dynamic-truncator.ts` to prevent overflow
- **Manual version check**: Use `opencode-version.ts` for semver safety
| Utility | Import Count | Purpose |
|---------|-------------|---------|
| `logger.ts` | 62 | `/tmp/oh-my-opencode.log` |
| `data-path.ts` | 11 | XDG storage resolution |
| `model-requirements.ts` | 11 | Agent fallback chains |
| `system-directive.ts` | 11 | System message filtering |
| `frontmatter.ts` | 10 | YAML metadata extraction |

166
src/tools/AGENTS.md
View File

@@ -1,83 +1,109 @@
# TOOLS KNOWLEDGE BASE
# src/tools/ — 26 Tools Across 14 Directories
**Generated:** 2026-02-17
## OVERVIEW
26 tools across 14 directories. Two patterns: Direct ToolDefinition (static) and Factory Function (context-dependent).
26 tools registered via `createToolRegistry()`. Two patterns: factory functions (`createXXXTool`) for 19 tools, direct `ToolDefinition` for 7 (LSP + interactive_bash).
## STRUCTURE
```
tools/
├── delegate-task/ # Category routing (constants.ts 569 lines, tools.ts 213 lines)
├── task/ # 4 tools: create, list, get, update (task-create.ts, task-list.ts, task-get.ts, task-update.ts)
├── lsp/ # 6 LSP tools: goto_definition, find_references, symbols, diagnostics, prepare_rename, rename
├── ast-grep/ # 2 tools: search, replace (25 languages)
├── grep/ # Content search (60s timeout, 10MB limit)
├── glob/ # File pattern matching (60s timeout, 100 file limit)
├── session-manager/ # 4 tools: list, read, search, info
├── call-omo-agent/ # Direct agent invocation (explore/librarian)
├── background-task/ # background_output, background_cancel
├── interactive-bash/ # Tmux session management (135 lines)
├── look-at/ # Multimodal PDF/image analysis (156 lines)
├── skill/ # Skill execution with MCP support (211 lines)
├── skill-mcp/ # MCP tool/resource/prompt operations (182 lines)
└── slashcommand/ # Slash command dispatch
```
## TOOL CATALOG
## TOOL INVENTORY
### Task Management (4)
| Tool | Category | Pattern | Key Logic |
|------|----------|---------|-----------|
| `task_create` | Task | Factory | Auto-generated T-{uuid} ID, threadID recording, dependency management |
| `task_list` | Task | Factory | Active tasks with summary (excludes completed/deleted), filters unresolved blockers |
| `task_get` | Task | Factory | Full task object by ID |
| `task_update` | Task | Factory | Status/field updates, additive addBlocks/addBlockedBy for dependencies |
| `task` | Delegation | Factory | Category routing with skill injection, background execution |
| `call_omo_agent` | Agent | Factory | Direct explore/librarian invocation |
| `background_output` | Background | Factory | Retrieve background task result (block, timeout, full_session) |
| `background_cancel` | Background | Factory | Cancel running/all background tasks |
| `lsp_goto_definition` | LSP | Direct | Jump to symbol definition |
| `lsp_find_references` | LSP | Direct | Find all usages across workspace |
| `lsp_symbols` | LSP | Direct | Document or workspace symbol search |
| `lsp_diagnostics` | LSP | Direct | Get errors/warnings from language server |
| `lsp_prepare_rename` | LSP | Direct | Validate rename is possible |
| `lsp_rename` | LSP | Direct | Rename symbol across workspace |
| `ast_grep_search` | Search | Factory | AST-aware code search (25 languages) |
| `ast_grep_replace` | Search | Factory | AST-aware code replacement (dry-run default) |
| `grep` | Search | Factory | Regex content search with safety limits |
| `glob` | Search | Factory | File pattern matching |
| `session_list` | Session | Factory | List all sessions |
| `session_read` | Session | Factory | Read session messages with filters |
| `session_search` | Session | Factory | Search across sessions |
| `session_info` | Session | Factory | Session metadata and stats |
| `interactive_bash` | System | Direct | Tmux session management |
| `look_at` | System | Factory | Multimodal PDF/image analysis via dedicated agent |
| `skill` | Skill | Factory | Load skill instructions with MCP support |
| `skill_mcp` | Skill | Factory | Call MCP tools/resources/prompts from skill-embedded servers |
| `slashcommand` | Command | Factory | Slash command dispatch with argument substitution |
| Tool | Factory | Parameters |
|------|---------|------------|
| `task_create` | `createTaskCreateTool` | subject, description, blockedBy, blocks, metadata, parentID |
| `task_list` | `createTaskList` | (none) |
| `task_get` | `createTaskGetTool` | id |
| `task_update` | `createTaskUpdateTool` | id, subject, description, status, addBlocks, addBlockedBy, owner, metadata |
## DELEGATION SYSTEM (delegate-task)
### Delegation (1)
8 built-in categories with domain-optimized models:
| Tool | Factory | Parameters |
|------|---------|------------|
| `task` | `createDelegateTask` | description, prompt, category, subagent_type, run_in_background, session_id, load_skills, command |
**8 Built-in Categories**: visual-engineering, ultrabrain, deep, artistry, quick, unspecified-low, unspecified-high, writing
### Agent Invocation (1)
| Tool | Factory | Parameters |
|------|---------|------------|
| `call_omo_agent` | `createCallOmoAgent` | description, prompt, subagent_type, run_in_background, session_id |
### Background Tasks (2)
| Tool | Factory | Parameters |
|------|---------|------------|
| `background_output` | `createBackgroundOutput` | task_id, block, timeout, full_session, include_thinking, message_limit |
| `background_cancel` | `createBackgroundCancel` | taskId, all |
### LSP Refactoring (6) — Direct ToolDefinition
| Tool | Parameters |
|------|------------|
| `lsp_goto_definition` | filePath, line, character |
| `lsp_find_references` | filePath, line, character, includeDeclaration |
| `lsp_symbols` | filePath, scope (document/workspace), query, limit |
| `lsp_diagnostics` | filePath, severity |
| `lsp_prepare_rename` | filePath, line, character |
| `lsp_rename` | filePath, line, character, newName |
### Code Search (4)
| Tool | Factory | Parameters |
|------|---------|------------|
| `ast_grep_search` | `createAstGrepTools` | pattern, lang, paths, globs, context |
| `ast_grep_replace` | `createAstGrepTools` | pattern, rewrite, lang, paths, globs, dryRun |
| `grep` | `createGrepTools` | pattern, path, include (60s timeout, 10MB limit) |
| `glob` | `createGlobTools` | pattern, path (60s timeout, 100 file limit) |
### Session History (4)
| Tool | Factory | Parameters |
|------|---------|------------|
| `session_list` | `createSessionManagerTools` | (none) |
| `session_read` | `createSessionManagerTools` | session_id, include_todos, limit |
| `session_search` | `createSessionManagerTools` | query, session_id, case_sensitive, limit |
| `session_info` | `createSessionManagerTools` | session_id |
### Skill/Command (3)
| Tool | Factory | Parameters |
|------|---------|------------|
| `skill` | `createSkillTool` | name |
| `skill_mcp` | `createSkillMcpTool` | mcp_name, tool_name/resource_name/prompt_name, arguments, grep |
| `slashcommand` | `createSlashcommandTool` | command, user_message |
### System (2)
| Tool | Factory | Parameters |
|------|---------|------------|
| `interactive_bash` | Direct | tmux_command |
| `look_at` | `createLookAt` | file_path, image_data, goal |
### Editing (1) — Conditional
| Tool | Factory | Parameters |
|------|---------|------------|
| `hashline_edit` | `createHashlineEditTool` | file, edits[] |
## DELEGATION CATEGORIES
| Category | Model | Domain |
|----------|-------|--------|
| `visual-engineering` | gemini-3-pro | UI/UX, design, styling |
| `ultrabrain` | gpt-5.3-codex xhigh | Deep logic, architecture |
| `deep` | gpt-5.3-codex medium | Autonomous problem-solving |
| `artistry` | gemini-3-pro high | Creative, unconventional |
| `quick` | claude-haiku-4-5 | Trivial tasks |
| `unspecified-low` | claude-sonnet-4-5 | Moderate effort |
| `unspecified-high` | claude-opus-4-6 max | High effort |
| `writing` | kimi-k2p5 | Documentation, prose |
| visual-engineering | gemini-3-pro | Frontend, UI/UX |
| ultrabrain | gpt-5.3-codex xhigh | Hard logic |
| deep | gpt-5.3-codex medium | Autonomous problem-solving |
| artistry | gemini-3-pro high | Creative approaches |
| quick | claude-haiku-4-5 | Trivial tasks |
| unspecified-low | claude-sonnet-4-5 | Moderate effort |
| unspecified-high | claude-opus-4-6 max | High effort |
| writing | kimi-k2p5 | Documentation |
## HOW TO ADD
## HOW TO ADD A TOOL
1. Create `src/tools/[name]/` with index.ts, tools.ts, types.ts, constants.ts
2. Static tools → `builtinTools` export, Factory → separate export
3. Register in `src/plugin/tool-registry.ts`
## NAMING
- **Tool names**: snake_case (`lsp_goto_definition`)
- **Functions**: camelCase (`createDelegateTask`)
- **Directories**: kebab-case (`delegate-task/`)
1. Create `src/tools/{name}/index.ts` exporting factory
2. Create `src/tools/{name}/types.ts` for parameter schemas
3. Create `src/tools/{name}/tools.ts` for implementation
4. Register in `src/plugin/tool-registry.ts`