Bot Chat Commands

Built-in chat commands — status, model switching, usage, context compression, queuing — plus Python-registered, file-based, and entry-point custom commands for Telegram, Discord, Slack, and WhatsApp bots.

from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="You are a helpful assistant.")
agent.start("What commands are available?")

The user types a slash command in chat; the bot runs built-in handlers for status, model, usage, and session control.

Command Picker

graph TB
    Q{What do you need?} --> A[Cancel current answer only]
    Q --> A2[Cancel current answer AND my queued messages]
    Q --> B[Free context space]
    Q --> M[See where we left off]
    Q --> C[Change LLM]
    Q --> D[See cost/tokens]
    Q --> E[Queue a follow-up]
    Q --> F[Author a skill from sources]
    Q --> G[Rewind the last turn]
    Q --> H[List or switch sessions]
    Q --> I[Re-run your last message]
    Q --> J[Toggle reasoning visibility]
    Q --> K[Accept a suggested automation]
    Q --> L[Create from a template]
    Q --> M[Run a project command file]
    Q --> N[Inspect background tasks]
    A --> A1[/stop]
    A2 --> A3[/stop all  ·  /cancel]
    B --> B1[/compress]
    M --> M1[/recap]
    C --> C1[/model]
    D --> D1[/usage]
    E --> E1[/queue]
    F --> F1[/learn]
    G --> G1[/undo]
    H --> H1[/sessions, /resume]
    I --> I1[/retry]
    J --> J1[/reasoning]
    K --> K1[/automations]
    L --> L1[/blueprint]
    N --> N1[/tasks]
    M --> M1[".praisonai/commands/*.md → /name"]

    classDef agent fill:#8B0000,color:#fff
    classDef tool fill:#189AB4,color:#fff
    classDef source fill:#6366F1,color:#fff

    class Q agent
    class A,A2,B,C,D,E,F,G,H,I,J,K,L,N,A1,A3,B1,C1,D1,E1,F1,G1,H1,I1,J1,K1,L1,N1 tool
    class M,M1 source

