Skip to content

Commit d451c09

Browse files
codeaholicguycodeaholicguy
committed
docs: add channel command
1 parent 787962f commit d451c09

1 file changed

Lines changed: 177 additions & 0 deletions

File tree

‎web/content/docs/12-channel.md‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
---
2+
title: Channel
3+
description: Connect AI agents with messaging channels like Telegram for remote interaction
4+
slug: channel
5+
order: 13
6+
---
7+
8+
> ⚠️ **WARNING**
9+
> This feature is currently **experimental**, works on macOS and Linux with ai-devkit from version 0.22.1. Behaviors and commands may change in future versions.
10+
11+
The `channel` command lets you bridge a running AI agent to a messaging platform like Telegram. Once connected, you can send prompts to your agent and receive responses directly from your messaging app — no need to be at your terminal.
12+
13+
## Prerequisites
14+
15+
- **AI DevKit** installed globally (see [Getting Started](/docs/1-getting-started))
16+
- **A running AI agent** (Claude Code or Codex) detected by AI DevKit (see [Agent Management](/docs/8-agent-management))
17+
- **A Telegram bot token** from [@BotFather](https://t.me/BotFather)
18+
- **Terminal environment**: The agent must be running in **tmux**, **iTerm2**, or **Apple Terminal** (same requirements as `agent open`)
19+
20+
## How It Works
21+
22+
The channel bridge connects two sides:
23+
24+
1. **Input**: Messages you send to your Telegram bot are forwarded to the agent's terminal as keystrokes.
25+
2. **Output**: New messages in the agent's conversation are polled and sent back to your Telegram chat.
26+
27+
The first Telegram user to message the bot is automatically authorized. All other users are rejected. This means:
28+
- Only **one person** can control the agent per bridge session.
29+
- If you restart the bridge, the first user to message again becomes the authorized user.
30+
- There is no password or additional authentication — anyone who knows your bot's username can attempt to message it, but only the first user's messages are forwarded.
31+
32+
> **Tip**: Keep your bot username private, or use Telegram's bot settings to restrict who can find and message your bot.
33+
34+
## Commands
35+
36+
### Connect a Channel
37+
38+
Configure a messaging channel by providing your bot token.
39+
40+
```bash
41+
ai-devkit channel connect telegram
42+
```
43+
44+
You will be prompted to enter your Telegram bot token. AI DevKit validates the token by calling the Telegram API, then stores the configuration locally.
45+
46+
> **Note**: Channel configuration is stored in `~/.ai-devkit/config.json`. The bot token is saved in plaintext — do not commit this file to version control.
47+
48+
If a Telegram channel is already configured, you will be asked whether to overwrite it.
49+
50+
### List Channels
51+
52+
Show all configured channels and their status.
53+
54+
```bash
55+
ai-devkit channel list
56+
```
57+
58+
**Table output includes:**
59+
60+
| Name | Type | Status | Bot | Created |
61+
|------|------|--------|-----|---------|
62+
| `telegram` | `telegram` | enabled | `@my_bot` | 4/21/2026 |
63+
64+
### Start the Bridge
65+
66+
Start the channel bridge between Telegram and a running agent.
67+
68+
```bash
69+
ai-devkit channel start --agent <name>
70+
```
71+
72+
**Options:**
73+
74+
| Option | Description |
75+
|--------|-------------|
76+
| `--agent <name>` | **(Required)** Name of the running agent to bridge |
77+
| `--debug` | Enable debug logging for troubleshooting |
78+
79+
Debug output is printed to the same terminal where the bridge is running. It includes timestamps for message polling, Telegram delivery, and terminal writes. Look for lines prefixed with `channel` to trace message flow.
80+
81+
Once started, send a message to your Telegram bot to begin interacting with the agent. Press `Ctrl+C` to stop the bridge.
82+
83+
**Example:**
84+
85+
```bash
86+
ai-devkit channel start --agent my-project
87+
```
88+
89+
```
90+
✔ Bridge started: Telegram @my_bot <-> Agent "my-project" (PID: 12345)
91+
ℹ Send a message to your Telegram bot to start chatting.
92+
ℹ Press Ctrl+C to stop.
93+
```
94+
95+
### Show Channel Status
96+
97+
Display details about configured channels.
98+
99+
```bash
100+
ai-devkit channel status
101+
```
102+
103+
**Example output:**
104+
105+
```
106+
telegram (telegram)
107+
Enabled: yes
108+
Bot: @my_bot
109+
Configured: 2026-04-21T10:30:00.000Z
110+
```
111+
112+
> **Note**: `channel list` shows a summary table of all channels. `channel status` shows detailed configuration for each channel.
113+
114+
### Disconnect a Channel
115+
116+
Remove a channel configuration.
117+
118+
```bash
119+
ai-devkit channel disconnect telegram
120+
```
121+
122+
You will be asked to confirm before the configuration is removed.
123+
124+
## Walkthrough
125+
126+
Here is a step-by-step guide to set up a Telegram bridge. For full option details on each command, see [Commands](#commands) above.
127+
128+
1. **Create a Telegram bot**
129+
- Open Telegram and search for **@BotFather**
130+
- Send `/newbot` and follow the prompts to get a bot token
131+
- The token looks like `123456789:ABCdefGhIJKlmNoPQRsTUVwxyz` (a number, colon, then a hash). Copy the **entire string** including the colon.
132+
133+
2. **Connect the channel**
134+
```bash
135+
ai-devkit channel connect telegram
136+
```
137+
Paste your bot token when prompted.
138+
139+
3. **Start an AI agent** (if not already running)
140+
```bash
141+
claude # or codex
142+
```
143+
The agent name is derived from your working directory (e.g., running `claude` in `~/code/my-project` creates an agent named `my-project`). Verify with:
144+
```bash
145+
ai-devkit agent list
146+
```
147+
148+
4. **Start the bridge**
149+
```bash
150+
ai-devkit channel start --agent my-project
151+
```
152+
153+
5. **Chat from Telegram**
154+
Open your bot in Telegram and send a message (e.g., "What files are in this project?"). You should see:
155+
- A typing indicator while the agent processes your message
156+
- The agent's response appearing as a Telegram message from your bot
157+
158+
If nothing appears after 30 seconds, check the [Troubleshooting](#troubleshooting) section below.
159+
160+
## Troubleshooting
161+
162+
### "No running agents detected"
163+
Ensure your AI agent (e.g., `claude`) is running. Use `ai-devkit agent list` to verify.
164+
165+
### "Cannot find terminal for agent"
166+
The agent must be running in a supported terminal (tmux, iTerm2, or Apple Terminal). VS Code terminal is not supported for external control. See [Agent Management — Troubleshooting](/docs/8-agent-management#troubleshooting) for more details.
167+
168+
### "No Telegram channel configured"
169+
Run `ai-devkit channel connect telegram` first to set up your bot token.
170+
171+
### Agent process exits while bridge is running
172+
The bridge continues running but stops receiving new agent responses. You will not see an error — messages from Telegram are still sent to the terminal, but there is no agent to process them. Stop the bridge with `Ctrl+C` and restart after relaunching your agent.
173+
174+
### Messages not appearing in Telegram
175+
- Ensure you are the first user to message the bot (only the first user is authorized).
176+
- Check that the agent has a session file by running `ai-devkit agent detail --id <name>`.
177+
- Use `--debug` flag when starting the bridge to see detailed logs.

0 commit comments

Comments
 (0)