ai-terminal-remote-bot

Secure remote terminal bot with Claude Code integration. Control your server and use Claude Code interactively from Telegram.

Features

• Remote Terminal: Execute commands, navigate filesystem, view files
• Claude Code Integration: Interactive AI sessions with real-time tool usage visibility
• Media Support: Send documents, photos, and audio with automatic handling
• Audio Transcription: Voice messages and audio files are transcribed using Whisper (JS/ONNX, offline, no API keys). First transcription downloads ~40MB model.
• Security Hardened: Command validation, path restrictions, rate limiting, no shell injection
• Clean Architecture: Strategy Pattern, DI, per-user sessions, SOLID principles

Install

npm install -g ai-terminal-remote-bot

Or clone and link:

git clone <repo>
cd ai-terminal-remote-bot
npm install
npm link

Setup

ai-terminal-remote-bot          # First run triggers setup wizard
ai-terminal-remote-bot --config # Re-run setup anytime

You'll need:

1. A Telegram bot token from @BotFather
2. Your Telegram user ID from @userinfobot

Config is stored in ~/.ai-terminal-remote-bot/config.json with 0600 permissions.

Commands

| Command | Description | |---------|-------------| | /run <cmd> | Execute a shell command | | /cd <dir> | Change directory | | /ls [args] | List files | | /cat <file> | View file contents | | /status | System status (RAM, disk, uptime) | | /procs | Top processes by CPU | | /kill <PID> | Kill a process | | /claude [prompt] | Enter Claude mode / send prompt | | /ask <question> | One-shot Claude query | | /new | New Claude conversation | | /exit | Return to terminal mode |

In terminal mode, plain text is executed as bash commands. In Claude mode, plain text is sent to Claude Code.

Security

• Dangerous commands (rm -rf, shutdown, etc.) require confirmation
• Irrecoverable commands (fork bombs, mkfs, dd) are blocked entirely
• /ls, /cat, /kill use execFile() with args array (no shell)
• Claude prompts use spawn('claude', ['-p', prompt]) via argv (no shell interpolation)
• Path validation against configurable allowed paths
• Rate limiting: 30 requests/minute sliding window
• Config file permissions enforced at 0600

Architecture

cli.js → config.mjs → setup.mjs OR server.mjs
                                      ├── platforms/telegram.mjs  (Strategy Pattern)
                                      ├── modules/terminal.mjs    (execFile/spawn)
                                      ├── modules/claude.mjs      (spawn with argv)
                                      ├── modules/media.mjs       (safe file handling)
                                      ├── security.mjs            (validation layer)
                                      └── utils.mjs               (pure functions)

License

MIT