How to Configure Custom Slash Commands in Reasonix: A Complete Guide

Custom slash commands in Reasonix are Markdown-based prompt templates that live in specific directories, where the relative file path determines the command name and frontmatter variables drive dynamic argument substitution.

When working with the esengine/DeepSeek-Reasonix codebase, you can configure custom slash commands to create reusable prompt shortcuts without modifying any Go source code. These commands are simple Markdown files that Reasonix discovers, loads, and renders at runtime, transforming your chat interface into a specialized workflow tool.

How Custom Slash Commands Work in Reasonix

Reasonix treats custom slash commands as prompt templates written in Markdown. The system follows a five-stage lifecycle implemented across internal/command/command.go and internal/config/paths.go:

1. Discovery – CommandDirs() in internal/config/paths.go builds an ordered list of directories to scan, including user configuration, project-specific folders, and plugin directories.
2. Loading – command.Load() (or LoadRoots) walks every *.md file, parses optional YAML frontmatter, and instantiates a Command struct.
3. Naming – The relative path of the file becomes the slash command name by replacing path separators with colons (e.g., git/commit.md becomes /git:commit).
4. Rendering – Command.Render performs variable substitution on $ARGUMENTS, positional placeholders $1..$N, and the literal $$ escape sequence.
5. Invocation – The UI layer in internal/control/input.go resolves the entered slash via CustomCommand and injects the rendered prompt into the chat turn.

Because the loader only reads UTF-8 files and parses lightweight frontmatter, you can add commands without compiling or restarting the underlying Go binary—only the session needs reloading.

Creating Your First Custom Slash Command

Step 1: Create the Markdown File

Create a file ending in .md within your project's .reasonix/commands folder. The file supports optional YAML frontmatter for metadata and a body containing your prompt template.

---
description: "Generate a brief summary of a web page"
argument-hint: "<url>"
---
Summarize the content at $ARGUMENTS in two sentences.

• description populates the help text in the slash-menu UI.
• argument-hint shows users the expected input format.
• $ARGUMENTS substitutes the entire text following the command invocation.

Save this as .reasonix/commands/summary.md. After reloading Reasonix, you can invoke it by typing /summary https://github.com/esengine/DeepSeek-Reasonix.

Step 2: Configure Command Directories

By default, Reasonix scans three locations via the CommandDirs() helper:

• <reasonix-home>/commands (user-global configuration)
• <workspace-root>/.reasonix/commands (project-specific)
• Plugin command folders (prefixed with the plugin name)

To add custom locations outside these defaults, edit your reasonix.toml configuration file:

command_dirs = ["my/extra/commands", "shared/team-prompts"]

As noted in reasonix.example.toml, entries in command_dirs are resolved relative to the workspace root and appended to the default scan list.

Step 3: Reload and Invoke

The command.Load function picks up new files automatically when Reasonix initializes a new session. Once loaded:

1. Type / to open the slash-menu and see your command listed with its description.
2. Enter arguments after the command name (e.g., /summary https://example.com).
3. Reasonix sends the rendered text—"Summarize the content at https://example.com in two sentences."—to the model as a normal chat turn.

Understanding the Command Lifecycle

Discovery Phase

The CommandDirs() function in internal/config/paths.go (lines 12–18) constructs the prioritized list of directories. Reasonix checks these in order, allowing project commands to override user commands with identical names.

Loading and Naming Conventions

LoadRoots in internal/command/command.go (lines 71–84) handles the filesystem walk. File paths determine command names through a specific transformation:

• User/Project commands: category/action.md becomes /category:action
• Plugin commands: Prefixed with the plugin identifier (e.g., myplugin:category:action)

This namespacing prevents collisions between plugins and local overrides.

Rendering and Variable Substitution

The Render method (lines 45–61 in internal/command/command.go) processes three substitution patterns:

• $ARGUMENTS – Inserts the entire argument string provided after the command.
• $1, $2, ... $N – Inserts positional arguments (space-delimited).
• $$ – Renders a literal dollar sign (escape sequence).

This logic executes at invocation time, ensuring dynamic content injection without static templating limitations.

Advanced Configuration Options

Hidden Commands: Add hidden = true to the frontmatter to exclude a command from the slash-menu autocomplete while keeping it functional for direct invocation. This is useful for internal debugging scripts or deprecated commands you still support.

Plugin-Scoped Commands: When developing plugins, place Markdown files in your plugin's commands/ directory. Reasonix automatically qualifies these names with the plugin prefix, as documented in docs/PLUGIN_PACKAGES.md (lines 93–99), ensuring clean separation between plugin functionality and user customizations.

Summary

• Custom slash commands in Reasonix are Markdown files stored in .reasonix/commands/ or paths listed in command_dirs.
• The relative file path determines the command name (e.g., docs/explain.md becomes /docs:explain).
• Use frontmatter keys description and argument-hint to populate the UI help text.
• Variable substitution supports $ARGUMENTS for full input and $1..$N for positional parameters via Command.Render.
• The discovery logic in internal/config/paths.go and loading logic in internal/command/command.go require no Go code changes to extend functionality.

Frequently Asked Questions

Where should I store my custom slash command files?

Place them in your project's .reasonix/commands/ directory for project-specific commands, or in <reasonix-home>/commands for global availability across all sessions. You can also define additional paths in the command_dirs array within reasonix.toml. According to the source in internal/config/paths.go, these directories are scanned in a specific priority order, with project-level commands taking precedence over user-global ones.

What template variables are available in command files?

Reasonix supports three substitution patterns processed by Command.Render in internal/command/command.go. Use $ARGUMENTS to capture everything typed after the command name, or $1, $2, etc., to capture specific positional arguments. To include a literal dollar sign in your template, escape it with $$.

How does Reasonix convert file paths to command names?

The LoadRoots function in internal/command/command.go derives command names by taking the file's path relative to its command root and replacing path separators with colons. For example, a file at git/commit.md becomes the /git:commit command. Plugin commands are automatically prefixed with the plugin name using the format <plugin>:<name> to prevent naming collisions.

Can I hide a custom command from the autocomplete menu?

Yes. Add hidden = true to the YAML frontmatter of your Markdown command file. The command remains fully functional when typed manually, but it will not appear in the slash-menu UI suggestions. This is useful for creating internal utilities or beta commands that you don't want to surface to all users.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}