diff --git a/packages/web/src/content/docs/docs/commands.mdx b/packages/web/src/content/docs/docs/commands.mdx index 621cf872..59c9536a 100644 --- a/packages/web/src/content/docs/docs/commands.mdx +++ b/packages/web/src/content/docs/docs/commands.mdx @@ -3,7 +3,13 @@ title: Commands description: Create custom commands for repetitive tasks. --- -Define custom commands to automate repetitive coding tasks. +Custom commands let you specify a prompt you want to run when that command is executed in the TUI. + +```bash frame="none" +/my-command +``` + +Custom commands are in addition to the built-in commands like `/init`, `/undo`, `/redo`, `/share`, `/help`. [Learn more](/docs/tui#commands). --- @@ -34,12 +40,78 @@ Use the command by typing `/` followed by the command name. --- -## Use arguments +## Configure + +You can add custom commands through the opencode config or by creating markdown files in the `command/` directory. + +--- + +### JSON + +Use the `command` option in your opencode [config](/docs/config): + +```json title="opencode.jsonc" {4-12} +{ + "$schema": "https://opencode.ai/config.json", + "command": { + // This becomes the name of the command + "test": { + // This is the prompt that will be sent to the LLM + "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.", + // This is show as the description in the TUI + "description": "Run tests with coverage", + "agent": "build", + "model": "anthropic/claude-3-5-sonnet-20241022" + }, + } +} +``` + +Now you can run this command in the TUI: + +```bash frame="none" +/test +``` + +--- + +### Markdown + +You can also define commands using markdown files. Place them in: + +- Global: `~/.config/opencode/command/` +- Per-project: `.opencode/command/` + +```markdown title="~/.config/opencode/command/test.md" +--- +description: Run tests with coverage +agent: build +model: anthropic/claude-3-5-sonnet-20241022 +--- + +Run the full test suite with coverage report and show any failures. +Focus on the failing tests and suggest fixes. +``` + +The markdown file name becomes the command name. For example, `test.md` lets +you run: + +```bash frame="none" +/test +``` + +--- + +## Prompt config + +The prompts for the custom commands support several special placeholders and syntax. + +--- + +### Arguments Pass arguments to commands using the `$ARGUMENTS` placeholder. -Create `.opencode/command/component.md`: - ```md title=".opencode/command/component.md" --- description: Create a new component @@ -52,16 +124,18 @@ Include proper typing and basic structure. Run the command with arguments: ```bash frame="none" -"/component Button" +/component Button ``` +And `$ARGUMENTS` will be replaced with `Button`. + --- -## Inject shell output +### Shell output -Use !`command` to inject shell command output into your prompt. +Use _!`command`_ to inject [bash command](/docs/tui#bash-commands) output into your prompt. -Create `.opencode/command/analyze-coverage.md`: +For example, to create a custom command that analyzes test coverage: ```md title=".opencode/command/analyze-coverage.md" --- @@ -74,7 +148,7 @@ Here are the current test results: Based on these results, suggest improvements to increase coverage. ``` -Create `.opencode/command/review-changes.md`: +Or to review recent changes: ```md title=".opencode/command/review-changes.md" --- @@ -91,12 +165,10 @@ Commands run in your project's root directory and their output becomes part of t --- -## Reference files +### File references Include files in your command using `@` followed by the filename. -Create `.opencode/command/review-component.md`: - ```md title=".opencode/command/review-component.md" --- description: Review component @@ -110,47 +182,90 @@ The file content gets included in the prompt automatically. --- -## Command properties +## Options -Configure commands with these optional frontmatter properties: +Let's look at the configuration options in detail. -- **description**: Brief explanation of what the command does -- **agent**: Agent to use (defaults to "build") -- **model**: Specific model to use for this command - -Create `.opencode/command/code-review.md`: - -```md title=".opencode/command/code-review.md" ---- -description: Code review assistant -agent: build -model: anthropic/claude-3-5-sonnet-20241022 --- -Review the code for best practices and suggest improvements. +### Template + +The `template` option defines the prompt that will be sent to the LLM when the command is executed. + +```json title="opencode.json" +{ + "command": { + "test": { + "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes." + } + } +} ``` ---- - -## Command directory - -Store command files in these locations: - -- `.opencode/command/` - Project-specific commands -- `command/` - Global commands in config directory - -Project commands take precedence over global ones. +This is a **required** config option. --- -## Built-in commands +### Description -opencode includes several built-in commands: +Use the `description` option to provide a brief description of what the command does. -- `/init` - Initialize project and create AGENTS.md -- `/undo` - Revert the last changes -- `/redo` - Restore reverted changes -- `/share` - Share the current conversation -- `/help` - Show available commands and keybinds +```json title="opencode.json" +{ + "command": { + "test": { + "description": "Run tests with coverage" + } + } +} +``` -Use `/help` to see all available commands in your setup. +This is shown as the description in the TUI when you type in the command. + +--- + +### Agent + +Use the `agent` config to optionally specify which [agent](/docs/agents) should execute this command. + +```json title="opencode.json" +{ + "command": { + "review": { + "agent": "plan" + } + } +} +``` + +This is an **optional** config option. If not specified, defaults to "build". + +--- + +### Model + +Use the `model` config to override the default model for this command. + +```json title="opencode.json" +{ + "command": { + "analyze": { + "model": "anthropic/claude-3-5-sonnet-20241022" + } + } +} +``` + +This is an **optional** config option. + +--- + +## Built-in + +opencode includes several built-in commands like `/init`, `/undo`, `/redo`, `/share`, `/help`; [learn more](/docs/tui#commands). + +:::note +Custom commands can override built-in commands. +::: + +If you define a custom command with the same name, it will override the built-in command. diff --git a/packages/web/src/content/docs/docs/config.mdx b/packages/web/src/content/docs/docs/config.mdx index 06eb6ee7..045bc596 100644 --- a/packages/web/src/content/docs/docs/config.mdx +++ b/packages/web/src/content/docs/docs/config.mdx @@ -152,6 +152,32 @@ By default, sharing is set to manual mode where you need to explicitly share con --- +### Commands + +You can configure custom commands for repetitive tasks through the `command` option. + +```jsonc title="opencode.jsonc" +{ + "$schema": "https://opencode.ai/config.json", + "command": { + "test": { + "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.", + "description": "Run tests with coverage", + "agent": "build", + "model": "anthropic/claude-3-5-sonnet-20241022" + }, + "component": { + "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.", + "description": "Create a new component" + } + } +} +``` + +You can also define commands using markdown files in `~/.config/opencode/command/` or `.opencode/command/`. [Learn more here](/docs/commands). + +--- + ### Keybinds You can customize your keybinds through the `keybinds` option. @@ -220,6 +246,11 @@ You can configure permissions to control what AI agents can do in your codebase } ``` +This allows you to configure explicit approval requirements for sensitive operations: + +- `edit` - Controls whether file editing operations require user approval (`"ask"` or `"allow"`) +- `bash` - Controls whether bash commands require user approval (can be `"ask"`/`"allow"` or a pattern map) + [Learn more about permissions here](/docs/permissions). --- @@ -259,13 +290,6 @@ about rules here](/docs/rules). You can disable providers that are loaded automatically through the `disabled_providers` option. This is useful when you want to prevent certain providers from being loaded even if their credentials are available. -The `disabled_providers` option accepts an array of provider IDs. When a provider is disabled: - -- It won't be loaded even if environment variables are set -- It won't be loaded even if API keys are configured through `opencode auth login` -- The provider's models won't appear in the model selection list - - ```json title="opencode.json" { "$schema": "https://opencode.ai/config.json", @@ -273,12 +297,11 @@ The `disabled_providers` option accepts an array of provider IDs. When a provide } ``` -The permissions system allows you to configure explicit approval requirements for sensitive operations: +The `disabled_providers` option accepts an array of provider IDs. When a provider is disabled: -- `edit` - Controls whether file editing operations require user approval (`"ask"` or `"allow"`) -- `bash` - Controls whether bash commands require user approval (can be `"ask"`/`"allow"` or a pattern map) - -[Learn more about permissions here](/docs/permissions). +- It won't be loaded even if environment variables are set. +- It won't be loaded even if API keys are configured through `opencode auth login`. +- The provider's models won't appear in the model selection list. --- diff --git a/packages/web/src/content/docs/docs/tui.mdx b/packages/web/src/content/docs/docs/tui.mdx index a886cd31..113bad69 100644 --- a/packages/web/src/content/docs/docs/tui.mdx +++ b/packages/web/src/content/docs/docs/tui.mdx @@ -25,6 +25,12 @@ Once you're in the TUI, you can prompt it with a message. Give me a quick summary of the codebase. ``` +--- + +## File references + +You can reference files in your messages using `@`. This does a fuzzy file search in the current working directory. + :::tip You can also use `@` to reference files in your messages. ::: @@ -33,6 +39,20 @@ You can also use `@` to reference files in your messages. How is auth handled in @packages/functions/src/api/index.ts? ``` +The content of the file is added to the conversation automatically. + +--- + +## Bash commands + +Start a message with `!` to run a shell command. + +```bash frame="none" +!ls -la +``` + +The output of the command is added to the conversation as a tool result. + --- ## Commands @@ -235,18 +255,6 @@ Unshare current session. [Learn more](/docs/share#un-sharing). --- -## Bash commands - -Start a message with `!` to run a shell command. - -```bash frame="none" -!ls -la -``` - -The output of the command is added to the conversation as a tool result. - ---- - ## Editor setup Both the `/editor` and `/export` commands use the editor specified in your `EDITOR` environment variable. @@ -300,6 +308,8 @@ Popular editor options include: - `notepad` - Windows Notepad - `subl` - Sublime Text -:::tip -Some editors need command-line arguments to run in blocking mode. The --wait flag makes the editor process block until closed, which is necessary for opencode to function correctly. +:::note +Some editors like VS Code need to be started with the `--wait` flag. ::: + +Some editors need command-line arguments to run in blocking mode. The `--wait` flag makes the editor process block until closed.