Lightweight Telegram bot for persistent AI conversations using Pi coding agent.
A minimalist alternative to OpenClaw - use your Claude Pro/Max or ChatGPT Plus subscription directly in Telegram, no API costs.
- Persistent Sessions - Conversations are saved and auto-compacted
- Workspace Navigation - Change directories with
/cd, run shell commands with/shell - Session Management - Archive, switch, and clean up old sessions
- File Attachments - Automatically sends files created by Pi (PDF, images, documents)
- Rate Limiting - Prevents message spam (configurable cooldown)
- Access Control - Optional allowlist for authorized users
- Typing Indicators - Shows activity while AI is processing
Mini-Claw follows a layered architecture with clean separation between the Telegram bot layer, core services, Pi agent integration, and storage.
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Telegram │────►│ Mini-Claw │────►│ Pi Agent │
│ (User) │◄────│ (Bot) │◄────│ (Session) │
└─────────────┘ └─────────────┘ └─────────────┘
│
▼
~/.mini-claw/
└── sessions/
└── telegram-<chat_id>.jsonl
📚 Full Architecture Documentation - Comprehensive docs with detailed diagrams, data flows, and component descriptions.
Key Features:
- Per-chat isolation - AsyncLock prevents concurrent Pi executions
- Activity streaming - Real-time status updates (reading, writing, running)
- File detection - Auto-sends created files (images, PDFs, documents)
- Session management - Archive, switch, title generation, cleanup
- Node.js 22+
- pnpm
- Pi coding agent installed globally
# Clone and install git clone https://github.com/yourusername/mini-claw cd mini-claw pnpm install # Login to AI provider (Claude or ChatGPT) pi /login # Configure bot token cp .env.example .env # Edit .env with your TELEGRAM_BOT_TOKEN # Start the bot pnpm start
make install # Install dependencies make login # Authenticate with AI provider make dev # Development mode (watch) make start # Production mode make test # Run tests
| Command | Description |
|---|---|
/start |
Welcome message |
/help |
Show all commands |
/pwd |
Show current working directory |
/cd <path> |
Change working directory |
/home |
Go to home directory |
/shell <cmd> |
Run shell command directly |
/session |
List and manage sessions |
/new |
Start fresh session (archives old) |
/status |
Show bot status |
# Required TELEGRAM_BOT_TOKEN=your_bot_token # Optional MINI_CLAW_WORKSPACE=/path/to/workspace # Default: ~/mini-claw-workspace MINI_CLAW_SESSION_DIR=~/.mini-claw/sessions PI_THINKING_LEVEL=low # low | medium | high ALLOWED_USERS=123456,789012 # Comma-separated user IDs # Rate limiting & timeouts (milliseconds) RATE_LIMIT_COOLDOWN_MS=5000 # Default: 5 seconds PI_TIMEOUT_MS=300000 # Default: 5 minutes SHELL_TIMEOUT_MS=60000 # Default: 60 seconds # Web search (optional) BRAVE_API_KEY=your_brave_api_key # For Pi web search skill
make install-service
systemctl --user start mini-claw
systemctl --user enable mini-clawpnpm build pm2 start dist/index.js --name mini-claw pm2 save
tmux new -s mini-claw
pnpm start
# Ctrl+B, D to detach# Run in watch mode pnpm dev # Type checking pnpm typecheck # Run tests pnpm test # Run tests with coverage pnpm test:coverage
| Module | Coverage |
|---|---|
| config.ts | 100% |
| sessions.ts | 100% |
| workspace.ts | 100% |
| pi-runner.ts | 100% |
- Runtime: Node.js 22+, TypeScript
- Telegram: grammY
- AI: Pi coding agent
- Testing: Vitest
pi /login
Check for running Pi processes:
ps aux | grep piMIT