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

docs(agents): document omo-codex Light edition (lazycodex) across AGENTS.md tree

Browse Source 
- root: refresh stale header (v4.2.0->v4.5.12 / 39aadbf9f->92bad87d8 / 2026-05-31), add CODEX LIGHT EDITION section (identity, marketplace sisyphuslabs/omo precision, lazycodex-ai disambiguation, 8 components, install, publish.yml lazycodex pipeline, telemetry), fix package counts and hook-handler count (13->14)
- packages: 23->26 sibling packages (+git-bash-mcp +omo-codex +shared-skills)
- packages/omo-codex: new AGENTS.md (layout, 8 components, install + sync-script mechanics)
- src/cli: note --platform=codex install path via install-codex/
This commit is contained in:
YeonGyu-Kim
2026-05-31 14:19:34 +09:00
parent 92bad87d84
commit 247bba39e5
4 changed files with 87 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+30 -10
View File
@@ -2,11 +2,11 @@
> **HOLD THE FUCK UP. THIS ENTIRE GODDAMN CODEBASE IS BEING RIPPED APART AND REBUILT RIGHT NOW. A MASSIVE MULTI-HARNESS AGENT OS REFACTOR IS IN PROGRESS — WE ARE RESTRUCTURING EVERYTHING TO SUPPORT MULTIPLE AGENT HARNESSES (OPENCODE, CODEX, PI, AND OTHERS). DO NOT TRUST THE STRUCTURE BELOW AS STABLE. READ THE [ROADMAP](./ROADMAP.md) BEFORE YOU TOUCH ANYTHING OR SO HELP ME GOD.**
**Generated:** 2026-05-20 | **Commit:** 39aadbf9f | **Branch:** dev | **Release:** v4.2.0
**Generated:** 2026-05-31 | **Commit:** 92bad87d8 | **Branch:** dev | **Release:** v4.5.12
## OVERVIEW
OpenCode plugin (npm: `oh-my-opencode`, dual-published as `oh-my-openagent` during the rename transition) extending OpenCode with 11 agents, 54–61 lifecycle hooks (base / +team-mode) across 57 dirs, 20–39 tools (gated by config flags including team-mode), 3-tier MCP system (built-in + .mcp.json + skill-embedded), Hashline LINE#ID edit tool, IntentGate keyword detector, Team Mode (parallel multi-agent coordination, OFF by default), Boulder feature (boulder-state work tracking + cli/boulder subcommand), configurable agent ordering, and Claude Code compatibility. **Repository contains ~2167 TypeScript files across `src/`, `script/`, `test-support/`, and `packages/web/`, ~313k LOC; `src/` itself has 120 barrel `index.ts` files.** Entry: `src/index.ts` is an 18-line wrapper that delegates to `src/testing/create-plugin-module.ts` `createPluginModule()` → 7-step init.
OpenCode plugin (npm: `oh-my-opencode`, dual-published as `oh-my-openagent` during the rename transition) extending OpenCode with 11 agents, 54-61 lifecycle hooks (base / +team-mode) across 57 dirs, 20-39 tools (gated by config flags including team-mode), 3-tier MCP system (built-in + .mcp.json + skill-embedded), Hashline LINE#ID edit tool, IntentGate keyword detector, Team Mode (parallel multi-agent coordination, OFF by default), Boulder feature (boulder-state work tracking + cli/boulder subcommand), configurable agent ordering, and Claude Code compatibility. **Repository contains ~2167 TypeScript files across `src/`, `script/`, `test-support/`, and `packages/web/`, ~313k LOC; `src/` itself has 120 barrel `index.ts` files.** Entry: `src/index.ts` is an 18-line wrapper that delegates to `src/testing/create-plugin-module.ts` `createPluginModule()` → 7-step init. Ships in two editions of one product: **Ultimate** (omo for OpenCode, this plugin) and **Light** (omo for Codex CLI = [`packages/omo-codex/`](file:///Users/yeongyu/local-workspaces/omo/packages/omo-codex/AGENTS.md), distributed as the `lazycodex` alias; see CODEX LIGHT EDITION below).
## STRUCTURE
@@ -15,7 +15,7 @@ oh-my-opencode/
├── src/
│ ├── index.ts # Plugin entry; thin wrapper that re-exports `createPluginModule()` from `src/testing/`
│ ├── plugin-config.ts # JSONC multi-level config: user → project → defaults (Zod v4)
│ ├── plugin-interface.ts # 11 OpenCode hook handlers (+2 wired in src/testing/create-plugin-module.ts)
│ ├── plugin-interface.ts # 12 OpenCode hook handlers (+2 wired in src/testing/create-plugin-module.ts)
│ ├── create-managers.ts # 4 managers (Tmux, Background, SkillMcp, ConfigHandler)
│ ├── create-tools.ts # ToolRegistry composition
│ ├── create-hooks.ts # 5-tier hook composition
@@ -27,12 +27,12 @@ oh-my-opencode/
│ ├── config/ # Zod v4 schema system (30 schema files)
│ ├── cli/ # CLI: install, run, doctor, mcp-oauth, refresh-model-capabilities, get-local-version, boulder
│ ├── mcp/ # 5 built-in MCPs (3 remote + local stdio lsp + ast_grep)
│ ├── plugin/ # 11 OpenCode hook handlers + 5-tier hook composition
│ ├── plugin/ # 12 OpenCode hook handlers + 5-tier hook composition
│ ├── plugin-handlers/ # 6-phase config loading pipeline
│ ├── openclaw/ # Bidirectional external integration (Discord/Telegram/HTTP/shell + reply listener daemon)
│ ├── generated/ # model-capabilities.generated.json (refreshed via build:model-capabilities)
│ └── testing/ # Test utilities + `create-plugin-module.ts` (extracted plugin entry factory, 182 LOC)
├── packages/ # 11 platform binaries + 2 MCP packages + 9 Core packages + web
├── packages/ # 26 sibling pkgs: 11 platform binaries + 3 MCP packages + 9 Core packages + omo-codex (Codex Light) + shared-skills + web
│ ├── utils/ # Shared utilities — deep-merge, snake-case, frontmatter, file-utils, etc.
│ ├── model-core/ # Model resolution pipeline with ProviderCache DI
│ ├── prompts-core/ # Markdown prompt loading + bundled mode prompts (search/analyze/team/hyperplan)
@@ -42,6 +42,9 @@ oh-my-opencode/
│ ├── comment-checker-core/ # apply-patch parser, binary runner with injectable spawn
│ ├── hashline-core/ # Hashline edit primitives and diff helpers shared by adapter shims
│ ├── boulder-state/ # Work tracking state machine, split storage
│ ├── omo-codex/ # Codex CLI Light edition (lazycodex); vendored Codex plugin `omo` + TS installer + telemetry
│ ├── git-bash-mcp/ # Windows-only git_bash stdio MCP (Codex edition)
│ ├── shared-skills/ # Cross-harness SKILL.md bundle shared by OpenCode + Codex
│ └── web/ # Marketing site (Next.js 15 + Cloudflare Workers). Independent package with own bun.lock
├── bin/ # Platform-detection JS shim (oh-my-opencode + oh-my-openagent)
├── script/ # Build/publish automation (singular, not scripts/)
@@ -71,17 +74,18 @@ pluginModule.server(input, options)
├─→ createManagers() # TmuxSessionManager, BackgroundManager, SkillMcpManager, ConfigHandler
├─→ createTools() # SkillContext + AvailableCategories + ToolRegistry
├─→ createHooks() # 5-tier: Session + ToolGuard + Transform + Continuation + Skill
└─→ createPluginInterface() # 11 OpenCode hook handlers → PluginInterface
└─→ createPluginInterface() # 12 OpenCode hook handlers → PluginInterface
```
## 13 OPENCODE HOOK HANDLERS
## 14 OPENCODE HOOK HANDLERS
11 wired in [`src/plugin-interface.ts`](file:///Users/yeongyu/local-workspaces/omo/src/plugin-interface.ts) + 2 wired directly in [`src/testing/create-plugin-module.ts`](file:///Users/yeongyu/local-workspaces/omo/src/testing/create-plugin-module.ts) (`experimental.session.compacting` + `experimental.compaction.autocontinue`).
12 wired in [`src/plugin-interface.ts`](file:///Users/yeongyu/local-workspaces/omo/src/plugin-interface.ts) + 2 wired directly in [`src/testing/create-plugin-module.ts`](file:///Users/yeongyu/local-workspaces/omo/src/testing/create-plugin-module.ts) (`experimental.session.compacting` + `experimental.compaction.autocontinue`).
| Handler | OpenCode Hook | Purpose |
|---------|---------------|---------|
| `config` | `config` | 6-phase pipeline: provider → plugin-components → agents → tools → MCPs → commands |
| `tool` | `tool` | 20–39 registered tools (config-gated: team-mode +12, task system +4, hashline +1, interactive_bash +1, look_at +1) |
| `tool.definition` | `tool.definition` | Per-tool definition transform (applies `todo-description-override`) |
| `chat.message` | `chat.message` | First-message variant, session setup, keyword detection (ultrawork/search/analyze/team) |
| `chat.params` | `chat.params` | Anthropic effort, think mode, runtime fallback override |
| `chat.headers` | `chat.headers` | Copilot `x-initiator` header injection |
@@ -137,6 +141,22 @@ Teams live as directories under `~/.omo/teams/{name}/config.json` (user) or `<pr
**Implementation:** [`src/features/team-mode/`](file:///Users/yeongyu/local-workspaces/omo/src/features/team-mode/AGENTS.md). User docs: [`docs/guide/team-mode.md`](file:///Users/yeongyu/local-workspaces/omo/docs/guide/team-mode.md).
## CODEX LIGHT EDITION (omo-codex / lazycodex)
oh-my-openagent ships in two editions of one product. **Ultimate** = this OpenCode plugin (omo for OpenCode). **Light** = omo for the OpenAI Codex CLI, vendored under [`packages/omo-codex/`](file:///Users/yeongyu/local-workspaces/omo/packages/omo-codex/AGENTS.md). "omo in Codex" / "omo for Codex" = **lazycodex**, and the public GitHub repo [`code-yeongyu/lazycodex`](https://github.com/code-yeongyu/lazycodex) IS this: a thin distribution layer over `omo-codex` (site lazycodex.ai; "Codex for no-brainers, just prompt with `ultrawork`"; Codex edition "coming June 2026", currently OpenCode-only).
- **Package:** `@oh-my-opencode/omo-codex` (private, v0.1.0): "Codex harness adapter. Vendored Codex plugin namespace `omo` + TypeScript installer + telemetry." Plugin bundle pkg = `@sisyphuslabs/omo-codex-plugin`. Reuses `@oh-my-opencode/utils` + `@oh-my-opencode/shared-skills`.
- **Marketplace identity (precision):** Codex sees marketplace `sisyphuslabs`, plugin `omo`, enabled as `omo@sisyphuslabs`. `lazycodex` is ONLY the repo/npm/bin alias, never the marketplace name.
- **Alias mechanics:** root `package.json` maps `lazycodex` to `bin/oh-my-opencode.js` (1 of 4 bin aliases: `oh-my-opencode`, `oh-my-openagent`, `omo`, `lazycodex`, all the same compiled CLI). `bunx lazycodex install` is exactly `bunx omo install --platform=codex`. Routing: `src/cli/cli-program.ts` (lazycodex defaults platform to codex), `bin/platform.js` (lazycodex resolves the `oh-my-openagent` platform family). `src/cli/star-request.ts` stars both repos.
- **Disambiguation:** the `lazycodex` npm package (this repo's CLI republished by `publish.yml` with a name/version rewrite) is NOT `lazycodex-ai` (the `code-yeongyu/lazycodex` repo's own published npm package, currently `lazycodex-ai@0.2.1`).
- **Components (8):** `comment-checker`, `git-bash`, `lsp`, `rules`, `start-work-continuation`, `telemetry`, `ultrawork`, `ulw-loop`, wired to Codex events `SessionStart`/`UserPromptSubmit`/`PreToolUse`/`PostToolUse`/`PostCompact`/`Stop`/`SubagentStop`. No agent orchestration, no `team_*`, no built-in MCPs beyond LSP, no hashline.
- **Install:** `bunx omo install --platform=codex` (or `bunx lazycodex install`, or `--platform=both`) copies the plugin to `~/.codex/plugins/cache/sisyphuslabs/omo/<version>/`, links agent TOMLs via `~/.codex/.tmp/marketplaces/sisyphuslabs/plugins/omo/`, enables `omo@sisyphuslabs` in `~/.codex/config.toml`, links component CLIs into `~/.local/bin`. Windows: Git Bash preflight (`winget install --id Git.Git`). Installer: [`src/cli/install-codex/`](file:///Users/yeongyu/local-workspaces/omo/src/cli/install-codex/) + `packages/omo-codex/scripts/install*.mjs`.
- **Deploy / publish** ([`.github/workflows/publish.yml`](file:///Users/yeongyu/local-workspaces/omo/.github/workflows/publish.yml), manual dispatch):
- `publish_lazycodex` (default **true**) publishes the npm alias `lazycodex`: rewrites root `package.json` name to `lazycodex` + version to the release + optionalDeps `oh-my-opencode-*` to `oh-my-openagent-*`, skips when `registry.npmjs.org/lazycodex/${VERSION}` exists, publishes `--access public --provenance --tag latest`, then restores `package.json`.
- `sync_lazycodex_marketplace` (default **false**, needs secret `LAZYCODEX_SYNC_TOKEN`) checks out `code-yeongyu/lazycodex`, builds the plugin + ast-grep-mcp + lsp-tools-mcp, runs [`script/sync-lazycodex-marketplace.ts`](file:///Users/yeongyu/local-workspaces/omo/script/sync-lazycodex-marketplace.ts) `<source-root> <lazycodex-root>`, then `git push origin HEAD:main`.
- **Sync mechanism is file copy + commit push, NOT a git subtree:** `marketplace.json` to `.agents/plugins/marketplace.json`; `plugin/` to `plugins/omo/`; bundles `ast-grep-mcp` + `lsp-tools-mcp` `dist/cli.js` to `plugins/omo/components/*/dist/`; rewrites `.mcp.json` paths; validates via `script/lazycodex-marketplace-validation.ts`. Root `package.json` `files` ships `packages/omo-codex/{marketplace.json,plugin,plugin/.codex-plugin,scripts}`. First-publish playbook: [`docs/reference/lazycodex-npm-reservation.md`](file:///Users/yeongyu/local-workspaces/omo/docs/reference/lazycodex-npm-reservation.md). CI gate: `bun run test:codex` (ci.yml `codex-compatibility`, ubuntu/macos/windows).
- **Telemetry:** event `omo_codex_daily_active` (once per UTC day per machine, id `sha256("omo-codex:"+hostname)`); opt-out `OMO_CODEX_DISABLE_POSTHOG=1` / `OMO_CODEX_SEND_ANONYMOUS_TELEMETRY=0` (global flags also disable). Full internals: [`packages/omo-codex/AGENTS.md`](file:///Users/yeongyu/local-workspaces/omo/packages/omo-codex/AGENTS.md).
## MULTI-LEVEL CONFIG
```
@@ -252,8 +272,8 @@ bunx oh-my-opencode mcp-oauth login <server-url> # Tier-3 MCP OAuth (PKCE + DCR
| Workflow | Trigger | Purpose |
|----------|---------|---------|
| `ci.yml` | push/PR to master/dev | Tests, typecheck, build, auto-commit schema on master push, draft "next" release on dev push (blocks master-targeting PRs) |
| `publish.yml` | manual dispatch | Test, typecheck, preflight-trust (OIDC verify 24 packages), dual npm publish (`oh-my-opencode` + `oh-my-openagent`), platform binaries, GitHub release, merge to master |
| `ci.yml` | push/PR to master/dev | Tests, typecheck, build, codex-compatibility (`bun run test:codex`, ubuntu/macos/windows), auto-commit schema on master push, draft "next" release on dev push (blocks master-targeting PRs) |
| `publish.yml` | manual dispatch | Test, typecheck, preflight-trust (OIDC verify 24 packages), dual npm publish (`oh-my-opencode` + `oh-my-openagent`) + `lazycodex` npm alias (`publish_lazycodex`, default on) + optional Codex marketplace sync to `code-yeongyu/lazycodex` (`sync_lazycodex_marketplace`, default off, needs `LAZYCODEX_SYNC_TOKEN`), platform binaries, GitHub release, merge to master |
| `publish-platform.yml` | called by publish.yml | 11 platform binaries via `bun compile` (darwin/linux/windows) |
| `sisyphus-agent.yml` | @mention or manual dispatch | AI agent handles issues/PRs |
| `refresh-model-capabilities.yml` | weekly cron / dispatch | Refresh model capabilities from models.dev API |