Slash Commands

Interactive slash commands for PraisonAI CLI

Slash Commands

PraisonAI CLI provides interactive slash commands for quick actions during your AI coding sessions. Inspired by Gemini CLI, Codex CLI, and Claude Code, these commands give you powerful control without leaving the terminal.

Overview

Slash commands start with / and provide quick access to common operations in interactive mode.

❯ /help
❯ /tools
❯ /clear
❯ /exit

Available Commands (Interactive Mode)

When using praisonai chat, these commands are available. Installed skills and your custom .praisonai/commands/*.md files appear in the same / menu alongside these built-ins.

Built-in Tools

Interactive mode includes 5 built-in tools that the AI can use:

❯ /tools
Available tools: 5
  • read_file
  • write_file
  • list_files
  • execute_command
  • internet_search

Usage Examples

Starting Interactive Mode

# Start interactive mode
praisonai chat

# Or use short flag
praisonai -i

Using Help

❯ /help

Commands:
  /help          - Show this help
  /exit          - Exit interactive mode
  /clear         - Clear screen
  /tools         - List available tools
  /profile       - Toggle profiling (show timing breakdown)
  /model [name]  - Show or change current model
  /code-review [file|--staged]     - Review the uncommitted diff for bugs (read-only)
  /security-review [file|--staged] - Audit the uncommitted diff for security issues (read-only)
  /stats         - Show session statistics (tokens, cost)
  /compact       - Compact chat_history (auto-runs at the turn boundary too)
  /compact-display - Toggle compact output display (alias /dense)
  /git-status    - Show working-tree status
  /git-diff      - Show the uncommitted diff
  /git-log [n]   - Show recent commits
  /git-commit [m]- Stage and commit (message auto-generated when omitted)
  /git-undo      - Undo the last commit (keeps changes staged)
  /map [path]    - Show the repository map
  /undo          - Undo last turn (files + conversation when checkpointing on)
  /revert [n]    - Revert the last N turns (files + conversation)
  /queue         - Show queued messages
  /queue clear   - Clear message queue

@ Mentions:
  @file.txt      - Include file content in prompt
  @src/          - Include directory listing

Features:
  • File operations (read, write, list)
  • Shell command execution
  • Web search
  • Context compression for long sessions
  • Queue messages while agent is processing

Listing Tools

❯ /tools
Available tools: 5
  • read_file
  • write_file
  • list_files
  • execute_command
  • internet_search

Using Tools via Natural Language

# List files
❯ list files in current folder
Here are the files: README.md, main.py, config.yaml

# Read a file
❯ read the contents of README.md
The file contains: # My Project...

# Search the web
❯ search the web for latest AI news
Here are the results from web search...

Python API

You can also use slash commands programmatically:

from praisonai.cli.features import SlashCommandHandler

# Create handler
handler = SlashCommandHandler()

# Check if input is a command
if handler.is_command("/help"):
    result = handler.execute("/help")
    print(result)

# Get completions for auto-complete
completions = handler.get_completions("/he")
# Returns: ["/help"]

Custom Commands

File-based commands in .praisonai/commands/.md (and .claude/commands/.md / .agents/commands/*.md when present) auto-register in interactive mode with kind=CommandKind.CUSTOM. Disable discovery with SlashCommandHandler(discover_custom=False). Edits apply on the next prompt without restarting the session. See Custom Agents & Commands → Live edits during interactive sessions. See Custom Agents & Commands.

Unified Command Registry

Type / at the interactive prompt to see every registered command in one menu — built-ins first, then your .praisonai/commands/*.md files, then installed skills (SkillCommandSource), then MCP prompts, then any praisonai.commands pack. A skill named my-skill shows up as /my-skill with the skill’s own description from SKILL.md frontmatter, and pressing Enter runs it (the skill body renders as a prompt with any args appended).

Inside praisonai code (and the REPL / async TUI) a single CommandRegistry aggregates every command source into one /name namespace — built-ins, your .praisonai/commands/.md files (plus .claude/commands/.md and .agents/commands/*.md when present), skills, MCP prompts, and pip-installed command packs all appear together.

Commands you run most float to the top of the / popup. See Completion Ranking.

Not every installed skill appears in the / menu. A skill whose SKILL.md frontmatter sets user-invocable: false is treated as model-only: the LLM can still auto-trigger it from the system-prompt listing, but it is absent from the completion menu and typing /<name> falls through to “Unknown command”. See Skills → Invocation Policy for the full visibility truth table.

Custom commands work inside praisonai code

Create .praisonai/commands/mydeploy.md:

Deploy to {{env}}: run tests, build the image, push to registry.

Then invoke it inside the interactive session:

> /mydeploy staging

This runs the exact interpolated template that praisonai run --command mydeploy staging would — full parity between interactive and CLI invocation.

Skills work inside praisonai code

Type / at the prompt and your installed skills appear in the completion menu next to built-ins and custom commands:

> /
  /help                  Show help
  /clear                 Clear the screen
  /mydeploy staging      Deploy to staging: run tests, build...
  /my-skill              Does a useful thing        ← installed skill
  /pr-summary            Summarise a PR

> /my-skill extra context

/my-skill renders SKILL.md‘s body with the user’s args appended, matching praisonai "/my-skill extra context" --skills ./skills/my-skill.

Ship a command pack as a pip package

Register a command source in the praisonai.commands entry-point group in pyproject.toml:

[project.entry-points."praisonai.commands"]
my_commands = "my_package.commands:make_source"

The registry discovers it on start — no user code needed. A broken pack is logged and skipped, never taking down the registry.

Register programmatic slash commands:

from praisonai.cli.features.slash_commands import (
    SlashCommand, SlashCommandHandler, CommandKind
)

# Define custom command
def my_command(args, context):
    return {"type": "custom", "message": f"Args: {args}"}

custom_cmd = SlashCommand(
    name="mycommand",
    description="My custom command",
    handler=my_command,
    kind=CommandKind.ACTION,
    aliases=["mc"]
)

# Register it
handler = SlashCommandHandler()
handler.register(custom_cmd)

# Use it
result = handler.execute("/mycommand arg1 arg2")

Command Context

Provide context for commands that need session data:

from praisonai.cli.features.slash_commands import CommandContext

# Create context with session data
context = CommandContext(
    total_tokens=5000,
    total_cost=0.015,
    prompt_count=10,
    current_model="gpt-4o",
    session_start_time=time.time() - 300
)

# Set context on handler
handler.set_context(context)

# Now /cost will show real data
result = handler.execute("/cost")

Integration with Interactive Mode

Slash commands are automatically available in interactive mode:

praisonai chat

>>> Hello, help me with my code
[AI responds...]

>>> /cost
Model:          gpt-4o-mini
Total tokens:   1500
Estimated cost: $0.0003

>>> /model gpt-4o-mini
Model changed to: gpt-4o-mini

>>> /exit
Goodbye!

Command Reference

/help

Show help information.

/help              # Show all commands
/help <command>    # Show help for specific command

/clear and /new

Reset the conversation. As of PR #4943 both clear the agent’s conversation memory as well as the screen — the old behaviour only wiped the display, leaving the model still holding the prior turns. In the async TUI both also reset the token collector (as does /clear in the legacy REPL), so /cost starts at zero for the new conversation.

/clear             # clear screen + agent memory + /cost totals
/new               # start a fresh conversation (screen + agent memory + /cost totals)

/import

Restore a conversation from a file into both the screen and the agent’s state.

/import chat.json  # load messages and rebuild the agent so it remembers them

Previously /import printed Imported N messages and then answered as though none of them existed — the transcript was restored on screen but never plumbed into the agent. It now goes through the same persist + rebuild path as /continue.

/cost

Display session cost and token statistics.

/cost              # Show full statistics

/model

Manage the AI model.

/model             # Show current model
/model <name>      # Change to specified model

/plan

Toggle a persistent read-only mode — writes, edits, deletions, and shell commands are denied until you leave the mode.

> /plan
[PLAN] Plan mode enabled — read-only. Writes/edits/commands are denied until you /plan off.

> /plan refactor the auth module
[PLAN] Creating plan (read-only) for: refactor the auth module
...

> /plan off
Plan mode disabled. Writes/edits/commands are allowed again.

While plan mode is active, the status bar shows [PLAN].

Real-world flow:

1. Open on an unfamiliar codebase

   Start praisonai chat with your default policy.

2. Enter read-only mode

   Type /plan — the status bar flips to [PLAN] and writes/edits are denied.

3. Explore freely

   Ask read src/auth/*.py and summarise the auth flow — the agent uses read-only tools only.

4. Plan a fix under enforcement

   Type /plan design a fix for the token-refresh bug — the agent produces a step-by-step plan with no accidental edits mid-plan.

5. Exit and execute

   Type /plan off — the status bar clears and your launch-time policy returns. Now apply the plan writes and edits normally.

/diff

Show workspace file changes made this session, from the session-start baseline to the working directory.

/diff              # all changes since session start
/diff --turn       # only the last turn's changes (alias: -t)
/diff <file>       # changes to a single file since session start

/diff is backed by the checkpoint engine, so it requires auto-checkpointing: set checkpoints.auto: true in config or PRAISONAI_CHECKPOINTS=on. When disabled, /diff prints an enable hint and does nothing else.

/commit

Commit changes with an AI-generated message.

/commit            # Auto-generate commit message
/commit "message"  # Use custom message

/profile

Toggle profiling to see timing breakdown.

/profile           # Toggle profiling on/off

When enabled, shows timing after each response:

─── Profiling ───
Import:      0.1ms
Agent setup: 0.3ms
LLM call:    1,234.5ms
Display:     15.2ms
Total:       1,250.1ms

/stats

Show session statistics.

/stats             # Show token usage and cost

Output:

Session Statistics
  Model:          gpt-4o-mini
  Requests:       5
  Input tokens:   1,234
  Output tokens:  2,567
  Total tokens:   3,801
  Estimated cost: $0.0023
  History turns:  10

/stats works on every REPL surface — the legacy REPL, the async TUI (praisonai code), and praisonai chat. In the async TUI it shares the same renderer as /cost, so both print the same panel and you don’t need to remember which command works where.

/compact

Compact the model’s own chat_history to free context tokens.

/compact           # compact chat_history now; reports what it freed

This command:

• Compacts the model’s chat_history, not just the transcript pane.
• Reports what it freed (for example: 120 messages, 240,483 → 94,191 tokens).
• Runs automatically at the turn boundary when the session nears its context budget, instead of waiting for the provider to reject the request.

/compact-display

Toggle compact output display mode — the old /compact behaviour.

/compact-display   # toggle dense output
/dense             # alias

Git operator commands

Five git operator commands run directly, without the agent deciding to commit. They’re operator commands, not agent tools.

/git-status              # branch + staged/modified/untracked files
/git-diff [--staged]     # uncommitted diff (or staged diff)
/git-log [n]             # last n commits (default 10)
/git-commit [message]    # stage + commit; message auto-generated when omitted
/git-undo                # undo the last commit, keeping changes in the tree

See Git Integration → Operator slash commands.

/map

Show the repository map — an operator overview of an unfamiliar repo, not an agent tool.

/map                     # map the workspace root
/map src/api             # map a specific directory

See Repository Map.

/undo

Undo the last turn. What /undo restores depends on whether checkpointing and the session store are wired in.

/undo              # roll back the last turn

/revert

Revert the last N turns — files and conversation together. Mirrors /undo but takes a turn count.

/revert            # roll back the last 1 turn
/revert 3          # roll back the last 3 turns
/revert last       # explicit alias for the last 1 turn

A diff preview is shown before restore, and /revert refuses to run beyond the recorded turn count (Can only revert 1..N turn(s).). Checkpointing is on by default in praisonai interactive mode and praisonai code, so /revert works out of the box.

/export

Export the current conversation to a file — available in the legacy REPL (the surface praisonai code runs by default).

/export              # write to a default file (conversation.md)
/export out.md       # write to a caller-supplied path
/export out.json     # a .json path exports JSON

/export picks one of two paths automatically:

You don’t need to --session first — the fallback means /export always produces something useful. See praisonai session export for the same renderer on the CLI.

/queue

Manage the message queue. Queue messages while the AI agent is processing and they’ll be executed in order.

/queue             # Show all queued messages
/queue clear       # Clear the entire queue
/queue remove N    # Remove message at index N

Output when messages are queued:

❯ /queue
⏳ Processing...

Queued Messages (2):
  0. ↳ Add docstrings to the function
  1. ↳ Create unit tests

Use /queue clear to clear, /queue remove N to remove

/tasks

Inspect and cancel background tasks without leaving the conversation — parity with the CLI-only praisonai background list.

/tasks               # List background tasks (id, name, status, progress)
/tasks <id>          # Show detail for one task (incl. result/error)
/tasks cancel <id>   # Cancel a running task

/tasks reuses the same process-wide runner (get_background_runner()) as praisonai background list, so it shows the same tasks across the REPL, TUI, and bots.

When there are no tasks, it prints the empty state:

❯ /tasks
No background tasks

cancel stops the underlying future, not just the task record — a running task is actually interrupted.

Best Practices

1. Use aliases – /h is faster than /help
2. Check costs regularly – Use /cost to monitor spending
3. Explore unfamiliar code with /plan first – Read-only enforcement prevents accidental writes while you form a plan; run /plan off when you’re ready to execute
4. Commit frequently – Use /commit after each logical change

Related Features

• Message Queue – Full message queue documentation
• Interactive TUI – Full interactive terminal interface
• Background Tasks – /tasks and praisonai background list
• Cost Tracking – Detailed cost monitoring
• Git Integration – Git operations