> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firebender.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Commands

> Complete reference for custom command configuration

Commands are custom prompts you can trigger with a slash in chat. Define commands using `.mdc` files in the `.firebender/commands/` directory.

<Info>
  Type `/help` in the chat to get help creating commands
</Info>

## Configuration Locations

Firebender supports two command scopes:

* **Project Commands**: `.firebender/commands/*.mdc` in your project root
* **Personal Commands**: `~/.firebender/commands/*.mdc` for commands that apply across all projects

**Precedence**: Project commands take precedence over personal commands with the same name.

## File Format

Command files use the `.mdc` extension with optional YAML frontmatter:

```markdown .firebender/commands/create-pr.mdc theme={null}
---
name: create pr
description: Create a GitHub PR from current changes
model: default
mode: write
---

Create a PR using `gh` and `git` commands. Determine the best PR title and body based on other merged commits.

Make sure non default branch is used (ie. do not push to main).

If changes are uncommitted, then commit them and push.

Use `--no-pager` with git commands because you won't have access to STDIN while the command is still running.
```

### Frontmatter Fields

All frontmatter fields are optional:

| Field         | Type     | Description                                                      |
| ------------- | -------- | ---------------------------------------------------------------- |
| `name`        | `string` | Command name shown in UI. Defaults to filename without extension |
| `description` | `string` | Brief description shown in command picker                        |
| `model`       | `string` | Model to use. See [available models](/get-started/models)        |
| `mode`        | `string` | Execution mode: `auto`, `read`, `write`, or `composer`           |

### No Frontmatter

If you omit the frontmatter, the filename becomes the command name and the entire file content is the prompt:

```markdown .firebender/commands/quick-review.mdc theme={null}
Review the current file for potential bugs, performance issues, and code style problems.

Focus on:
- Null safety
- Resource leaks
- Threading issues
```

This command will appear as "quick-review" in the command picker.

## Frontmatter Reference

### name

The display name for the command. If omitted, uses the filename without the `.mdc` extension.

```yaml theme={null}
name: create pr
```

### description

A brief description shown in the command picker to help identify the command.

```yaml theme={null}
description: Create a GitHub PR with AI-generated title and body
```

### model

The AI model to use for this command. Options:

* `"default"`: Uses the system's default model
* `"quick"`: Uses the fastest available model
* Any specific model ID (e.g., `"claude-sonnet-4-20250514"`, `"gpt-4o"`)

If omitted, uses the model currently selected in chat.

```yaml theme={null}
model: quick
```

See [available models](/get-started/models) for valid model IDs.

### mode

How Firebender should execute the command:

* `"auto"`: Let Firebender determine the best mode (default)
* `"read"`: Read-only mode for analysis and explanations
* `"write"`: Agent mode for code changes and terminal commands
* `"composer"`: UI composition mode

If omitted, uses the mode currently selected in chat.

```yaml theme={null}
mode: write
```

## Examples

### Code Review Command

```markdown .firebender/commands/review-diff.mdc theme={null}
---
name: review diff
description: Review staged changes before commit
mode: read
---

Review the current git diff for:

1. **Bugs**: Logic errors, null pointer issues, race conditions
2. **Security**: Input validation, SQL injection, XSS vulnerabilities
3. **Performance**: N+1 queries, unnecessary allocations, blocking calls
4. **Style**: Naming conventions, code organization, documentation

Provide actionable feedback with specific line references.
```

### Changelog Generator

```markdown .firebender/commands/write-changelog.mdc theme={null}
---
name: write changelog
description: Generate changelog entry from recent commits
model: default
mode: write
---

Analyze recent commits and generate a changelog entry.

1. Run `git log --oneline -20` to see recent commits
2. Group changes by type (features, fixes, improvements)
3. Write user-friendly descriptions
4. Update CHANGELOG.md with the new entry
```

### Quick Question (Read-only)

```markdown ~/.firebender/commands/explain.mdc theme={null}
---
name: explain
description: Quick explanation of selected code
model: quick
mode: read
---

Explain the selected code concisely:
- What it does
- Why it's implemented this way
- Any potential issues or improvements
```

## Symbolic Links

Commands support symbolic links. You can symlink command files from a shared location:

```bash theme={null}
ln -s ~/shared-commands/team-pr.mdc .firebender/commands/team-pr.mdc
```

## Migration from firebender.json

If you have commands defined in `firebender.json`, migrate them to `.mdc` files:

**Before** (deprecated):

```json theme={null}
{
  "commands": [
    {
      "name": "create pr",
      "path": "commands/pr.md",
      "mode": "write"
    }
  ]
}
```

**After**:

```markdown .firebender/commands/create-pr.mdc theme={null}
---
name: create pr
mode: write
---

(contents of commands/pr.md)
```

<Warning>
  The `commands` field in `firebender.json` is deprecated. Use `.firebender/commands/*.mdc` files instead.
</Warning>

For user-facing overview and examples, see [Commands](/input/commands).

## Cookbooks

Ready-to-use command examples:

* [Quick Question](https://github.com/firebenders/cookbooks/tree/main/quick-question)
* [Review Pull Request](https://github.com/firebenders/cookbooks/tree/main/review-pr)
* [Update Changelog](https://github.com/firebenders/cookbooks/tree/main/update-changelog)
* [Create Design Document](https://github.com/firebenders/cookbooks/tree/main/create-design-doc)