Package Exports

ai-terminal-remote-bot
ai-terminal-remote-bot/cli.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (ai-terminal-remote-bot) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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:

A Telegram bot token from @BotFather
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