pythonclaw 0.3.3__tar.gz → 0.5.0__tar.gz

{pythonclaw-0.3.3/pythonclaw.egg-info → pythonclaw-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythonclaw
-Version: 0.3.3
+Version: 0.5.0
 Summary: OpenClaw reimagined in pure Python — autonomous AI agent with memory, RAG, skills, web dashboard, and multi-channel support.
 Author-email: Eric Wang <wangchen2007915@gmail.com>
 License: MIT
@@ -8,7 +8,7 @@ Project-URL: Homepage, https://github.com/ericwang915/PythonClaw
 Project-URL: Documentation, https://github.com/ericwang915/PythonClaw#readme
 Project-URL: Repository, https://github.com/ericwang915/PythonClaw
 Project-URL: Issues, https://github.com/ericwang915/PythonClaw/issues
-Keywords: llm,agent,ai,autonomous,memory,rag,skills,telegram,chatbot,framework
+Keywords: llm,agent,ai,autonomous,memory,rag,skills,telegram,discord,whatsapp,chatbot,framework
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
@@ -27,6 +27,7 @@ Requires-Dist: anthropic
 Requires-Dist: google-generativeai
 Requires-Dist: python-telegram-bot[job-queue]>=20.0
 Requires-Dist: discord.py>=2.3
+Requires-Dist: pywa[fastapi]>=2.8
 Requires-Dist: apscheduler>=3.10
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: fastapi>=0.100
@@ -83,9 +84,12 @@ Dynamic: license-file
 | 🌐 | **Web dashboard** | Browser UI for chat, config, skill catalog, identity editing, and marketplace |
 | 🎙️ | **Voice input** | Deepgram speech-to-text in the web chat |
 | ⏰ | **Cron jobs** | Schedule tasks via YAML or let the agent create its own |
-| 📡 | **Multi-channel** | CLI, Web, Telegram, Discord — same agent, different interfaces |
+| 📡 | **Multi-channel** | CLI, Web, Telegram, Discord, WhatsApp — same agent, different interfaces |
 | 🔄 | **Daemon mode** | PID-managed background process with `start` / `stop` / `status` |
 | 🧬 | **Soul + Persona** | Separate core identity from swappable role presentation |
+| 🔧 | **TOOLS.md** | Local environment notes — your cheat sheet for the agent |
+| 🔒 | **Per-group isolation** | Each chat session gets its own memory (optional) |
+| 🔁 | **Concurrency control** | Per-session locks + global semaphore prevent interleaving |
 
 ---
 
@@ -112,7 +116,7 @@ pythonclaw stop
 ```bash
 git clone https://github.com/ericwang915/PythonClaw.git
 cd PythonClaw
-pip install -e ".[all]"
+pip install -e .
 pythonclaw onboard
 ```
 
@@ -125,7 +129,7 @@ pythonclaw onboard
 | `pythonclaw onboard` | Interactive setup wizard — choose LLM provider, enter API key |
 | `pythonclaw start` | Start the agent as a background daemon |
 | `pythonclaw start -f` | Start in foreground (no daemonize) |
-| `pythonclaw start --channels telegram discord` | Start with messaging channels |
+| `pythonclaw start --channels telegram discord whatsapp` | Start with messaging channels |
 | `pythonclaw stop` | Stop the running daemon |
 | `pythonclaw status` | Show daemon status (PID, uptime, port) |
 | `pythonclaw chat` | Interactive CLI chat (foreground REPL) |
@@ -170,24 +174,25 @@ $ pythonclaw start
 ## Architecture
 
 ```
-┌──────────────────────────────────────────────────────────┐
-│                       PythonClaw                         │
-├──────────┬───────────┬───────────┬───────────────────────┤
-│ CLI      │ Daemon    │ Sessions  │      Core             │
-│          │           │           │                       │
-│ onboard  │ start /   │ Store(MD) │ Agent                 │
-│ chat     │ stop /    │ Manager   │ ├─ Memory (Markdown)  │
-│ skill …  │ status    │           │ ├─ RAG (Hybrid)       │
-│          │           │           │ ├─ Skills (3-tier)    │
-│ Web UI ◄─┤ Channels  │           │ ├─ Compaction         │
-│ Voice In │ Telegram  │           │ ├─ Soul + Persona     │
-│          │ Discord   │           │ └─ Tool Execution     │
-├──────────┴───────────┴───────────┴───────────────────────┤
-│             LLM Provider Abstraction Layer               │
-│ DeepSeek │ Grok │ Claude │ Gemini │ Kimi │ GLM          │
-├──────────────────────────────────────────────────────────┤
-│            SkillHub Marketplace (skillhub.club)          │
-└──────────────────────────────────────────────────────────┘
+┌──────────────────────────────────────────────────────────────┐
+│                         PythonClaw                            │
+├──────────┬────────────┬───────────┬──────────────────────────┤
+│ CLI      │ Daemon     │ Sessions  │      Core                │
+│          │            │           │                          │
+│ onboard  │ start /    │ Store(MD) │ Agent                    │
+│ chat     │ stop /     │ Manager   │ ├─ Memory (Markdown)     │
+│ skill …  │ status     │ Locks +   │ ├─ RAG (Hybrid)          │
+│          │            │ Semaphore │ ├─ Skills (3-tier)        │
+│ Web UI ◄─┤ Channels   │           │ ├─ Compaction            │
+│ Voice In │ Telegram   │ Per-group │ ├─ Soul + Persona        │
+│          │ Discord    │ Isolation │ ├─ Group Context          │
+│          │ WhatsApp   │           │ └─ Tool Execution        │
+├──────────┴────────────┴───────────┴──────────────────────────┤
+│               LLM Provider Abstraction Layer                 │
+│ DeepSeek │ Grok │ Claude │ Gemini │ Kimi │ GLM              │
+├──────────────────────────────────────────────────────────────┤
+│              SkillHub Marketplace (skillhub.club)            │
+└──────────────────────────────────────────────────────────────┘
 ```
 
 ---
@@ -220,8 +225,11 @@ See [`pythonclaw.example.json`](pythonclaw.example.json) for the full template.
   "web":      { "host": "0.0.0.0", "port": 7788 },
   "channels": {
     "telegram": { "token": "" },
-    "discord":  { "token": "" }
-  }
+    "discord":  { "token": "" },
+    "whatsapp": { "phoneNumberId": "", "token": "", "verifyToken": "pythonclaw_verify" }
+  },
+  "isolation":   { "perGroup": false },
+  "concurrency": { "maxAgents": 4 }
 }
 ```
 
@@ -235,8 +243,8 @@ Environment variables (e.g. `DEEPSEEK_API_KEY`, `TAVILY_API_KEY`) override JSON
 |----------|---------------|---------------|
 | **DeepSeek** | `deepseek-chat` | — |
 | **Grok (xAI)** | `grok-3` | — |
-| **Claude (Anthropic)** | `claude-sonnet-4-20250514` | `pip install pythonclaw[anthropic]` |
-| **Gemini (Google)** | `gemini-2.0-flash` | `pip install pythonclaw[gemini]` |
+| **Claude (Anthropic)** | `claude-sonnet-4-20250514` | — (included) |
+| **Gemini (Google)** | `gemini-2.0-flash` | — (included) |
 | **Kimi (Moonshot)** | `moonshot-v1-128k` | — |
 | **GLM (Zhipu)** | `glm-4-flash` | — |
 | Any OpenAI-compatible | Custom | — |
@@ -282,11 +290,28 @@ Also accessible from the web dashboard **Marketplace** tab.
 ### Markdown Memory
 
 ```
