Install and run
Prerequisites
Section titled “Prerequisites”| Requirement | Notes |
|---|---|
| Linux or macOS | Windows isn’t supported natively: the permission hook, restarts (systemd or a bash script) and process tracking (/proc) assume a Unix system. WSL 2 is Linux underneath, so it should work there as on Linux, but that is untested. |
| Node.js 22+ | with npm. TeleCoder refuses to start on anything older. |
| A C++ toolchain (Linux) | node-pty is compiled during npm install on Linux, which needs python3, make and g++: sudo apt install python3 make g++ (Debian, Ubuntu) or sudo dnf install python3 make gcc-c++ (Fedora, RHEL). macOS uses a prebuilt binary. |
| Claude Code CLI, logged in | Install it with curl -fsSL https://claude.ai/install.sh | bash (it goes in ~/.local/bin; log in again if that isn’t on your PATH yet) and run claude once and /login, as the user the bot will run as. For a machine you won’t sign in on, claude setup-token makes a long-lived token to put in CLAUDE_CODE_OAUTH_TOKEN; an ANTHROPIC_API_KEY works too, billed per use. The bot warns at startup if it finds no login, and replies with how to log in if a message fails on it. |
| Telegram bot token | from @BotFather |
| Your Telegram user ID | the number, not your @username. telecoder init finds it when you message your bot; by hand, message @userinfobot |
| ffmpeg (optional) | only for spoken replies through Groq (/tts). Transcribing voice notes doesn’t need it. |
Install from npm
Section titled “Install from npm”npm install -g telecodertelecoder init # or, without installing first: npx telecoder inittelecoder init checks Node and the claude CLI and its login, asks for the
bot token from @BotFather and checks it with Telegram, then has you send the
bot /start to learn your user id, so there’s no @userinfobot step. It asks
for the folder your projects are in, SDK or PTY, and whether to turn on voice
transcription or Telegraph, and writes ~/.telecoder/.env (set
TELECODER_HOME to keep it somewhere else) with just those settings, readable
by you only. Every other setting stays at its default; .env.example lists
them all. Run it again to change an answer. For scripts, the flags
--token-env VAR, --owner-id, --workspace, --transport and --yes
skip the questions; the CLI reference lists them all.
telecoder start # runs every bot in ~/.telecoder/instances.json instead, if there is onetelecoder doctor # checks Node, the claude CLI and its login, and your configOpen your bot in Telegram → /start
/update installs the latest release; /rebuildbot is for source checkouts only.
Run it in the background
Section titled “Run it in the background”telecoder start runs in your terminal and stops with it. To keep the bot running,
start it at boot, and let /restartbot restart it from chat (an npm install restarts
by exiting, for its service manager to start it again):
telecoder service install # systemd user unit on Linux, LaunchAgent on macOStelecoder service status # is it running?telecoder service logs # follow its output (--no-follow: the last 100 lines)telecoder service restart # also brings it back after a config error stopped ittelecoder service uninstall # stop it and remove the unit- Linux writes
~/.config/systemd/user/telecoder.serviceand enables it. The unit runs thenodeandtelecoderit was installed with, from~/.telecoder(orTELECODER_HOME), with aPATHthat findsclaude,gitandffmpeg. It holds no secrets — the bot reads its.env. It restarts on any exit except a configuration error (exit 78: fix the.env, thentelecoder service restart), andsystemctl --user stop telecoderstops it for good. It asks before turning on lingering (loginctl enable-linger), which keeps user services running after you log out and starts them at boot;--yesanswers yes to everything,--no-lingerskips it. Undersudo -uit finds the user’s systemd manager by itself when one is running; when none is (no login and no lingering, as for a service account) it says to runsudo loginctl enable-linger <user>first. Without a usablesystemd --userat all (a container, WSL without systemd) it prints the unit and other ways to run it instead. - macOS writes
~/Library/LaunchAgents/dev.telecoder.telecoder.plistand loads it; output goes to~/Library/Logs/telecoder/telecoder.log. A LaunchAgent runs while you are logged in. launchd can’t exempt one exit code fromKeepAlive, so under launchd a bot stopped by a configuration error exits 0 instead, which it leaves alone.
Run telecoder service install again after moving node, claude or your config:
it shows what changes and asks before replacing the unit. --name <name> installs a
second one side by side, and --dry-run prints the file without writing anything. An
npx telecoder isn’t installed anywhere lasting, so install it with
npm install -g telecoder first. A source checkout is run with
the bot control script or npm start as before;
node dist/cli.js service install --from-checkout installs a unit for it anyway.
From source
Section titled “From source”git clone https://github.com/gitaarik/telecoder.gitcd telecodercp .env.example .envEdit .env — a .env or instances.json next to package.json is used instead of ~/.telecoder:
TELEGRAM_BOT_TOKEN=your_bot_tokenALLOWED_USER_IDS=your_user_idnpm installnpx tsx src/cli.ts doctor # checks Node, the claude CLI and its login, and your confignpm run dev # dev mode with hot reloadOpen your bot in Telegram → /start
Run the tests
Section titled “Run the tests”The test suite needs no bot token, Claude login or .env:
npm installnpm test