link-project-to-chat 0.4.0

Link a project directory to a Telegram bot that chats with Claude

link-project-to-chat

Chat with Claude about a project via Telegram. Links a local directory to a Telegram bot — send messages, get responses with full project context.

Security warning

This tool runs claude --dangerously-skip-permissions and exposes a /run command for arbitrary shell execution. It is a remote shell on your machine. Only use it with a bot token you control and never share the token.

Access is restricted to a single Telegram username. On first contact, the bot locks in that user's numeric Telegram ID — subsequent requests are validated by ID, not username, so a username change cannot bypass access.

Requirements

• Python 3.11+
• Claude Code installed and authenticated (claude on PATH)
• A Telegram bot token — create a bot via @BotFather on Telegram

Install

pipx install link-project-to-chat

Usage

Quick start (no config file)

link-project-to-chat start --path /path/to/project --token YOUR_BOT_TOKEN --username your_telegram_username

With config

# Set your Telegram username (once)
link-project-to-chat configure --username your_telegram_username

# Link a project
link-project-to-chat link /path/to/project --token YOUR_BOT_TOKEN

# Start the bot
link-project-to-chat start

Multiple projects

Each project needs its own bot token. Start them in separate terminals:

link-project-to-chat start --project project-a
link-project-to-chat start --project project-b

Example session

You: what does the auth module do?
Claude: The auth module handles JWT token validation and...

You: /run pytest tests/auth/ -x
Running 12 tests...
12 passed in 3.81s

You: add a test for expired token handling
Claude: I'll add a test for that. [edits file]...

You: /tasks
+ #1 [command] pytest
+ #2 [claude] add a test for expired token...

How it works

Claude messages and /run commands both execute in parallel — they don't block each other. Claude messages share the same session context, so responses build on each other even when sent concurrently.

Commands

Command	Description
(message)	Chat with Claude in the project context
/run <cmd>	Run a shell command in the project directory
/tasks	List active tasks
/log <id>	Show task output
/cancel [id|all]	Cancel tasks
/model haiku/sonnet/opus	Set Claude model
/effort low/medium/high/max	Set Claude thinking depth
/compact	Compress session context
/reset	Clear the Claude session
/status	Show bot status
/help	Show available commands

CLI reference

link-project-to-chat configure --username USER
link-project-to-chat link <path> --token TOKEN [--name NAME]
link-project-to-chat unlink <name>
link-project-to-chat list
link-project-to-chat start [--project NAME] [--path PATH] [--token TOKEN] [--username USER] [--session-id ID] [--model MODEL]

Config is stored at ~/.link-project-to-chat/config.json.

Planned features

• Discord support — same interface over Discord instead of Telegram
• Voice commands — transcribe voice messages via a speech-to-text service and forward as text prompts
• Other coding agents — pluggable backend to support agents beyond Claude Code (e.g. Aider)

Contributions welcome.

License

MIT