# CodeBuddy Code Slash Commands

CodeBuddy Code supports slash commands, allowing you to perform special operations, manage sessions, and customize common workflows within your chat.

## Built-in Slash Commands

These commands are used to manage your CodeBuddy Code sessions. Here is the current support status:

| Command | Parameters | CodeBuddy Support | Description |
| --- | --- |:---:| --- |
| `/help` | | ✅ Supported | Display help information and provide guidance on feedback channels. |
| `/clear` | | ✅ Supported | Start a new conversation (old conversations can be restored via `/resume`). |
| `/login` | | ✅ Supported | Log in to your account. |
| `/logout` | | ✅ Supported | Log out of your current account. |
| `/doctor` | | ✅ Supported | Check the status and environment of CodeBuddy Code. |
| `/status` | | ✅ Supported | Display the status of the current repository and session. |
| `/add-dir` | `<path>` | ✅ Supported | Add a working directory. Specify the path of the directory to add. |
| `/agents` | | ✅ Supported | Manage experimental AI agents |
| `/branch` | `[name]` | ✅ Supported | Create a branch at the current conversation point, copying active conversation history to a new session and automatically switching to it. Optionally specify a branch name. |
| `/btw` | `<question>` | ✅ Supported | Quick side question without interrupting the current Agent workflow. Useful for asking brief questions while the Agent is executing a task. Answers are generated based on existing context. |
| `/compact`| | ✅ Supported | Compress context. |
| `/config`| `[list \| get \| set]` | ✅ Supported | View or modify local configuration. Opens an interactive panel when used without parameters, `list` lists current settings, `get <key>` reads a setting, `set <key> <value>` modifies a setting. |
| `/context` | | ✅ Supported | Calculate the context token distribution for the current session. |
| `/cost` | | ✅ Supported | Display session cost and token usage. |
| `/init` | | ✅ Supported | Initialize a new CodeBuddy repository. |
| `/mcp` | | ✅ Supported | Manage MCP connections. |
| `/memory`| | ✅ Supported | Manage long-term memory |
| `/model` | `[list \| model-name]` | ✅ Supported | Switch or view the currently used AI model. Opens an interactive selection interface when used without parameters, `list` lists available models, or directly switches to the specified model when provided with a model name (e.g., `/model gpt-4o`). |
| `/model:text-to-image` | `[list \| model-id]` | ✅ Supported | Switch or view the currently used text-to-image model. Opens an interactive selection interface when used without parameters, `list` lists available models, or directly switches to the specified model when provided with a model ID. |
| `/model:image-to-image` | `[list \| model-id]` | ✅ Supported | Switch or view the currently used image-to-image model. Opens an interactive selection interface when used without parameters, `list` lists available models, or directly switches to the specified model when provided with a model ID. |
| `/permissions` | | ✅ Supported | Manage tool permissions and workspace directory access permissions. |
| `/plan` | | ✅ Supported | Preview the plan file content in the current plan mode. |
| `/goal` | `<condition> \| clear` | ✅ Supported | Keep working until a condition is met. `/goal <condition>` sets a goal condition (e.g., `/goal all tests pass`), registering a session-level prompt-based Stop hook. Each time the model wants to stop, a small-model evaluator checks whether the condition is satisfied; if not, it injects the reason into history so the model continues working. `/goal` without arguments opens the recap panel. `/goal clear` (aliases: `stop` / `off` / `reset` / `none` / `cancel`) ends the goal early. See [Goal Documentation](./goal.md). |
| `/upgrade` | | ✅ Supported | Open the upgrade page in your browser to view premium features and subscription options. |
| `/bashes` | | ✅ Supported | List and manage background tasks. |
| `/terminal-setup` | | ✅ Supported | Configure Shift+Enter keyboard shortcut binding for inserting line breaks in the input box. |
| `/todos` | | ✅ Supported | Display the to-do list in the current session. |
| `/statusline` | | ✅ Supported | Configure terminal status line display, which can show session information, model status, etc. |
| `/security-review` | | ✅ Supported | Perform a security review of code in the current branch by a senior security engineer for focused security auditing to identify high-confidence security vulnerabilities. |
| `/theme` | | ✅ Supported | Open the theme selection panel, where you can select and preview different terminal themes (dark, light, colorblind-friendly, ANSI, etc.). |
| `/export` | | ✅ Supported | Export the current conversation to a file or clipboard. |
| `/feedback` | | ✅ Supported | Open the feedback page to submit bug reports or feature suggestions. |
| `/fork` | `[name]` | ✅ Supported | Create a branch at the current conversation point (alias for `/branch`). Copies active conversation history to a new session and automatically switches to it. Use `/resume` to return to the original conversation. |
| `/resume` | `[list \| session-id]` | ✅ Supported | Resume a previous session. Opens an interactive panel when used without parameters, `list` lists all sessions, or directly switches to the specified session when provided with a session-id. |
| `/rewind` | | ✅ Supported | Rewind conversation to a previous message point. You can choose to rewind conversation only, code only, or both. See [Checkpointing](checkpointing.md) for details. |
| `/sandbox` | | ✅ Supported | Manage Bash command sandbox mode and control security policies for command execution. See [Sandbox Documentation](bash-sandboxing.md) for details. |
| `/stats` | | ✅ Supported | Display usage statistics, including token usage, model invocation counts, session duration, and other detailed data. Supports both overview and per-model classification views. |
| `/ide` | | ✅ Supported | Manage IDE integration status. View currently connected IDE, switch IDE connections, or disconnect. See [IDE Integration Documentation](ide-integrations.md) for details. |
| `/plugin` | `[action] [args...]` | ✅ Supported | Manage plugins and the plugin marketplace. Opens an interactive interface when used without parameters, supporting operations like `marketplace add`, `install`, `enable`, `disable`, `uninstall`, etc. See [Plugin Documentation](plugins.md) for details. |
| `/plugin-validate` | `[path]` | ✅ Supported | Validate plugin directory structure and manifest. Validates the current directory when used without parameters. See [Plugin Reference](plugins-reference.md) for details. |
| `/reload-plugins` | | ✅ Supported | Reload all plugins (Skills, Agents, Hooks, MCP/LSP servers, etc.) without restarting. |
| `/skills` | | ✅ Supported | View all currently loaded Skills, including user-level, project-level, and plugin-level Skills, and display estimated token count. See [Skills Documentation](skills.md) for details. |
| `/insights` | | ✅ Supported | Generate AI-driven usage insight reports, analyzing your CodeBuddy Code usage patterns, interaction style, project domains, friction points, and other dimensions, generating an HTML report viewable in the browser. |

