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

docs(AGENTS.md): update root project metadata to match codebase

Browse Source 
- TS files: 1268 -> ~1602, LOC: 160k -> ~214k
- Hooks: 48 -> 52 (Session 24, Tool-Guard 14, Transform 5)
- Config schema: 24 -> 27 files, barrel exports: 98 -> 104
- Hook handlers: 8 -> 10 (add compacting handler)
- CI table: fix refresh-model-capabilities trigger description
- Conventions: add CI bun version, inline test comment style
This commit is contained in:
YeonGyu-Kim
2026-04-05 14:04:09 +09:00
parent a8ab137ee9
commit 8dd186f0be
1 changed files with 37 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+37 -32
View File
@@ -1,10 +1,10 @@
# oh-my-opencode — O P E N C O D E Plugin # oh-my-opencode — O P E N C O D E Plugin
**Generated:** 2026-03-06 | **Commit:** 7fe44024 | **Branch:** dev **Generated:** 2026-04-05 | **Commit:** c9be5bb51 | **Branch:** dev
## OVERVIEW ## OVERVIEW
OpenCode plugin (npm: `oh-my-opencode`) that extends Claude Code (OpenCode fork) with multi-agent orchestration, 48 lifecycle hooks, 26 tools, skill/command/MCP systems, and Claude Code compatibility. 1268 TypeScript files, 160k LOC. OpenCode plugin (npm: `oh-my-opencode`) that extends Claude Code (OpenCode fork) with multi-agent orchestration, 52 lifecycle hooks, 26 tools, skill/command/MCP systems, and Claude Code compatibility. ~1602 TypeScript source files, ~214k LOC.
## STRUCTURE ## STRUCTURE
@@ -14,16 +14,16 @@ oh-my-opencode/
│ ├── index.ts # Plugin entry: loadConfig → createManagers → createTools → createHooks → createPluginInterface │ ├── index.ts # Plugin entry: loadConfig → createManagers → createTools → createHooks → createPluginInterface
│ ├── plugin-config.ts # JSONC multi-level config: user → project → defaults (Zod v4) │ ├── plugin-config.ts # JSONC multi-level config: user → project → defaults (Zod v4)
│ ├── agents/ # 11 agents (Sisyphus, Hephaestus, Oracle, Librarian, Explore, Atlas, Prometheus, Metis, Momus, Multimodal-Looker, Sisyphus-Junior) │ ├── agents/ # 11 agents (Sisyphus, Hephaestus, Oracle, Librarian, Explore, Atlas, Prometheus, Metis, Momus, Multimodal-Looker, Sisyphus-Junior)
│ ├── hooks/ # 48 lifecycle hooks across dedicated modules and standalone files │ ├── hooks/ # 52 lifecycle hooks across dedicated modules and standalone files
│ ├── tools/ # 26 tools across 15 directories │ ├── tools/ # 26 tools across 16 directories
│ ├── features/ # 19 feature modules (background-agent, skill-loader, tmux, MCP-OAuth, etc.) │ ├── features/ # 19 feature modules (background-agent, skill-loader, tmux, MCP-OAuth, etc.)
│ ├── shared/ # 95+ utility files in 13 categories │ ├── shared/ # 100+ utility files
│ ├── config/ # Zod v4 schema system (24 files) │ ├── config/ # Zod v4 schema system (27 files)
│ ├── cli/ # CLI: install, run, doctor, mcp-oauth (Commander.js) │ ├── cli/ # CLI: install, run, doctor, mcp-oauth (Commander.js)
│ ├── mcp/ # 3 built-in remote MCPs (websearch, context7, grep_app) │ ├── mcp/ # 3 built-in remote MCPs (websearch, context7, grep_app)
│ ├── plugin/ # 8 OpenCode hook handlers + 48 hook composition │ ├── plugin/ # 8 OpenCode hook handlers + 52 hook composition
│ └── plugin-handlers/ # 6-phase config loading pipeline │ └── plugin-handlers/ # 6-phase config loading pipeline
├── packages/ # Monorepo: cli-runner, 12 platform binaries ├── packages/ # Monorepo: cli-runner, 11 platform binaries
└── local-ignore/ # Dev-only test fixtures └── local-ignore/ # Dev-only test fixtures
``` ```
@@ -34,11 +34,11 @@ OhMyOpenCodePlugin(ctx)
├─→ loadPluginConfig() # JSONC parse → project/user merge → Zod validate → migrate ├─→ loadPluginConfig() # JSONC parse → project/user merge → Zod validate → migrate
├─→ createManagers() # TmuxSessionManager, BackgroundManager, SkillMcpManager, ConfigHandler ├─→ createManagers() # TmuxSessionManager, BackgroundManager, SkillMcpManager, ConfigHandler
├─→ createTools() # SkillContext + AvailableCategories + ToolRegistry (26 tools) ├─→ createTools() # SkillContext + AvailableCategories + ToolRegistry (26 tools)
├─→ createHooks() # 3-tier: Core(39) + Continuation(7) + Skill(2) = 48 hooks ├─→ createHooks() # 3-tier: Core(43) + Continuation(7) + Skill(2) = 52 hooks
└─→ createPluginInterface() # 8 OpenCode hook handlers → PluginInterface └─→ createPluginInterface() # 10 OpenCode hook handlers → PluginInterface
``` ```
## 8 OPENCODE HOOK HANDLERS ## 10 OPENCODE HOOK HANDLERS
| Handler | Purpose | | Handler | Purpose |
|---------|---------| |---------|---------|
@@ -51,6 +51,7 @@ OhMyOpenCodePlugin(ctx)
| `tool.execute.before` | Pre-tool hooks (file guard, label truncator, rules injector) | | `tool.execute.before` | Pre-tool hooks (file guard, label truncator, rules injector) |
| `tool.execute.after` | Post-tool hooks (output truncation, metadata store) | | `tool.execute.after` | Post-tool hooks (output truncation, metadata store) |
| `experimental.chat.messages.transform` | Context injection, thinking block validation | | `experimental.chat.messages.transform` | Context injection, thinking block validation |
| `experimental.session.compacting` | Context + todo preservation during compaction |
## WHERE TO LOOK ## WHERE TO LOOK
@@ -74,11 +75,11 @@ OhMyOpenCodePlugin(ctx)
Project (.opencode/oh-my-opencode.jsonc) → User (~/.config/opencode/oh-my-opencode.jsonc) → Defaults Project (.opencode/oh-my-opencode.jsonc) → User (~/.config/opencode/oh-my-opencode.jsonc) → Defaults
``` ```
- `agents`, `categories`, `claude_code`: deep merged recursively - `agents`, `categories`, `claude_code`: deep merged recursively (prototype-pollution-safe)
- `disabled_*` arrays: Set union (concatenated + deduplicated) - `disabled_*` arrays: Set union (concatenated + deduplicated)
- All other fields: override replaces base value - All other fields: override replaces base value
- Zod `safeParse()` fills defaults for omitted fields - Zod `safeParse()` fills defaults for omitted fields; partial parsing as fallback
- `migrateConfigFile()` transforms legacy keys automatically - `migrateConfigFile()` transforms legacy keys automatically (idempotent via `_migrations` tracking)
Fields: agents (14 overridable, 21 fields each), categories (8 built-in + custom), disabled_* arrays (agents, hooks, mcps, skills, commands, tools), 19 feature-specific configs. Fields: agents (14 overridable, 21 fields each), categories (8 built-in + custom), disabled_* arrays (agents, hooks, mcps, skills, commands, tools), 19 feature-specific configs.
@@ -92,19 +93,20 @@ Fields: agents (14 overridable, 21 fields each), categories (8 built-in + custom
## CONVENTIONS ## CONVENTIONS
- **Runtime**: Bun only — never use npm/yarn - **Runtime**: Bun only (1.3.11 in CI) -- never use npm/yarn
- **TypeScript**: strict mode, ESNext, bundler moduleResolution, `bun-types` (never `@types/node`) - **TypeScript**: strict mode, ESNext, bundler moduleResolution, `bun-types` (never `@types/node`)
- **Test pattern**: Bun test (`bun:test`), co-located `*.test.ts`, given/when/then style (nested describe with `#given`/`#when`/`#then` prefixes) - **Test pattern**: Bun test (`bun:test`), co-located `*.test.ts`, given/when/then style (nested describe with `#given`/`#when`/`#then` prefixes or inline `// given` / `// when` / `// then` comments)
- **CI test split**: mock-heavy tests run in isolation (separate `bun test` processes), rest in batch - **CI test split**: `script/run-ci-tests.ts` auto-detects `mock.module()` usage, isolates those tests in separate processes
- **Factory pattern**: `createXXX()` for all tools, hooks, agents - **Factory pattern**: `createXXX()` for all tools, hooks, agents
- **Hook tiers**: Session (23) → Tool-Guard (12) → Transform (4) → Continuation (7) → Skill (2) - **Hook tiers**: Session (24) → Tool-Guard (14) → Transform (5) → Continuation (7) → Skill (2)
- **Agent modes**: `primary` (respects UI model) vs `subagent` (own fallback chain) vs `all` - **Agent modes**: `primary` (respects UI model) vs `subagent` (own fallback chain) vs `all`
- **Model resolution**: 4-step: override → category-default → provider-fallback → system-default - **Model resolution**: 4-step: override → category-default → provider-fallback → system-default
- **Config format**: JSONC with comments, Zod v4 validation, snake_case keys - **Config format**: JSONC with comments, Zod v4 validation, snake_case keys
- **File naming**: kebab-case for all files/directories - **File naming**: kebab-case for all files/directories
- **Module structure**: index.ts barrel exports, no catch-all files (utils.ts, helpers.ts banned), 200 LOC soft limit - **Module structure**: index.ts barrel exports, no catch-all files (utils.ts, helpers.ts banned), 200 LOC soft limit
- **Imports**: relative within module, barrel imports across modules (`import { log } from "./shared"`) - **Imports**: relative within module, barrel imports across modules (`import { log } from "./shared"`)
- **No path aliases**: no `@/` — relative imports only - **No path aliases**: no `@/` -- relative imports only
- **Dual package**: `oh-my-opencode` + `oh-my-openagent` published simultaneously (transition period)
## ANTI-PATTERNS ## ANTI-PATTERNS
@@ -112,14 +114,14 @@ Fields: agents (14 overridable, 21 fields each), categories (8 built-in + custom
- Never suppress lint/type errors - Never suppress lint/type errors
- Never add emojis to code/comments unless user explicitly asks - Never add emojis to code/comments unless user explicitly asks
- Never commit unless explicitly requested - Never commit unless explicitly requested
- Never run `bun publish` directly — use GitHub Actions - Never run `bun publish` directly -- use GitHub Actions
- Never modify `package.json` version locally - Never modify `package.json` version locally
- Test: given/when/then — never use Arrange-Act-Assert comments - Test: given/when/then -- never use Arrange-Act-Assert comments
- Comments: avoid AI-generated comment patterns (enforced by comment-checker hook) - Comments: avoid AI-generated comment patterns (enforced by comment-checker hook)
- Never create catch-all files (`utils.ts`, `helpers.ts`, `service.ts`) - Never create catch-all files (`utils.ts`, `helpers.ts`, `service.ts`)
- Empty catch blocks `catch(e) {}` — always handle errors - Empty catch blocks `catch(e) {}` -- always handle errors
- Never use em dashes (—), en dashes (–), or AI filler phrases in generated content - Never use em dashes, en dashes, or AI filler phrases in generated content
- index.ts is entry point ONLY — never dump business logic there - index.ts is entry point ONLY -- never dump business logic there
## COMMANDS ## COMMANDS
@@ -138,20 +140,23 @@ bunx oh-my-opencode run # Non-interactive session
| Workflow | Trigger | Purpose | | Workflow | Trigger | Purpose |
|----------|---------|---------| |----------|---------|---------|
| ci.yml | push/PR to master/dev | Tests (split: mock-heavy isolated + batch), typecheck, build, schema auto-commit | | ci.yml | push/PR to master/dev | Tests (split: mock-heavy isolated + batch), typecheck, build, schema auto-commit |
| publish.yml | manual dispatch | Version bump, npm publish, platform binaries, GitHub release, merge to master | | publish.yml | manual dispatch | Version bump, dual npm publish (oh-my-opencode + oh-my-openagent), platform binaries, GitHub release |
| publish-platform.yml | called by publish | 12 platform binaries via bun compile (darwin/linux/windows) | | publish-platform.yml | called by publish | 11 platform binaries via bun compile (darwin/linux/windows) |
| sisyphus-agent.yml | @mention / dispatch | AI agent handles issues/PRs | | sisyphus-agent.yml | @mention / dispatch | AI agent handles issues/PRs |
| refresh-model-capabilities.yml | weekly schedule / dispatch | Auto-refresh model capabilities from models.dev API |
| cla.yml | issue_comment/PR | CLA assistant for contributors | | cla.yml | issue_comment/PR | CLA assistant for contributors |
| lint-workflows.yml | push to .github/ | actionlint + shellcheck on workflow files | | lint-workflows.yml | push to .github/ | actionlint + shellcheck on workflow files |
## NOTES ## NOTES
- Logger writes to `/tmp/oh-my-opencode.log` — check there for debugging - Logger writes to `/tmp/oh-my-opencode.log` -- check there for debugging
- Background tasks: 5 concurrent per model/provider (configurable) - Background tasks: 5 concurrent per model/provider (configurable, circuit breaker support)
- Plugin load timeout: 10s for Claude Code plugins - Plugin load timeout: 10s for Claude Code plugins
- Model fallback priority: Claude > OpenAI > Gemini > Copilot > OpenCode Zen > Z.ai > Kimi - Model fallback: per-agent chains in `shared/model-requirements.ts`, not a single global priority
- Config migration runs automatically on legacy keys (agent names, hook names, model versions) - Config migration: idempotent via `_migrations` tracking, creates timestamped backups before atomic writes
- Build: bun build (ESM) + tsc --emitDeclarationOnly, externals: @ast-grep/napi - Build: bun build (ESM) + tsc --emitDeclarationOnly, externals: @ast-grep/napi
- Test setup: `test-setup.ts` preloaded via bunfig.toml, mock-heavy tests run in isolation in CI - Test setup: `test-setup.ts` preloaded via bunfig.toml, resets session/cache state between tests
- 98 barrel export files (index.ts) establish module boundaries - 104 barrel export files (index.ts) establish module boundaries
- Architecture rules enforced via `.sisyphus/rules/modular-code-enforcement.md` - Architecture rules enforced via `.sisyphus/rules/modular-code-enforcement.md`
- Windows builds run on `windows-latest` runner (not cross-compiled) to avoid Bun segfaults
- Platform binaries detect AVX2 + libc family at runtime, fallback to baseline if needed