Claumon

A service that bridges Claude Code and OpenCode to Telegram, so you can approve tool permissions, answer questions, and receive notifications from your phone.

Not affiliated with Anthropic, PBC. "Claude" and "Claude Code" are trademarks of Anthropic.

Security notice: Claumon is a lightweight personal bridge — not production-grade security software. Hooks run shell commands with your user privileges; a careless approval can delete files or run harmful commands. Telegram bot messages are not end-to-end encrypted; if your bot token leaks, someone could send fake approvals. Never expose the Flask service to the public internet without HTTPS and authentication. Always review tool inputs before approving. See SECURITY.md for details. No warranty — use at your own risk.

Features

• Permission approval — YES/NO/Always Allow buttons in Telegram when Claude needs to run a tool
• PreToolUse gating — approve or deny Bash commands before they execute
• AskUserQuestion — multiple choice buttons, multi-select toggles, free-text "Other..." input
• Notifications — fire-and-forget alerts when Claude is idle or needs attention
• Auto-approve — safe read-only tools (Read, Glob, Grep, etc.) are approved instantly, never reach Telegram
• Debounced sending — transient permissions that resolve quickly are never sent to Telegram
• OpenCode plugin — same service, TypeScript plugin for OpenCode (Bun runtime)
• API key auth — optional X-API-Key header to secure the API
• Rate limiting — per-endpoint limits to prevent abuse
• Audit logging — rotating file log of all operations

Prerequisites

• Python 3.12+ or Docker
• A Telegram bot token (create via @BotFather)
• Your Telegram chat ID (get via @userinfobot)
• jq (required by hook scripts)

Quick Start

Option 1: Full install

git clone https://github.com/RobNL2/claumon.git
cd claumon
bash install.sh

This copies hooks to ~/.claude/hooks/, merges settings into ~/.claude/settings.json, creates a Python venv, and installs dependencies. If OpenCode is detected, it installs the plugin too.

Edit .env with your Telegram credentials, then start the service:

# macOS/Linux
venv/bin/python -m claumon.service

# Windows (MSYS2/git-bash)
venv/Scripts/python -m claumon.service

Option 2: Docker

git clone https://github.com/RobNL2/claumon.git
cd claumon
cp .env.example .env
# Edit .env with your TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID

docker compose up -d

Uses network_mode: host so the container binds directly to 127.0.0.1:9000 — hooks reach it the same way as a bare-metal install. State and audit logs persist via a ~/.claude volume mount.

You still need the hooks installed locally:

bash install-hooks.sh

Option 3: Hooks only

If the service runs on another machine or in Docker and you only need the Claude Code hooks locally:

bash install-hooks.sh

Requires curl and jq. Downloads hooks to ~/.claude/hooks/ and merges the hook configuration into ~/.claude/settings.json.

Configuration

Copy .env.example to .env and fill in at minimum the two required values:

Variable	Required	Default	Description
TELEGRAM_BOT_TOKEN	Yes	—	Bot token from @BotFather
TELEGRAM_CHAT_ID	Yes	—	Your Telegram user ID
CLAUMON_API_KEY	No	—	When set, all API requests must include X-API-Key header
CLAUMON_SEND_DELAY	No	3	Seconds to wait before sending permissions to Telegram (0 to disable)
CLAUMON_LOG_LEVEL	No	DEBUG	DEBUG, INFO, WARNING, or ERROR
CLAUMON_AUDIT_LOG	No	~/.claude/claumon-audit.log	Path to audit log file
CLAUMON_RATE_LIMIT_DEFAULT	No	60/minute	Default rate limit for all endpoints

Usage

Once the service is running and hooks are installed, restart Claude Code. From then on:

1. Read-only tools (Read, Glob, Grep, WebSearch, WebFetch, Task) are auto-approved instantly
2. Write tools (Bash, Write, Edit) trigger a Telegram message with YES / NO / Always Allow buttons
3. PreToolUse fires for Bash commands, giving you a chance to ALLOW or DENY before execution
4. AskUserQuestion prompts appear as option buttons in Telegram — including multi-select and free-text input
5. Notifications (idle, task complete) appear as fire-and-forget messages

Permissions that resolve before the debounce delay (default 3s) are never sent to Telegram.

Telegram Commands

Command	Description
/clear or /expire	Clear all pending questions and responses, edit expired messages
/status	Show pending count, unclaimed responses, last poll timestamp

OpenCode Plugin

Claumon includes a TypeScript plugin for OpenCode. It uses the same Flask API — no server changes needed.

OpenCode Hook	Behavior
permission.ask	POST permission, poll for YES/NO. Fail-open if service is down
tool.execute.before	Opt-in via CLAUMON_PRETOOLUSE=1. Throws on deny
event	Fire-and-forget for session lifecycle events

Set CLAUMON_URL and CLAUMON_API_KEY in your environment. See CLAUDE.md for details.

API Reference

Endpoint	Method	Description
/health	GET	Health check (exempt from auth and rate limits)
/api/status	GET	Service state (pending count, last poll)
/api/claude/question	POST	Hook scripts send permissions, questions, and notifications here
/api/response/get?request_id=X	GET	Hook scripts poll for the user's Telegram reply

Testing

# Python tests (71 tests)
venv/Scripts/python -m pytest -v    # Windows
venv/bin/python -m pytest -v        # macOS/Linux

# OpenCode plugin tests
cd opencode-plugin && bun test

License

MIT