Slash commands deep dive

• Manual control over plugin behavior. Configure which directories are auto-committed, start/stop a focus session, clear an audit log.
• Quick lookups that don't need the LLM. /disk-cleanup status reads a JSON file and formats it. No model call, no token spend, sub-millisecond response.
• Power-user shortcuts for common workflows. /journal entry text appends to today's file in one step instead of dictating the workflow to the agent.

• Anything the agent could decide on its own. If the user could just say "clean up disk" in natural language and the agent would call the right tool, prefer a tool over a slash command.
• Long-running operations. Slash handlers are synchronous from the user's perspective. Anything over a few seconds should be a tool the agent kicks off and awaits.
• Operations that need to be discoverable by the LLM. The LLM can't call slash commands. If the agent should know about this capability and chain it with other actions, it's a tool.

For most plugins, a leading-word subcommand pattern is enough:

def handler(args: str) -> str:
    argv = args.strip().split()  # whitespace tokens
    if not argv or argv[0] in ("help", "-h", "--help"):
        return _HELP_TEXT

    sub = argv[0]
    rest = argv[1:]

    if sub == "status":
        return show_status()

    if sub == "add":
        if len(rest) < 1:
            return "Usage: /your-cmd add <value>"
        return add_value(rest[0])

    if sub == "set":
        if len(rest) < 2:
            return "Usage: /your-cmd set <key> <value>"
        return set_kv(rest[0], " ".join(rest[1:]))

    return f"Unknown subcommand: {sub}\n\n{_HELP_TEXT}"

For commands like /journal entry "had coffee with John", use shlex.split:

import shlex

def handler(args: str) -> str:
    try:
        argv = shlex.split(args.strip(), posix=True)
    except ValueError:
        return "Mismatched quotes — try again."

    if not argv:
        return _HELP_TEXT
    # ...

For commands with many optional flags (e.g. /search query:foo limit:10 sort:newest), parse key:value tokens:

def parse_flags(args: str) -> dict:
    flags = {}
    for tok in args.strip().split():
        if ":" in tok:
            key, _, val = tok.partition(":")
            flags[key.strip()] = val.strip()
    return flags

Always use Markdown. The desktop app and most channels (Telegram, Discord, Web) render it natively — bold, headings, tables, inline code, bullet lists all work. Plain text returns get displayed as-is and look like raw output dumps in the chat thread.

# ❌ Bad — looks like a terminal log in the chat
def status_bad(args: str) -> str:
    return (
        "auto-commit is ENABLED. Allowed roots:\n"
        "  • /Users/me/projects (git repo)\n"
        "  • /Users/me/notes    (git repo)"
    )


# ✅ Good — Markdown renders properly
def status_good(args: str) -> str:
    return (
        "**auto-commit is ENABLED**\n\n"
        "| Root | Status |\n"
        "|---|---|\n"
        "| `/Users/me/projects` | 🟢 git repo |\n"
        "| `/Users/me/notes` | 🟢 git repo |"
    )

Useful Markdown elements for slash output:

• **bold** for status / labels / counts
• `code` for IDs, paths, commands, technical values
• ## Heading for record titles when showing one item
• Tables for structured records (key/value, listings with columns)
• - bullet for lists (each line; use trailing two-space for line breaks)
• _italic_ for empty-state messages ("_no results_")
• Avoid HTML — not all channels render it

See the bundled case-tracker plugin for a real-world example of slash handlers returning rich Markdown — tables for one-record details, bullet lists for search results, code spans for IDs, headings for sections.