Metadata-Version: 2.4
Name: rudder-agent
Version: 0.1.0
Summary: Mobile control panel for AI agents — control your bots from Telegram
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: python-telegram-bot==21.3
Requires-Dist: anthropic>=0.40.0
Requires-Dist: python-dotenv
Requires-Dist: pyyaml

# Rudder

**Mobile control panel for AI agents.** Control your bots from Telegram — from anywhere, on any device.

> "Rudder puts every developer in the captain's chair of their AI agents."

---

## What is Rudder?

You build AI agents. They run on your machine. But when you're away from your desk, you're flying blind.

Rudder wraps your agent with a Telegram interface so you can:
- **Ask questions** in plain English ("what positions are open?")
- **Approve or deny** tool calls before they execute
- **Run commands** on your machine remotely
- **Check logs** and file contents from your phone

---

## Quick Start

```bash
pip install rudder-agent
rudder init      # guided setup wizard
rudder start     # launch your bot
```

Then open Telegram and message your bot.

---

## What Rudder Can Do

| Command | Example |
|---|---|
| Read files | "show me the last 20 lines of app.log" |
| Run commands | "run my_script" → Approve/Deny on phone |
| List files | "what files are in my project?" |
| Answer questions | "what's the status of my agent?" |

---

## Requirements

- Python 3.10+
- A Telegram account and bot token (free)
- An Anthropic API key ([console.anthropic.com](https://console.anthropic.com))

---

## Setup — Step by Step

### Step 1 — Create a Telegram bot

1. Open Telegram and search for **@BotFather** (official blue checkmark)
2. Send this message: `/newbot`
3. BotFather will ask: **"What's the name of your bot?"**
   - This is the display name shown in chats — e.g. `My Agent Bot`
4. BotFather will ask: **"What username would you like to give it?"**
   - Must end in `bot` — e.g. `myagent_bot` or `MyAgentBot`
   - Must be unique across all of Telegram
5. BotFather will reply with your **bot token** — it looks like:
   ```
   1234567890:AAFabcdefGHIjklmNOPqrstUVwxyz123456
   ```
6. **Copy and save this token** — you'll need it in Step 4

---

### Step 2 — Get your Telegram user ID

Rudder only accepts messages from **you** — it needs your personal user ID to enforce this.

1. Open Telegram and search for **@userinfobot**
2. Send any message (e.g. `/start`)
3. It will reply with your **Id** number — e.g. `123456789`
4. **Copy this number**

---

### Step 3 — Get an Anthropic API key

Rudder uses Claude to understand your messages.

1. Go to [console.anthropic.com](https://console.anthropic.com)
2. Sign up or log in
3. Go to **API Keys** → **Create Key**
4. Copy the key — it starts with `sk-ant-...`

---

### Step 4 — Install and configure Rudder

Open a terminal in the folder where your AI agent project lives, then run:

```bash
pip install rudder-agent
rudder init
```

The wizard will ask for:
- Your **Telegram bot token** (from Step 1)
- Your **Anthropic API key** (from Step 3)
- Your **Telegram user ID** (from Step 2)
- The **path to your working directory** — the folder Rudder should have access to

> **Tip:** Run `rudder init` from inside your project folder. When asked for the working directory, you can just press Enter to use the current folder.

This creates a `rudder.yaml` file in the current folder. Keep this file safe — it contains your API keys.

---

### Step 5 — Start Rudder

```bash
rudder start
```

You should see:
```
Rudder started. Open Telegram and message your bot.
```

---

### Step 6 — Message your bot

Open Telegram, search for your bot by its username (e.g. `@myagent_bot`), and send a message.

Try:
- `hello`
- `what files are in my project?`
- `show me the contents of app.log`

---

## Troubleshooting

**Bot doesn't respond**
- Make sure `rudder start` is running in your terminal
- Check that your bot token in `rudder.yaml` is correct
- Try sending `/start` to your bot first

**"Unauthorized" error**
- Your `allowed_user_id` in `rudder.yaml` doesn't match your actual Telegram ID
- Re-check your ID with @userinfobot

**"Working directory not found" error**
- The `working_dir` path in `rudder.yaml` doesn't exist on your machine
- Update it to a valid folder path

**Bot stops when I close the terminal**
- This is expected — the bot runs in your terminal session
- For always-on usage, set it up as a background service

---

## Security

- Only your Telegram user ID can send commands
- Destructive actions (bash, file writes) require explicit Approve/Deny on your phone
- Your API keys stay on your machine — never sent anywhere else
- Self-hosted: you control everything

---

## Roadmap

- [x] Telegram channel
- [x] Bash, read/write file, list files tools
- [x] Approve/Deny on mobile
- [x] `pip install rudder-agent` — installable package
- [x] `rudder init` setup wizard
- [ ] Discord channel
- [ ] Custom plugin tools
- [ ] `pip install rudder-agent[github]` — GitHub tools

---

## License

MIT