-context/memory/
+~/.pythonclaw/context/memory/
 ├── MEMORY.md           # Curated long-term memory
 └── 2026-02-23.md       # Daily append-only log
 ```
 
+When **per-group isolation** is enabled (`"isolation": { "perGroup": true }` in config),
+each session (Telegram chat, Discord channel, etc.) gets its own `memory/`, `persona/`,
+and `soul/` under `~/.pythonclaw/context/groups/<session-id>/`, while global memories
+remain accessible via read-through fallback.
+
+### TOOLS.md — Local Notes
+
+```
+~/.pythonclaw/context/tools/
+└── TOOLS.md              # Your environment-specific cheat sheet
+```
+
+Skills define *how* tools work. `TOOLS.md` stores *your* specifics — SSH hosts, device
+nicknames, project paths, preferred defaults, API endpoints. Keeping them apart means
+you can update skills without losing your notes, and share skills without leaking your
+infrastructure. Editable from the web dashboard.
+
 ### Hybrid RAG Pipeline
 
 ```
@@ -333,7 +358,7 @@ PythonClaw/
 │   │   ├── memory/            # Markdown memory
 │   │   ├── knowledge/         # Knowledge-base RAG
 │   │   └── retrieval/         # BM25 + dense + fusion + reranker
-│   ├── channels/              # Telegram, Discord
+│   ├── channels/              # Telegram, Discord, WhatsApp
 │   ├── scheduler/             # Cron jobs, heartbeat
 │   ├── web/                   # FastAPI dashboard + static assets
 │   └── templates/             # Built-in skill templates
