Files

T

YeonGyu-Kim 330e437f08 docs(agents): regenerate hierarchical AGENTS.md for 2026-05-20

Sync the AGENTS.md hierarchy to current code state:

Drift fixes in 11 existing files
- Root: 2026-05-20 commit 39aadbf9f, ~2167 TS files, 120 barrel index.ts,
  57 src/hooks dirs, 297 (179 non-test) src/shared files, 11 OpenCode hook
  handlers in plugin-interface.ts, packages list adds ast-grep-mcp + rules-core,
  first-prompt-watchdog 206 LOC, parent-wake-notifier 587 LOC
- src/AGENTS.md: file counts, plugin-interface handler count
- src/shared/AGENTS.md: title + counts 278/170 -> 297/179
- src/hooks/AGENTS.md: 57 dirs, note unwired WIP (task-reminder,
  hashline-edit-diff-enhancer)
- src/features/AGENTS.md: module map with NON-TEST counts + sub-AGENTS.md
  column, 7 modules without sub-doc
- src/features/background-agent/AGENTS.md: add 12 newer files (parent-wake-
  notifier 587 LOC, loop-detector, error-classifier, fallback-retry-handler,
  process-cleanup, subagent-spawn-limits, session-status-classifier,
  compaction-aware-message-resolver, etc.)
- src/plugin/AGENTS.md: 11 handlers, add system-transform.ts + command-
  execute-before.ts + build-team-idle-wake-hint-client.ts
- src/config/AGENTS.md: note schema/internal/permission.ts
- src/cli/AGENTS.md: 8 commands including 'version'
- src/plugin-handlers/AGENTS.md, packages/web/AGENTS.md: date bump

New AGENTS.md in 4 directories
- packages/AGENTS.md: index of 15 packages (11 platform binaries + 2 MCP
  packages + rules-core + web), role map, conventions
- docs/AGENTS.md: WHERE TO LOOK table for 19 docs across 6 subdirs
- .opencode/AGENTS.md: 5 skills + 4 slash commands + relationship to .agents/
- .agents/AGENTS.md: superset migration target (9 skills + 4 commands)

2026-05-20 17:18:44 +09:00

3.6 KiB

Raw Blame History

src/cli/ — CLI: install, run, doctor, mcp-oauth, refresh-model-capabilities, get-local-version, version, boulder

Generated: 2026-05-20

OVERVIEW

Commander.js CLI with 8 commands. Entry: index.ts → runCli() in cli-program.ts.

COMMANDS

Command	Purpose	Key Logic
`install`	Interactive/non-interactive setup	Provider selection → config gen → plugin registration
`run <message>`	Non-interactive session launcher	Agent resolution (flag → env → config → Sisyphus)
`doctor`	4-category health checks	System, Config, Tools, Models
`get-local-version`	Version detection	Installed vs npm latest
`version`	Print plugin version	Trivial 2-line subcommand
`mcp-oauth`	OAuth token management	login (PKCE), logout, status
`refresh-model-capabilities`	Refresh models.dev cache	Model capabilities refresh
`boulder`	Boulder state inspector	Format work-state + tasks from `.omo/boulder-state/`

STRUCTURE

cli/
├── index.ts                     # Entry point → runCli()
├── cli-program.ts               # Commander.js program (8 commands)
├── install.ts                   # Routes to TUI or CLI installer
├── cli-installer.ts             # Non-interactive (console output)
├── tui-installer.ts             # Interactive (@clack/prompts)
├── model-fallback.ts            # Model config gen by provider availability
├── provider-availability.ts     # Provider detection
├── fallback-chain-resolution.ts # Fallback chain logic
├── config-manager/              # 20 config utilities
│   ├── plugin registration, provider config
│   ├── JSONC operations, auth plugins
│   └── npm dist-tags, binary detection
├── doctor/
│   ├── runner.ts                # Parallel check execution
│   ├── formatter.ts             # Output formatting
│   └── checks/                  # 15 check files in 4 categories
│       ├── system.ts            # Binary, plugin, version
│       ├── config.ts            # JSONC validity, Zod schema
│       ├── tools.ts             # AST-Grep, LSP, GH CLI, MCP
│       └── model-resolution.ts  # Cache, resolution, overrides (6 sub-files)
├── run/                         # Session launcher
│   ├── runner.ts                # Main orchestration
│   ├── agent-resolver.ts        # Flag → env → config → Sisyphus
│   ├── session-resolver.ts      # Create/resume sessions
│   ├── event-handlers.ts        # Event processing
│   └── poll-for-completion.ts   # Wait for todos/background tasks
└── mcp-oauth/                   # OAuth token management

MODEL FALLBACK SYSTEM

No single global priority. CLI install-time resolution uses per-agent fallback chains from model-fallback-requirements.ts.

Common patterns: Claude/OpenAI/Gemini are preferred when an agent chain includes them, librarian prefers ZAI, sisyphus falls back through Kimi then GLM-5, and hephaestus requires OpenAI-compatible providers.

DOCTOR CHECKS

Category	Validates
System	Binary found, version >=1.0.150, plugin registered, version match
Config	JSONC validity, Zod schema, model override syntax
Tools	AST-Grep, comment-checker, LSP servers, GH CLI, MCP servers
Models	Cache exists, model resolution, agent/category overrides, availability

HOW TO ADD A DOCTOR CHECK

Create src/cli/doctor/checks/{name}.ts
Export check function matching DoctorCheck interface
Register in checks/index.ts

3.6 KiB Raw Blame History