claude-link 0.2.1__tar.gz

claude_link-0.2.1/.github/workflows/publish.yml

@@ -0,0 +1,21 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

claude_link-0.2.1/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.env
+venv/
+claude.md
+PLAN.md

claude_link-0.2.1/CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing to claude-link
+
+Thanks for your interest! This doc explains how the project is built.
+
+## Architecture
+
+```
+src/claude_bridge/
+├── __init__.py     # Version string
+├── __main__.py     # python -m claude_bridge entry
+├── cli.py          # CLI argument parsing, startup checks
+├── config.py       # Config load/save, setup wizard, verification
+└── bot.py          # Telegram bot core, Claude CLI runner, queue
+```
+
+**5 files, ~450 lines total.** That's the whole project.
+
+### Flow
+
+```
+cli.py          →  Parses args, loads config, checks Claude is installed
+  ↓
+config.py       →  If no config: runs wizard (token, chat ID, verification)
+  ↓
+bot.py          →  Starts Telegram polling, listens for messages
+  ↓
+_send_to_claude →  Queues the message
+  ↓
+_queue_worker   →  Picks up message, acquires lock
+  ↓
+_run_claude     →  Spawns `claude -p "..." --output-format stream-json`
+  ↓                Streams stdout, parses JSON events, updates Telegram status
+  ↓                Logs tool usage to console
+  ↓
+response        →  Sends result back to Telegram
+```
+
+### Key design decisions
+
+**One dependency** — `python-telegram-bot>=20.0`. Voice transcription uses `httpx` which comes as a transitive dependency. No extra packages needed.
+
+**Subprocess, not SDK** — Claude Code is invoked as a CLI subprocess with `--output-format stream-json`. This means the bridge works with any Claude Code version without API coupling.
+
+**Queue + Lock** — Messages are queued and processed sequentially. Only one Claude process runs at a time. `/cancel` kills the process and drains the queue.
+
+**Cross-platform subprocess** — Uses `create_subprocess_exec` on Unix (no shell injection risk) and `create_subprocess_shell` with `list2cmdline` escaping on Windows (where exec can't find binaries on PATH).
+
+**Config as plain JSON** — `~/.claude-link.json` with `chmod 600`. No dotenv, no YAML, no environment variables.
+
+## Development setup
+
+```bash
+git clone https://github.com/Qsanti/claude-link.git
+cd claude-link
+python -m venv venv
+source venv/bin/activate  # or venv\Scripts\activate on Windows
+pip install -e .
+```
+
+Now `claude-link` runs from source.
+
+## Code style
+
+- Keep it simple. No abstractions for things that happen once.
+- No extra dependencies unless absolutely necessary.
+- Every file should be readable top to bottom in a few minutes.
+- Security by default (file permissions, auth checks, no shell on Unix).

claude_link-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Qsanti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

claude_link-0.2.1/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: claude-link
+Version: 0.2.1
+Summary: Connect Claude Code to Telegram in one command
+Project-URL: Homepage, https://github.com/Qsanti/claude-bridge
+Project-URL: Repository, https://github.com/Qsanti/claude-bridge
+Project-URL: Issues, https://github.com/Qsanti/claude-bridge/issues
+Author-email: Qsanti <santiagossc@live.com.ar>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,claude,claude-code,cli,telegram
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: python-telegram-bot>=20.0
+Description-Content-Type: text/markdown
+
+# claude-link
+
+Control Claude Code from your phone. Nothing more.
+
+```
+Phone → Telegram → claude-link → Claude Code → response → Phone
+```
+
+claude-link is not a bot. It has no AI, no logic, no cloud servers.
+It's a **bridge** — it forwards messages between Telegram and the Claude Code CLI running on your machine.
+
+You start it when you want. You stop it when you're done. That's it.
+
+Your existing Claude Code config, skills, CLAUDE.md, and project context — all there, because it's the same session running on your computer.
+
+## Install
+
+```bash
+pip install claude-link
+```
+
+## Run
+
+```bash
+claude-link
+```
+
+Just the first time, it walks you through connecting your Telegram bot. Takes 2 minutes.
+
+No daemon, no background process, no always-on server. It lives while your terminal lives.
+
+## Terminal output
+
+```
+[12:35:10] 📩 Message from Santiago: "list my projects"
+[12:35:10] 🤖 Claude working...
+[12:35:11]    📖 Reading CLAUDE.md
+[12:35:12]    ⚙️ Running: ls ~/projects
+[12:35:14] ✅ Done (4s)
+[12:35:14] 📤 Reply: "You have 3 projects..."
+```
+
+## Commands
+
+`/cancel` — stop current task and clear queue · `/new` — fresh conversation · `/status` — bot info · `/help` — all commands
+
+Voice messages supported with `claude-link --enable-voice` (requires OpenAI key).
+
+## Prerequisites
+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated
+- Python 3.10+
+- A Telegram bot token (from [@BotFather](https://t.me/BotFather))
+- Your Telegram Chat ID (from [@userinfobot](https://t.me/userinfobot))
+
+## Security
+
+Single-user only. Config stored with restricted permissions. No shell injection. Nothing stored remotely. Unauthorized attempts logged.
+
+## License
+
+MIT

claude_link-0.2.1/README.md

@@ -0,0 +1,62 @@
+# claude-link
+
+Control Claude Code from your phone. Nothing more.
+
+```
+Phone → Telegram → claude-link → Claude Code → response → Phone
+```
+
+claude-link is not a bot. It has no AI, no logic, no cloud servers.
+It's a **bridge** — it forwards messages between Telegram and the Claude Code CLI running on your machine.
+
+You start it when you want. You stop it when you're done. That's it.
+
+Your existing Claude Code config, skills, CLAUDE.md, and project context — all there, because it's the same session running on your computer.
+
+## Install
+
+```bash
+pip install claude-link
+```
+
+## Run
+
+```bash
+claude-link
+```
+
+Just the first time, it walks you through connecting your Telegram bot. Takes 2 minutes.
+
+No daemon, no background process, no always-on server. It lives while your terminal lives.
+
+## Terminal output
+
+```
+[12:35:10] 📩 Message from Santiago: "list my projects"
+[12:35:10] 🤖 Claude working...
+[12:35:11]    📖 Reading CLAUDE.md
+[12:35:12]    ⚙️ Running: ls ~/projects
+[12:35:14] ✅ Done (4s)
+[12:35:14] 📤 Reply: "You have 3 projects..."
+```
+
+## Commands
+
+`/cancel` — stop current task and clear queue · `/new` — fresh conversation · `/status` — bot info · `/help` — all commands
+
+Voice messages supported with `claude-link --enable-voice` (requires OpenAI key).
+
+## Prerequisites
+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated
+- Python 3.10+
+- A Telegram bot token (from [@BotFather](https://t.me/BotFather))
+- Your Telegram Chat ID (from [@userinfobot](https://t.me/userinfobot))
+
+## Security
+
+Single-user only. Config stored with restricted permissions. No shell injection. Nothing stored remotely. Unauthorized attempts logged.
+
+## License
+
+MIT

claude_link-0.2.1/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "claude-link"
+version = "0.2.1"
+description = "Connect Claude Code to Telegram in one command"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Qsanti", email = "santiagossc@live.com.ar" }]
+keywords = ["claude", "telegram", "ai", "cli", "claude-code"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Communications :: Chat",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "python-telegram-bot>=20.0",
+]
+
+[project.scripts]
+claude-link = "claude_bridge.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Qsanti/claude-bridge"
+Repository = "https://github.com/Qsanti/claude-bridge"
+Issues = "https://github.com/Qsanti/claude-bridge/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/claude_bridge"]
+
+[tool.hatch.build.targets.sdist]
+exclude = ["venv/", "dist/", "*.egg-info/"]

claude_link-0.2.1/src/claude_bridge/__init__.py

@@ -0,0 +1,3 @@
+"""claude-bridge — Connect Claude Code to Telegram in one command."""
+
+__version__ = "0.2.1"

claude_link-0.2.1/src/claude_bridge/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as: python -m claude_bridge"""
+
+from .cli import main
+
+main()

claude_link-0.2.1/src/claude_bridge/bot.py

@@ -0,0 +1,473 @@
+"""Telegram bot core — receives messages, runs Claude, logs everything."""
+
+import asyncio
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+from datetime import datetime
+from pathlib import Path
+
+import httpx
+from telegram import Update, Bot
+from telegram.ext import Application, CommandHandler, MessageHandler, filters, ContextTypes
+
+# Session file for conversation persistence
+SESSION_FILE = Path.home() / ".claude-link-session.json"
+
+# Queue + lock for sequential Claude CLI execution
+_claude_lock = asyncio.Lock()
+_message_queue: asyncio.Queue | None = None
+_active_proc: asyncio.subprocess.Process | None = None
+
+# Tool icons for console + Telegram status
+TOOL_ICONS = {
+    "Bash": "⚙️",
+    "Read": "📖",
+    "Edit": "✏️",
+    "Write": "📝",
+    "Grep": "🔍",
+    "Glob": "📁",
+    "WebFetch": "🌐",
+    "WebSearch": "🌐",
+    "Task": "🤖",
+    "Skill": "🎯",
+    "TodoWrite": "📋",
+}
+
+WELCOME_TEXT = (
+    "🌉 claude-link is online!\n\n"
+    "Send me a message and I'll forward it to Claude Code.\n\n"
+    "Commands:\n"
+    "/cancel — Stop current task\n"
+    "/new — Start fresh session\n"
+    "/status — Bot info\n"
+    "/help — All commands"
+)
+
+HELP_TEXT = (
+    "🌉 claude-link\n\n"
+    "Commands:\n"
+    "  /cancel — Stop current task + clear queue\n"
+    "  /new — Start a fresh conversation\n"
+    "  /status — Show bot info\n"
+    "  /help — Show this message\n\n"
+    "Everything else is sent directly to Claude."
+)
+
+
+def _ts() -> str:
+    """Timestamp for console logs."""
+    return datetime.now().strftime("%H:%M:%S")
+
+
+def _log(icon: str, msg: str):
+    """Print a timestamped log line."""
+    print(f"[{_ts()}] {icon} {msg}")
+
+
+def _tool_label(name: str, inp: dict) -> str:
+    """Short description of a tool call."""
+    icon = TOOL_ICONS.get(name, "🔧")
+    if name == "Read" and "file_path" in inp:
+        return f"{icon} Reading {os.path.basename(inp['file_path'])}"
+    if name in ("Edit", "Write") and "file_path" in inp:
+        return f"{icon} {'Editing' if name == 'Edit' else 'Writing'} {os.path.basename(inp['file_path'])}"
+    if name == "Bash" and "command" in inp:
+        return f"{icon} Running: {inp['command'][:60]}"
+    if name == "Grep" and "pattern" in inp:
+        return f"{icon} Searching: {inp['pattern'][:40]}"
+    if name == "Glob" and "pattern" in inp:
+        return f"{icon} Finding: {inp['pattern'][:40]}"
+    if name == "Task" and "description" in inp:
+        return f"{icon} Sub-agent: {inp['description'][:50]}"
+    return f"{icon} {name}"
+
+
+def _load_session() -> str | None:
+    if SESSION_FILE.exists():
+        data = json.loads(SESSION_FILE.read_text())
+        return data.get("session_id")
+    return None
+
+
+def _save_session(session_id: str | None):
+    SESSION_FILE.write_text(json.dumps({"session_id": session_id}) + "\n")
+    try:
+        os.chmod(SESSION_FILE, 0o600)
+    except OSError:
+        pass
+
+
+def _clear_session():
+    if SESSION_FILE.exists():
+        SESSION_FILE.unlink()
+
+
+def _transcribe_audio(audio_path: str, api_key: str) -> str | None:
+    """Transcribe audio using OpenAI Whisper API via httpx."""
+    try:
+        with open(audio_path, "rb") as f:
+            resp = httpx.post(
+                "https://api.openai.com/v1/audio/transcriptions",
+                headers={"Authorization": f"Bearer {api_key}"},
+                data={"model": "whisper-1"},
+                files={"file": ("audio.ogg", f, "audio/ogg")},
+                timeout=30,
+            )
+        if resp.status_code == 200:
+            return resp.json().get("text", "").strip()
+    except Exception as e:
+        _log("⚠️", f"Transcription error: {type(e).__name__}")
+    return None
+
+
+async def _run_claude(message: str, cfg: dict, status_msg, session_id: str | None) -> tuple[str | None, str | None]:
+    """Run Claude CLI with stream-json, update Telegram status + console logs."""
+    global _active_proc
+    claude_path = shutil.which(cfg.get("claude_path", "claude")) or cfg.get("claude_path", "claude")
+    workspace = cfg.get("workspace", str(Path.home()))
+
+    args = ["-p", message, "--output-format", "stream-json", "--verbose"]
+    if session_id:
+        args.extend(["--resume", session_id])
+
+    env = {k: v for k, v in os.environ.items() if k != "CLAUDECODE"}
+
+    # Use exec on Unix (safer, no shell injection risk), shell only on Windows
+    if sys.platform == "win32":
+        cmd_line = subprocess.list2cmdline([claude_path] + args)
+        proc = await asyncio.create_subprocess_shell(
+            cmd_line,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=workspace,
+            env=env,
+        )
+    else:
+        proc = await asyncio.create_subprocess_exec(
+            claude_path, *args,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=workspace,
+            env=env,
+        )
+
+    _active_proc = proc
+
+    status_lines = ["⏳ Working..."]
+    last_edit = 0
+    result_text = None
+    new_session_id = None
+    expired = False
+    start = time.time()
+
+    async def _update_status():
+        nonlocal last_edit
+        now = time.time()
+        if now - last_edit < 2:
+            return
+        last_edit = now
+        try:
+            await status_msg.edit_text("\n".join(status_lines[-10:]))
+        except Exception:
+            pass
+
+    async for raw in proc.stdout:
+        line = raw.decode("utf-8", errors="replace").strip()
+        if not line:
+            continue
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError:
+            if "no conversation found" in line.lower() or "session" in line.lower():
+                expired = True
+            continue
+
+        etype = event.get("type")
+
+        if etype == "assistant":
+            for block in event.get("message", {}).get("content", []):
+                if block.get("type") == "tool_use":
+                    label = _tool_label(block.get("name", ""), block.get("input", {}))
+                    status_lines.append(label)
+                    _log("  ", label)
+                    await _update_status()
+
+        elif etype == "result":
+            result_text = event.get("result")
+            new_session_id = event.get("session_id")
+
+    await proc.wait()
+    _active_proc = None
+
+    elapsed = int(time.time() - start)
+    status_lines.append(f"✅ Done ({elapsed}s)")
+    try:
+        await status_msg.edit_text("\n".join(status_lines[-10:]))
+    except Exception:
+        pass
+
+    if expired:
+        return None, None
+
+    if result_text is None:
+        stderr = ""
+        if proc.stderr:
+            stderr = (await proc.stderr.read()).decode("utf-8", errors="replace")
+        if "no conversation found" in stderr.lower():
+            return None, None
+        return stderr or "No response from Claude.", None
+
+    return result_text, new_session_id
+
+
+async def _queue_worker():
+    """Process queued messages one at a time."""
+    while True:
+        text, update, cfg = await _message_queue.get()
+        try:
+            async with _claude_lock:
+                await _send_to_claude_inner(text, update, cfg)
+        except Exception as e:
+            _log("⚠️", f"Queue worker error: {type(e).__name__}")
+        finally:
+            _message_queue.task_done()
+
+
+async def _send_to_claude(text: str, update: Update, cfg: dict):
+    """Enqueue a message for Claude. If busy, notifies the user it's queued."""
+    if _claude_lock.locked():
+        pos = _message_queue.qsize() + 1
+        await update.message.reply_text(f"📋 Queued (position {pos}). Will process when current task finishes.")
+        _log("📋", f"Message queued (position {pos})")
+
+    await _message_queue.put((text, update, cfg))
+
+
+async def _send_to_claude_inner(text: str, update: Update, cfg: dict):
+    """Inner logic: send text to Claude and reply (called under lock)."""
+    status_msg = await update.message.reply_text("⏳ Working...")
+    _log("🤖", "Claude working...")
+
+    session_id = _load_session()
+
+    # Try with existing session
+    if session_id:
+        response, new_sid = await _run_claude(text, cfg, status_msg, session_id)
+        if response is None:
+            _log("🔄", "Session expired, starting fresh")
+            _clear_session()
+            session_id = None
+
+    # Fresh session
+    if not session_id:
+        prompt = f"First, silently read CLAUDE.md for context. Then respond to: {text}"
+        response, new_sid = await _run_claude(prompt, cfg, status_msg, None)
+
+    if new_sid:
+        _save_session(new_sid)
+
+    if not response or not response.strip():
+        response = "(No response from Claude)"
+
+    # Truncate if too long for Telegram
+    if len(response) > 4000:
+        response = response[:4000] + "\n\n... (truncated)"
+
+    _log("📤", f"Reply: \"{response[:80]}{'...' if len(response) > 80 else ''}\"")
+    await update.message.reply_text(response)
+
+
+def _check_auth(update: Update, cfg: dict) -> bool:
+    """Check if the message is from the authorized chat. Logs unauthorized attempts."""
+    if update.effective_chat.id != cfg["chat_id"]:
+        user = update.effective_user
+        name = f"{user.first_name or ''} (id={user.id})" if user else f"id={update.effective_chat.id}"
+        _log("⛔", f"Unauthorized access attempt from {name}")
+        return False
+    return True
+
+
+async def _handle_message(update: Update, context: ContextTypes.DEFAULT_TYPE):
+    """Handle incoming text messages."""
+    cfg = context.bot_data["cfg"]
+
+    if not _check_auth(update, cfg):
+        return
+
+    text = update.message.text
+    user = update.effective_user.first_name or "User"
+
+    _log("📩", f"Message from {user}: \"{text[:80]}{'...' if len(text) > 80 else ''}\"")
+
+    await _send_to_claude(text, update, cfg)
+
+
+async def _handle_voice(update: Update, context: ContextTypes.DEFAULT_TYPE):
+    """Handle voice messages — transcribe and send to Claude."""
+    cfg = context.bot_data["cfg"]
+
+    if not _check_auth(update, cfg):
+        return
+
+    api_key = cfg.get("openai_api_key")
+    if not api_key:
+        await update.message.reply_text(
+            "🎤 Voice messages are not enabled.\n\n"
+            "To enable, run in your terminal:\n"
+            "  claude-bridge --enable-voice"
+        )
+        return
+
+    user = update.effective_user.first_name or "User"
+    _log("🎤", f"Voice message from {user}")
+
+    await update.message.reply_text("🎤 Transcribing...")
+
+    voice = update.message.voice
+    file = await context.bot.get_file(voice.file_id)
+
+    with tempfile.NamedTemporaryFile(suffix=".ogg", delete=False) as tmp:
+        tmp_path = tmp.name
+
+    await file.download_to_drive(tmp_path)
+
+    try:
+        transcript = _transcribe_audio(tmp_path, api_key)
+
+        if not transcript:
+            await update.message.reply_text("❌ Could not transcribe voice message.")
+            return
+
+        _log("📝", f"Transcribed: \"{transcript[:80]}{'...' if len(transcript) > 80 else ''}\"")
+        await update.message.reply_text(f"📝 {transcript}")
+
+        voice_text = f"[This is a voice message transcription]: {transcript}"
+        await _send_to_claude(voice_text, update, cfg)
+
+    finally:
+        if os.path.exists(tmp_path):
+            os.remove(tmp_path)
+
+
+def _drain_queue() -> int:
+    """Empty the message queue. Returns number of messages cleared."""
+    count = 0
+    while not _message_queue.empty():
+        try:
+            _message_queue.get_nowait()
+            _message_queue.task_done()
+            count += 1
+        except asyncio.QueueEmpty:
+            break
+    return count
+
+
+async def _handle_cancel(update: Update, context: ContextTypes.DEFAULT_TYPE):
+    """Handle /cancel command — kill active Claude process and clear queue."""
+    cfg = context.bot_data["cfg"]
+    if not _check_auth(update, cfg):
+        return
+
+    global _active_proc
+
+    if _active_proc is None or _active_proc.returncode is not None:
+        await update.message.reply_text("Nothing running.")
+        return
+
+    # Kill the process
+    try:
+        _active_proc.terminate()
+        try:
+            await asyncio.wait_for(_active_proc.wait(), timeout=2)
+        except asyncio.TimeoutError:
+            _active_proc.kill()
+    except ProcessLookupError:
+        pass
+
+    _active_proc = None
+
+    # Drain the queue
+    cleared = _drain_queue()
+
+    suffix = f" ({cleared} queued message{'s' if cleared != 1 else ''} cleared)" if cleared else ""
+    _log("⛔", f"Cancelled by user{suffix}")
+    await update.message.reply_text(f"⛔ Cancelled{suffix}")
+
+
+async def _handle_new(update: Update, context: ContextTypes.DEFAULT_TYPE):
+    """Handle /new command — clear session."""
+    cfg = context.bot_data["cfg"]
+    if not _check_auth(update, cfg):
+        return
+
+    _clear_session()
+    _log("🔄", "Session cleared by user")
+    await update.message.reply_text("Session cleared. Next message starts fresh.")
+
+
+async def _handle_status(update: Update, context: ContextTypes.DEFAULT_TYPE):
+    """Handle /status command."""
+    cfg = context.bot_data["cfg"]
+    if not _check_auth(update, cfg):
+        return
+
+    has_session = _load_session() is not None
+    voice = "Enabled" if cfg.get("openai_api_key") else "Disabled"
+    await update.message.reply_text(
+        f"🌉 claude-link\n"
+        f"Session: {'Active' if has_session else 'None'}\n"
+        f"Voice: {voice}\n"
+        f"Workspace: {cfg['workspace']}\n"
+        f"Claude: {cfg.get('claude_path', 'claude')}"
+    )
+
+
+async def _handle_help(update: Update, context: ContextTypes.DEFAULT_TYPE):
+    """Handle /help command."""
+    cfg = context.bot_data["cfg"]
+    if not _check_auth(update, cfg):
+        return
+
+    await update.message.reply_text(HELP_TEXT)
+
+
+async def _send_welcome(app: Application):
+    """Send a welcome message and start the queue worker."""
+    global _message_queue
+    _message_queue = asyncio.Queue()
+    asyncio.create_task(_queue_worker())
+
+    cfg = app.bot_data["cfg"]
+    try:
+        await app.bot.send_message(chat_id=cfg["chat_id"], text=WELCOME_TEXT)
+        _log("📤", "Welcome message sent")
+    except Exception as e:
+        _log("⚠️", f"Could not send welcome message: {e}")
+
+
+def run_bot(cfg: dict):
+    """Start the Telegram bot. Blocks until Ctrl+C."""
+    _log("🚀", "Bot starting...")
+
+    app = Application.builder().token(cfg["telegram_token"]).build()
+    app.bot_data["cfg"] = cfg
+
+    app.add_handler(CommandHandler("cancel", _handle_cancel))
+    app.add_handler(CommandHandler("new", _handle_new))
+    app.add_handler(CommandHandler("status", _handle_status))
+    app.add_handler(CommandHandler("help", _handle_help))
+    app.add_handler(MessageHandler(filters.VOICE, _handle_voice))
+    app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, _handle_message))
+
+    # Send welcome message on startup
+    app.post_init = _send_welcome
+
+    _log("✅", f"Listening for messages from chat {cfg['chat_id']}")
+    print(f"[{_ts()}]    Press Ctrl+C to stop\n")
+
+    app.run_polling(allowed_updates=Update.ALL_TYPES)

claude_link-0.2.1/src/claude_bridge/cli.py

@@ -0,0 +1,70 @@
+"""CLI entry point — argument parsing and startup."""
+
+import argparse
+import shutil
+import sys
+
+from . import __version__
+from . import config
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="claude-link",
+        description="Connect Claude Code to Telegram in one command",
+    )
+    parser.add_argument(
+        "-v", "--version", action="version", version=f"claude-link {__version__}"
+    )
+    parser.add_argument(
+        "--setup", action="store_true", help="Re-run the setup wizard"
+    )
+    parser.add_argument(
+        "--enable-voice", action="store_true", help="Enable voice transcription (requires OpenAI key)"
+    )
+    parser.add_argument(
+        "--workspace", type=str, help="Override workspace directory"
+    )
+    args = parser.parse_args()
+
+    # Handle --enable-voice
+    if args.enable_voice:
+        cfg = config.load()
+        if cfg is None:
+            print("❌ Run claude-link first to complete initial setup.")
+            sys.exit(1)
+        api_key = config.voice_wizard()
+        if api_key:
+            cfg["openai_api_key"] = api_key
+            config.save(cfg)
+        sys.exit(0)
+
+    # Load or create config
+    cfg = config.load()
+    if cfg is None or args.setup:
+        cfg = config.setup_wizard()
+
+    # Override workspace if provided
+    if args.workspace:
+        cfg["workspace"] = args.workspace
+
+    # Check claude is available
+    claude_path = cfg.get("claude_path", "claude")
+    if not shutil.which(claude_path):
+        print(f"❌ Claude Code not found at '{claude_path}'")
+        print("   Install it: https://docs.anthropic.com/en/docs/claude-code")
+        print(f"   Or set a custom path with: claude-link --setup")
+        sys.exit(1)
+
+    # Start the bot
+    voice = "on" if cfg.get("openai_api_key") else "off"
+    print(f"\n🌉 claude-link v{__version__}")
+    print(f"   Workspace: {cfg['workspace']}")
+    print(f"   Claude: {claude_path}")
+    print(f"   Chat ID: {cfg['chat_id']}")
+    print(f"   Voice: {voice}")
+    print()
+
+    from .bot import run_bot
+
+    run_bot(cfg)

claude_link-0.2.1/src/claude_bridge/config.py

@@ -0,0 +1,223 @@
+"""Configuration management — load/save ~/.claude-bridge.json"""
+
+import json
+import os
+import secrets
+from pathlib import Path
+
+import httpx
+
+CONFIG_PATH = Path.home() / ".claude-link.json"
+
+DEFAULTS = {
+    "claude_path": "claude",
+    "workspace": str(Path.home()),
+}
+
+BOT_DESCRIPTION = "Claude Code on Telegram — powered by claude-link"
+BOT_SHORT_DESCRIPTION = "Send me a message and I'll forward it to Claude Code"
+BOT_COMMANDS = [
+    {"command": "cancel", "description": "Stop current task and clear queue"},
+    {"command": "new", "description": "Start a fresh conversation"},
+    {"command": "status", "description": "Show bot info"},
+    {"command": "help", "description": "Show available commands"},
+]
+
+
+def load() -> dict | None:
+    """Load config from disk. Returns None if not found."""
+    if not CONFIG_PATH.exists():
+        return None
+    return json.loads(CONFIG_PATH.read_text())
+
+
+def save(config: dict):
+    """Save config to disk with restricted permissions (owner-only)."""
+    CONFIG_PATH.write_text(json.dumps(config, indent=2) + "\n")
+    try:
+        os.chmod(CONFIG_PATH, 0o600)
+    except OSError:
+        pass  # Windows doesn't support Unix permissions
+
+
+def _bot_api(token: str, method: str, payload: dict = None) -> dict | None:
+    """Call a Telegram Bot API method."""
+    try:
+        url = f"https://api.telegram.org/bot{token}/{method}"
+        if payload:
+            resp = httpx.post(url, json=payload, timeout=10)
+        else:
+            resp = httpx.get(url, timeout=10)
+        data = resp.json()
+        if data.get("ok"):
+            return data.get("result")
+    except Exception:
+        pass
+    return None
+
+
+def _configure_bot(token: str):
+    """Auto-configure bot description and commands."""
+    _bot_api(token, "setMyDescription", {"description": BOT_DESCRIPTION})
+    _bot_api(token, "setMyShortDescription", {"short_description": BOT_SHORT_DESCRIPTION})
+    _bot_api(token, "setMyCommands", {"commands": BOT_COMMANDS})
+    print("  ✅ Bot configured (description + commands)")
+
+
+def _verify_telegram(token: str, chat_id: int) -> bool:
+    """Send a verification code via Telegram and ask user to confirm."""
+    code = str(secrets.randbelow(9000) + 1000)
+
+    print("  🔐 Sending verification code to your Telegram...")
+
+    resp = _bot_api(token, "sendMessage", {
+        "chat_id": chat_id,
+        "text": f"🌉 claude-link verification code:\n\n🔑 {code}\n\nEnter this code in your terminal to complete setup.",
+    })
+
+    if resp is None:
+        print("\n  ❌ Could not send message.")
+        print("  → Make sure you've opened the bot link above and pressed Start!")
+        return False
+
+    print()
+    print("  📱 Check your Telegram — a code was sent!")
+    user_code = input("  Enter the 4-digit code: ").strip()
+
+    if user_code == code:
+        print("  ✅ Verified!\n")
+        return True
+
+    # One retry
+    print("  ❌ Wrong code. Try once more:")
+    user_code = input("  Enter the 4-digit code: ").strip()
+
+    if user_code == code:
+        print("  ✅ Verified!\n")
+        return True
+
+    print("  ❌ Verification failed. Check your token and chat ID.\n")
+    return False
+
+
+def voice_wizard() -> str | None:
+    """Mini-wizard to enable voice transcription."""
+    print()
+    print("🎤 Enable voice transcription")
+    print("=" * 40)
+    print("  Requires an OpenAI API key (for Whisper)")
+    print("  → Get one at https://platform.openai.com/api-keys")
+    print()
+
+    api_key = input("  OpenAI API Key: ").strip()
+    if not api_key:
+        print("  ❌ Cancelled.\n")
+        return None
+
+    # Validate key with a simple API call
+    print("  Validating key...")
+    try:
+        resp = httpx.get(
+            "https://api.openai.com/v1/models",
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=10,
+        )
+        if resp.status_code != 200:
+            print("  ❌ Invalid API key.\n")
+            return None
+    except Exception:
+        print("  ❌ Could not reach OpenAI API.\n")
+        return None
+
+    print("  ✅ Voice transcription enabled!\n")
+    return api_key
+
+
+def setup_wizard() -> dict:
+    """Interactive first-time setup."""
+    print()
+    print("🌉 claude-link — Setup")
+    print("=" * 40)
+    print("  You only need to do this once.")
+    print()
+
+    # Step 1: Bot Token
+    print("Step 1: Create a Telegram bot")
+    print("  → Open https://t.me/BotFather")
+    print("  → Send /newbot and follow the steps")
+    print("  → Copy the token it gives you")
+    print()
+    token = input("  Bot Token: ").strip()
+    if not token:
+        print("\n❌ Token is required.")
+        raise SystemExit(1)
+
+    # Validate token and get bot info
+    print("\n  Validating token...")
+    bot_info = _bot_api(token, "getMe")
+    if not bot_info:
+        print("  ❌ Invalid token. Please check and try again.")
+        raise SystemExit(1)
+
+    bot_username = bot_info.get("username", "")
+    bot_name = bot_info.get("first_name", "your bot")
+    print(f"  ✅ Connected to @{bot_username} ({bot_name})")
+    print()
+
+    # Auto-configure bot
+    _configure_bot(token)
+    print()
+
+    # Step 2: Chat ID
+    print("Step 2: Get your Chat ID")
+    print("  → Open https://t.me/userinfobot")
+    print("  → It will reply with your ID (a number)")
+    print()
+    chat_id = input("  Chat ID: ").strip()
+    if not chat_id or not chat_id.lstrip("-").isdigit():
+        print("\n  ❌ Valid Chat ID is required (must be a number).")
+        raise SystemExit(1)
+    print()
+
+    # Step 3: Verify connection
+    print("Step 3: Verify connection")
+    print(f"  → Open your bot: https://t.me/{bot_username}")
+    print("  → Press Start if you haven't already")
+    print()
+    input("  Press Enter when ready...")
+    print()
+
+    if not _verify_telegram(token, int(chat_id)):
+        raise SystemExit(1)
+
+    # Step 4: Claude path
+    print("Step 4: Claude Code CLI path")
+    print(f"  → Press Enter to use default: {DEFAULTS['claude_path']}")
+    print("  → Only change if claude is installed somewhere else")
+    claude_path = input(f"  Claude path [{DEFAULTS['claude_path']}]: ").strip()
+    print()
+
+    # Step 5: Workspace
+    print("Step 5: Workspace directory")
+    print("  → This is where Claude will work (read/edit files)")
+    print(f"  → Press Enter to use default: {DEFAULTS['workspace']}")
+    workspace = input(f"  Workspace [{DEFAULTS['workspace']}]: ").strip()
+    print()
+
+    config = {
+        "telegram_token": token,
+        "chat_id": int(chat_id),
+        "claude_path": claude_path or DEFAULTS["claude_path"],
+        "workspace": workspace or DEFAULTS["workspace"],
+    }
+
+    save(config)
+    print(f"✅ Config saved to {CONFIG_PATH}")
+    print()
+
+    # Tip about bot photo
+    print("💡 Tip: To set a profile photo for your bot,")
+    print("   send /setuserpic to @BotFather")
+    print()
+
+    return config