@@ -351,7 +376,7 @@ PythonClaw/
 git clone https://github.com/ericwang915/PythonClaw.git
 cd PythonClaw
 python -m venv .venv && source .venv/bin/activate
-pip install -e ".[all]"
+pip install -e .
 pytest tests/ -v
 ```
 
@@ -373,7 +398,7 @@ We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 | Dashboard | Web UI | Web UI (localhost:7788) |
 | Memory | Markdown | Markdown (long-term + daily) |
 | Skills | Plugin system | Three-tier + SkillHub marketplace |
-| Channels | Discord, Telegram, WhatsApp | CLI, Web, Telegram, Discord |
+| Channels | Discord, Telegram, WhatsApp | CLI, Web, Telegram, Discord, WhatsApp |
 | Voice | — | Deepgram STT |
 | LLM Providers | OpenAI, Anthropic, Gemini | DeepSeek, Grok, Claude, Gemini, Kimi, GLM |
 | Daemon | Background process | PID-managed (`start`/`stop`/`status`) |

{pythonclaw-0.3.3 → pythonclaw-0.5.0}/README.md

@@ -42,9 +42,12 @@
 | 🌐 | **Web dashboard** | Browser UI for chat, config, skill catalog, identity editing, and marketplace |
 | 🎙️ | **Voice input** | Deepgram speech-to-text in the web chat |
 | ⏰ | **Cron jobs** | Schedule tasks via YAML or let the agent create its own |
-| 📡 | **Multi-channel** | CLI, Web, Telegram, Discord — same agent, different interfaces |
+| 📡 | **Multi-channel** | CLI, Web, Telegram, Discord, WhatsApp — same agent, different interfaces |
 | 🔄 | **Daemon mode** | PID-managed background process with `start` / `stop` / `status` |
 | 🧬 | **Soul + Persona** | Separate core identity from swappable role presentation |
+| 🔧 | **TOOLS.md** | Local environment notes — your cheat sheet for the agent |
+| 🔒 | **Per-group isolation** | Each chat session gets its own memory (optional) |
+| 🔁 | **Concurrency control** | Per-session locks + global semaphore prevent interleaving |
 
 ---
 
@@ -71,7 +74,7 @@ pythonclaw stop
 ```bash
 git clone https://github.com/ericwang915/PythonClaw.git
 cd PythonClaw
-pip install -e ".[all]"
+pip install -e .
 pythonclaw onboard
 ```
 
@@ -84,7 +87,7 @@ pythonclaw onboard
 | `pythonclaw onboard` | Interactive setup wizard — choose LLM provider, enter API key |
 | `pythonclaw start` | Start the agent as a background daemon |
 | `pythonclaw start -f` | Start in foreground (no daemonize) |
-| `pythonclaw start --channels telegram discord` | Start with messaging channels |
+| `pythonclaw start --channels telegram discord whatsapp` | Start with messaging channels |
 | `pythonclaw stop` | Stop the running daemon |
 | `pythonclaw status` | Show daemon status (PID, uptime, port) |
 | `pythonclaw chat` | Interactive CLI chat (foreground REPL) |
@@ -129,24 +132,25 @@ $ pythonclaw start
 ## Architecture
 
 ```
