@neocode-ai/web 1.1.1

package/src/content/docs/commands.mdx

@@ -0,0 +1,323 @@
+---
+title: Commands
+description: Create custom commands for repetitive 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).
+
+---
+
+## Create command files
+
+Create markdown files in the `commands/` directory to define custom commands.
+
+Create `.neocode/commands/test.md`:
+
+```md title=".neocode/commands/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 frontmatter defines command properties. The content becomes the template.
+
+Use the command by typing `/` followed by the command name.
+
+```bash frame="none"
+"/test"
+```
+
+---
+
+## Configure
+
+You can add custom commands through the NeoCode config or by creating markdown files in the `commands/` directory.
+
+---
+
+### JSON
+
+Use the `command` option in your NeoCode [config](/docs/config):
+
+```json title="neocode.jsonc" {4-12}
+{
+  "$schema": "https://neo.khulnasoft.com/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 shown 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/neocode/commands/`
+- Per-project: `.neocode/commands/`
+
+```markdown title="~/.config/neocode/commands/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.
+
+```md title=".neocode/commands/component.md"
+---
+description: Create a new component
+---
+
+Create a new React component named $ARGUMENTS with TypeScript support.
+Include proper typing and basic structure.
+```
+
+Run the command with arguments:
+
+```bash frame="none"
+/component Button
+```
+
+And `$ARGUMENTS` will be replaced with `Button`.
+
+You can also access individual arguments using positional parameters:
+
+- `$1` - First argument
+- `$2` - Second argument
+- `$3` - Third argument
+- And so on...
+
+For example:
+
+```md title=".neocode/commands/create-file.md"
+---
+description: Create a new file with content
+---
+
+Create a file named $1 in the directory $2
+with the following content: $3
+```
+
+Run the command:
+
+```bash frame="none"
+/create-file config.json src "{ \"key\": \"value\" }"
+```
+
+This replaces:
+
+- `$1` with `config.json`
+- `$2` with `src`
+- `$3` with `{ "key": "value" }`
+
+---
+
+### Shell output
+
+Use _!`command`_ to inject [bash command](/docs/tui#bash-commands) output into your prompt.
+
+For example, to create a custom command that analyzes test coverage:
+
+```md title=".neocode/commands/analyze-coverage.md"
+---
+description: Analyze test coverage
+---
+
+Here are the current test results:
+!`npm test`
+
+Based on these results, suggest improvements to increase coverage.
+```
+
+Or to review recent changes:
+
+```md title=".neocode/commands/review-changes.md"
+---
+description: Review recent changes
+---
+
+Recent git commits:
+!`git log --oneline -10`
+
+Review these changes and suggest any improvements.
+```
+
+Commands run in your project's root directory and their output becomes part of the prompt.
+
+---
+
+### File references
+
+Include files in your command using `@` followed by the filename.
+
+```md title=".neocode/commands/review-component.md"
+---
+description: Review component
+---
+
+Review the component in @src/components/Button.tsx.
+Check for performance issues and suggest improvements.
+```
+
+The file content gets included in the prompt automatically.
+
+---
+
+## Options
+
+Let's look at the configuration options in detail.
+
+---
+
+### Template
+
+The `template` option defines the prompt that will be sent to the LLM when the command is executed.
+
+```json title="neocode.json"
+{
+  "command": {
+    "test": {
+      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes."
+    }
+  }
+}
+```
+
+This is a **required** config option.
+
+---
+
+### Description
+
+Use the `description` option to provide a brief description of what the command does.
+
+```json title="neocode.json"
+{
+  "command": {
+    "test": {
+      "description": "Run tests with coverage"
+    }
+  }
+}
+```
+
+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.
+If this is a [subagent](/docs/agents/#subagents) the command will trigger a subagent invocation by default.
+To disable this behavior, set `subtask` to `false`.
+
+```json title="neocode.json"
+{
+  "command": {
+    "review": {
+      "agent": "plan"
+    }
+  }
+}
+```
+
+This is an **optional** config option. If not specified, defaults to your current agent.
+
+---
+
+### Subtask
+
+Use the `subtask` boolean to force the command to trigger a [subagent](/docs/agents/#subagents) invocation.
+This is useful if you want the command to not pollute your primary context and will **force** the agent to act as a subagent,
+even if `mode` is set to `primary` on the [agent](/docs/agents) configuration.
+
+```json title="neocode.json"
+{
+  "command": {
+    "analyze": {
+      "subtask": true
+    }
+  }
+}
+```
+
+This is an **optional** config option.
+
+---
+
+### Model
+
+Use the `model` config to override the default model for this command.
+
+```json title="neocode.json"
+{
+  "command": {
+    "analyze": {
+      "model": "anthropic/claude-3-5-sonnet-20241022"
+    }
+  }
+}
+```
+
+This is an **optional** config option.
+
+---
+
+## Built-in
+
+neocode 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.