Built-in Commands
Relevant source files
The following files were used as context for generating this wiki page:
Built-in commands in Oh-My-OpenCode are specialized, high-level directives that provide structured workflows for complex development tasks. These commands go beyond simple tool calls by orchestrating multiple agents, background tasks, and deterministic verification steps to achieve specific outcomes such as project initialization, intelligent refactoring, or work plan generation.
These commands are implemented as templates that guide the primary orchestrator (Sisyphus) or specialized planning agents (Prometheus) through multi-phase execution loops. They leverage the project's orchestration capabilities, including parallel background exploration and automated verification through LSP and AST-grep tools.
Sources: README.md:154-175, src/features/builtin-commands/templates/refactor.ts:18-35
Command Discovery and Execution
The system utilizes a central discovery mechanism to load and execute commands from various scopes, including project-specific, user-global, and built-in templates.
Command Scopes and Loading
Commands are categorized into distinct scopes, which determines their priority and source location. The discoverCommandsSync function aggregates these from the filesystem and internal registers.
| Scope | Description | Source Path |
|---|---|---|
builtin | Hardcoded project commands | Internal templates |
opencode-project | Plugin-specific project commands | .opencode/command/ |
project | User-defined project commands | .claude/commands/ |
opencode | Plugin-specific global commands | ~/.config/opencode/command/ |
user | User-defined global commands | ~/.config/claude/commands/ |
Sources: src/tools/slashcommand/tools.ts:57-81
Execution Flow
When a slash command is invoked, the system follows a structured path to load, resolve references, and substitute arguments into the command template.
The formatLoadedCommand function handles the final preparation of the command string, ensuring that ${user_message} placeholders are replaced with actual user input and that all internal file references are expanded.
Sources: src/tools/slashcommand/tools.ts:114-142
Strategic Planning Commands
Planning is a core pillar of the built-in command architecture. Commands like /start-work (implied via Prometheus triggers) rely on a dedicated planning phase to ensure zero-human intervention during execution.
Prometheus Plan Generation
The Prometheus agent acts as a strategic planning consultant. It interprets user implementation requests as requests to "create a work plan."
| Phase | Action | Purpose |
|---|---|---|
| Interview | Default consultant mode | Clarify requirements and gather context |
| Metis Review | Mandatory consultation | Gap analysis and guardrail identification |
| Generation | Atomic plan write | Create .sisyphus/plans/*.md with verification strategy |
| Self-Review | Gap classification | Identify critical, minor, or ambiguous gaps |
Sources: src/agents/prometheus/identity-constraints.ts:25-50, src/agents/prometheus/plan-generation.ts:133-160
Specialized Built-in Templates
/init-deep: Hierarchical Documentation
The /init-deep command is used to generate or update AGENTS.md files across a project. It uses a complexity-scoring matrix to determine where documentation is most needed.
- Discovery: Simultaneously fires background explore agents to find entry points, conventions, and anti-patterns.
- Scoring: Weighs factors like file count (3x), module boundaries (2x), and reference centrality (3x) to decide where to place
AGENTS.mdfiles. - Parallel Generation: Once the root
AGENTS.mdis drafted, subdirectory files are generated in parallel writing tasks.
Sources: src/features/builtin-commands/templates/init-deep.ts:28-55, src/features/builtin-commands/templates/init-deep.ts:113-138
/refactor: Intelligent Transformation
The /refactor command implements a deterministic, multi-phase loop for codebase transformations.
Verification and Safety Standards
Every built-in command template enforces a strict verification protocol to maintain codebase integrity.
- LSP Diagnostics: Commands must check
lsp_diagnosticsafter changes to ensure zero new errors. - Test Requirement: The
/refactorcommand specifically assesses test coverage. If coverage is "LOW" or "NONE," the agent is instructed to block aggressive changes or ask the user to add tests first. - Deterministic Tools: Commands prioritize
lsp_renamefor symbol changes andast_grep_replace(with dry runs) for structural changes over simple regex.
Sources: src/features/builtin-commands/templates/refactor.ts:145-165, src/features/builtin-commands/templates/refactor.ts:285-305
Summary
Built-in commands provide the "intelligence" layer of Oh-My-OpenCode, transforming vague user requests into verifiable, multi-step execution paths. By combining template-based guidance with autonomous agent orchestration, these commands ensure that complex tasks like refactoring and project initialization follow established engineering best practices.
Sources: README.md:165-175, src/agents/prometheus/identity-constraints.ts:15-20