-┌──────────────────────────────────────────────────────────┐
-│                       PythonClaw                         │
-├──────────┬───────────┬───────────┬───────────────────────┤
-│ CLI      │ Daemon    │ Sessions  │      Core             │
-│          │           │           │                       │
-│ onboard  │ start /   │ Store(MD) │ Agent                 │
-│ chat     │ stop /    │ Manager   │ ├─ Memory (Markdown)  │
-│ skill …  │ status    │           │ ├─ RAG (Hybrid)       │
-│          │           │           │ ├─ Skills (3-tier)    │
-│ Web UI ◄─┤ Channels  │           │ ├─ Compaction         │
-│ Voice In │ Telegram  │           │ ├─ Soul + Persona     │
-│          │ Discord   │           │ └─ Tool Execution     │
-├──────────┴───────────┴───────────┴───────────────────────┤
-│             LLM Provider Abstraction Layer               │
-│ DeepSeek │ Grok │ Claude │ Gemini │ Kimi │ GLM          │
-├──────────────────────────────────────────────────────────┤
-│            SkillHub Marketplace (skillhub.club)          │
-└──────────────────────────────────────────────────────────┘
+┌──────────────────────────────────────────────────────────────┐
+│                         PythonClaw                            │
+├──────────┬────────────┬───────────┬──────────────────────────┤
+│ CLI      │ Daemon     │ Sessions  │      Core                │
+│          │            │           │                          │
+│ onboard  │ start /    │ Store(MD) │ Agent                    │
+│ chat     │ stop /     │ Manager   │ ├─ Memory (Markdown)     │
+│ skill …  │ status     │ Locks +   │ ├─ RAG (Hybrid)          │
+│          │            │ Semaphore │ ├─ Skills (3-tier)        │
+│ Web UI ◄─┤ Channels   │           │ ├─ Compaction            │
+│ Voice In │ Telegram   │ Per-group │ ├─ Soul + Persona        │
+│          │ Discord    │ Isolation │ ├─ Group Context          │
+│          │ WhatsApp   │           │ └─ Tool Execution        │
+├──────────┴────────────┴───────────┴──────────────────────────┤
+│               LLM Provider Abstraction Layer                 │
+│ DeepSeek │ Grok │ Claude │ Gemini │ Kimi │ GLM              │
+├──────────────────────────────────────────────────────────────┤
+│              SkillHub Marketplace (skillhub.club)            │
+└──────────────────────────────────────────────────────────────┘
 ```
 
 ---
@@ -179,8 +183,11 @@ See [`pythonclaw.example.json`](pythonclaw.example.json) for the full template.
   "web":      { "host": "0.0.0.0", "port": 7788 },
   "channels": {
     "telegram": { "token": "" },
-    "discord":  { "token": "" }
-  }
+    "discord":  { "token": "" },
+    "whatsapp": { "phoneNumberId": "", "token": "", "verifyToken": "pythonclaw_verify" }
+  },
+  "isolation":   { "perGroup": false },
+  "concurrency": { "maxAgents": 4 }
 }
 ```
 
@@ -194,8 +201,8 @@ Environment variables (e.g. `DEEPSEEK_API_KEY`, `TAVILY_API_KEY`) override JSON
 |----------|---------------|---------------|
 | **DeepSeek** | `deepseek-chat` | — |
 | **Grok (xAI)** | `grok-3` | — |
-| **Claude (Anthropic)** | `claude-sonnet-4-20250514` | `pip install pythonclaw[anthropic]` |
-| **Gemini (Google)** | `gemini-2.0-flash` | `pip install pythonclaw[gemini]` |
+| **Claude (Anthropic)** | `claude-sonnet-4-20250514` | — (included) |
+| **Gemini (Google)** | `gemini-2.0-flash` | — (included) |
 | **Kimi (Moonshot)** | `moonshot-v1-128k` | — |
 | **GLM (Zhipu)** | `glm-4-flash` | — |
 | Any OpenAI-compatible | Custom | — |
@@ -241,11 +248,28 @@ Also accessible from the web dashboard **Marketplace** tab.
 ### Markdown Memory
 
 ```
-context/memory/
+~/.pythonclaw/context/memory/
 ├── MEMORY.md           # Curated long-term memory
 └── 2026-02-23.md       # Daily append-only log
 ```
 
