# gchat-claude-channel

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

This is a [Claude Code channel](https://code.claude.com/docs/en/channels): 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**

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

**2. Configure**

```sh
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**

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

**4. Run it**

Interactive (loads the channel into your session):

```sh
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`](supervisor.sh.example) and [`com.example.gchat-terminal.plist.example`](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](LICENSE).