Pi Telegram Bot

A production-ready Telegram bot powered by the pi coding agent, following the official pi-mono architecture.

Features

• Full pi integration: Uses @mariozechner/pi-coding-agent package for agent functionality
• Session persistence: Conversations are saved and resumed across restarts
• Tools available: bash, read, write, edit
• Per-chat isolation: Each Telegram chat has its own workspace and context
• Memory system: Bot can remember things across sessions via MEMORY.md
• Health checks: HTTP endpoints for monitoring
• Structured logging: JSON logs with configurable levels
• Docker support: Easy deployment with Docker Compose

Prerequisites

• Node.js 18+
• Bun (recommended) or npm
• Telegram Bot Token (from @BotFather)
• OpenAI OAuth via pi CLI

Installation

Option 1: npm (for use as a library)

npm install pi-telegram-bot

Option 2: Clone and run locally

1. Clone the repository:

git clone https://github.com/queuephil/pi-telegram-bot.git
cd pi-telegram-bot

2. Install dependencies:

bun install

3. Set up environment variables:

cp .env.example .env
# Edit .env with your credentials

4. Get Telegram Bot Token:

   • Message @BotFather on Telegram
   • Send /newbot and follow instructions
   • Copy the bot token to your .env file

5. Get your Telegram User ID:

   • Message @userinfobot on Telegram
   • Copy your user ID to ALLOWED_USERS in .env

6. Set up OpenAI OAuth:

   # Run pi CLI and login
   pi
   /login
   # Select OpenAI and follow browser instructions
      
   # Then copy the auth.json
   mkdir -p ~/.pi/telegram-bot
   cp ~/.pi/agent/auth.json ~/.pi/telegram-bot/auth.json

Usage

Development mode (with auto-restart):

bun run dev

Production mode:

bun run build
bun start

Using Docker:

# Build and run with Docker Compose
docker-compose up -d

# Or build manually
docker build -t pi-telegram-bot .
docker run -d --env-file .env -v $(pwd)/data:/app/data pi-telegram-bot

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | TELEGRAM_BOT_TOKEN | Required Bot token from @BotFather | - | | ALLOWED_USERS | Comma-separated list of allowed user IDs | (empty = allow all) | | WORKING_DIR | Directory for chat data | ./data | | PI_PROVIDER | AI provider (currently only openai supported) | openai | | PI_MODEL | Model to use | gpt-5.1-codex-mini | | LOG_LEVEL | Log level: trace, debug, info, warn, error | info | | HEALTH_CHECK_PORT | Health check server port | 3000 | | NODE_ENV | Environment: development, production, test | development |

Bot Commands

• /start - Show welcome message
• /new - Clear session and start fresh conversation
• /help - Show available commands

Workspace Structure

Each chat gets its own directory:

data/
└── <chat_id>/
    ├── MEMORY.md          # Persistent memory
    ├── context.jsonl      # Conversation history
    └── files/             # Working files

Health Checks

The bot exposes health check endpoints for monitoring:

• GET /health - Returns 200 when healthy, 503 when unhealthy
• GET /ready - Returns 200 when ready to receive traffic

Development

Available Scripts

# Run tests
bun test

# Run tests with coverage
bun run test:coverage

# Lint code
bun run lint

# Fix linting issues
bun run lint:fix

# Format code
bun run format

# Type check
bun run typecheck

# Clean build files
bun run clean

Architecture

This bot follows the same architecture as the official mom (Slack bot) package:

1. AgentRunner: Manages the pi agent session per chat
2. SessionManager: Persists conversation context to context.jsonl
3. Tools: bash, read, write, edit (same as pi CLI)
4. Event system: Subscribes to agent events for real-time updates

The bot maintains conversation state using the same @mariozechner/pi-coding-agent package that powers the official pi CLI.

Security Notes

• The bot runs bash commands on the host machine - use with caution
• Each chat has isolated workspace (no cross-chat access)
• Use ALLOWED_USERS to restrict access to specific users
• Review what files/commands the bot has access to

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Run tests and linting (bun test && bun run lint)
4. Commit your changes (git commit -m 'Add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

License

MIT