Metadata-Version: 2.4
Name: codecast
Version: 0.2.17
Summary: Bot-based system to interact with Claude CLI on remote machines
Author: Chivier Humber
License-Expression: MIT
Project-URL: Homepage, https://github.com/Chivier/codecast
Project-URL: Repository, https://github.com/Chivier/codecast
Project-URL: Issues, https://github.com/Chivier/codecast/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pyyaml>=6.0
Requires-Dist: ruamel.yaml>=0.18.0
Requires-Dist: asyncssh>=2.14.0
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: discord.py>=2.3.0
Requires-Dist: python-telegram-bot>=20.0
Requires-Dist: textual>=0.50.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: aiohttp-jinja2>=1.6
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.21; extra == "test"
Provides-Extra: lark
Requires-Dist: lark-oapi>=1.4.0; extra == "lark"

<p align="center">
  <img src="docs/images/logo.png" alt="Codecast" width="200">
</p>

<h1 align="center">Codecast</h1>

<p align="center">
  Control Claude CLI on remote machines from Discord & Telegram
</p>

<p align="center">
  <a href="https://pypi.org/project/codecast/"><img src="https://img.shields.io/pypi/v/codecast" alt="PyPI"></a>
  <a href="https://github.com/Chivier/codecast/actions"><img src="https://github.com/Chivier/codecast/actions/workflows/lint.yml/badge.svg" alt="CI"></a>
  <a href="https://github.com/Chivier/codecast/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Chivier/codecast" alt="License"></a>
  <img src="https://img.shields.io/pypi/pyversions/codecast" alt="Python">
</p>

---

Send a message in Discord or Telegram. It reaches Claude CLI on your GPU server, your cloud VM, or any machine with SSH access — and streams the response back in real time.

## Why Codecast?

| Problem | Solution |
|---------|----------|
| Claude CLI only runs locally | Run it on any remote machine via SSH |
| Lose context when you close the terminal | Sessions persist — detach and resume anytime |
| Can't use Claude on mobile | Chat through Discord or Telegram from any device |
| Managing multiple dev machines is tedious | One bot, many machines — switch with a command |

## Architecture

<p align="center">
  <img src="docs/images/framework.svg" alt="Codecast Architecture" width="600">
</p>

## Quick Start

**Prerequisites:** Python 3.11+, [Rust/cargo](https://rustup.rs/), SSH access to a remote machine with Claude CLI installed.

```bash
pip install codecast
```

**Configure:**

```bash
cp config.example.yaml ~/.codecast/config.yaml
$EDITOR ~/.codecast/config.yaml   # add machines + bot token
```

**Run:**

```bash
codecast
```

Then open Discord or Telegram and type `/start my-server ~/projects/myapp`.

## Key Features

- **Persistent sessions** — Claude CLI runs as a long-lived process; context survives across messages
- **SSH tunnels** — daemon binds to localhost only, never exposed to the internet
- **Detach & resume** — `/exit` keeps the session alive, `/resume` picks it back up
- **Multiple machines** — connect any number of servers, switch between them
- **Permission modes** — `auto` (full autonomy), `code` (auto-edit files), `plan` (read-only), `ask` (confirm everything)
- **Real-time streaming** — responses stream back via SSE as Claude types
- **Mobile-friendly** — works from any device with Discord or Telegram

## Commands

| Command | What it does |
|---------|-------------|
| `/start <machine> <path>` | Start a new Claude session |
| `/resume <name>` | Resume a detached session |
| `/new` | New session, same directory |
| `/clear` | Fresh context, same directory |
| `/exit` | Detach (process keeps running) |
| `/ls machine` | List machines |
| `/ls session` | List sessions |
| `/mode <auto\|code\|plan\|ask>` | Switch permission mode |
| `/status` | Current session info |
| `/health` | Daemon health check |

See [Commands Reference](./docs/commands-reference.md) for the full list.

## Documentation

| Guide | Description |
|-------|-------------|
| [Getting Started](./docs/getting-started.md) | Installation, first session walkthrough |
| [Adding a Discord Bot](./docs/adding-a-discord-bot.md) | Create a Discord Application step by step |
| [Adding a Telegram Bot](./docs/adding-a-telegram-bot.md) | Create a Telegram bot via BotFather |
| [Adding a Server](./docs/adding-a-server.md) | SSH config, jump hosts, password auth |
| [Commands Reference](./docs/commands-reference.md) | Every command with examples |

## Configuration

Config files are searched in order:
1. CLI argument: `codecast /path/to/config.yaml`
2. `~/.codecast/config.yaml`
3. `./config.yaml` (dev fallback)

## Requirements

- **Python 3.11+** — head node
- **SSH access** — to remote machine(s) with Claude CLI installed
- **Bot token** — Discord and/or Telegram
- **Rust toolchain** (optional) — only needed to build the daemon binary from source

### Building the Daemon (optional)

The head node (Python) installs without Rust. The daemon binary is a separate Rust project that runs on remote machines. If you need to build it from source:

```bash
# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

# Build the daemon
git clone https://github.com/Chivier/codecast.git
cd codecast
cargo build --release
# Binary at: target/release/codecast-daemon
```

> **Note:** On some systems you may also need a C compiler and development headers:
> - **Debian/Ubuntu:** `sudo apt install build-essential pkg-config libssl-dev`
> - **Fedora/RHEL:** `sudo dnf install gcc pkg-config openssl-devel`
> - **macOS:** `xcode-select --install`

### One-line Install (from source)

```bash
curl -fsSL https://raw.githubusercontent.com/Chivier/codecast/main/scripts/install.sh | bash
```

This clones the repo, creates a virtualenv, installs Python dependencies, and optionally builds the daemon if Rust is available.

## License

MIT
