projects/pi-telegram-247/README.md

# Pi 24/7 Telegram Agent on Render

Running Pi coding agent as a background service with Telegram interface.

## Architecture

```
Render Free Tier (ephemeral)
├── Pi (headless RPC mode, --no-session)
│   └── pi-telegram-connect extension
├── Telegram Bot (via extension)
└── No persistent storage
```

**Note:** Render free tier has no persistent storage. Sessions reset on restart. 
This is fine for a 24/7 agent - it keeps general context in the system prompt, 
not session history.

## Prerequisites

1. **Render Account** - https://render.com
2. **Telegram Bot Token** - From @BotFather
3. **Pi API Key** - From your LLM provider (Anthropic/OpenAI)
4. **GitHub Repo** - To deploy from

## Quick Deploy

### 1. Fork/Clone This Repo

```bash
git clone https://github.com/yourusername/pi-telegram-247.git
cd pi-telegram-247
```

### 2. Set Environment Variables in Render

| Variable | Description |
|----------|-------------|
| `TELEGRAM_BOT_TOKEN` | Bot token from @BotFather |
| `ANTHROPIC_API_KEY` | Or OPENAI_API_KEY |
| `PI_PROVIDER` | `anthropic` or `openai` |
| `PI_MODEL` | e.g., `claude-sonnet-4-20250514` |

### 3. Deploy to Render

1. Connect GitHub repo
2. Select **Background Worker** type
3. Use `render.yaml` for auto-config
4. Deploy

## Local Development

```bash
# Install dependencies
./scripts/setup.sh

# Configure
cp .env.example .env
# Edit .env with your keys

# Run
./scripts/run.sh
```

## How It Works

Pi runs in **RPC mode** (headless) with the `pi-telegram-connect` extension:

1. Pi starts with `pi --mode rpc`
2. Extension connects to Telegram via long polling
3. Messages flow: Telegram → Extension → Pi → Response → Telegram
4. Session persists in `/data/pi-sessions/`

## Telegram Commands

- `/start` - Show help
- `/new` - New session
- `/stop` - Abort current turn
- `/status` - Show bot status

## SCRAPER TODO

- [ ] Channel scraper using Telethon
- [ ] AI-ready JSON output
- [ ] Resume capability
- [ ] Media download support

## References

- [Pi RPC Mode](https://pi.dev/docs/latest/rpc)
- [pi-telegram-connect](https://github.com/artyom-ivanov/pi-telegram-connect)
- [Pi Extensions](https://pi.dev/packages)
- [Render Background Workers](https://render.com/docs/background-workers)