# Multi-topic routing

`pi-telegram` can route different Telegram forum topics in one group to different live pi sessions.

## Model

One pi process owns Telegram polling for the bot. Other live pi sessions register as targets. The router sends each group-topic update to the target session bound to that topic.

Private chats continue to use the existing single-session behavior.

## Bind a topic from Telegram

1. In the pi session that should own the topic, run:

   ```text
   /tg-bind-code
   ```

2. Copy the code printed by pi.
3. In the target Telegram topic, send:

   ```text
   /bind CODE
   ```

The topic is now bound to that pi session.

## Bind a topic manually from pi

Run:

```text
/tg-connect-topic <chatId> <threadId>
```

## Local chat broadcast

To mirror local pi prompts and final assistant replies to the bound topic:

```text
/tg-broadcast-on
```

To stop mirroring:

```text
/tg-broadcast-off
```

To check state:

```text
/tg-broadcast-status
```

Telegram-originated turns are not mirrored back to avoid echo loops.

## Status footer

The footer shows connection, role, topic, queue/active state, and broadcast state, for example:

```text
telegram connected · router · topic 15 “Dev” · broadcast off
telegram connected · target · topic 15 · q2 · active · broadcast on
telegram router offline · target · topic 15 saved · broadcast off
```

## Runtime files

Runtime session state is stored in:

```text
~/.pi/agent/pi-telegram-sessions.json
~/.pi/agent/pi-telegram-router/inbox/
```

These files are runtime state and can be deleted when no pi sessions are running.

## Temporary topic broker cleanup

If `~/.pi/agent/extensions/telegram-topic-broker` exists from earlier experiments, disable it before using this feature. It is not part of `pi-telegram-group-topic`.