Metadata-Version: 2.5
Name: tg-harness
Version: 0.1.2
Summary: Tiny authenticated Telegram harness for Telethon workflows
Project-URL: Homepage, https://github.com/speech115/tg
Project-URL: Repository, https://github.com/speech115/tg
Project-URL: Issues, https://github.com/speech115/tg/issues
Author: speech115
License-Expression: MIT
License-File: LICENSE
Keywords: agents,automation,cli,telegram,telethon
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.12
Requires-Dist: telethon==1.44.0
Description-Content-Type: text/markdown

<img src="https://raw.githubusercontent.com/speech115/tg/main/static/banner-ink.svg" alt="tg" width="100%" />

<div align="center">

# tg

**A tiny authenticated Telegram harness for agents and humans.**

One Python process. One authenticated Telegram account per run. The full Telethon surface.

</div>

`tg` keeps the runtime deliberately small: configuration, named sessions,
authentication, locking, and Python process semantics. Telethon remains the Telegram
API.

Telethon is the API; `tg` only provides the authenticated execution boundary.
When a workflow is missing, write the missing logic as ordinary Python and run it
through `tg`.

```text
agent wants something in Telegram
        │
        ▼
      tg
        │
        ├── client.*        friendly Telethon methods
        └── functions.*     raw Telegram API when needed
```

**Three commands plus direct Python execution.**

```bash
tg login
tg doctor
tg skill
tg script.py
```

The Python distribution is `tg-harness`. The installed command is `tg`.

## Give it to your agent

Install from PyPI:

```bash
uv tool install tg-harness
```

Or install the current GitHub version:

```bash
uv tool install git+https://github.com/speech115/tg.git
```

Then give the agent this instruction:

```text
Use tg for Telegram. Run tg doctor first. If the account is not authorized, ask
me to complete tg login. For Telegram work, use one tg program per decision
boundary, prefer Telethon client methods, and fall back to functions.* / types.*
for raw Telegram requests.
```

Requires Python 3.12+ and a POSIX system (macOS or Linux).

## Configure once

Create Telegram API credentials at https://my.telegram.org/apps, then create
`~/.config/tg/config.toml`:

```toml
[telegram]
api_id = 123456
api_hash = "your-api-hash"
```

Alternatively, set `TG_API_ID` and `TG_API_HASH` in the environment.

Set `TG_CONFIG` when the config lives elsewhere.

Authorize the default account:

```bash
tg login
tg doctor
```

The default account is `main`. Named accounts map directly to Telethon session files:

```bash
tg --account work login
tg --account work doctor
tg --account work script.py
```

```text
~/.local/state/tg/
├── main.session
├── work.session
└── another.session
```

Account names must match `[A-Za-z0-9_-]+`.

## Run ordinary Python

For a one-off task:

```bash
tg <<'PY'
dialogs = await client.get_dialogs(limit=10)
for dialog in dialogs:
    print(dialog.name)
PY
```

For reusable logic:

```bash
tg script.py arg1 --flag
tg --account work script.py arg1 --flag
```

Every run gets:

```python
client  # authenticated Telethon client
functions  # raw Telegram request constructors
types  # raw Telegram types
account  # selected named account
```

It also gets normal `__file__`, `sys.argv`, and local-import behavior.

Prefer the friendly API when it fits:

```python
messages = await client.get_messages("me", limit=20)
```

Drop to the raw API when it does not:

```python
result = await client(functions.users.GetFullUserRequest(id=types.InputUserSelf()))
```

## How it works

```text
                            one tg process
                                   │
                     authenticated Telethon client
                                   │
               ┌───────────────────┴───────────────────┐
               │                                       │
          client.* helpers                      raw TL requests
               │                                functions.* / types.*
               └───────────────────┬───────────────────┘
                                   │
                              Telegram API

config      ~/.config/tg/config.toml (or TG_CONFIG)
sessions    ~/.local/state/tg/<account>.session
locking     one process per named session
```

Workflow logic stays in ordinary Python scripts.

## Agent skill

The repository ships `skills/tg/SKILL.md`.

Use `tg skill` to print the bundled instructions. Its main rule is simple: bundle
deterministic operations into one `tg` process and stop only at a real decision
boundary. That avoids reconnecting for every API call and keeps agent behavior
both faster and simpler.

## Trust boundary

`tg` is intentionally **not a sandbox**.

Code passed to it has the permissions of the selected Telegram account and can read,
send, edit, delete, download, join, leave, and perform raw Telegram API operations.

Treat these as secrets:

- `api_hash`
- Telethon `.session` files
- any exported authorization material

The runtime keeps sessions outside the repository and serializes access to each named
session with a lock.

See [CONTRIBUTING.md](CONTRIBUTING.md) for development and integration instructions.

## License

MIT. See [LICENSE](LICENSE).
