CLI Reference
Relevant source files
The following files were used as context for generating this wiki page:
The CLI (Command Line Interface) in the OhMyOpenCode project serves as the primary entry point for user interaction with autonomous AI agents. It facilitates project initialization, task planning, and execution management. The CLI translates high-level user intents into structured workflows executed by specialized agents such as Prometheus (the planner) and Sisyphus (the orchestrator).
Key functionalities provided through the interface include project knowledge base generation, work plan initialization, and Git history management. The system is designed to handle tasks ranging from trivial single-file fixes to complex multi-module architectural changes.
Core Built-in Commands
The CLI provides specialized commands to manage the lifecycle of an AI-assisted development session. These commands often trigger specific templates or agent modes.
Project Initialization: /init-deep
The /init-deep command is used to generate a hierarchical knowledge base for the project by creating or updating AGENTS.md files. It employs a scoring matrix to determine which directories require dedicated documentation based on file count, complexity, and symbol density.
| Option | Description |
|---|---|
--create-new | Reads existing context, removes all current AGENTS.md files, and regenerates from scratch. |
--max-depth=N | Limits the directory depth for documentation generation (default: 3). |
Sources: src/features/builtin-commands/templates/init-deep.ts:4-8
Work Execution: /start-work
This command initiates the execution phase. It transitions the system from Planning Mode (Prometheus) to Orchestration Mode (Sisyphus or Atlas). It requires a generated plan file typically located in .sisyphus/plans/{name}.md.
Sources: src/agents/prometheus/identity-constraints.ts:60, src/agents/prometheus/interview-mode.ts:241
Agent Planning & Interview Flow
The CLI interacts with the Prometheus agent to establish a work plan before implementation begins. This process is governed by a multi-phase interview and research loop.
Intent Classification
When a user provides a prompt, the system classifies the intent to determine the depth of the consultation.
| Intent Tier | Signal | Strategy |
|---|---|---|
| Trivial | Single file, <10 lines | Skip heavy interview; quick confirm then plan. |
| Refactoring | Existing code changes | Focus on safety, test coverage, and risk. |
| Architecture | System design, 5+ modules | Deep interview; mandatory Oracle consultation. |
| Research | Path unclear | Parallel probes and synthesis. |
Sources: src/agents/prometheus/interview-mode.ts:13-25, src/agents/prometheus/gpt.ts:74-80
Discovery & Research Logic
Before asking the user questions, the CLI triggers parallel background research using explore and librarian subagents.
The diagram above illustrates the transition from initial user prompt to the generation of a decision-complete work plan.
Sources: src/agents/prometheus/interview-mode.ts:71-90, src/agents/prometheus/gpt.ts:130-145
Task & Todo Management
The CLI tracks work through two primary systems: the Task System (for high-level coordination) and Todo Discipline (for atomic step tracking).
Execution Workflow
- On Start: Create tasks/todos with atomic steps immediately upon receiving a request.
- In Progress: Mark exactly one task as
in_progressbefore starting the step. - Completed: Mark as
completedimmediately after finishing; batching is forbidden. - Scope Changes: Update tasks before proceeding with new work.
Sources: src/agents/hephaestus/gpt.ts:40-52, src/agents/sisyphus/default.ts:43-55
Manual QA Mandate
The CLI requires evidence of manual verification. Acceptance criteria must be defined before coding, and evidence must be reported for all user-facing changes.
| Change Type | Required Verification Action |
|---|---|
| CLI Command | Run command in Bash and show output. |
| Build Output | Run build and verify output files exist. |
| API Behavior | Call endpoint via curl and show response. |
| UI Changes | Use Playwright to load page and verify interactions. |
Sources: src/hooks/keyword-detector/ultrawork/gemini.ts:200-215, src/hooks/keyword-detector/ultrawork/gpt.ts:125-135
Git Operations Reference
Specialized Git operations are handled by the git-master skill, which enforces strict atomic commit patterns and history management.
Commit Strategies
The system enforces a "Multiple Commits by Default" rule based on the number of files changed.
- 3+ files: Minimum 2 commits.
- 5+ files: Minimum 3 commits.
- 10+ files: Minimum 5 commits.
Sources: src/features/builtin-skills/git-master/SKILL.md:33-40
History Archaeologist Commands
The CLI supports several history search patterns for debugging and analysis:
| Goal | Command Pattern |
|---|---|
| Find when string was added | git log -S "string" --oneline |
| Find regex in diffs | git log -G "regex" --oneline |
| Line attribution | git blame -L start,end path/to/file |
| Locate bug origin | git bisect start && git bisect bad && git bisect good [tag] |
Sources: src/features/builtin-skills/git-master/SKILL.md:380-410
Execution Environment Constraints
The CLI operates within strict boundaries to ensure safety and project integrity.
- Prometheus (Planner): Restricted to writing only
.mdfiles in.sisyphus/plans/and.sisyphus/drafts/. It is forbidden from editing source code or running implementation commands. - Sisyphus/Hephaestus (Executors): Must run
lsp_diagnosticson all modified files and ensure a zero-error exit code for builds/tests. - Session Continuity: Every tool-triggered
task()returns asession_id. Subsequent CLI interactions must reuse this ID to preserve context and reduce token overhead.
Sources: src/agents/prometheus/identity-constraints.ts:30-45, src/agents/sisyphus/default.ts:250-265, src/agents/hephaestus/gpt.ts:192-200
The CLI architecture ensures a transition from strategic planning to verified implementation, maintaining a rigorous audit trail via markdown plans and task tracking.