Custom Commands

Custom commands are reusable prompt templates that you invoke as slash commands. They let you standardize common workflows — code reviews, commit messages, documentation generation, or anything you do repeatedly.

Edge Cases

This section covers important edge cases and considerations when working with custom commands:

• Command Name Conflicts: If two commands have the same name, the last loaded command takes precedence
• Invalid File Format: Commands with malformed markdown or missing headings are skipped during loading
• Permission Issues: Commands are not loaded if the system cannot read their files due to permission restrictions
• Directory Changes: Changes to the commands directory (adding/removing files) require a CLI restart to take effect
• Large Commands: Very large command files may impact performance during loading and execution

These edge cases are handled gracefully by the system to prevent disruptions to normal operation.

Creating a Command

Create a markdown file in ~/.coalcode/commands/. The filename (without .md) becomes the command name.

Example: /review

Create ~/.coalcode/commands/review.md:

# Code Review

Review the code I provide. Focus on:
- Correctness and edge cases
- Security vulnerabilities
- Performance issues
- Code clarity and naming

Be specific. Reference file names and line numbers.

Now you can use it:

/review src/auth/oauth.ts

How Commands Work

When you invoke a custom command:

1. The markdown content is sent to the AI as context
2. Any text you type after the command name is passed as the user message
3. The AI has full access to all tools (read files, search, bash, etc.)

The first # Heading in the file is used as the command's description in the autocomplete menu and in /commands output.

Command Execution Flow

The custom command execution follows this sequence:

1. Command Recognition: The CLI identifies the command based on the first word after /
2. Template Retrieval: The markdown file corresponding to the command name is located in ~/.coalcode/commands/
3. Content Preparation: The markdown content (excluding the first heading) is prepared as context for the AI
4. User Input Processing: Any arguments or text following the command name are formatted as the user's input message
5. AI Processing: The AI receives both the command context and user input, then executes the requested task
6. Output Generation: The AI responds with its processing result
7. Result Display: The response is displayed in the terminal or chat interface

This execution flow ensures that commands are consistently processed while maintaining flexibility for complex operations.

Listing Commands

/commands

This shows all custom commands from ~/.coalcode/commands/ with their descriptions.

Example Command

On first launch, LogiCoal creates an example command at ~/.coalcode/commands/example.md that explains the format. You can delete it or use it as a template.

Tips

• Keep prompts focused on a single task for best results
• Include specific instructions about output format if you want structured responses
• Commands can reference any tools — tell the AI to "search the codebase first" or "run the tests after making changes"
• Arguments are flexible — pass file paths, descriptions, or any context after the command name
• Commands are loaded on startup. Create or edit them between sessions, or restart to pick up changes.

Managing Commands

/command create

Launches an interactive wizard that walks you through building a command step by step:

1. Name — The slash command name (e.g., review becomes /review)
2. Description — A short summary shown in autocomplete and /commands output
3. Purpose — What the command should accomplish (used as the core system prompt)
4. Steps — Ordered instructions the AI should follow. Uses an interactive step editor (↑↓: navigate, w/s: reorder, a: add, e: edit, d: delete)
5. Tools — Which tools the command should use (read files, write files, bash, web search, etc.)
6. Auto-approve — Whether write operations should run without confirmation
7. Output format — Expected output style (markdown, code, summary, etc.)
8. Confirm — Review the generated markdown before saving

The wizard saves the result to ~/.coalcode/commands/<name>.md.

/command edit <name>

Opens an existing command in the creation wizard with all fields pre-populated. Make changes through the same step-by-step flow, then save.

/command edit review

/command delete <name>

Deletes a custom command file immediately.

/command delete review

/command list

Lists all custom commands with their descriptions. Same as /commands.

/command list

/command

With no arguments, shows a help summary of all subcommands.

More Examples

/explain

# Explain Code

Explain the provided code in plain language. Cover:
- What it does at a high level
- Key data flow and control flow
- Any notable patterns or design decisions
- Potential gotchas or edge cases

/test

# Write Tests

Write comprehensive tests for the provided code. Use the existing test framework in the project. Cover:
- Happy path
- Edge cases
- Error handling
- Run the tests after writing them and fix any failures

/commit

# Commit Message

Look at the current git diff (staged and unstaged changes). Write a clear, concise commit message that:
- Summarizes what changed and why
- Uses imperative mood ("Add feature" not "Added feature")
- Keeps the subject line under 72 characters