+When **per-group isolation** is enabled (`"isolation": { "perGroup": true }` in config),
+each session (Telegram chat, Discord channel, etc.) gets its own `memory/`, `persona/`,
+and `soul/` under `~/.pythonclaw/context/groups/<session-id>/`, while global memories
+remain accessible via read-through fallback.
+
+### TOOLS.md — Local Notes
+
+```
+~/.pythonclaw/context/tools/
+└── TOOLS.md              # Your environment-specific cheat sheet
+```
+
+Skills define *how* tools work. `TOOLS.md` stores *your* specifics — SSH hosts, device
+nicknames, project paths, preferred defaults, API endpoints. Keeping them apart means
+you can update skills without losing your notes, and share skills without leaking your
+infrastructure. Editable from the web dashboard.
+
 ### Hybrid RAG Pipeline
 
 ```
@@ -292,7 +316,7 @@ PythonClaw/
 │   │   ├── memory/            # Markdown memory
 │   │   ├── knowledge/         # Knowledge-base RAG
 │   │   └── retrieval/         # BM25 + dense + fusion + reranker
-│   ├── channels/              # Telegram, Discord
+│   ├── channels/              # Telegram, Discord, WhatsApp
 │   ├── scheduler/             # Cron jobs, heartbeat
 │   ├── web/                   # FastAPI dashboard + static assets
 │   └── templates/             # Built-in skill templates
@@ -310,7 +334,7 @@ PythonClaw/
 git clone https://github.com/ericwang915/PythonClaw.git
 cd PythonClaw
 python -m venv .venv && source .venv/bin/activate
-pip install -e ".[all]"
+pip install -e .
 pytest tests/ -v
 ```
 
@@ -332,7 +356,7 @@ We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 | Dashboard | Web UI | Web UI (localhost:7788) |
 | Memory | Markdown | Markdown (long-term + daily) |
 | Skills | Plugin system | Three-tier + SkillHub marketplace |
-| Channels | Discord, Telegram, WhatsApp | CLI, Web, Telegram, Discord |
+| Channels | Discord, Telegram, WhatsApp | CLI, Web, Telegram, Discord, WhatsApp |
 | Voice | — | Deepgram STT |
 | LLM Providers | OpenAI, Anthropic, Gemini | DeepSeek, Grok, Claude, Gemini, Kimi, GLM |
 | Daemon | Background process | PID-managed (`start`/`stop`/`status`) |

