# How Custom Slash Commands Work in Reasonix Sessions: A Complete Technical Guide

> Learn how custom slash commands work in Reasonix sessions. Discover how Markdown-defined instructions are parsed, registered, and executed by the model via UI autocomplete. Explore the DeepSeek-Reasonix repository for details.

- Repository: [YHH/DeepSeek-Reasonix](https://github.com/esengine/DeepSeek-Reasonix)
- Tags: technical-guide
- Published: 2026-08-08

---

**Custom slash commands in Reasonix are Markdown-defined instructions stored in `.reasonix/commands/` that get parsed at startup, registered in a local registry, and executed by the model when triggered via the UI autocomplete menu.**

The **DeepSeek-Reasonix** repository implements a sophisticated local command system that allows users to define reusable prompt templates using simple Markdown files. Understanding how these **custom slash commands** operate requires examining the discovery mechanisms in [`internal/config/paths.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/paths.go), the parsing logic in [`internal/command/command.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/command/command.go), and the execution flow through [`internal/control/input.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/control/input.go).

## Command Discovery and Loading

Reasonix initializes its command ecosystem by scanning specific filesystem locations for Markdown definitions.

### Directory Structure and Scanning

At startup, the engine queries [`internal/config/paths.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/paths.go) (line 550) to determine the command directories. The system primarily searches the **`.reasonix/commands/`** folder within the project root, while maintaining backward compatibility with the legacy **`.claude/commands/`** location.

The discovery process recursively identifies all `*.md` files in these directories. Each file represents an isolated command definition that the system will parse into a structured format.

### The Command Parser Implementation

The loading logic resides in [`internal/command/command.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/command/command.go). The `LoadCommand` function reads each Markdown file and splits it into two components: an optional YAML front-matter block and the body text.

```go
// From internal/command/command.go
func LoadCommand(path string) (Command, error) {
    data, err := os.ReadFile(path)
    if err != nil { return Command{}, err }
    // Split front‑matter (YAML) from body, parse into struct
    // → Command{Name: "greet", Title: "Greet a teammate", …, Body: "Hi @{{.arg}}! 🎉"}
}

```

The front-matter supports four key fields:
- **`title`** — Human-readable name displayed in the slash menu
- **`desc`** — Short description for the autocomplete dropdown
- **`danger`** — Boolean flag that renders a warning pill in the UI
- **`args`** — Schema defining expected arguments for validation

## Command Registration and Namespacing

Once parsed, commands enter a runtime registry that manages availability and prevents conflicts.

### Built-in vs Custom Commands

All discovered commands populate the **`SLASH_CMDS`** registry, which serves as the single source of truth for both the TUI/desktop interface and the AI model. The registry is exposed to the model via the `slash_command` tool, as implemented in [`internal/serve/serve.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/serve/serve.go) (line 697).

Built-in commands like `/help` and `/quit` occupy reserved namespaces that take precedence over custom definitions.

### Collision Handling and Qualified Names

When plugins or custom definitions risk name collisions, Reasonix applies automatic qualification logic. According to [`internal/pluginpkg/pluginpkg.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/pluginpkg/pluginpkg.go) (line 86), plugin-contributed commands receive a prefixed identifier in the format **`plugin:command`**.

If a custom command conflicts with a built-in name, the system automatically rewrites it to a qualified form (`/reasonix:<name>`) and displays this variant in the menu, as documented in `site/src/pages/docs.astro` (lines 280-313).

## User Interface Integration

The frontend components bridge the registry with user interaction through autocomplete functionality.

### Autocomplete and Menu Rendering

When a user types `/` in the composer, the UI filters `SLASH_CMDS` against the current input. The rendering logic in [`desktop/frontend/src/components/Composer.tsx`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/frontend/src/components/Composer.tsx) (line 1231) displays a dropdown containing:
- Command name and description
- Danger indicators (when the `danger` flag is set)
- Argument hints based on the `args` schema

Navigation handling occurs in [`desktop/frontend/src/App.tsx`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/frontend/src/App.tsx) (line 2305), managing keyboard selection and insertion.

### Input Handling and Execution Flow

Command execution follows a strict resolution path in [`internal/control/input.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/control/input.go) (line 579). The `CustomCommand` function normalizes input (case-insensitive, slash-normalized) and matches it against the registry:

```go
// From internal/control/input.go
func CustomCommand(input string) (Command, bool) {
    name, args := splitSlash(input) // “greet”, “alice”
    cmd, ok := commandRegistry.Lookup(name) // case‑insensitive, slash‑normalized
    if ok { cmd.Body = applyArgs(cmd.Body, args) }
    return cmd, ok
}

```

When matched, the command body (with interpolated arguments) inserts into the conversation as a standard user turn. The model processes this locally without external service calls, ensuring zero-latency execution.

## Creating Custom Slash Commands

Developers define commands using Markdown with YAML front-matter. Store files in `.reasonix/commands/<name>.md`:

```markdown
---
title: Greet a teammate
desc: Sends a friendly greeting to @username
danger: false
---
Hi @{{.arg}}! 🎉

```

**Invocation in a Reasonix session:**

```text
/greet alice

```

The UI surfaces this in the autocomplete menu with the description "Sends a friendly greeting to @username". Upon execution, Reasonix injects the resolved body:

```text
Hi @alice! 🎉

```

The model then processes this content as a standard conversation turn.

## Summary

- **Discovery**: Reasonix scans `.reasonix/commands/` and `.claude/commands/` at startup via [`internal/config/paths.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/paths.go) (line 550)
- **Parsing**: [`internal/command/command.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/command/command.go) extracts YAML front-matter (title, desc, danger, args) and body content into structured `Command` structs
- **Registration**: Commands populate the `SLASH_CMDS` registry, exposed to the model through the `slash_command` tool in [`internal/serve/serve.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/serve/serve.go)
- **Collision Handling**: Plugin commands use `plugin:command` format; conflicts with built-ins auto-qualify as `/reasonix:<name>` per [`internal/pluginpkg/pluginpkg.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/pluginpkg/pluginpkg.go) (line 86)
- **Execution**: [`internal/control/input.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/control/input.go) (line 579) resolves slash input, interpolates arguments, and inserts the body as a local model turn
- **UI Integration**: [`desktop/frontend/src/components/Composer.tsx`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/frontend/src/components/Composer.tsx) (line 1231) renders autocomplete menus with metadata from the registry

## Frequently Asked Questions

### Where should I place custom slash command files?

Place Markdown files defining your commands in the `.reasonix/commands/` directory at your project root. Reasonix also maintains backward compatibility with the legacy `.claude/commands/` location. The system discovers these automatically at session startup by querying the path resolution logic in [`internal/config/paths.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/paths.go).

### Can custom commands override built-in commands like /help?

No. Built-in commands occupy reserved namespaces and take precedence over custom definitions. If you create a custom command with a conflicting name, Reasonix automatically rewrites it to a qualified form (such as `/reasonix:<name>`) to prevent collisions, as implemented in the namespacing logic of [`internal/pluginpkg/pluginpkg.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/pluginpkg/pluginpkg.go).

### How are arguments passed to custom slash commands?

Arguments pass through the `splitSlash` function in [`internal/control/input.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/control/input.go), which separates the command name from trailing text. The system applies these arguments to the command body template using `applyArgs` before insertion. You can define expected arguments in the front-matter `args` field to enable autocomplete hints in the UI.

### Do slash commands execute code locally or remotely?

Custom slash commands execute entirely locally. When triggered, Reasonix inserts the command body (with interpolated arguments) directly into the conversation as a user turn. The local model processes this content immediately without external API calls, providing zero-latency execution as noted in the [`internal/control/input.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/control/input.go) implementation.