# 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).
