Custom Commands

Introduction

Tuanjie AI Custom Commands let you save your most frequently used or favorite prompts as shortcuts. By turning complex prompts into concise commands, you can significantly simplify your workflow, ensure your team follows consistent standards, and streamline your daily development.

What Are Custom Commands?

Custom Commands are reusable prompt templates defined in TOML format. They allow you to:

• Save frequently used complex prompts as short commands
• Support parameter injection so commands can dynamically respond to user input
• Execute shell commands and inject results into prompts
• Directly embed file content into prompts
• Create namespaced commands for easy organization

Core Value of Custom Commands

• Improve Efficiency: Replace lengthy prompts with short commands (such as /commit)
• Maintain Consistency: Ensure the team uses the same workflow and standards
• Reduce Input: Avoid re-entering the same prompt content
• Context Aware: Commands can accept parameters and dynamically generate prompts
• Maintainability: Manage common workflows in one place for easy updates and sharing

Scenarios Suitable for Custom Commands

• Complex prompts used repeatedly (such as code review, commit message generation, documentation writing)
• Tasks requiring specific output formats (such as Conventional Commits, API documentation, test reports)
• Team processes requiring consistent standards (such as code style checks, security audits)
• Tasks that need to combine shell commands or file content (such as Git operations, file analysis)

Scenarios NOT suitable for Custom Commands:

• Simple one-time tasks
• Tasks requiring complex logic and conditional statements (consider using Skills or Subagents)
• Tasks requiring persistent state (consider using Extensions)

Managing Commands via GUI

1. Type / in the dialog box and select "Manage commands" from the dropdown menu. Or directly type /commands.
2. In the opened dialog box, you can view all available commands and their descriptions.
3. After creating a new command, run /commands reload to load the changes.
4. Enter the command name directly in the conversation window (such as /commit) to execute.

Difference between Project and Global when creating commands:

• Project: The command is only available in the current project and can be shared with the team via the project repository
• Global: The command is available in all projects, ideal for your personal commonly used commands

Managing Commands via CLI

Command Discovery Paths and Priorities

Tuanjie AI automatically loads Commands from two locations, in priority order (highest to lowest):

Project Commands

• Path: .codely/commands/ or .agents/commands/
• Purpose: Team-shared, project-scoped, highest priority
• Can be committed to version control and shared with the team

User Commands

• Path: ~/.codely/commands/ or ~/.agents/commands/
• Purpose: Personal global use, effective for all projects

Priority Rules:

Project commands > User commands

Within the same level: .agents/commands/ takes precedence over .codely/commands/

How Commands Work

1. Discovery: When creating a new session or running /commands reload, Tuanjie AI scans all paths and loads command names and descriptions
2. Execution: When you enter a command (such as /commit), Tuanjie AI loads the corresponding TOML file
3. Processing: Parses special syntax ({{args}}, !{...}, @{...}) in the command
4. Injection: Injects parameters, shell command outputs, or file content into the prompt
5. Sending: Sends the generated prompt to the AI model

Command Naming and Namespacing

Command names are determined by their file path relative to the commands directory. Subdirectories are used to create namespaced commands, and path separators (/ or \) are converted to colons (:).

• ~/.codely/commands/test.toml → Command /test
• <project>/.codely/commands/git/commit.toml → Command /git:commit
• <project>/.codely/commands/review/security.toml → Command /review:security

Managing Within Interactive Sessions

Use /commands series commands in the Tuanjie AI conversation input box:

# List all available commands
/commands list

# Rescan and reload all commands
/commands reload

How to Trigger and Use Commands

1. Ensure the command has been discovered: Verify with /commands list
2. Enter the command name directly in the conversation, for example:

   /commit
   /git:fix Button is misaligned
   /review FileCommandLoader.ts --verbose

3. Tuanjie AI will load the corresponding TOML file, process the special syntax within it, and send the generated prompt to the AI

Creating Custom Commands

Creating Manually

Standard Directory Structure

~/.codely/commands/                    # User commands directory
├── git/
│   ├── commit.toml                   # Git commit command
│   ├── fix.toml                      # Git fix command
│   └── push.toml                     # Git push command
├── refactor/
│   ├── pure.toml                     # Pure function refactoring
│   └── clean.toml                    # Code cleanup
└── test/
    ├── unit.toml                     # Unit tests
    └── integration.toml              # Integration tests

TOML File Format

Command definition files must be written in TOML format and use the .toml file extension.

Basic Example:

# ~/.codely/commands/commit.toml
# Invoked by: /commit

description = "Generate Conventional Commit commit messages based on staged changes."
prompt = """
Generate a Conventional Commit message based on the following git diff:

!{git diff --staged}

Commit message format:
<type>(<scope>): <subject>

<body>

<footer>

Type must be one of the following:
- feat: New feature
- fix: Bug fix
- docs: Documentation changes
- style: Code formatting (changes that don't affect code execution)
- refactor: Refactoring (neither new feature nor bug fix)
- perf: Performance optimization
- test: Add tests
- chore: Build process or auxiliary tool changes
"""

Required Fields:

Field	Type	Description
prompt	String	The prompt that will be sent to the Tuanjie AI model when the command is executed. Can be a single-line or multi-line string.

