convez.ai
PluginAutomaçãoIntermediário
OctopusGarage

tmux-claude-bot

OctopusGarage/tmux-claude-bot

Controle Claude Code via Telegram/Feishu direto do seu tmux

Ver no GitHub
BomPluginScore · de 0 a 100

Bot que controla remotamente sessões do Claude Code rodando em tmux, via Telegram ou Feishu/Lark. Permite enviar prompts, receber respostas em tempo real, transcrever áudio e gerenciar múltiplos projetos em paralelo, tudo com instalação de uma linha no macOS.

Instalação

$npx convez-ai OctopusGarage/tmux-claude-bot

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
75%
Último commit
há 1 dia
Versão
v0.2.1
Issues abertas
1
Contribuidores
2

Casos de uso

  • Automatizar tarefas de desenvolvimento remotamente via mensagens
  • Gerenciar múltiplos projetos com sessões Claude isoladas
  • Executar comandos por voz e receber outputs em tempo real

Veredito

Ferramenta bem pensada para quem quer orquestrar Claude Code de fora do terminal. Implementação sólida com fila de execução, detecção de idle e suporte a múltiplos canais (Telegram/Feishu), mas escopo bastante nicho—exige tmux, Claude Code CLI e macOS.

README

A tradução para o português deste README ainda está na fila.

tmux-claude-bot

CI Coverage version Node License: MIT TypeScript platform: macOS Checked with Biome

A chat bot that drives Claude Code inside tmux sessions — remote-control your local Claude from Telegram and/or Feishu/Lark, with voice and text input. Supports multiple projects, each with its own tmux session. Pick one chat app or run both.

Contents

Features

  • Multi-project tmux sessions — each project gets its own tmux session (tmux_proj_<path>)
  • Project switching — create, switch, and remove projects via Telegram commands
  • Real-time output streaming — captures tmux pane and streams output to Telegram
  • Queue-based execution — prevents concurrent commands from interleaving
  • Idle detection — polls tmux pane to detect when Claude is idle vs. running
  • Directory guard — operations restricted to configured allowed directories

Demo

Telegram — keyboard & outputVoice transcriptionFeishu/Lark
Telegram keyboardVoiceFeishu

Architecture

Telegram Bot (grammy)
    │
    ├── bot/
    │   └── handlers.ts  — command routing, middleware, session validation
    │
    ├── services/
    │   ├── tmux.ts              — tmux pane capture, send-keys, session management
    │   ├── claude.ts            — start/stop Claude, idle poll, queue orchestration
    │   ├── queue.ts             — FIFO command queue with mutex
    │   ├── output.ts            — tmux output → Telegram message chunking
    │   └── currentProject.ts    — .current_project file lifecycle + session cache
    │
    └── config.ts    — env loading via dotenv + Zod validation

Quick Start

Install (macOS)

curl -fsSL https://raw.githubusercontent.com/OctopusGarage/tmux-claude-bot/main/install.sh | bash

The installer checks prerequisites (node, tmux, Claude Code CLI), installs dependencies, then runs a guided wizard that:

  1. asks which chat app to connect — Telegram, Feishu/Lark, or both,
  2. Telegram: asks for your bot token (@BotFather), validates it live, and auto-captures your Telegram id (just message the bot),
  3. Feishu/Lark: renders a QR code — scan it to create the app; credentials are written for you,
  4. asks which project directories the bot may use,

and finally installs and starts the bot as a launchd service (auto-restart on crash/boot).

Re-running the installer updates code + dependencies and restarts the service while preserving your .env and runtime state — a safe one-click update. Add Feishu later anytime with npm run setup:lark.

Prefer to clone first? git clone … && cd tmux-claude-bot && ./install.sh does the same thing in place. The install location defaults to ~/.tmux-claude-bot; override it with TMUX_CLAUDE_BOT_DIR=/path.

Install with an AI assistant

Not comfortable on the command line? Copy this prompt to any AI assistant (ChatGPT, Claude, Gemini, or an agent with shell access) — it downloads the release, reads the bundled guide, and walks you through it:

Install "tmux-claude-bot" on my Mac for me (open-source, macOS-only). Download the latest
release tarball from https://github.com/OctopusGarage/tmux-claude-bot/releases/latest,
extract it, read the INSTALL.md inside, and follow it. Guide me step by step and ask me
for anything it needs (like my Telegram bot token).

By default the installer fetches the latest stable release — a lean tarball without tests/, docs/, or dev-config files. Pin a specific version, or track main:

# pin a released version
TMUX_CLAUDE_BOT_VERSION=v0.1.0 curl -fsSL https://raw.githubusercontent.com/OctopusGarage/tmux-claude-bot/main/install.sh | bash

# track the latest main (development)
TMUX_CLAUDE_BOT_VERSION=main curl -fsSL https://raw.githubusercontent.com/OctopusGarage/tmux-claude-bot/main/install.sh | bash

Manage

npm run service:install     # (re)install + start the launchd service
npm run doctor              # health check (incl. single-instance 409 guard)
npm run setup:reconfigure   # change token / authorized users / directories
npm run service:uninstall   # stop and remove the launchd service

First message

In Telegram: /add_project ~/projects/myapp then /start.

Configuration

All settings via .env:

