PROJECT KNOWLEDGE BASE

Generated: 2026-02-02T21:16:00+09:00 Commit: d80adac3 Branch: dev

IMPORTANT: PULL REQUEST TARGET BRANCH

ALL PULL REQUESTS MUST TARGET THE dev BRANCH.

DO NOT CREATE PULL REQUESTS TARGETING master BRANCH.

PRs to master will be automatically rejected by CI.

OVERVIEW

O P E N C O D E plugin: multi-model agent orchestration (Claude Opus 4.5, GPT-5.2, Gemini 3 Flash). 34 lifecycle hooks, 20+ tools (LSP, AST-Grep, delegation), 11 specialized agents, full Claude Code compatibility. "oh-my-zsh" for O P E N C O D E.

STRUCTURE

oh-my-opencode/
├── src/
│   ├── agents/        # 11 AI agents - see src/agents/AGENTS.md
│   ├── hooks/         # 34 lifecycle hooks - see src/hooks/AGENTS.md
│   ├── tools/         # 20+ tools - see src/tools/AGENTS.md
│   ├── features/      # Background agents, Claude Code compat - see src/features/AGENTS.md
│   ├── shared/        # 55 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, TypeScript types
│   └── index.ts       # Main plugin entry (788 lines)
├── script/            # build-schema.ts, build-binaries.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`
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 index.ts
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`
Background agents	`src/features/background-agent/`	manager.ts (1418 lines)
Orchestrator	`src/hooks/atlas/`	Main orchestration hook (757 lines)

TDD (Test-Driven Development)

MANDATORY. RED-GREEN-REFACTOR:

RED: Write test → bun test → FAIL
GREEN: Implement minimum → PASS
REFACTOR: Clean up → stay GREEN

Rules:

NEVER write implementation before test
NEVER delete failing tests - fix the code
Test file: *.test.ts alongside source (100 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, 100 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
Agent Calls	Sequential - use `delegate_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

AGENT MODELS

Agent	Model	Purpose
Sisyphus	anthropic/claude-opus-4-5	Primary orchestrator (fallback: kimi-k2.5 → glm-4.7 → gpt-5.2-codex → gemini-3-pro)
Hephaestus	openai/gpt-5.2-codex	Autonomous deep worker, "The Legitimate Craftsman" (requires gpt-5.2-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-5	Strategic planning (fallback: kimi-k2.5 → gpt-5.2)

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

Commit & push changes
Trigger: gh workflow run publish -f bump=patch
Never bun publish directly, never bump version locally

COMPLEXITY HOTSPOTS

File	Lines	Description
`src/features/builtin-skills/skills.ts`	1729	Skill definitions
`src/features/background-agent/manager.ts`	1457	Task lifecycle, concurrency
`src/agents/prometheus-prompt.ts`	1283	Planning agent prompt
`src/tools/delegate-task/tools.ts`	1135	Category-based delegation
`src/hooks/atlas/index.ts`	757	Orchestrator hook
`src/index.ts`	788	Main plugin entry
`src/cli/config-manager.ts`	667	JSONC config parsing
`src/features/builtin-commands/templates/refactor.ts`	619	Refactor command template

MCP ARCHITECTURE

Three-tier system:

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

CONFIG SYSTEM

Zod validation: src/config/schema.ts
JSONC support: Comments, trailing commas
Multi-level: Project (.opencode/) → User (~/.config/opencode/)

NOTES

O P E N C O D E: 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

6.2 KiB Raw Blame History