Skip to content
ꦕcarakaINSTALLGitHub ↗
INSTALL

Telegram to Claude Code, from one command.

Caraka v0.2 runs locally with one private Telegram account, one workspace, and Claude Code. No webhook, open port, model key, or hand-written config.

no global install, no repo to clone
ON THIS PAGE7
01

What must be there

The wizard checks local prerequisites before it asks for the value it cannot discover: your Telegram bot token.

1
Node.js 22 or newer
The runtime for Caraka and npx. Check it with node --version before starting.
2
Git
Claude works inside the repository you choose. Caraka checks that Git is available before pairing.
3
A coding agent, signed in
Claude Code over the official ACP adapter is the route verified here; init accepts any of the seven presets it finds on PATH. Run claude auth status to confirm access.
NOT NEEDED
Dockera cloud accounta domainan open porta webhooka reverse proxya TLS certificatea background service
02

No Node.js yet

npx ships with Node, so without it the first command does not exist. This is the only thing to solve before touching Caraka. Version 22 or newer, for the built-in fetch and test runner.

macOSbrew install node
macOS / Linuxcurl -fsSL https://fnm.vercel.app/install | bash && fnm install 22
Ubuntu / Debiancurl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt install -y nodejs
Fedorasudo dnf install nodejs22
Archsudo pacman -S nodejs npm
Windowswinget install OpenJS.NodeJS.LTS # use PowerShell or WSL2
03

Claude Code and Telegram

This release supports Claude Code through the official ACP adapter. Telegram supplies transport and identity; Claude keeps its runtime, tools, and model access.

Claude CodeREQUIRED
npm install --global @anthropic-ai/claude-codeclaude auth login
Caraka uses your existing Claude access. It does not ask for or store a model API key.
Telegram botREQUIRED
open @BotFather and send /newbotkeep the token out of chat and issues
The init wizard validates the token, then stores it in a mode-0600 secret file.
Topic modeOPTIONAL
enable topic mode for the bot in @BotFatherotherwise Caraka uses linear mode
A topic failure never blocks a task. Linear replies carry a workspace and session header.
04

What init checks

Every check happens before config is written. A rejected token or unconfirmed pairing leaves no new credential behind.

CHECKCOMMANDREADYIF MISSING
Nodenode --versionv22+nodejs.org
Gitgit --versionfoundinstall Git
Claudeclaude --versionfoundnpm install -g …
Authclaude auth statuslogged inclaude auth login
TelegramgetMevalid botcopy a new token
Identityone-time deep linkterminal approvalrun init again
NO MODEL KEYClaude keeps its own authentication, model, tools, and sandbox.
LOOPBACK ONLYNothing is opened to the internet. Telegram is polled, Discord and Baileys are outbound sockets, and both listeners — the dashboard and the WhatsApp Cloud API webhook — bind 127.0.0.1 unless you say otherwise.
PRIVATE TOKENThe bot token stays outside config.yaml in a mode-0600 file.
ONE OPERATOROne operator, deliberately. More than one workspace is supported, and @slug in front of a message picks which.
LANGUAGE ASKED ONCEinit asks for English or Indonesian and writes the answer to config.yaml. Caraka never picks a language from the text of a message.
05

Choose an install path

Fastest path, no global packagenpx caraka init
Use Caraka every day from PATHnpm i -g caraka
Want Codex or Claude to helpcopy the prompt below
Choose a different repository--workspace PATH
Already pairednpx caraka doctor
06

Ask Codex or Claude to install it

Paste this into either coding agent. It lets the agent handle checks while keeping the Telegram token out of the conversation transcript.

Install Caraka for the repository in my current working directory.

Read https://github.com/CarakaDev/caraka first. Verify Node.js 22 or newer,
Git, Claude Code, and `claude auth status`. Fix only missing prerequisites
without changing my repository.

Never ask me to paste, reveal, or repeat the Telegram bot token in chat, command
output, logs, or a committed file. Tell me to create a bot with @BotFather, then
hand me this command to run myself in a local terminal:

  npx caraka init --workspace "$PWD"

After I confirm init is complete, run `npx caraka doctor`, explain failed
checks, and start it with `npx caraka start`. Do not enable a webhook, open a
port, install a service, or change Claude's model/provider configuration.
✓The agent checks Node, Git, Claude Code, and Claude authentication first.
✓The Telegram token never enters the AI conversation or a committed file.
✓The user performs the private token step in the local init wizard.
✓The agent may continue with doctor after pairing is complete.
✓No webhook or listening port is enabled.
✓The agent installs no service. caraka service --print writes a unit to stdout for you to install yourself.
✓Claude keeps its current model and provider configuration.
✓Repository files are not changed by the installer.
07

Verify and run

Doctor is read-only. Start keeps the gateway in the foreground so you can stop it with Ctrl-C while evaluating v0.2.

$ npx caraka doctor
✓Node.js · ready
✓Git · ready
✓Claude login · ready
✓Telegram · ready
✓Allowlist · ready
$ npx caraka start
Ctrl-C stops it here; npx caraka stop ends one started elsewhere
$ npx caraka service --print systemd
prints a unit and writes nothing; the macOS agent starts at login, not at boot
Still stuck?
Every failed check names the next action. Never include your Telegram token in an issue.