AGENTS.md

1# src/config/ - Zod v4 Schema System
2 
3**Generated:** 2026-07-17 (7d664b96b)
4 
5## OVERVIEW
6 
736 non-test schema files composing `OhMyOpenCodeConfigSchema` (plus `schema/internal/permission.ts` for shared internal helpers). Zod v4 validation with `safeParse()`. All fields optional; omitted fields use defaults from the schema. Auto-emitted to `assets/oh-my-opencode.schema.json` via `bun run build:schema`.
8 
9## SCHEMA TREE
10 
11```
12config/schema/
13├── oh-my-opencode-config.ts    # ROOT: composes all sub-schemas
14├── agent-names.ts              # BuiltinAgentNameSchema enum (11 names: sisyphus, hephaestus, prometheus, oracle, librarian, explore, multimodal-looker, metis, momus, atlas, sisyphus-junior)
15├── agent-overrides.ts          # AgentOverrideConfigSchema (21 fields per agent)
16├── agent-definitions.ts        # custom agent definition schema
17├── categories.ts               # 8 built-in + custom categories
18├── hooks.ts                    # HookNameSchema (56 enum values; `team-tool-gating` is the only team-* one in schema; others are wired by direct config gates)
19├── skills.ts                   # SkillsConfigSchema (sources, paths, recursive)
20├── commands.ts                 # BuiltinCommandNameSchema (goal, refactor, start-work, stop-continuation, remove-ai-slops, hyperplan)
21├── experimental.ts             # Feature flags incl plugin_load_timeout_ms (min 1000), task_system, max_tools
22├── sisyphus.ts                 # SisyphusConfigSchema (task system)
23├── sisyphus-agent.ts           # SisyphusAgentConfigSchema
24├── goal.ts                     # GoalConfigSchema (enabled, auto_start, default_max_iterations) - replaces ralph_loop
25├── ralph-loop.ts               # RalphLoopConfigSchema (DEPRECATED: parsed loose at root, migrated to goal in validate.ts)
26├── tmux.ts                     # TmuxConfigSchema + TmuxLayoutSchema
27├── websearch.ts                # provider: "exa" | "tavily"
28├── claude-code.ts              # CC compatibility settings (plugins, plugins_override)
29├── comment-checker.ts          # AI comment detection config
30├── notification.ts             # OS notification settings
31├── git-master.ts               # commit_footer: boolean | string
32├── git-env-prefix.ts           # Git environment prefix config
33├── browser-automation.ts       # provider: playwright | agent-browser | dev-browser | playwright-cli; playwright_mcp_args (user-config only)
34├── background-task.ts          # Concurrency limits per model/provider, syncPollTimeoutMs
35├── fallback-models.ts          # FallbackModelsConfigSchema
36├── runtime-fallback.ts         # RuntimeFallbackConfigSchema (reactive provider fallback)
37├── babysitting.ts              # Unstable agent monitoring
38├── dynamic-context-pruning.ts  # Context pruning settings
39├── start-work.ts               # StartWorkConfigSchema (auto_commit)
40├── openclaw.ts                 # OpenClaw integration settings
41├── model-capabilities.ts       # Model capabilities config
42├── keyword-detector.ts         # disabled_keywords (ultrawork|search|analyze|team)
43├── default-mode.ts             # DefaultModeConfigSchema (auto-inject ultrawork / auto-create goal on session start)
44├── i18n.ts                     # I18nConfigSchema (locale override; falls back to LANG env var)
45├── codegraph.ts                # CodegraphConfigSchema (auto_init, auto_provision, enabled, telemetry, watch_debounce_ms)
46├── monitor.ts                  # MonitorConfigSchema (live_mode_enabled, allowed_commands, batch/ring limits, flush_interval_ms)
47├── tui.ts                      # TuiConfigSchema + TuiSidebarConfigSchema (sidebar.enabled)
48└── team-mode.ts                # TeamModeConfigSchema (enabled, max_parallel_members, max_members, tmux_visualization)
49```
50 
51## ROOT SCHEMA FIELDS
52 
53`$schema`, `new_task_system_enabled`, `default_run_agent`, `agent_order`, `agent_definitions`, `disabled_mcps`, `disabled_agents`, `disabled_skills`, `disabled_hooks`, `disabled_commands`, `disabled_tools`, `disabled_providers`, `mcp_env_allowlist`, `hashline_edit`, `telemetry`, `model_fallback`, `agents`, `categories`, `claude_code`, `sisyphus_agent`, `comment_checker`, `experimental`, `auto_update`, `skills`, **`goal`** (new; replaces `ralph_loop`), `ralph_loop` (deprecated; migrated to `goal` in `validate.ts`), `runtime_fallback`, `background_task`, `notification`, `model_capabilities`, `openclaw`, `i18n`, `monitor`, `codegraph`, **`team_mode`**, `keyword_detector`, `babysitting`, `git_master`, `browser_automation_engine`, `websearch`, `tmux`, `tui`, `sisyphus`, `start_work`, `default_mode`, `_migrations`.
54 
55## RALPH_LOOP -> GOAL MIGRATION
56 
57`goal` replaces the deprecated `ralph_loop` subsystem. `validate.ts` `migrateRalphLoopConfig()` maps legacy `ralph_loop.{enabled, default_max_iterations}` to `goal.{enabled, auto_start, default_max_iterations}` (`auto_start` defaults `false`, `default_max_iterations` defaults `100`); explicit `goal` config wins over migrated values. The root `ralph_loop` key is parsed loose (`z.record`) only for migration and logs a deprecation warning; `RalphLoopConfigSchema` still ships but is no longer composed into the root. `default_mode.ralph_loop` became `default_mode.goal` (auto-create a goal from the first main-session message). The `ralph-loop` hook and the `ralph-loop` / `ulw-loop` / `cancel-ralph` commands were removed; the `goal` hook and `goal` command replace them.
58 
59## TEAM_MODE SCHEMA (11 fields)
60 
61```jsonc
62{
63  "team_mode": {
64    "enabled": false,                       // gate for 12 team_* tools and conditional hooks
65    "tmux_visualization": false,            // render tmux pane layout for the team
66    "max_parallel_members": 4,              // 1..8 concurrent active members
67    "max_members": 8,                       // 1..8 hard cap on team size
68    "max_messages_per_run": 10000,          // ≥1
69    "max_wall_clock_minutes": 120,          // ≥1
70    "max_member_turns": 500,                // ≥1
71    "base_dir": null,                       // override of ~/.omo/teams or <project>/.omo/teams
72    "message_payload_max_bytes": 32768,     // ≥1024
73    "recipient_unread_max_bytes": 262144,   // ≥1024
74    "mailbox_poll_interval_ms": 3000        // ≥500
75  }
76}
77```
78 
79When `enabled: true`:
80- 12 `team_*` tools register (`tool-registry.ts` `teamModeToolsRecord`)
81- 3 team-mode hooks register conditionally: `team-mode-status-injector` + `team-mailbox-injector` (Transform tier) and `team-tool-gating` (Tool Guard tier)
82- 4 team-session-event handlers register in `src/plugin/event.ts`: `team-idle-wake-hint`, `team-lead-orphan-handler`, `team-member-error-handler`, `team-member-status-handler`
83- `team-mode` built-in skill loads
84- Doctor check `cli/doctor/checks/team-mode.ts` runs
85 
86## AGENT OVERRIDE FIELDS (per-agent)
87 
88`model`, `variant`, `category`, `skills`, `temperature`, `top_p`, `prompt`, `prompt_append`, `tools`, `disable`, `description`, `mode`, `color`, `permission`, `maxTokens`, `thinking`, `reasoningEffort`, `textVerbosity`, `providerOptions`, `fallback_models`, `ultrawork`.
89 
90## HOW TO ADD A CONFIG FIELD
91 
921. Create `src/config/schema/{name}.ts` with Zod schema
932. Add field to `oh-my-opencode-config.ts` root schema
943. Reference via `z.infer<typeof YourSchema>` for the TypeScript type
954. Access in handlers via `pluginConfig.{field_name}` (snake_case JSON, snake_case TS field)
965. Run `bun run build:schema` to regenerate `assets/oh-my-opencode.schema.json`
97