File-based (.praisonai/commands/*.md) and entry-point commands surface alongside built-ins — see File-based & Entry-point Commands.

Every PraisonAI bot comes with built-in chat commands. Just type a command in your chat — no setup required.

Built-in Commands

Per-Command Access Control

Restrict which commands each user may run with admin_users and user_allowed_commands on Telegram, Slack, and Discord — admins get full access, regular users only run commands you list. All built-in commands, including the new runtime controls, are gated by this policy.

Command classification is now gated by two layers: content-trust (new — BotMessage.allow_control, so an untrusted producer’s /-prefixed body is never treated as a command) and identity ACL (existing — admin_users / user_allowed_commands). Content-trust fires first. See Control-Trust Provenance.

Quick Start

1. Install PraisonAI

   pip install praisonai

2. Set Your Bot Token

   export TELEGRAM_BOT_TOKEN=your_token_here

3. Start the Bot

   praisonai bot telegram --token $TELEGRAM_BOT_TOKEN

4. Send a Command

   Open your bot chat and type:

   /status

   You’ll see the agent name, model, platform, and uptime.

Platform Examples

praisonai bot telegram --token $TELEGRAM_BOT_TOKEN

praisonai bot discord --token $DISCORD_BOT_TOKEN

praisonai bot slack --token $SLACK_BOT_TOKEN --app-token $SLACK_APP_TOKEN

Command Details

/status

Shows current bot information:

/whoami

Shows permission information for the caller:

Example output:

User Information
User ID: 456
Username: alice
Role: User
Allowed commands: help, status, whoami

A command outside your allowed list — or one that doesn’t exist — falls through to the agent rather than vanishing. See Unknown or Misspelled Commands.

/new

Resets the conversation:

• Clears all previous messages from the agent’s session
• Replies with a confirmation message
• Next message starts a completely new conversation
• Clears any per-user /model override — so a “start fresh” also un-does a bad or unavailable model switch (a stuck /model gpt-9-imaginary no longer persists past /new)

/stop

Cancels the current agent task immediately. Pick the scope that matches what you want stopped.

graph TB
    Q{What do you want to stop?} --> A[Just the running answer]
    Q --> B[The running answer AND my queued follow-ups]
    A --> A1[/stop  ·  stop]
    B --> B1[/stop all  ·  /cancel]

    classDef q fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef turn fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef session fill:#F59E0B,stroke:#7C90A0,color:#fff

    class Q q
    class A,A1 turn
    class B,B1 session

Turn-scoped (default):

/stop:

• Immediately interrupts the current agent processing
• Replies with confirmation that the task was cancelled
• Next message starts a fresh task

/stop all and /cancel additionally:

• Drain any pending messages the user queued behind the running turn
• Report the drained count as pending_cancelled: N so nothing is silently dropped

/help

Lists all available commands — both built-in and custom — with their descriptions.

/model

Switches the LLM model for your conversation, or reports which model is currently active.

Show current model — /model with no argument:

Current model: gpt-4o-mini
Use /model <name> to switch (e.g., /model gpt-4o)

Switch model — /model <name>:

/model gpt-4o
✅ Model switched to gpt-4o for this conversation.

Restart-required guard — when the gateway’s code on disk has changed since the process started (e.g. you ran git pull or pip install -U against the running checkout), /model <name> refuses the switch instead of risking a half-loaded module:

/model gpt-4o
⚠️ Gateway code changed on disk since it started (2aa28d1 → def5678). Restart the gateway to apply updates before switching models.

Restart the gateway/bot process and try again. The check is best-effort: when the fingerprint can’t be determined (no git checkout, unreadable files) the switch proceeds normally.

To disable the guard (e.g. on a sandboxed CI runner where in-place updates are deliberate):

session_manager.code_skew_guard = False

/usage

Reports token usage and a rough estimated cost for the session.

Example output:

📊 Token Usage
Total: 18,204 tokens
Prompt: 12,800 | Completion: 5,404
Est. cost: $0.0036

/compress

Compresses your conversation history to free context-window space.

• Requires at least 10 messages — shorter histories get: "ℹ️ Conversation too short to compress (need at least 10 messages)."
• Targets ~50% token reduction, always preserving the most recent 10 messages and all system messages
• Reports messages removed and tokens freed:

✅ Compressed 32 messages, freed ~12,400 tokens.

• If the context optimizer library is unavailable, falls back to keeping system messages and the last 10 messages
• On failure the history is left untouched: "❌ Compression failed: {error}"

/recap

Renders a read-only “where were we” summary of the session without changing anything.

Example output:

📌 Recap — where we were:
[Previous conversation summary]
User asked about deploy runbook; we outlined steps 1–3.
Recent:
• user: what about step 4?
• assistant: step 4 covers rollback…

• Read-only. Never mutates the transcript and never triggers compaction — safe to run mid-conversation.
• Reuses a persisted summary when present. If /compress has already produced a compaction summary, /recap shows it verbatim instead of re-summarising.
• Otherwise it runs the naive summariser over a copy of the history, so the original is untouched and no compaction event is emitted.
• Always preserves the recent tail — the last few messages are appended verbatim.
• Output is bounded to ~3500 characters so Telegram deliveries never overflow the 4096-char message limit; when trimming is needed the older summary is truncated, never the recent tail.

Empty history returns:

Nothing to recap yet — this session has no messages.

When the access policy denies the command, the bot replies:

⛔ You are not permitted to run /recap

The same recap is available as a Python primitive when you build a custom surface:

from praisonaiagents.compaction import build_recap

history = [
    {"role": "user", "content": "Outline the deploy runbook."},
    {"role": "assistant", "content": "Steps 1–3 cover build, test, ship."},
    {"role": "user", "content": "What about step 4?"},
    {"role": "assistant", "content": "Step 4 covers rollback."},
]

print(build_recap(history))

/queue

Adds a follow-up message that runs after the current task completes.

Check pending queue — /queue with no argument:

📝 Pending follow-up: summarise the key findings

Or if nothing is pending:

No follow-up queued. Use /queue <message> to add one while a task is running.

Queue a message — three possible outcomes depending on bot state:

/undo

Rewinds the last turn’s file changes via Agent.undo().

• Requires change tracking and the pre-run snapshot — autonomy=AutonomyConfig(track_changes=True, snapshot=True) (see File Snapshot)
• Returns "✅ Reverted the last turn." when files were restored, "ℹ️ Nothing to undo." when there is nothing to revert
• Degrades gracefully when undo is unavailable: "❌ This agent does not support undo (change tracking not enabled)."

/sessions

Lists recent saved sessions for the requesting user only. Session lookups are scoped via the per-user storage key so one caller cannot enumerate another user’s sessions.

Example output:

📁 Recent sessions:
• telegram:123456789
• telegram:123456789:project-a

Use /resume <id> to switch to one.

Returns "No saved sessions yet." when nothing is stored.

/resume

Switches to a previously saved session.

/resume telegram:123456789:project-a
✅ Resumed session telegram:123456789:project-a.

• Usage: /resume <id> — run /sessions first to see IDs
• Returns "❌ Session {id} not found." when the ID is unknown
• When the session manager lacks a resume_session primitive, the bot reports honestly rather than claiming a switch succeeded

/retry

Re-runs your most recent user message through the normal session.chat(...) path.

🔁 Retrying your last message:
Summarise the deployment runbook in three bullets.

Returns "ℹ️ Nothing to retry — no previous message found." when the history is empty.

/reasoning

Toggles whether extended-thinking output is shown for this user in this conversation. The preference is stored per user on the session manager.

/reasoning
🧠 Reasoning output will be shown for this conversation.

Run again to hide:

/reasoning
🙈 Reasoning output will be hidden for this conversation.

Defaults to hidden when no preference is set. Adapters consult is_reasoning_visible() when rendering responses.

/tasks

Inspect background tasks from inside the chat — no need to switch to a terminal. /tasks merges two sources into one list: background tasks (from BackgroundRunner) and background subagents spawned from chat (from BackgroundJobManager).

Example output:

/tasks
🧩 Background tasks:
• aa1b2c… research — running (35%)
• ff9d3e… summary  — completed (100%)
• 3f8a91c2 Research the latest Python 3.13 features — running

Use /tasks <id> for detail or /tasks cancel <id>.

/tasks 3f8a91c2
🧩 Task 3f8a91c2 — Research the latest Python 3.13 features
Status: completed
Result: Python 3.13 adds an experimental free-threaded build…

The list shows at most 20 entries: background tasks first, then background-subagent jobs newest-first in the remaining slots. Subagent detail shows Result: or Error: trimmed to the first 200 characters.

/tasks cancel <id> on a background subagent calls BackgroundJobManager.cancel_job(id) and only reports success when the job was actually cancelled.

Handler strings:

• Background Tasks — how tasks get submitted in the first place
• Background Subagents — chat-spawned jobs that /tasks also lists
• Command Access Control — /tasks respects the same policy, so admins can restrict it

/learn

Authors a grounded, reusable SKILL.md from sources you name — a codebase, API docs, PDFs, configs, or the current chat.

/learn deploy steps from this repo and the runbook PDF

• Calls agent.learn_skill(request) which gathers the named sources with the agent’s existing tools and writes one grounded SKILL.md via skill_manage
• Admin-only by default when a CommandAccessPolicy is configured (admin_users or user_allowed_commands set) — it belongs to PRIVILEGED_COMMANDS because it reads host sources and alters future agent behaviour
• Available to all users when no policy is configured (backward-compatible)

/automations

Lists pending automation suggestions, one message per suggestion, each with its own ✓ Accept / ✕ Dismiss inline keyboard. Telegram only today.

• Header when suggestions exist: 💡 You have 1 pending automation suggestion: (pluralised by count)
• Header when empty: You have no pending automation suggestions.\nUse /blueprint to create one from a template.
• Each Accept button carries sug:accept:<id>; each Dismiss carries sug:dismiss:<id>
• The automations permission is re-checked on every button tap. A denied user sees ⛔ You are not permitted to manage automations appended to the message
• When the scheduler extra isn’t installed: ❌ Automations are not available (scheduler not installed).

/blueprint

Creates an automation directly from a blueprint template. Telegram only today.

Three call shapes:

1. /blueprint (no args) → lists available blueprints + usage:

📋 Create an automation from a template:

• morning-brief — Daily morning briefing with news and priorities
• important-mail — Check for important emails at a regular interval
• weekly-review — End-of-week summary and review

Usage: /blueprint <name> [slot=value ...]
Example: /blueprint morning-brief hour=8 weekdays=mon-fri

1. /blueprint <name> → creates a job with blueprint defaults
2. /blueprint <name> hour=8 weekdays=mon-fri → slot overrides

Slot overrides use key=value grammar. Integer-looking values are coerced to int, so hour, minute, and interval_minutes resolve correctly (_parse_slot_args).

Success and error strings from _automations.create_from_blueprint:

✅ Automation scheduled from 'morning-brief'. Added job 'morning-brief' (schedule cron:0 8 * * mon,tue,wed,thu,fri)

❌ Blueprint 'unknown' not found. Available: morning-brief, important-mail, weekly-review

Unknown or Misspelled Commands

An unknown slash command — a typo like /statu, or a custom command name that isn’t registered on this deployment — is dispatched to the agent as the raw text, the same as any free-form message. The bot never silently drops a command.

Custom Commands

Register your own commands using register_command(). Available on all bot adapters.

from praisonai.bots import TelegramBot
from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful")
bot = TelegramBot(token="YOUR_TOKEN", agent=agent)

# Register a custom command
async def handle_ping(message):
    return "Pong! Bot is alive."

bot.register_command("ping", handle_ping, description="Check if bot is alive")

import asyncio
asyncio.run(bot.start())
# Now /ping is available alongside /status, /new, /stop, /help

register_command() API

bot.register_command(
    name="mycommand",           # Command name (without /)
    handler=my_handler,          # Async or sync callable
    description="What it does",  # Shown in /help
    usage="/mycommand <arg>",    # Optional usage string
    channels=["telegram"],       # Optional: restrict to specific platforms
)

The description you pass here IS the label users see in the native / menu on Telegram and Discord. See Slash Command Menu.

list_commands()

Get all registered commands:

commands = bot.list_commands()
# Returns: [ChatCommandInfo(name="status", ...), ChatCommandInfo(name="new", ...), ...]

# Filter by platform
telegram_commands = bot.list_commands(platform="telegram")

File-based and Entry-point Commands in Bot Chats

One .praisonai/commands/{name}.md file authored once runs in praisonai code and in every bot chat — no duplication, no per-platform wiring.

Quick Start — one file, every chat

Author a single command file:

---
description: Summarise the current channel
argument-hint: <topic?>
---
Summarise recent messages about $ARGUMENTS.

Start the bot — nothing new to wire. The resolver discovers the file automatically once bot commands are enabled in config:

from praisonai.bots import TelegramBot
from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful.")
bot = TelegramBot(token="YOUR_TOKEN", agent=agent)

import asyncio
asyncio.run(bot.start())
# /summary is now available in Telegram — same file also works in `praisonai code`.

The user runs it in chat:

User:  /summary Q3 revenue
Bot:   [agent replies with a Q3 revenue summary]

One command source, every surface

The same .praisonai/commands/*.md files already documented for Custom Agents & Commands now reach bot chats too — the resolver reuses that loader through the sanctioned _code_bridge seam instead of reimplementing it.

Configuration — BotCommandsConfigSchema

Enable and tune the bridge with a commands block on each channel.

# bots.yaml
channels:
  telegram:
    token: env:TELEGRAM_BOT_TOKEN
    commands:
      allow_shell: false          # default; opt-in per deployment (see safety)
      expose: [summary, deploy]   # optional allow-list; omit → all project commands
      include_user_scope: false   # default; user ~/.praisonai commands excluded

from praisonai_bot.bots._config_schema import (
    ChannelConfigSchema,
    BotCommandsConfigSchema,
)

channel = ChannelConfigSchema(
    platform="telegram",
    token="${TELEGRAM_BOT_TOKEN}",
    commands=BotCommandsConfigSchema(
        allow_shell=False,
        expose=["summary", "deploy"],
        include_user_scope=False,
    ),
)

export TELEGRAM_BOT_TOKEN=your_token_here
# Author .praisonai/commands/summary.md, then start the bot with a config
# whose channel enables commands. With an empty `expose`, every project
# command is surfaced automatically.
praisonai bot serve --config bots.yaml

Safety posture: double opt-in for shell

Shell substitution needs both the deployment and the command to say yes.

When either is false, the resolver drops the ! marker so the segment becomes plain backticks — the safe $ARGUMENTS and @file parts still interpolate normally instead of the whole command failing.

Precedence & collision rules

When two sources define the same command name, one wins.

/help and the native / menu are populated through the shared ChatCommandMixin, so file and entry-point commands appear in both automatically — no per-adapter wiring.

Packaged commands via entry-point

Installed packages add bot commands through the praisonai.bot_commands entry-point group — no forking.

# pyproject.toml
[project.entry-points."praisonai.bot_commands"]
mypkg = "mypkg.bot_commands:commands"

# mypkg/bot_commands.py
commands = {
    "greet": {
        "description": "Say hi",
        "template": "Say hello to $ARGUMENTS.",
        "allow_shell": False,   # optional; safe default
    },
}
# Or expose a zero-argument callable that returns the same dict.

The loader accepts three spec shapes per command:

User interaction flow

1. A teammate authors .praisonai/commands/deploy.md with description: "Run the deploy checklist" and opens a PR.
2. After merge, everyone using praisonai code gets /deploy — no restart of code.
3. On the next bot restart, /deploy also appears in Telegram’s native / menu with the same description, and running it in chat replies with the interpolated template through the normal session.chat path.
4. Same file. Two surfaces. No duplication.

Security & Allowlists

Built-in commands (/status, /new, /help) and custom commands registered via register_command() go through the same security pipeline as regular text messages. If allowed_users is set and the sender is not in it, the command is silently dropped with no reply. If unknown_user_policy="pair", unknown senders get the pairing flow before the command runs. If group_policy="mention_only", commands in groups still need a mention. observe behaves like mention_only for command dispatch — slash-commands in groups still need a mention; only free-form messages are passively recorded. Under command_only on Telegram, Discord and Slack, a plain @mention without a slash-command does not run the agent — only slash-commands do.

from praisonai.bots import TelegramBot
from praisonaiagents import BotConfig
from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful")
bot = TelegramBot(
    token="YOUR_TOKEN",
    agent=agent,
    config=BotConfig(allowed_users=["123456789"]),  # Only this user
)

# /help, /status, /new from any other user are now silently ignored

For full allowlist setup, see the Bot Security guide. This security hardening was implemented in PR #1835.

Python Usage

Start bots programmatically — built-in commands are always available:

from praisonai.bots import TelegramBot
from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful")
bot = TelegramBot(token="YOUR_TOKEN", agent=agent)

import asyncio
asyncio.run(bot.start())
# /status, /new, /stop, /model, /usage, /compress, /recap, /queue, /tasks, /help available automatically
# /stop all and /cancel (session-scoped stop) are handled by the gateway when the bot is gateway-routed

from praisonai.bots import DiscordBot
from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful")
bot = DiscordBot(token="YOUR_TOKEN", agent=agent)

import asyncio
asyncio.run(bot.start())

from praisonai.bots import SlackBot
from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful")
bot = SlackBot(token="YOUR_TOKEN", app_token="YOUR_APP_TOKEN", agent=agent)

import asyncio
asyncio.run(bot.start())

from praisonai.bots import WhatsAppBot
from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful")
bot = WhatsAppBot(mode="web", agent=agent)
# /stop, /status, /new, /help registered automatically

import asyncio
asyncio.run(bot.start())

Native / Autocomplete (Telegram + Discord)

Typing / in Telegram or Discord surfaces the bot’s commands with descriptions through each platform’s native menu — no configuration needed.

The bot publishes the menu automatically on startup — no user code required:

from praisonai.bots import TelegramBot
from praisonaiagents import Agent

agent = Agent(name="Support", instructions="Answer customer questions.")
bot = TelegramBot(token="YOUR_TOKEN", agent=agent)

import asyncio
asyncio.run(bot.start())  # /-menu appears in Telegram automatically

Custom commands flow through the same registry, so they appear alongside the built-ins on the next restart:

from praisonai.bots import TelegramBot
from praisonaiagents import Agent

agent = Agent(name="Support", instructions="Answer customer questions.")
bot = TelegramBot(token="YOUR_TOKEN", agent=agent)

async def summary(message):
    return "Latest summary..."

bot.register_command("summary", summary, description="Get the latest summary")

import asyncio
asyncio.run(bot.start())  # /summary appears alongside /status, /model, /usage in the / menu

Design Guarantees

The menu is a discoverability layer that never changes how commands run.

Per-Platform Behaviour

Out-of-range names are skipped; over-length descriptions are truncated.

Best Practices

Related