description: "Run unit tests for my project and report results."
argument-hint: "[test-file]"
allowed-tools: Bash(npm run:*)
model: gemini-3.1-pro
---

Please run the `npm run test -- $1` command for me and summarize the test results. If no test file is provided, run all tests.
```

Supported metadata fields:

| Field | Description | Example |
|------|------|------|
| `description` | A brief description of the command, displayed in autocomplete hints. | `"Run unit tests"` |
| `argument-hint` | Describes the parameters required by the command, providing input hints to users. | `"[test-file]"` or `"[pr-number] [priority] [assignee]"` |
| `model` | Specifies the AI model to use when executing this command. | `gemini-3.1-pro` |
| `allowed-tools` | List of tools this command can use, supporting fine-grained tool permission control. | `Bash(git:*), Read` |
| `disable-model-invocation` | When set to `true`, the command won't appear in the Skill tool and can only be triggered manually via `/command-name`. | `true` |

> 💡 **Note**: If `allowed-tools` is specified, the command can only use the listed tools. Use `Bash(git:*)` to allow all git commands, `Bash(git add:*)` to allow only `git add` commands.

### Using Arguments

Your custom commands can accept arguments, just like shell scripts. There are two ways to handle arguments:

#### Method 1: Positional Parameters ($1, $2, $3, ...)

Access individual arguments by position. This approach is suitable when you need to use different arguments in different parts of the command.

**Example: `review-pr.md`**
```markdown
---
description: "Code review"
argument-hint: "[pr-number] [priority] [assignee]"
---

Please review PR #$1 with priority $2 and assign to $3 for final confirmation.

Focus on the following aspects:
- Code style and best practices
- Performance impact
- Security issues
- Test coverage
```

* When invoking `/review-pr 456 high alice`:
  - `$1` = `456`
  - `$2` = `high`
  - `$3` = `alice`

#### Method 2: Capture All Arguments ($ARGUMENTS)

Capture all arguments at once. This approach is suitable when the number of arguments is uncertain.

**Example: `fix-issue.md`**
```markdown
---
description: "Fix code issues"
argument-hint: "[issue-number] [details...]"
---

Please fix issue #$ARGUMENTS, following our coding standards.

Follow these steps:
1. Understand the problem
2. Locate the root cause
3. Implement the fix
4. Add tests
5. Verify the fix
```

* When invoking `/fix-issue 123 high-priority refactor-auth-module`:
  - `$ARGUMENTS` = `123 high-priority refactor-auth-module`

> 💡 **Argument Parsing Rules**: Arguments are separated by spaces. Use single or double quotes to handle arguments containing spaces. For example, `/greet "Hello World"` will pass `"Hello World"` as a single argument.

### Executing Shell Commands

Prefix any line in your command with `!` and wrap the command in backticks, and that line will be executed as a shell command. Its output (`stdout`) will be captured and injected into the context for subsequent AI analysis.

> ⚠️ **Important Note**: When using shell command execution, you must include the `Bash` tool in the `allowed-tools` frontmatter, otherwise the command cannot be executed.

**Example: `status.md`**
```markdown
---
description: "Display and analyze the current git repository status."
allowed-tools: Bash(git status:*), Bash(git diff:*)
---

Current git status:
!`git status`

Changes in the current branch:
!`git diff HEAD`

Based on the output above, please summarize the current branch status for me.
```

**More Examples: `commit.md`**
```markdown
---
description: "Create a git commit."
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git diff:*), Bash(git commit:*)
argument-hint: "[message]"
---

## Current Status

- Git status: !`git status`
- Staged changes: !`git diff --cached`
- Recent commits: !`git log --oneline -5`

