Agent Connect

中文文档 Русская документация

Control Claude Code or Codex sessions remotely via Telegram. Agent Connect keeps the agent process in a local tmux window, reads its output, and sends keystrokes back to that same terminal session.

Features

• Topic-based sessions: one Telegram Forum topic maps to one tmux window.
• Multi-bot configuration stored in SQLite with a React management console.
• Claude Code and Codex support, including hook-based session tracking.
• Telegram notifications for final answers by default, with optional intermediate tool/status messages.
• Directory browser, session resume, history, screenshots, and slash command forwarding.
• Markdown to Telegram HTML formatting through the workspace @yc-tech/telegramify-markdown package.

Requirements

• Node.js 22+
• pnpm 10.6.3+ (only for monorepo development; not needed for npm i -g)
• tmux
• Claude Code (claude) and/or Codex (codex) available in PATH

Quick Start (npm install)

If you just ran npm i -g @yc-tech/agent-connect-cli, work through these steps in order. Hand this section to your Claude / Codex if you want them to walk you through it.

1. Create the Telegram bot

1. Open @BotFather, /newbot, follow the prompts — copy the token it returns (1234567890:AB...).
2. Important: open the bot's mini-app via BotFather's profile → Settings → Bot Settings → Threaded Mode → Enable. Without this, topic creation silently fails later.

2. Set env vars

mkdir -p ~/.agent-connect
cat >> ~/.agent-connect/.env <<EOF
TELEGRAM_BOT_TOKEN=<paste your token>
TELEGRAM_ALLOWED_USERS=<your numeric Telegram id>
EOF
chmod 600 ~/.agent-connect/.env

Get your numeric Telegram ID by DM'ing @userinfobot. Multiple IDs: comma-separated, no spaces. Without TELEGRAM_ALLOWED_USERS, anyone who finds the bot can talk to it.

3. Start the daemon + install hooks

agc start --daemon       # spawns detached supervisor + server
agc status               # should print "live healthz: 200 ✓"
agc hook --install       # wires Claude Code + Codex hooks

If agc status reports live healthz: ✗:

• Port clash: lsof -i :17666 — pick another with AGENT_CONNECT_HTTP_PORT=17777 in .env, then agc stop && agc start --daemon.
• Missing token: re-check ~/.agent-connect/.env (the var name must be exactly TELEGRAM_BOT_TOKEN).
• Crash: agc logs and scroll back.

4. Create the Telegram group + first message

1. In Telegram → New Group → add the bot → enable Topics in group settings → promote the bot to admin with "Manage Topics" permission.
2. Create a topic (any name), send any message (e.g. hi).
3. The bot replies with a directory browser. Pick a directory → it launches a tmux window + Claude/Codex session there.
4. Subsequent messages in the topic route to that agent; its output (status spinner, intermediate work, final answer) streams back.

Common gotchas

Symptom	Cause	Fix
Bot ignores your message	Your user id isn't in TELEGRAM_ALLOWED_USERS	DM @userinfobot to check
Directory browser appears but picking nothing happens	Bot is not group admin	Group settings → promote bot
Topic stays "New Topic" forever	Bot lacks "Manage Topics" admin permission	Same — admin + Manage Topics
Claude/Codex runs but Telegram shows no Thinking…	Hook didn't fire because agc isn't on the agent process's PATH	Restart Claude / Codex; if persistent, AGENT_CONNECT_HOOK_COMMAND=/absolute/path/to/agc agc hook --install
agc status says unreachable after restart	Daemon crashed; agc logs last ~50 lines

Useful commands once it's running

agc status                  # uptime / restart count / healthz
agc logs                    # tail today's log
agc restart                 # reload server code (supervisor stays up)
agc stop                    # graceful shutdown
agc send /tmp/foo.zip       # send a local file (≤50MB) to the topic
                            # bound to the current tmux window

Web admin console: http://127.0.0.1:17666/ (port matches AGENT_CONNECT_HTTP_PORT). Use it to add a second bot, toggle per-bot settings, or browse active sessions.

Install And Run (monorepo development)

pnpm install
pnpm dev

pnpm dev starts:

• Fastify API and bot service on 127.0.0.1:17666 (override with AGENT_CONNECT_HTTP_PORT)
• React management console on 127.0.0.1:5173

Common commands:

pnpm dev:bot       # bot/API only
pnpm dev:web       # web console only
pnpm start         # run compiled CLI service
pnpm hook:install  # synchronize Claude and Codex hooks
pnpm typecheck
pnpm build
pnpm test:ts

To expose agc globally from this workspace:

