Metadata-Version: 2.4
Name: skatebot
Version: 0.1.0
Summary: 🛼 A thin launcher for agent bots on chat channels
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.31

# skate 🛼

Launch an AI-agent bot on a chat channel by answering three questions:

| | choices |
|---|---|
| **agent** | **Claude Code** (MVP) · Codex · Gemini · GitHub Copilot |
| **channel** | **Telegram** (MVP) · Slack · Discord *(later)* |
| **compute** | **Existing VPS / Hetzner** (MVP) · provisioned AWS/GCP/Fly *(later)* |

skate is a thin **launcher**, not a framework. It deploys a small long-poll
**gateway** that bridges the channel to the agent's headless CLI, runs it under
systemd, and gets out of the way. Architecture reverse-engineered from openClaw &
Hermes — see [`PLAN.md`](PLAN.md).

## How it works

```
operator machine                         target VPS (systemd service)
  skate up  ──SSH/rsync──▶  agent CLI (claude) + OAuth creds
                            gateway daemon  ── long-poll ──▶ api.telegram.org
                              ├─ allowlist gate (numeric user IDs)
                              ├─ per-chat session (sqlite + claude --resume)
                              └─ each turn: claude -p --output-format json
```

Long-polling means **no public URL, no inbound ports, no TLS** — the bot dials out,
so it runs on any box with outbound HTTPS.

## Quick start (MVP: Claude Code + Telegram + existing VPS)

1. Create a bot with [@BotFather](https://t.me/BotFather) → `/newbot` → copy the token.
2. Get your numeric user ID from [@userinfobot](https://t.me/userinfobot).
3. Deploy:

```bash
pip install -e .
skate up \
  --name yann-bot \
  --agent claude --auth oauth \
  --host <vps-ip> --ssh-key ~/.ssh/id_ed25519 \
  --allow 8581449495 \
  --save specs/yann-bot.json
# (prompts for the BotFather token; or pass --token / $TELEGRAM_BOT_TOKEN)
```

Then message your bot. Manage it:

```bash
skate status --spec specs/yann-bot.json
skate logs   --spec specs/yann-bot.json
skate down   --spec specs/yann-bot.json
```

### Test the gateway locally (no VPS)

```bash
skate run-local --spec specs/yann-bot.json --token <bot-token>
```

## Auth (OAuth, MVP)

For Claude Code the launcher copies your local `~/.claude/.credentials.json` to the
target (so the box you run `skate up` from must be logged in: `claude setup-token`).
API-key auth (`--auth api-key`) is planned.

## Bot commands

`/start` · `/help` · `/new` (reset conversation) · `/status`. Anything else is sent
to the agent.

## Status

MVP scaffold. Working: spec model, Telegram long-poll gateway, Claude Code adapter,
existing-VPS deploy (rsync + systemd), local run. Planned: codex/gemini/copilot
adapters, Hetzner/AWS/GCP/Fly provisioning, Slack/Discord channels, voice/image.