## Task

Based on the information above, create a git commit using the provided commit message: $1

If no message is provided, use a default descriptive message.
```

### File References

Use the `@` prefix in your command to include file contents. The system will automatically read the file and inject its contents into the AI context.

**Example**
```markdown
---
description: "Code review"
---

Please review the following files:

@src/utils/helpers.js
@src/utils/validators.js

Find potential performance issues and code style problems.
```

---

## Best Practices

### 1. Clear and Explicit Descriptions

Write clear `description` and `argument-hint` to help users and AI understand the command's purpose:

```markdown
---
description: "Perform security audit, scan code for potential vulnerabilities and security issues"
argument-hint: "[files...] [--severity high|medium|low]"
---
```

### 2. Use Fine-grained Tool Permissions

Restrict the tools and operations a command can use through `allowed-tools`:

```markdown
---
allowed-tools: Bash(npm test:*), Bash(git diff:*), Read
description: "Run tests and compare with main branch"
---
```

This is safer and more efficient than allowing all tools.

### 3. Organize Commands into Subdirectories

Create logical groupings for large numbers of commands:

```
.codebuddy/commands/
├── frontend/
│   ├── build.md
│   ├── test.md
│   └── lint.md
├── backend/
│   ├── migrate.md
│   ├── deploy.md
│   └── logs.md
└── git/
    ├── commit.md
    ├── review.md
    └── release.md
```

Invocation methods:
- `/frontend:build`
- `/backend:deploy`
- `/git:commit "message"`

### 4. Provide Useful Context

Insert useful information before shell command execution:

```markdown
---
description: "Analyze code coverage"
allowed-tools: Bash(npm run:*)
---

## Current Status

Project root directory: !`pwd`
Current branch: !`git rev-parse --abbrev-ref HEAD`

## Task

Please run tests and generate coverage report:
!`npm run coverage`

Based on the results above, summarize the code coverage situation for me.
```

### 5. Handle Optional Parameters

Use conditional logic to handle optional parameters:

```markdown
---
description: "Run specific or all tests"
argument-hint: "[test-file]"
allowed-tools: Bash(npm run:*)
---

When $1 is empty, all tests will be run; otherwise, run the specified test file.

Command: !`npm run test -- $1`
```

### 6. Specify Specific Models

Specify models for commands that require specific capabilities:

```markdown
---
description: "Code complexity analysis"
model: gemini-3.1-pro
---

Analyze the complexity of this code...
```

---

## Common Usage Scenarios

### Scenario 1: Code Review Workflow

Create `.codebuddy/commands/code-review.md`:

```markdown
---
description: "Perform code review on specified files"
argument-hint: "[file-paths...]"
allowed-tools: Read
---

Please perform a code review on the following files, focusing on code quality, maintainability, and security:

@$ARGUMENTS

Review points:
1. Code style and naming conventions
2. Function complexity
3. Error handling
4. Performance considerations
5. Security vulnerabilities
```

### Scenario 2: Automated Deployment

Create `.codebuddy/commands/deploy.md`:

```markdown
---
description: "Deploy application to specified environment"
argument-hint: "[environment] [version]"
allowed-tools: Bash(npm run:*), Bash(git:*)
---

## Deployment Process

Current version: !`cat package.json | grep version`
Latest tag: !`git describe --tags --abbrev=0`

Target environment: $1
Target version: $2

Preparing to deploy $2 to $1 environment...
```

### Scenario 3: Project Diagnostics

Create `.codebuddy/commands/diagnose.md`:

```markdown
---
description: "Diagnose project status and environment"
allowed-tools: Bash(npm list:*), Bash(git:*), Bash(node --version:*)
---

## Project Diagnostic Report

Node version: !`node --version`
NPM version: !`npm --version`
Git status: !`git status --short`
Dependency information: !`npm list --depth=0`

Based on the information above, please summarize the project status and provide recommendations.
```

---

## Troubleshooting

### Command Not Executing

1. **Check command file location**
   - Project commands: `.codebuddy/commands/*.md`
   - Global commands: `~/.codebuddy/commands/*.md`

2. **Check frontmatter format**
   - Ensure YAML syntax is correct
   - If `allowed-tools` is specified, ensure tool format is correct

3. **Check shell command permissions**
   - If using `!` prefix to execute commands, must include `Bash` tool in `allowed-tools`

### Arguments Not Properly Substituted

Ensure you're using the correct argument format:
- `$1`, `$2`, `$3` for positional parameters
- `$ARGUMENTS` for all arguments
- Correctly specify `argument-hint` in frontmatter

### File References Not Working

1. Use absolute paths or paths relative to the project root directory
2. Ensure there are no spaces in the path, or use quotes around the complete path
3. Check that the file exists and is readable

---

## Tips and Tricks

- 📝 **Version Control**: Commit project commands to Git so team members can share them
- 🔒 **Permission Control**: Use `allowed-tools` to ensure commands only use necessary permissions
- ⚡ **Performance**: Avoid executing time-consuming operations in shell commands
- 🎯 **Clarity**: Use explicit naming and descriptions to help the team understand command purposes