Optional Fields:

Field	Type	Description
description	String	A short single-line description of the command's functionality. This text will be displayed next to the command in the /help menu.

Parameter Processing

Custom Commands support two powerful parameter processing methods.

1. Precise Control with {{args}}

If your prompt contains the special placeholder {{args}}, the CLI will replace the placeholder with the text the user entered after the command name.

Example:

# git/fix.toml
description = "Generate code fixes for given issues."
prompt = "Provide code fixes for the following described issue: {{args}}."

Invocation: /git:fix Button is misaligned

Model receives: Provide code fixes for the following described issue: Button is misaligned.

2. Default Parameter Processing

If your prompt does not contain {{args}}, the CLI will append the complete command entered by the user to the end of the prompt, separated by two line breaks.

Example:

# review.toml
description = "Review the provided code."
prompt = """
You are a professional code review expert.

Review the code provided by the user, focusing on the following aspects:
- Code style and formatting
- Potential bugs
- Performance issues
- Security vulnerabilities

**The user's original command will be appended below your instructions.**
"""

Invocation: /review FileCommandLoader.ts

Model receives: Original prompt + line break + FileCommandLoader.ts

Executing Shell Commands (!{...})

You can make commands dynamic by directly executing shell commands within prompts and injecting their output.

How It Works:

1. Use the !{command} syntax to execute shell commands
2. If {{args}} exists within the block, shell escaping is automatically performed
3. The CLI will prompt you to confirm before executing the command (security measure)
4. Command output replaces the !{...} block

Example:

# git/commit.toml
description = "Generate Git commit messages based on staged changes."
prompt = """
Generate a Conventional Commit message based on the following git diff:

!{git diff --staged}
"""

Invocation: /git:commit

CLI executes git diff --staged, injects the output into the prompt, and then sends it to the AI.

Security Tip: Always confirm shell command execution and avoid hardcoding sensitive information in commands.

Injecting File Content (@{...})

You can use the @{...} syntax to directly embed the content of files or directory lists into prompts.

How It Works:

• File injection: @{path/to/file.txt} is replaced with the content of file.txt
• Multi-modal support: Supports images (PNG, JPEG), PDF, audio, or video files
• Directory listing: @{path/to/dir} traverses the directory and inserts all file content
• Workspace aware: Commands search for paths in both the current directory and the workspace directory
• Processing order: File injection is processed before shell commands and parameter replacement

Example:

# review.toml
description = "Review the provided context using best practices guide."
prompt = """
You are a professional code review expert.

Review `{{args}}`.

Use the following best practices for review:

@{docs/best-practices.md}
"""

Invocation: /review FileCommandLoader.ts

CLI injects the content of docs/best-practices.md into the prompt, replaces {{args}} with FileCommandLoader.ts, and then sends it to the AI.

Example: Creating a "Pure Function" Refactoring Command

Let's create a global command that asks the model to refactor a piece of code into a pure function.

Step 1: Create File and Directory

macOS/Linux:

mkdir -p ~/.codely/commands/refactor
touch ~/.codely/commands/refactor/pure.toml

Windows (PowerShell):

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codely\commands\refactor"
New-Item -ItemType File -Force -Path "$env:USERPROFILE\.codely\commands\refactor\pure.toml"

Step 2: Add Content to File

# ~/.codely/commands/refactor/pure.toml
# Invoked by: /refactor:pure

description = "Ask the model to refactor the current context into a pure function."
prompt = """
Analyze the code I provided in the current context.
Refactor it into a pure function.

Your response should include:
1. The refactored pure function code block.
2. A brief explanation of the main changes you made and how they contribute to purity.

Characteristics of pure functions:
- Same input always produces same output
- Does not modify external state
- No side effects
- Does not depend on external mutable state
"""

Step 3: Run the Command

# First add the file to context
@my-messy-function.js

# Then invoke the command
/refactor:pure

Best Practices

1. Description Optimization: Write clear, specific descriptions to help others understand the purpose of commands
2. Organize Commands: Create subdirectories for related commands and use namespaces to maintain clear structure
3. Parameter Processing: Choose the appropriate parameter processing method based on your needs ({{args}} or default behavior)
4. Security First: Always confirm shell command execution and avoid hardcoding sensitive information
5. Document Commands: Add comments within command files to explain their purpose and usage
6. Version Control: Include project commands in version control for easy team collaboration

Command Reference Table

Feature	Syntax	Description
Parameter injection	{{args}}	Inject user input into the prompt
Shell command	!{command}	Execute shell command and inject output
File injection	@{path}	Inject content of file or directory
Command separator	/ or :	Create namespaced commands
Line break	"""	Create multi-line prompts

Common Questions

How do I reload commands?

Run /commands reload to reload commands without restarting the CLI.

How do I view all available commands?

Run /commands list or /help to view all available commands and their descriptions.

Can project commands override global commands?

Yes. If a command in the project directory has the same name as a command in the user directory, the project command will take priority.

How do I delete commands?

Simply delete the corresponding .toml file and then run /commands reload.

Do commands support nesting?

Yes. You can create subdirectories of any depth to organize commands, such as /tools:database:migrate.

---

Document Version: 1.0 Last Updated: March 26, 2026