ambient-claude

Claude Code, but it texts you first.

It noticed a failing test, found the auth bypass, and messaged me the fix — I just said "approved".

Connect your Claude Code session to Telegram, so it can message you when something happens — a failed CI run, a low battery, an error in a log — not only when you message it.

It's a small skill, not a daemon. A ~300-line shim long-polls Telegram into a local file. Your live Claude Code session watches that file and replies. The same session can also watch other things (CI, logs, a price) and message you first when they change.

The brain is your actual Claude Code session, so it runs on the Claude Code plan you already have (no separate API key), and your existing skills, CLAUDE.md, and MCP servers are already loaded.

Status (v0.1): verified end-to-end against a real bot — auth, receiving text and media, and sending text and files all work. The one gap: inbound voice arrives as an audio file with no transcript (Telegram, unlike WeChat, doesn't transcribe for bots — bring your own STT). The same shim-plus-Monitor architecture also runs over WeChat in the sibling weixin-bridge skill. See Status.

How it works

Telegram  ⇄  telegram-shim.mjs (listen)  →  ~/.ambient-claude/inbox.jsonl
                                                  │  (Monitor)
                          your Claude Code session ──▶ reply via `send -`

• scripts/telegram-shim.mjs — the only code. Talks the Telegram Bot API: listen, send, sendfile, typing, whoami. No dependencies.
• SKILL.md — what your session does: start the listener, watch the inbox, reply, and arm proactive monitors.
• The brain is your live session. No daemon, no claude -p per message.

Setup

1. Get a bot token from @BotFather (/newbot). Get your chat id from @userinfobot.
2. Write ~/.ambient-claude/config.json:

   { "token": "<token>", "allowFrom": ["<your-chat-id>"] }

3. node scripts/telegram-shim.mjs whoami — check the config.
4. node scripts/telegram-shim.mjs listen — run in the background.
5. In a Claude Code session, follow SKILL.md: arm a Monitor on the inbox and reply per message.

Requires Node ≥ 18 and an authenticated claude CLI.

Channels

The same shim-plus-Monitor architecture runs over more than one transport — each is a thin, zero-dep wire; your live session is the shared brain.

• Telegram (scripts/telegram-shim.mjs) — official Bot API, verified end-to-end. The default.
• WeChat (sibling weixin-bridge skill) — your personal WeChat via a zero-dep shim.
• Discord (scripts/discord-shim.mjs) — new. The bot-friendly platform: an official Bot API with a real Gateway (not a self-bot), so it's legitimate to run. The shim connects the Discord Gateway v10 over the built-in WebSocket, writes each allowlisted inbound message to ~/.ambient-claude/discord-inbox.jsonl, and sends via REST (send / dm). Because a channel is a stream of many voices, the intended MVP is sense + connect: aggregate-sense what a channel is discussing and, on spotting a matchable need, propose an opt-in intro. See SKILL.md for setup (bot token, MESSAGE CONTENT intent, OAuth invite). Status: v0.1 — written to the documented Gateway v10 + REST spec, not yet run against a real bot token; the heartbeat / resume / identify state machine in particular wants a live token to verify.

Proactive monitors

A monitor is a shell command whose output lines are events. Arm one in your session; when it fires, the session decides whether to message you. Examples: tail -F app.log | grep ERROR, a CI poll, a battery check, a daily digest. Recipes are in SKILL.md.

Security

An inbound message makes your Claude Code session act in your project, with your files and shell. Anyone can message a Telegram bot, so the shim only accepts chat ids listed in allowFrom and drops the rest before your session sees them. Put your own chat id there first. The token in config.json is a secret.

Compared to other things

• Remote-control bots (most Claude Code + Telegram bridges): reply when you message them; they don't reach out on their own.
• Agent platforms (OpenClaw, QwenPaw): full platforms with their own agent and their own API key/bill. More capable, much larger, a different thing to run.
• This: your existing Claude Code session, made reachable and proactive over Telegram, in one small file. A sibling skill, weixin-bridge, does the same over WeChat.

Status

v0.1. Verified live against a real bot, end-to-end: authentication (getMe), receiving text (long-poll → inbox → your session), sending text (sendMessage), inbound media download (getFile), and outbound files (sendDocument) all work. The one gap: inbound voice arrives as an audio file with no transcript — Telegram, unlike WeChat, doesn't transcribe for bots, so bring your own STT (e.g. local whisper). node --check passes.

License

MIT