AGENTS.md

1# src/cli/ — CLI: install, run, doctor, mcp (oauth), refresh-model-capabilities, get-local-version, version, boulder, cleanup, ulw-loop
2 
3**Generated:** 2026-07-03
4 
5## OVERVIEW
6 
7Commander.js CLI with 10 commands (`sparkshell` removed 2026-07). Entry: `index.ts` → `runCli()` in `cli-program.ts`.
8 
9## COMMANDS
10 
11| Command | Purpose | Key Logic |
12|---------|---------|-----------|
13| `install` | Interactive/non-interactive setup | Provider selection → config gen → plugin registration |
14| `run <message>` | Non-interactive session launcher | Agent resolution (flag → env → config → Sisyphus) |
15| `doctor` | 4-category health checks | System, Config, Tools, Models |
16| `get-local-version` | Version detection | Installed vs npm latest |
17| `version` | Print plugin version | Trivial 2-line subcommand |
18| `mcp` | MCP management; nested `oauth` group | `mcp oauth login <server-name>` (PKCE), `logout`, `status` |
19| `refresh-model-capabilities` | Refresh models.dev cache | Model capabilities refresh |
20| `boulder` | Boulder state inspector | Format work-state + tasks from `.omo/boulder-state/` |
21| `cleanup` (alias `uninstall`) | Remove Codex Light state | Clean managed Codex cache/marketplace + repair project-local legacy Codex artifacts |
22| `ulw-loop` | Codex ulw-loop CLI | Run the Codex LazyCodex ulw-loop CLI |
23 
24`install` accepts `--platform=opencode|codex|both` (default `opencode`). `codex`/`both` route through `install-codex/` to install the Codex CLI Light edition (also `npx lazycodex-ai install`). See `packages/omo-codex/AGENTS.md`.
25 
26## STRUCTURE
27 
28```
29cli/
30├── index.ts                     # Entry point → runCli()
31├── cli-program.ts               # Commander.js program (10 commands)
32├── install.ts                   # Routes to TUI or CLI installer
33├── cli-installer.ts             # Non-interactive (console output)
34├── tui-installer.ts             # Interactive (@clack/prompts)
35├── model-fallback.ts            # Model config gen by provider availability
36├── provider-availability.ts     # Provider detection
37├── fallback-chain-resolution.ts # Fallback chain logic
38├── config-manager/              # 20 config utilities
39│   ├── plugin registration, provider config
40│   ├── JSONC operations, auth plugins
41│   └── npm dist-tags, binary detection
42├── doctor/
43│   ├── runner.ts                # Parallel check execution
44│   ├── formatter.ts             # Output formatting
45│   └── checks/                  # 15 check files in 4 categories
46│       ├── system.ts            # Binary, plugin, version
47│       ├── config.ts            # JSONC validity, Zod schema
48│       ├── tools.ts             # AST-Grep, LSP, GH CLI, MCP
49│       └── model-resolution.ts  # Cache, resolution, overrides (6 sub-files)
50├── run/                         # Session launcher
51│   ├── runner.ts                # Main orchestration
52│   ├── agent-resolver.ts        # Flag → env → config → Sisyphus
53│   ├── session-resolver.ts      # Create/resume sessions
54│   ├── event-handlers.ts        # Event processing
55│   └── poll-for-completion.ts   # Wait for todos/background tasks
56└── mcp-oauth/                   # OAuth token management
57```
58 
59## MODEL FALLBACK SYSTEM
60 
61No single global priority. CLI install-time resolution uses per-agent fallback chains from `model-fallback-requirements.ts`.
62 
63Common patterns: Claude/OpenAI/Gemini are preferred when an agent chain includes them, `librarian` follows its fallback chain before GLM providers, `sisyphus` falls back through Kimi then GLM-5, and `hephaestus` requires OpenAI-compatible providers.
64 
65## DOCTOR CHECKS
66 
67| Category | Validates |
68|----------|-----------|
69| **System** | Binary found, version >=1.0.150, plugin registered, version match |
70| **Config** | JSONC validity, Zod schema, model override syntax |
71| **Tools** | AST-Grep, comment-checker, LSP servers, GH CLI, MCP servers |
72| **Models** | Cache exists, model resolution, agent/category overrides, availability |
73 
74## HOW TO ADD A DOCTOR CHECK
75 
761. Create `src/cli/doctor/checks/{name}.ts`
772. Export check function matching `DoctorCheck` interface
783. Register in `checks/index.ts`
79