VariableDefaultDescription
TELEGRAM_BOT_TOKEN(optional)Telegram bot token from @BotFather. Blank = Telegram off (Feishu-only)
LARK_ENABLED / LARK_APP_ID / LARK_APP_SECRET / LARK_ALLOWED_OPEN_IDS / LARK_DOMAIN(optional)Feishu/Lark adapter — set by npm run setup:lark. At least one of Telegram/Feishu must be configured
CLAUDE_START_COMMANDclaude-yoloCommand to launch Claude
IDLE_POLL_TICKS3Consecutive idle polls before considered idle
POLL_INTERVAL_MS1000Milliseconds between idle polls
MAX_OUTPUT_LINES200Max tmux pane lines to capture
MAX_MESSAGE_LENGTH3500Max Telegram message size
TELEGRAM_ALLOWED_USER_IDS(empty)Comma-separated Telegram user IDs that can use the bot
CD_ALLOWED_DIRS(empty)Allowed directories for project creation

Session Naming

tmux session name format: tmux_proj_<absolute-path> with / replaced by -

Example: /home/user/projects/myapp → tmux_proj_-home-user-projects-myapp

The active session name is stored in .current_project (gitignored).

Telegram Commands

Projects (no Claude required)

CommandDescription
/list_projectsList all tmux_proj_* sessions
/current_projectShow current project and session status
/add_project <path>Create new project tmux session
/switch_<N>Switch to project by number
/remove_<N>Remove project session

Claude control (session required)

CommandWhenDescription
startsession existsStart Claude session
statussession existsCheck if Claude is running
peeksession existsCapture current tmux pane
escClaude runningSend Escape key
interruptClaude runningSend Ctrl-C
exitClaude runningSend /exit to Claude
restartClaude runningRestart with --continue flag
clearClaude runningSend /clear (clear context)
compactClaude runningSend /compact (compact context)
enterClaude runningSend Enter key
up / downClaude runningSend arrow keys
helpalwaysShow all commands

Natural language

When Claude is running, any text message is sent to Claude and the result is returned.

Voice transcription (optional)

Voice messages are transcribed locally with mlx-whisper (Apple Silicon only) and then forwarded to Claude like any text. The feature is off until you install it — if you never use voice, you can ignore this entirely.

Enable it (two ways):

  • From Telegram: send /voice_install. The bot runs the installer, enables the feature, and persists the path to .env — no restart needed. (No-op politely if the host isn't Apple Silicon.)
  • On the host: npm run whisper:install, then put the printed path into MLX_WHISPER_BIN in .env (or re-run npm run setup:reconfigure).

What gets installed (project-managed, reproducible — nothing global):

  • A project-local .venv created by uv, with mlx-whisper pinned in requirements.txt. Model weights are downloaded from HuggingFace on first transcription.
  • ffmpeg is required to decode audio (brew install ffmpeg). The installer and npm run doctor both check for it.

If you send a voice message before enabling the feature, the bot replies with a short note telling you how to turn it on — it never fails silently.

Recognition language. whisper's auto-detect often misreads Chinese as Japanese, so transcription forces a language — zh by default. Switch any time from Telegram with /voice_lang <zh|en|auto> (auto re-enables detection); it persists to .env. Override the default with WHISPER_LANGUAGE in .env.

Claude Running Detection

The bot decides whether Claude is running by process detection, not screen scraping: it walks the tmux pane's process tree (pane_pid → ps) and looks for a claude process. Present → running; absent → idle. This is theme- and output-independent. (Readiness — "Claude finished loading" — is still detected from the pane, since the process exists before it is ready for input.)

Production Deployment (macOS launchd)

The bot runs as a launchd service with automatic crash recovery:

npm run service:install     # install + start the launchd agent (auto-restart on crash/boot)
npm run service:uninstall   # stop and remove the launchd agent
npm run doctor              # verify it's healthy (single-instance check)

Note: the installer uses sed to substitute __PROJECT_DIR__ in the plist template before copying it to ~/Library/LaunchAgents/. Do not copy the plist manually — the placeholder will be left unresolved and the service will fail to spawn.

Features:

  • KeepAlive — auto-restart on crash
  • ThrottleInterval — min 10s between restarts (prevents crash loops)
  • Logs to logs/launchd.out.log and logs/launchd.err.log

Resilience

MechanismBehavior
Network retrygetMe retries 5× with exponential backoff (1s→30s)
Message retryHandler retries 3× with linear backoff (1s, 2s, 3s)
Queue persistenceUnprocessed messages saved to .queue/pending.json
Process auto-restartlaunchd KeepAlive restarts bot on crash
Handler isolationSingle message failure does not block queue

Development & releases

See CONTRIBUTING.md for local dev, the verification gates, and the install/deploy/release flow. In short:

  • Dev: npm install && npm run setup && npm run dev
  • Deploy this machine: /deploy (Claude command) or re-run the installer
  • Cut a release: /release [patch|minor|major] — gates, bumps, tags, pushes (CI publishes the GitHub Release), then redeploys + verifies this machine

Requirements

  • Node.js 20+
  • tmux
  • Claude Code CLI (claude-yolo or similar)
  • Optional, for voice: Apple Silicon Mac + uv + ffmpeg (see Voice transcription)
Ver o original no GitHub

Bom para

Relacionados