oh-my-opencode-free-fork/AGENTS.md

PROJECT KNOWLEDGE BASE

Generated: 2025-12-22T02:23:00+09:00 Commit: aad7a72 Branch: dev

OVERVIEW

OpenCode plugin implementing Claude Code/AmpCode features. Multi-model agent orchestration (GPT-5.2, Claude, Gemini, Grok), LSP tools (11), AST-Grep search, MCP integrations (context7, websearch_exa, grep_app). "oh-my-zsh" for OpenCode.

STRUCTURE

oh-my-opencode/
├── src/
│   ├── agents/        # AI agents (Sisyphus, oracle, librarian, explore, frontend, document-writer, multimodal-looker)
│   ├── hooks/         # 21 lifecycle hooks (comment-checker, rules-injector, keyword-detector, etc.)
│   ├── tools/         # LSP (11), AST-Grep, Grep, Glob, background-task, look-at, skill, slashcommand, interactive-bash, call-omo-agent
│   ├── mcp/           # MCP servers (context7, websearch_exa, grep_app)
│   ├── features/      # Background agent, Claude Code loaders (agent, command, skill, mcp, session-state), hook-message-injector
│   ├── config/        # Zod schema, TypeScript types
│   ├── auth/          # Google Antigravity OAuth
│   ├── shared/        # Utilities (deep-merge, pattern-matcher, logger, etc.)
│   └── index.ts       # Main plugin entry (OhMyOpenCodePlugin)
├── script/            # build-schema.ts, publish.ts, generate-changelog.ts
├── assets/            # JSON schema
└── dist/              # Build output (ESM + .d.ts)

WHERE TO LOOK

Task	Location	Notes
Add new agent	src/agents/	Create .ts file, add to builtinAgents in index.ts, update types.ts
Add new hook	src/hooks/	Create dir with createXXXHook(), export from index.ts
Add new tool	src/tools/	Dir with index/types/constants/tools.ts, add to builtinTools
Add MCP server	src/mcp/	Create config, add to index.ts
Modify LSP behavior	src/tools/lsp/	client.ts for connection, tools.ts for handlers
AST-Grep patterns	src/tools/ast-grep/	napi.ts for @ast-grep/napi binding
Google OAuth	src/auth/antigravity/	OAuth plugin for Google models
Config schema	src/config/schema.ts	Zod schema, run bun run build:schema after changes
Claude Code compat	src/features/claude-code-*-loader/	Command, skill, agent, mcp loaders
Background agents	src/features/background-agent/	manager.ts for task management
Interactive terminal	src/tools/interactive-bash/	tmux session management

CONVENTIONS

• Package manager: Bun only (bun run, bun build, bunx)
• Types: bun-types (not @types/node)
• Build: Dual output - bun build (ESM) + tsc --emitDeclarationOnly
• Exports: Barrel pattern - export * from "./module" in index.ts
• Directory naming: kebab-case (ast-grep/, claude-code-hooks/)
• Tool structure: Each tool has index.ts, types.ts, constants.ts, tools.ts, utils.ts
• Hook pattern: createXXXHook(input: PluginInput) returning event handlers
• Test style: BDD comments #given, #when, #then (same as AAA pattern)

ANTI-PATTERNS (THIS PROJECT)

• npm/yarn: Use bun exclusively
• @types/node: Use bun-types
• Bash file operations: Never use mkdir/touch/rm/cp/mv for file creation in code
• Generic AI aesthetics: No Space Grotesk, avoid typical AI-generated UI patterns
• Direct bun publish: Use GitHub Actions workflow_dispatch only (OIDC provenance)
• Local version bump: Version managed by CI workflow, never modify locally
• Rush completion: Never mark tasks complete without verification
• Interrupting work: Complete tasks fully before stopping
• Over-exploration: Stop searching when sufficient context found

UNIQUE STYLES

• Platform handling: Union type "darwin" | "linux" | "win32" | "unsupported"
• Optional props: Extensive use of ? for optional interface properties
• Flexible objects: Record<string, unknown> for dynamic configs
• Error handling: Consistent try/catch with async/await in all tools
• Agent tools restriction: Use tools: { include: [...] } or tools: { exclude: [...] }
• Temperature: Most agents use 0.1 for consistency
• Hook naming: createXXXHook function naming convention
• Date references: NEVER use 2024 in code/prompts (use current year)

AGENT MODELS

Agent	Model	Purpose
Sisyphus	anthropic/claude-opus-4-5	Primary orchestrator, team leader
oracle	openai/gpt-5.2	Strategic advisor, code review, architecture
librarian	anthropic/claude-sonnet-4-5	Multi-repo analysis, docs lookup, GitHub examples
explore	opencode/grok-code	Fast codebase exploration, file patterns
frontend-ui-ux-engineer	google/gemini-3-pro-preview	UI generation, design-focused
document-writer	google/gemini-3-pro-preview	Technical documentation
multimodal-looker	google/gemini-3-flash	PDF/image/diagram analysis

COMMANDS

# Type check
bun run typecheck

# Build (ESM + declarations + schema)
bun run build

# Clean + Build
bun run rebuild

# Build schema only
bun run build:schema

# Run tests
bun test

DEPLOYMENT

GitHub Actions workflow_dispatch only

1. package.json version NOT modified locally (auto-bumped by workflow)
2. Commit & push changes
3. Trigger publish workflow manually:
   • bump: major | minor | patch
   • version: (optional) specific version override

# Trigger via CLI
gh workflow run publish -f bump=patch

# Check status
gh run list --workflow=publish

Critical:

• Never run bun publish directly (OIDC provenance issue)
• Never bump version locally

CI PIPELINE

• ci.yml: Parallel test/typecheck jobs, build verification, auto-commit schema changes on master
• publish.yml: Manual workflow_dispatch, version bump, changelog generation, OIDC npm publishing
• Schema auto-commit prevents build drift
• Draft release creation on dev branch

NOTES

• Testing: Bun native test framework (bun test), BDD-style with #given/#when/#then comments
• OpenCode version: Requires >= 1.0.150 (earlier versions have config bugs)
• Multi-language docs: README.md (EN), README.ko.md (KO), README.ja.md (JA), README.zh-cn.md (ZH-CN)
• Config locations: ~/.config/opencode/oh-my-opencode.json (user) or .opencode/oh-my-opencode.json (project)
• Schema autocomplete: Add $schema field in config for IDE support
• Trusted dependencies: @ast-grep/cli, @ast-grep/napi, @code-yeongyu/comment-checker