Skip to content

Install

stolik

talk to all my Claude Code sessions from Telegram or Discord

One bot, two chats, many sessions. Two-way, and it pings me only when needed.

Architecture

one router, many sessions

Telegram

one group, a topic per folder

Discord

one private channel per folder

systemd --user service

Router

  • Telegram + Discord
  • Session registry
  • Presence detection
  • Voice transcription

[cat-garden]

Claude Code session

+ channel MCP server

[my-api]

Claude Code session

+ channel MCP server

[stolik]

Claude Code session

+ channel MCP server

Telegram / Discord ⇄ Router ⇄ sessionsHooks → router: Stop · Notification · UserPromptSubmit

Talking to a session

Swipe-reply

Goes to the session that sent it.

to <project>: …

Names the session in General. Works by voice too.

NEW

Plain message

In a folder topic, it goes to that folder's last session. In General, the one active in the last 30 minutes, or buttons.

When does it message me?

Only when I'm away

Away = 5 min idle, screen locked, or /away

Turn finished

Final message forwarded.

Permission prompt

Allow or deny from the phone.

Waiting for input

A nudge, so nothing stalls.

Judgment calls

Milestones, surprises, and decisions I might veto.

Phone superpowers

Voice notes

Transcribed on your PC. Speech never leaves it.

Photos & files

Land directly in the session.

Start work from the phone

New sessions in trusted folders, from anywhere.

Safety rails

  • Only the paired account
  • Secrets redacted before sending
  • Credential files can't be sent
  • Forwarded messages = untrusted data
  • No remote Allow if input was redacted
  • Phone-started sessions: trusted folders only, normal permissions
  • /lock kill switch, unlock only at the desk
  • Chat log on your PC

Built with Claude Code

Node + Telegram + Discord · runs locally

This guide sets up Telegram. For Discord, see Discord instead of Telegram. One install uses one chat app.

Terminal window
npm install -g stolik
stolik setup

Install it globally, as shown. Do not run setup with npx: npx runs the package from npm’s cache, and npm can clean that cache at any time. The plugin and the router service would then point into the cache and break. stolik service install refuses to run from there.

Setup asks for the bot token. Typing is hidden. Then it pairs the bot with your Telegram account.

  1. Setup prints a six-digit code.
  2. Open a private chat with the bot (not a group). Send it the code. The code works for 5 minutes and 5 tries. After 5 wrong codes, run stolik setup --pair to get a new one.
  3. Setup shows the account that sent the code. Answer y to confirm it is you.

Setup does not ask again if the install already has an owner. To pair a different account, run stolik setup --pair. For scripts, stolik setup --owner-id <number> sets the owner without pairing.

You can keep the router running during pairing. Until you pair, the router answers nobody. stolik doctor reports “not paired yet”.

Setup writes two files and prints the next steps:

  • ~/.config/stolik.env: the bot token and the owner’s chat id. Only your user can read it (mode 600).
  • ~/.config/stolik/config.json: everything else. The owner is stored as chat.telegram.ownerUserId. A missing file means defaults.

It also offers the optional model worker for voice notes and the digest. Say no for now. You can run setup again later.

  1. In Telegram, create a new private group and turn Topics on in its settings.
  2. Add your bot and make it an admin with Manage topics and Pin messages.
  3. Send /bind in the group.

The bot checks that /bind came from your paired account. Then it makes this group its home. It ignores messages and taps from anyone else.

After /bind, the bot posts the list of built-in addons in General with an Enable all button. Nothing is on until you choose. See Addons.

Terminal window
stolik service install --start
stolik service status

This writes a systemd user unit named stolik and starts it. The router runs in your login session, not as root. The unit runs the copy of stolik that wrote it, so keep the global install in place. Restarting the router leaves your tmux sessions and the Claude Code sessions in them running.

If you change the Node version, run stolik service install --start again so the unit uses the new one. Logs: journalctl --user -u stolik -f.

Setup prints the plugin folder. It is inside the global npm folder (npm root -g, then stolik/plugin). In Claude Code, run this once:

/plugin marketplace add <the plugin folder that setup printed>
/plugin install stolik@indicozy

The plugin holds the channel (how messages get into a session) and a few hooks (how answers and permission prompts get out).

Terminal window
cd ~/code/orbit-api
STOLIK_PLUGIN=1 tg-claude

tg-claude is claude with one extra flag: --dangerously-load-development-channels plugin:stolik@indicozy. STOLIK_PLUGIN=1 selects that plugin. Without it, tg-claude looks for a user-level MCP server named stolik, and the plugin does not create one. Claude Code shows a warning screen. Press Enter. For sessions that you start from Telegram, the router presses Enter on that screen for you. Why the flag? explains what it does and why stolik needs it.

A topic named orbit-api appears in your group. Write in it from your phone.

To keep the variable, add export STOLIK_PLUGIN=1 to your shell profile. Then alias claude=tg-claude works too. Subcommands such as claude mcp and claude -p pass through unchanged.

