# Telethryve First Run

This is the shortest path from zero to a working Telegram-connected bridge.

Use only an authorized Telethryve source release. By installing or using this
source tree, you agree to [USER_AGREEMENT.md](../USER_AGREEMENT.md) and
[LICENSE](../LICENSE). Do not mirror or redistribute the source code.

## Part 1: Create Your Telegram Bot Token

1. Open the Telegram app.
2. Search for `BotFather`.
3. Open the verified `@BotFather` chat.
4. Send `/start`.
5. Send `/newbot`.
6. When BotFather asks for a bot name, type any name you want.
7. When BotFather asks for a username, type a username that ends in `bot`.
8. BotFather will send you a bot token.
9. Copy that token.

The token looks something like this:

```text
1234567890:AAExampleTokenGoesHere
```

Do not share it.

## Part 2: Put The Token In `.env`

1. Open the Telethryve folder.
2. Open the `.env` file.
3. Find this line:

```text
TELEGRAM_BOT_TOKEN=
```

4. Paste your token after the `=`.
5. Save the file.

Example:

```text
TELEGRAM_BOT_TOKEN=1234567890:AAExampleTokenGoesHere
```

If you want long coding tasks to keep running without the bridge stopping them after a few minutes, also set:

```text
TELETHRYVE_COMMAND_TIMEOUT=0
```

Use `3600` instead if you want a one-hour cap.

## macOS: Ultra Simple Setup

1. Open Terminal.
2. Go into the Telethryve folder:

```bash
cd /path/to/telethryve
```

3. Run setup:

```bash
./setup.sh
```

The first setup run will ask you to type `I AGREE` to confirm the source-use terms.

This now also attempts to install optional voice-stack dependencies (`Phonebot`, local `.speaches`, `Vocodex` relay, and Playwright Chromium) when those sibling workspaces are present.
If `Phonebot`/`Vocodex` are not available on Git for the target machine, include bundled copies in `vendor/Phonebot*` and `vendor/Vocodex*` before running setup.

4. Open `.env`:

```bash
./edit_config.command
```

5. Paste your Telegram token into:

```text
TELEGRAM_BOT_TOKEN=
```

6. Save the file.
7. Start the bridge:

```bash
.venv/bin/python telethryve_bridge.py
```

8. Open Telegram.
9. Find your bot by the username you created.
10. Send it a message like:

```text
what's the status
```

If you want the bot to drive local apps later, send:

```text
enable app control
```

On macOS, you may also need to grant Accessibility and Automation to Terminal, iTerm, or Codex in System Settings > Privacy & Security.

When you come back to a named coding project later, say something like `pick up where we left off on the Telethryve project`. Telethryve will prefer that chat's remembered project thread before starting fresh.

## Windows: Ultra Simple Setup

1. Open the Telethryve folder in File Explorer.
2. Double-click `setup.bat`.
3. Type `I AGREE` when setup asks you to accept the source-use terms.
4. Wait for setup to finish.
5. Double-click `edit_config.bat`.
6. Find this line in `.env`:

```text
TELEGRAM_BOT_TOKEN=
```

7. Paste your token after the `=`.
8. Save the file.
9. Double-click `run.bat`.
10. Open Telegram.
11. Find your bot by the username you created.
12. Send it a message like:

```text
what's the status
```

If you want the bot to drive local apps later, send:

```text
enable app control
```

On macOS, you may also need to grant Accessibility and Automation to Terminal, iTerm, or Codex in System Settings > Privacy & Security.

## If It Does Not Work

Check these first:

1. Make sure the bot token is pasted into `.env` with no extra spaces.
2. Make sure you saved `.env`.
3. Make sure `run.bat` or `telethryve_bridge.py` is still running.
4. Make sure the `codex` CLI is installed.

To install Codex CLI:

```bash
npm install -g @openai/codex
codex --version
```