pnpm --filter agent-connect build
cd packages/cli
pnpm link --global
agc help

After linking, agc points to the TypeScript CLI.

For npm distribution, publish the workspace packages and install the CLI package:

pnpm -r publish
npm install -g @yc-tech/agent-connect-cli

Daemon Mode

After installing globally, run as a background service supervised with auto-restart on crash + healthz failure:

agc start --daemon     # spawn detached supervisor + server, return immediately
agc status             # uptime, restart count, last healthz probe
agc logs               # tail ~/.agent-connect/logs/current.log
agc restart            # respawn server child (supervisor stays up)
agc stop               # graceful shutdown of supervisor + server

The supervisor lives at PID recorded in ~/.agent-connect/supervisor.json. It polls GET /healthz every 10 s, triggers a restart after 3 consecutive failures, and respawns the server child with exponential backoff (1s/2s/5s/10s/30s) on unexpected exit. agc restart reloads whatever version of the bot is currently on disk — so npm install -g @yc-tech/agent-connect-cli@latest && agc restart upgrades cleanly without manual stop/start.

The web console is served by the bot itself at http://127.0.0.1:17666/ when running in daemon mode (or any production-built bot). During pnpm dev, the Vite dev server on :5173 keeps hot reload.

Telegram Setup

1. Chat with @BotFather to create a bot and get the bot token.
2. Open @BotFather's profile page and launch the mini app.
3. Select your bot, then go to Settings > Bot Settings.
4. Enable Threaded Mode.
5. Start pnpm dev, open http://127.0.0.1:5173, and add the bot config.

ALLOWED_USERS expects Telegram numeric user IDs, not phone numbers.

Configuration

The runtime loads .env from the repo root and $AGENT_CONNECT_DIR/.env.

Variable	Default	Description
AGENT_CONNECT_DIR	~/.agent-connect	Config/state directory
AGENT_CONNECT_DB_FILE	$AGENT_CONNECT_DIR/agent-connect.sqlite	SQLite database path
AGENT_CONNECT_TS_ENABLE_TELEGRAM	true	Start enabled bot runtimes
TMUX_SESSION_NAME	agent-connect	Default tmux session name
CLAUDE_COMMAND	claude --permission-mode bypassPermissions	Claude launch command
CODEX_COMMAND	codex --yolo	Codex launch command
MONITOR_POLL_INTERVAL	2.0	Transcript polling interval in seconds
AGENT_CONNECT_TOPIC_PROBE_INTERVAL	60.0	Deleted-topic probe interval; 0 disables probing
AGENT_CONNECT_SHOW_INTERMEDIATE_MESSAGES	false	Send full thinking/tool/local command messages
AGENT_CONNECT_SHOW_HIDDEN_DIRS	false	Show hidden directories in the directory browser
OPENAI_API_KEY	none	API key for voice transcription
OPENAI_BASE_URL	https://api.openai.com/v1	OpenAI API base URL

Proxy variables from .env are applied to Telegram/OpenAI HTTP requests:

export HTTP_PROXY=http://127.0.0.1:7890/
export HTTPS_PROXY=http://127.0.0.1:7890/
export http_proxy=http://127.0.0.1:7890/
export https_proxy=http://127.0.0.1:7890/
export NO_PROXY=127.0.0.1,localhost
export no_proxy=127.0.0.1,localhost

Hooks

The bot synchronizes Claude and Codex hooks on startup. Manual repair:

agc hook --install

The generated hook command is:

agc hook

For environments where hook processes do not inherit your shell PATH, override it explicitly before installing hooks, for example AGENT_CONNECT_HOOK_COMMAND=/absolute/path/to/agc agc hook --install.

Codex also needs [features].hooks = true; agc hook --install keeps that setting synchronized.

Data Storage

Path	Description
$AGENT_CONNECT_DIR/agent-connect.sqlite	Bot configuration database
$AGENT_CONNECT_DIR/bots/<id>/state.json	Topic bindings, window states, display names, read offsets
$AGENT_CONNECT_DIR/bots/<id>/session_map.json	Hook-generated window to session map
$AGENT_CONNECT_DIR/bots/<id>/monitor_state.json	Transcript byte offsets
~/.claude/projects/	Claude Code session data, read-only
~/.codex/	Codex session data and hook config

Workspace Layout

apps/bot/                       TypeScript bot runtime and Fastify API
apps/web/                       React + Vite + Zustand management console
packages/cli/                   `agc` command line entrypoint
packages/telegramify-markdown/  `@yc-tech/telegramify-markdown` formatting package
doc/                            Project notes
scripts/                        Local operations