oh-my-openagent/AGENTS.md

PROJECT KNOWLEDGE BASE

Generated: 2026-02-08T16:45:00+09:00 Commit: edee865f Branch: dev

---

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

Why This Matters

• master = production/published npm package
• dev = integration branch where features are merged and tested
• Feature branches → dev → (after testing) → master

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:

   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

The librarian agent is specialized for:

• Searching remote codebases (GitHub)
• Retrieving official documentation
• Finding implementation examples in open source

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

This is an international open-source project. To ensure accessibility and maintainability:

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

Why This Matters

• Global Collaboration: Contributors from all countries can participate
• Searchability: English keywords are universally searchable
• AI Agent Compatibility: AI tools work best with English content
• Consistency: Mixed languages create confusion and fragmentation

Enforcement

• Issues/PRs with non-English content may be closed with a request to resubmit in English
• Commit messages must be in English - CI may reject non-English commits
• Translated READMEs exist (README.ko.md, README.ja.md, etc.) but the primary docs are English

If you're not comfortable writing in English, use translation tools. Broken English is fine - we'll help fix it. Non-English is not acceptable.

---

OVERVIEW

OpenCode plugin: multi-model agent orchestration (Claude Opus 4.6, GPT-5.3 Codex, Gemini 3 Flash). 40+ lifecycle hooks, 25+ tools (LSP, AST-Grep, delegation), 11 specialized agents, full Claude Code compatibility. "oh-my-zsh" for OpenCode.

STRUCTURE

oh-my-opencode/
├── src/
│   ├── agents/           # 11 AI agents - see src/agents/AGENTS.md
│   ├── hooks/            # 40+ lifecycle hooks - see src/hooks/AGENTS.md
│   ├── tools/            # 25+ tools - see src/tools/AGENTS.md
│   ├── features/         # Background agents, skills, Claude Code compat - see src/features/AGENTS.md
│   ├── shared/           # 66 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 (schema.ts 455 lines), TypeScript types
│   ├── plugin-handlers/  # Plugin config loading (config-handler.ts 562 lines)
│   ├── index.ts          # Main plugin entry (999 lines)
│   ├── plugin-config.ts  # Config loading orchestration
│   └── plugin-state.ts   # Model cache state
├── script/               # build-schema.ts, build-binaries.ts, publish.ts
├── packages/             # 11 platform-specific binaries
└── dist/                 # Build output (ESM + .d.ts)

WHERE TO LOOK

Task	Location	Notes
Add agent	src/agents/	Create .ts with factory, add to agentSources in utils.ts
Add hook	src/hooks/	Create dir with createXXXHook(), register in index.ts
Add tool	src/tools/	Dir with index/types/constants/tools.ts
Add MCP	src/mcp/	Create config, add to createBuiltinMcps()
Add skill	src/features/builtin-skills/	Create dir with SKILL.md
Add command	src/features/builtin-commands/	Add template + register in commands.ts
Config schema	src/config/schema.ts	Zod schema, 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 (1556 lines)
Orchestrator	src/hooks/atlas/	Main orchestration hook (770 lines)
Delegation	src/tools/delegate-task/	Category routing (executor.ts 983 lines)

TDD (Test-Driven Development)

MANDATORY. RED-GREEN-REFACTOR:

1. RED: Write test → bun test → FAIL
2. GREEN: Implement minimum → PASS
3. REFACTOR: Clean up → stay GREEN

Rules:

• NEVER write implementation before test
• NEVER delete failing tests - fix the code
• Test file: *.test.ts alongside source (163 test files)
• BDD comments: //#given, //#when, //#then

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, 163 test files
• Temperature: 0.1 for code agents, max 0.3

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

AGENT MODELS

Agent	Model	Purpose
Sisyphus	anthropic/claude-opus-4-6	Primary orchestrator (fallback: kimi-k2.5 → glm-4.7 → gpt-5.3-codex → gemini-3-pro)
Hephaestus	openai/gpt-5.3-codex	Autonomous deep worker, "The Legitimate Craftsman" (requires gpt-5.3-codex, no fallback)
Atlas	anthropic/claude-sonnet-4-5	Master orchestrator (fallback: kimi-k2.5 → gpt-5.2)
oracle	openai/gpt-5.2	Consultation, debugging
librarian	zai-coding-plan/glm-4.7	Docs, GitHub search (fallback: glm-4.7-free)
explore	xai/grok-code-fast-1	Fast codebase grep (fallback: claude-haiku-4-5 → gpt-5-mini → gpt-5-nano)
multimodal-looker	google/gemini-3-flash	PDF/image analysis
Prometheus	anthropic/claude-opus-4-6	Strategic planning (fallback: kimi-k2.5 → gpt-5.2)
Metis	anthropic/claude-opus-4-6	Pre-planning analysis (temp 0.3, fallback: kimi-k2.5 → gpt-5.2)
Momus	openai/gpt-5.2	Plan validation (temp 0.1, fallback: claude-opus-4-6)
Sisyphus-Junior	anthropic/claude-sonnet-4-5	Category-spawned executor (temp 0.1)

COMMANDS

bun run typecheck      # Type check
bun run build          # ESM + declarations + schema
bun run rebuild        # Clean + Build
bun test               # 100+ test files

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	1642	Task lifecycle, concurrency
src/features/builtin-skills/skills/git-master.ts	1107	Git master skill definition
src/index.ts	999	Main plugin entry
src/tools/delegate-task/executor.ts	969	Category-based delegation executor
src/tools/lsp/client.ts	851	LSP client operations
src/tools/background-task/tools.ts	757	Background task tools
src/hooks/atlas/index.ts	697	Orchestrator hook
src/cli/config-manager.ts	667	JSONC config parsing
src/features/skill-mcp-manager/manager.ts	640	MCP client lifecycle
src/features/builtin-commands/templates/refactor.ts	619	Refactor command template
src/agents/hephaestus.ts	618	Autonomous deep worker agent
src/agents/utils.ts	571	Agent creation, model fallback resolution
src/plugin-handlers/config-handler.ts	562	Plugin config loading
src/tools/delegate-task/constants.ts	552	Delegation constants
src/cli/install.ts	542	Interactive CLI installer
src/hooks/task-continuation-enforcer.ts	530	Task completion enforcement
src/agents/sisyphus.ts	530	Main orchestrator agent

MCP ARCHITECTURE

Three-tier system:

1. Built-in: websearch (Exa/Tavily), context7 (docs), grep_app (GitHub)
2. Claude Code compat: .mcp.json with ${VAR} expansion
3. Skill-embedded: YAML frontmatter in skills

CONFIG SYSTEM

• Zod validation: src/config/schema.ts (455 lines)
• JSONC support: Comments, trailing commas
• Multi-level: Project (.opencode/) → User (~/.config/opencode/)
• Loading: src/plugin-handlers/config-handler.ts → merge → validate

NOTES

• OpenCode: Requires >= 1.0.150
• 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