gchat-claude-channel

Talk to your running Claude Code session from Google Chat — from your phone, from anywhere.

This is a Claude Code channel: messages you send in a Google Chat space are injected into the interactive Claude Code session you already have open, and the agent's replies come back to the same space. One live conversation, shared between your terminal and your phone.

Unlike bots that spawn a fresh headless claude -p per message, this pushes into your live session — full context, same working directory, same tools. It uses the official Claude Code Channels mechanism (a small MCP server that declares the claude/channel capability), plus Google's official Chat and Drive APIs. No scraping, no reverse engineering.

Status: Claude Code Channels is a research preview. The protocol may change between Claude Code versions. Requires Claude Code v2.1.80+.

---

⚠️ Security — read this first

By default the example supervisor runs the session with --permission-mode bypassPermissions, which means the agent executes commands coming from Google Chat with no per-action approval. That is powerful and dangerous. Before you deploy it:

1. The allowlist is the only wall. GCHAT_ALLOWED_SENDERS gates on the sender's Google user id, never the space. Only listed users' messages are injected; everyone else is silently ignored. Keep it to yourself (and people you fully trust). The server refuses to start with an empty allowlist.
2. Treat message content as untrusted. Anything you forward into the channel — a web page, a file, a screenshot — could contain hidden instructions (prompt injection). The channel labels senders as verified, but content is still data, not commands. Don't paste unknown content into a session that can run arbitrary code.
3. Prefer a dedicated space with only you and the bot account in it, so there is no way for a third party to post.
4. Want approvals instead of bypass? Remove --permission-mode bypassPermissions from the supervisor. The session will then prompt for each risky action — you'll need a channel permission relay to approve remotely, or the session blocks on local input.

This tool ships the bypass example because that is what makes a personal "phone as terminal" flow useful. If that trade-off isn't right for you, don't use bypass mode.

---

How it works

Google Chat space  ──poll──►  gchat MCP server  ──inject──►  your live Claude Code session
       ▲                        (this repo)                          │
       └──────────────  reply tool  ◄──────────────────────────────  ┘

The MCP server polls the space for new messages, verifies the sender against the allowlist, and injects the text (plus any downloaded attachments) as a channel notification. The agent replies with the reply tool, which posts back to the space.

---

Requirements

• Claude Code v2.1.80+
• Node.js 18+
• A Google Chat space and Google credentials with the Chat + Drive read scopes
• Optional: whisper and ffmpeg on PATH (for voice-note transcription and image conversion)

Setup

1. Install

git clone https://github.com/<you>/gchat-claude-channel
cd gchat-claude-channel
npm install

2. Configure

cp .env.example .env
# edit .env — see the comments in that file

You need three things in .env:

• GCHAT_SPACE — the space to watch (e.g. spaces/AAAAAAAAAAA; it's in the space URL, or list spaces via the Chat API).
• GCHAT_ALLOWED_SENDERS — your Google user resource name(s), e.g. users/1234567890. You can find yours by reading one of your own messages via the Chat API (messages.list → sender.name).
• Auth — either GCHAT_TOKEN_COMMAND (a command that prints an access token, e.g. gcloud auth print-access-token) or an OAuth refresh token trio. The token needs the chat.messages and drive.readonly scopes.

3. Register as an MCP server

claude mcp add --scope user gchat -- node "$(pwd)/server.js"

4. Run it

Interactive (loads the channel into your session):

claude --dangerously-load-development-channels server:gchat

(The dev flag is required because self-authored channels aren't on the approved allowlist during the research preview. You'll confirm a warning on first launch.)

Now post in your space — the message appears in the session, and the agent replies back to Chat.

Run it 24/7

See supervisor.sh.example and com.example.gchat-terminal.plist.example for a launchd setup (macOS) that keeps a tmux-hosted session alive, auto-answers the startup confirmations, and restarts on failure. Adapt the label/paths for your machine (or port to systemd on Linux).

Attachments

Images, PDFs, audio, and Drive files sent to the space are downloaded to an inbox; images/PDFs are handed to the agent to Read, Google native docs are exported to text, and audio is transcribed locally with whisper. Configure the whisper model/language via env (see .env.example).

Health checking

The server touches a heartbeat file (in GCHAT_STATE_DIR) on every successful poll. If polling stalls — e.g. the token expires — the heartbeat stops updating even while the process is still alive. Point your monitoring at the heartbeat's mtime to catch that "zombie" state, which a plain process check would miss.

Why this exists

At the time of writing, no channel shipped for Google Chat (the official channels cover Telegram, Discord, and iMessage), and multi-platform Claude Code gateways route to their own managed sessions rather than injecting into your live interactive one. This fills that gap for anyone living in Google Workspace.

License

MIT — see LICENSE.