Use this section in place of steps 1 and 2. Steps 3 to 5 of the Telegram guide stay the same. One install uses one chat app, so pick Telegram or Discord.

You need a Discord account and a server where you have Manage Server. The privacy check warns when someone else is in the server.

  1. Open the Discord Developer Portal. Choose New Application.
  2. Open Bot. Choose Reset Token, then copy the token. Discord shows it once. Setup asks for it next.
  3. Under Bot, turn on Message Content Intent. The bot cannot read messages without it.
  4. Keep Public Bot off. Then only the application’s owner can add the bot.
Terminal window
stolik setup --chat discord

Setup asks for the bot token. Typing is hidden. It then prints an invite link. Open the link and add the bot to your server. The invite needs Manage Server. It grants the rights stolik needs: view and send messages, read history, add reactions, attach files, manage channels and send voice messages.

Setup then prints a six-digit code. Add the bot to your server before you send the code. Send the code to the bot in a direct message, not in a channel. The code works once, for 5 minutes. After five wrong codes it stops. Run stolik setup --chat discord --pair to get a new code.

Setup shows the account that sent the code. Answer y to confirm it is you.

Setup stores the token as DISCORD_BOT_TOKEN in the secrets file, which only your user can read. It sets chat.app to discord in the config file. Your user id goes to chat.discord.ownerUserId.

In a text channel of your server, send !bind or /bind. That channel becomes the lobby. The bot answers there, and stolik keeps the lobby where it is.

Then follow steps 3 to 5 of the Telegram guide: start the router, add the plugin in Claude Code, and start a session.

Each project folder gets its own text channel, named after the folder. The channel sits under a category named stolik. The bot creates both.

  • Private. @everyone cannot view folder channels or the stolik categories. Only you and the bot can.
  • Idle. About 2 minutes after the last session in a folder ends, the channel moves to a category named stolik-idle. A session that starts again before then keeps the channel in stolik.
  • More categories. A category holds 50 channels. When one is full, stolik makes the next one: stolik 2, stolik 3, and so on. Idle folders use stolik-idle 2 and up in the same way.
  • Server limit. Discord allows 500 channels per server. Past that, stolik cannot make a folder channel. It logs the error, and the session uses the lobby.

Send commands as messages. Both / and ! work, so !bind and /bind do the same thing. For the list, see Commands.

stolik doctor runs privacy checks on the Discord server. The router runs the same checks at start and logs what it finds. The checks only warn. They never stop the router. They report:

  • Whether the bot is public. A public bot gets a warning.
  • Whether the Message Content intent is on.
  • How many members the server has. Expect two: you and the bot.
  • Whether @everyone can see the lobby, a stolik category or a folder channel. This check runs only when the server has more than two members.

Invites are not checked, because listing them needs Manage Server. Check them yourself under Server Settings, then Invites. Remove any invite you do not know.

Voice notes, voice cleanup and the digest use a local model worker: faster-whisper for speech and a small Qwen model for text. Models download on first use, load on demand and unload after 10 minutes idle.

Run stolik setup again and say yes at the model step. The worker lives in the package folder (ml/.venv), so you must be able to write to the global npm folder. If you cannot, set a prefix you own first with npm config set prefix ~/.local, then reinstall. It needs:

  • uv, which creates a Python 3.12 environment
  • a C++ compiler and CMake (the install builds llama-cpp-python from source)
  • the CUDA toolkit, if you want a GPU build. Without it you get a CPU build, which works and is slower.

The worker uses the CPU by default. To use a GPU, set gpu in config.json, for example { "cudaVisibleDevices": "0", "cudaDeviceOrder": "PCI_BUS_ID" }.

  • macOS (untested). brew install tmux node, then the same steps. The service is a LaunchAgent. Nobody ran this on a Mac yet. Tell us what breaks.
  • Windows (WSL2, untested). Install Ubuntu in WSL2, turn systemd on in /etc/wsl.conf, then follow the Linux steps inside WSL. WSL has no desktop session, so stolik treats you as always away and sends every answer.
  • Native Windows. Not supported.

stolik migrate copies your old tg-bridge settings and state into the stolik locations. It does not move anything. Your old files stay where they are.

  1. Stop the old service. Run systemctl --user disable --now tg-bridge. On macOS, run launchctl bootout gui/$(id -u)/com.tg-bridge.router. stolik migrate refuses to run while the old service is up.
  2. Run stolik migrate. stolik setup runs the same copy first when it finds the old files. Then start stolik with stolik service install --start.
  3. In Claude Code, remove the tg-bridge@indicozy plugin and add stolik@indicozy. The channel tools are now named mcp__stolik__…. Update any CLAUDE.md, hook or setting that names mcp__tg-bridge__.

Delete the old files after stolik works.

Terminal window
stolik doctor

Doctor checks Node, tmux and claude, the config and token file, the database, the addons and, with the token, the bot and its rights in the group. It names the check that fails.

On Discord, doctor also checks the bot token, the lobby channel and the stolik categories. It runs the privacy checks described above.