{pythonclaw-0.3.3 → pythonclaw-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pythonclaw"
-version = "0.3.3"
+version = "0.5.0"
 description = "OpenClaw reimagined in pure Python — autonomous AI agent with memory, RAG, skills, web dashboard, and multi-channel support."
 readme = "README.md"
 license = {text = "MIT"}
@@ -12,7 +12,7 @@ requires-python = ">=3.10"
 authors = [
     {name = "Eric Wang", email = "wangchen2007915@gmail.com"},
 ]
-keywords = ["llm", "agent", "ai", "autonomous", "memory", "rag", "skills", "telegram", "chatbot", "framework"]
+keywords = ["llm", "agent", "ai", "autonomous", "memory", "rag", "skills", "telegram", "discord", "whatsapp", "chatbot", "framework"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
@@ -31,6 +31,7 @@ dependencies = [
     "google-generativeai",
     "python-telegram-bot[job-queue]>=20.0",
     "discord.py>=2.3",
+    "pywa[fastapi]>=2.8",
     "apscheduler>=3.10",
     "pyyaml>=6.0",
     "fastapi>=0.100",
@@ -58,6 +59,7 @@ include = ["pythonclaw*"]
 [tool.setuptools.package-data]
 pythonclaw = [
     "templates/**/*.py",
+    "templates/**/*.sh",
     "templates/**/*.yaml",
     "templates/**/*.md",
     "web/static/**/*",
@@ -65,3 +67,15 @@ pythonclaw = [
 
 [tool.setuptools.exclude-package-data]
 "*" = ["__pycache__", "*.pyc", "*.pyo"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]

{pythonclaw-0.3.3 → pythonclaw-0.5.0}/pythonclaw/__init__.py

@@ -6,7 +6,7 @@ from .core.llm.base import LLMProvider
 from .core.llm.openai_compatible import OpenAICompatibleProvider
 from .init import init
 
-__version__ = "0.3.3"
+__version__ = "0.5.0"
 __all__ = [
     "Agent",
     "LLMProvider",

{pythonclaw-0.3.3 → pythonclaw-0.5.0}/pythonclaw/channels/discord_bot.py

@@ -183,9 +183,16 @@ class DiscordBot:
     async def _handle_chat(self, message: discord.Message, content: str, is_dm: bool) -> None:
         sid = self._session_id(message.author.id if is_dm else message.channel.id, is_dm)
         agent = self._sm.get_or_create(sid)
+
+        if self._sm.is_locked(sid):
+            await message.reply("Processing previous message…")
+
         async with message.channel.typing():
             try:
-                response = agent.chat(content)
+                async with self._sm.acquire(sid):
+                    import asyncio
+                    loop = asyncio.get_event_loop()
+                    response = await loop.run_in_executor(None, agent.chat, content)
             except Exception as exc:
                 logger.exception("[Discord] Agent.chat() raised an exception")
                 response = f"Sorry, something went wrong: {exc}"

{pythonclaw-0.3.3 → pythonclaw-0.5.0}/pythonclaw/channels/telegram_bot.py

@@ -23,10 +23,11 @@ IDs to restrict access.  Leave empty (or unset) to allow all users.
 
 from __future__ import annotations
 
+import asyncio
 import logging
 from typing import TYPE_CHECKING
 
-from telegram import Update
+from telegram import BotCommand, ReactionTypeEmoji, Update
 from telegram.ext import (
     Application,
     CommandHandler,
@@ -158,17 +159,61 @@ class TelegramBot:
             return
         sid = self._session_id(update.effective_chat.id)
         agent = self._sm.get_or_create(sid)
-        await update.message.chat.send_action("typing")
+
+        if self._sm.is_locked(sid):
+            await update.message.reply_text("⏳ Processing previous message…")
+
+        # React to the message so the user knows the bot saw it
+        try:
+            await update.message.set_reaction([ReactionTypeEmoji("👀")])
+        except Exception:
+            pass  # reaction API may fail on older bot API or in groups
+
+        # Keep "typing…" visible for the entire duration of processing.
+        # Telegram's typing indicator expires after ~5 s, so we resend it
+        # on a loop until the agent finishes.
+        typing_task = asyncio.create_task(
+            self._keep_typing(update.message.chat_id)
+        )
         try:
-            response = agent.chat(user_text)
+            async with self._sm.acquire(sid):
+                loop = asyncio.get_event_loop()
+                response = await loop.run_in_executor(None, agent.chat, user_text)
         except Exception as exc:
             logger.exception("[Telegram] Agent.chat() raised an exception")
             response = f"Sorry, something went wrong: {exc}"
+        finally:
+            typing_task.cancel()
+
+        # Clear the "seen" reaction once we reply
+        try:
+            await update.message.set_reaction([])
+        except Exception:
+            pass
+
         for chunk in _split_message(response or "(no response)"):
             await update.message.reply_text(chunk)
 
+    async def _keep_typing(self, chat_id: int) -> None:
+        """Re-send the 'typing' chat action every 4 s until cancelled."""
+        try:
+            while True:
+                await self._app.bot.send_chat_action(chat_id=chat_id, action="typing")
+                await asyncio.sleep(4)
+        except asyncio.CancelledError:
+            pass
+        except Exception:
+            logger.debug("[Telegram] _keep_typing stopped unexpectedly", exc_info=True)
+
     # ── Lifecycle ─────────────────────────────────────────────────────────────
 
+    _BOT_COMMANDS = [
+        BotCommand("start", "Show welcome message"),
+        BotCommand("reset", "Start a fresh session"),
+        BotCommand("status", "Show session info"),
+        BotCommand("compact", "Compact conversation history"),
+    ]
+
     def build_application(self) -> Application:
         app = Application.builder().token(self._token).build()
         app.add_handler(CommandHandler("start", self._cmd_start))
@@ -179,10 +224,19 @@ class TelegramBot:
         self._app = app
         return app
 
+    async def _register_commands(self) -> None:
+        """Register slash-commands with Telegram so they appear in the menu."""
+        try:
+            await self._app.bot.set_my_commands(self._BOT_COMMANDS)
+            logger.info("[Telegram] Registered %d bot commands", len(self._BOT_COMMANDS))
+        except Exception:
+            logger.warning("[Telegram] Failed to register bot commands", exc_info=True)
+
     def run_polling(self) -> None:
         """Blocking call — starts the bot using long polling (for standalone use)."""
         app = self.build_application()
         logger.info("[Telegram] Starting bot (polling mode)...")
+        app.post_init = lambda _app: self._register_commands()
         app.run_polling(drop_pending_updates=True)
 
     async def start_async(self) -> None:
@@ -191,6 +245,7 @@ class TelegramBot:
         logger.info("[Telegram] Initialising bot (async mode)...")
         await app.initialize()
         await app.start()
+        await self._register_commands()
         await app.updater.start_polling(drop_pending_updates=True)
 
     async def stop_async(self) -> None: