Commands & Automation
Relevant source files
The following files were used as context for generating this wiki page:
Commands & Automation in OpenWork provide a mechanism to turn repetitive agentic tasks into productized, reusable workflows. These are represented as / commands that trigger specific tools or prompts, effectively serving as an abstraction layer over raw CLI interactions for non-technical users.
The system allows users to save a task—complete with instructions and specific model configurations—as a command that can be re-run with new arguments. These commands are stored as Markdown files with YAML frontmatter, ensuring they are portable and version-controllable within the project's filesystem.
Sources: PRODUCT.md:129-130, README.md:10-20, ARCHITECTURE.md:12-25
Command Architecture and Storage
Commands are treated as first-class primitives within OpenWork. They are physically stored as .md files in specific directories depending on their intended scope.
Scoping and Locations
Commands exist in two primary scopes:
- Workspace Scope: Stored within the project directory at
.opencode/commands/. These are specific to a single project workspace. - Global Scope: Stored in the user's home directory at
~/.config/opencode/commands/. These are available across all workspaces.
Sources: packages/server/src/commands.ts:38-44, packages/app/src/app/command-state.ts:8
Command Data Structure
A command consists of metadata (name, description, agent, model) and a template (the prompt instructions). The template can include placeholders like $ARGUMENTS or $1, $2 to accept user input at runtime.
| Field | Type | Description |
|---|---|---|
name | string | The unique identifier used to trigger the command (e.g., /daily-standup). |
description | string | A short summary of what the command performs. |
template | string | The actual prompt or instructions sent to the OpenCode engine. |
agent | string | (Optional) Specifies a different model agent for execution. |
model | string | (Optional) The specific AI model to be used for this run. |
scope | string | Identifies if the command is workspace, global, or unknown. |
Sources: packages/server/src/commands.ts:28-35, packages/app/src/app/command-state.ts:11-30
Logic Flow: Command Execution
When a user triggers a command, the system creates a new OpenCode session specifically for that execution. If the command template contains placeholders, the UI prompts the user for details before submission.
Execution Sequence
The following diagram illustrates the lifecycle of a command execution from the UI to the OpenCode engine:
Explanation: This diagram shows how the CommandState manages session creation and command invocation via the SDK when a user triggers a command.
Sources: packages/app/src/app/command-state.ts:293-326, ARCHITECTURE.md:58-85
Command Management
Sanitization and Validation
Command names undergo strict sanitization to ensure filesystem compatibility. Spaces are replaced with hyphens, and non-alphanumeric characters (except underscores and hyphens) are removed.
// packages/app/src/app/command-state.ts:11-17
export const sanitizeCommandName = (value: string) => {
const trimmed = value.trim().replace(/^\/+/, "");
if (!trimmed) return "";
const normalized = trimmed.replace(/\s+/g, "-");
const cleaned = normalized.replace(/[^a-zA-Z0-9_-]/g, "");
return cleaned.replace(/-+/g, "-");
};
Sources: packages/app/src/app/command-state.ts:11-17, packages/server/src/commands.ts:57-58
Persistence Logic (Upsert)
Saving a command involves building a YAML frontmatter block and writing the content to the appropriate directory.
Explanation: The logic flow for persisting commands, accounting for both local (Tauri-based) and remote (OpenWork Server-based) storage.
Sources: packages/app/src/app/command-state.ts:145-195, packages/server/src/commands.ts:50-70
Automated Browser Setup
OpenWork includes pre-defined automation for common environment setups, such as browser automation. This is handled via the browser-setup command template.
Automation Flow for Browser Setup
- Check for Command: The UI checks if
browser-setup.mdexists in the workspace. - Auto-Provision: If missing, the app auto-writes the command to
.opencode/commands/browser-setup.md. - User Guidance: The command uses an LLM-driven flow to guide users through Chrome installation and MCP/plugin setup.
Sources: packages/app/pr/browser-entry-button.md:1-55
User Interface Components
The Commands view (commands.tsx) organizes available automations by scope and provides real-time feedback during the saving process.
Key UI Features
- Highlighting: When a command is saved, the UI scrolls to and highlights the new entry using
element.scrollIntoView. - Placeholder Detection: The UI identifies if a command requires additional details by checking the template for
$ARGUMENTSusing regex/\$(ARGUMENTS|\d+)/i. - Categorization: Commands are visually grouped into "Workspace", "Global", and "Other" (unknown scope) sections.
Sources: packages/app/src/app/pages/commands.tsx:35-55, packages/app/src/app/pages/commands.tsx:106-140
Conclusion
Commands & Automation bridge the gap between complex developer-centric tools and user-friendly product experiences. By leveraging a filesystem-backed Markdown format and a robust state management system, OpenWork enables users to define, share, and execute repeatable agentic workflows with minimal friction.