feat: custom commands (#133)

* Implement custom commands

* Add User: prefix

* Reuse var

* Check if the agent is busy and if so report a warning

* Update README

* fix typo

* Implement user and project scoped custom commands

* Allow for $ARGUMENTS

* UI tweaks

* Update internal/tui/components/dialog/arguments.go

Co-authored-by: Kujtim Hoxha <[email protected]>

* Also search in $HOME/.opencode/commands

---------

Co-authored-by: Kujtim Hoxha <[email protected]>

1 files changed, 64 insertions, 0 deletions

diff --git a/README.md b/README.md
index 407e913e2..b3eb37777 100644
--- a/README.md
+++ b/README.md
@@ -387,6 +387,70 @@ OpenCode is built with a modular architecture:
 - **internal/session**: Session management
 - **internal/lsp**: Language Server Protocol integration
 
+## Custom Commands
+
+OpenCode supports custom commands that can be created by users to quickly send predefined prompts to the AI assistant.
+
+### Creating Custom Commands
+
+Custom commands are predefined prompts stored as Markdown files in one of three locations:
+
+1. **User Commands** (prefixed with `user:`):
+   ```
+   $XDG_CONFIG_HOME/opencode/commands/
+   ```
+   (typically `~/.config/opencode/commands/` on Linux/macOS)
+
+   or
+
+   ```
+   $HOME/.opencode/commands/
+   ```
+
+2. **Project Commands** (prefixed with `project:`):
+   ```
+   <PROJECT DIR>/.opencode/commands/
+   ```
+
+Each `.md` file in these directories becomes a custom command. The file name (without extension) becomes the command ID.
+
+For example, creating a file at `~/.config/opencode/commands/prime-context.md` with content:
+
+```markdown
+RUN git ls-files
+READ README.md
+```
+
+This creates a command called `user:prime-context`.
+
+### Command Arguments
+
+You can create commands that accept arguments by including the `$ARGUMENTS` placeholder in your command file:
+
+```markdown
+RUN git show $ARGUMENTS
+```
+
+When you run this command, OpenCode will prompt you to enter the text that should replace `$ARGUMENTS`.
+
+### Organizing Commands
+
+You can organize commands in subdirectories:
+
+```
+~/.config/opencode/commands/git/commit.md
+```
+
+This creates a command with ID `user:git:commit`.
+
+### Using Custom Commands
+
+1. Press `Ctrl+K` to open the command dialog
+2. Select your custom command (prefixed with either `user:` or `project:`)
+3. Press Enter to execute the command
+
+The content of the command file will be sent as a message to the AI assistant.
+
 ## MCP (Model Context Protocol)
 
 OpenCode implements the Model Context Protocol (MCP) to extend its capabilities through external tools. MCP provides a standardized way for the AI assistant to interact with external services and tools.