Get started
This walks you through a first setup: a bot of your own, TeleCoder running on your machine in the background, and a first conversation. It takes about ten minutes. For every option along the way, see Install and run.
What you need
Section titled “What you need”- Linux or macOS. WSL 2 should work like Linux, but it’s untested.
- Node.js 22 or newer, with npm.
- Claude Code, installed and logged in on this machine:
curl -fsSL https://claude.ai/install.sh | bash, then runclaudeonce and/login. A Pro or Max subscription works, and so does an API key. - On Linux, a C++ toolchain, because
npm installcompilesnode-pty:sudo apt install python3 make g++(Debian, Ubuntu) orsudo dnf install python3 make gcc-c++(Fedora). macOS uses a prebuilt binary. - Telegram on your phone or computer.
TeleCoder runs as you, with your Claude login, on your machine. There’s no hosted version and no server to expose: the bot polls Telegram, so it needs no open port or tunnel.
1. Make a bot with BotFather
Section titled “1. Make a bot with BotFather”- Open @BotFather in Telegram and send
/newbot. - Give it a display name (anything, like My TeleCoder) and a username ending in
bot. - BotFather replies with a token like
123456789:AAH.... Keep it to hand for the next step, and keep it to yourself: whoever has it controls the bot.
2. Install and run the wizard
Section titled “2. Install and run the wizard”npm install -g telecodertelecoder inittelecoder init checks Node and your Claude login first, then asks for:
- The bot token. It checks the token with Telegram straight away.
- You. It asks you to send your new bot
/start, and learns your Telegram user ID from that. Only the IDs you allow can use the bot. - Your projects folder, the folder your code lives in, such as
~/dev. TeleCoder offers the folders in it as projects. - SDK or PTY. SDK is the lighter default. PTY drives the real
claudeterminal app, so yourCLAUDE.md, skills, plugins and slash commands all work as in a terminal. You can switch any time with/method; Providers has the details. - Voice and Telegraph, both optional.
- A picture for the bot. If your bot has no profile picture yet, the wizard offers to give it the TeleCoder icon, so it’s easy to spot in your chat list.
It writes your answers to ~/.telecoder/.env, readable by you only. Run it again to
change an answer, and run telecoder doctor whenever something seems off.
3. Keep it running
Section titled “3. Keep it running”telecoder service installThis installs TeleCoder as a service that starts at boot and restarts if it stops: a systemd user unit on Linux, a LaunchAgent on macOS.
On Linux it asks to turn on lingering (loginctl enable-linger). Say yes: without
it, systemd stops your user services when you log out, so the bot would go quiet the
moment you close your last SSH session or log out of your desktop.
telecoder service status # is it running?telecoder service logs # follow what it's doingPrefer to watch it in a terminal for now? telecoder start runs it in the foreground
instead, until you press Ctrl+C.
4. Your first conversation
Section titled “4. Your first conversation”- Open your bot in Telegram and send
/project. Tap the project you want to work on. - Type what you want, as you would in Claude Code: “What does this project do? Then look for any failing tests.”
- Claude works on your machine and streams its progress into the chat: what it reads, what it runs, and its answer.
When Claude wants to do something that needs your approval, such as running a command
or editing a file, you get the question with buttons. One tap answers it. /mode
sets how much it asks before acting.
A few things to try next:
- A voice note. Talk instead of typing, if you turned voice on.
/btwwhile Claude works, to ask a side question without stopping it./steer, to stop the turn and send a correction instead./modeland/effort, to switch model and reasoning effort./commands, for everything else. Commands has them all.
5. Turn on threads
Section titled “5. Turn on threads”With threads, every thread in the chat is its own Claude session. You can run several
tasks side by side and switch between them like chats, and /fork and /spinoff open
their branches in new threads. Without threads, the chat is one conversation at a time.
Telegram doesn’t let a bot turn threads on for itself, so it’s one switch for you:
- Open @BotFather and tap Open to start its Mini App.
- Pick your bot.
- Turn on Threaded Mode.
Then send the bot /restartbot so it picks up the change. (Bots made with /newbot
notice by themselves within a minute.) From then on, start a new thread to start a new
session. Threads are named after what they’re about.
Or use a group with topics. Make a group, turn on Topics in its settings, and add
your bot as an admin, so it sees every message and not just the ones that mention it.
Each topic is then a session. In ~/.telecoder/.env, add the group’s ID (a negative
number starting with -100; Telegram Web shows it in the address bar) to
ALLOWED_GROUP_IDS. In a group the bot only answers messages that @mention it, so
that people can talk among themselves. In a group that’s just you, set
GROUP_REQUIRE_MENTION=false as well. Then restart with telecoder service restart.
A group is also how you share a bot with others: see
Sharing a bot.
Where next
Section titled “Where next”- Features: everything TeleCoder does.
- Multiple bots: a bot per project, from one process.
- Configuration: every setting in
.env. - Troubleshooting: when the bot doesn’t answer.