@alexnodeland/claude-telegram 0.1.4 → 0.2.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2025-03-22
+
+### Added
+
+- **npm distribution** — install via `bun add -g @alexnodeland/claude-telegram`
+- **Daemon script** — `claude-telegram-daemon install` sets up launchd (macOS) or systemd (Linux) automatically
+- **CONTRIBUTING.md** — development setup, code style, testing, and PR guidelines
+- **GitHub Release workflow** — tag-triggered CI, GitHub Release, and npm publish with provenance
+
+### Changed
+
+- Quick start defaults to npm install instead of git clone
+- Orchestrator and channel mode docs updated for npm install path
+
 ## [0.1.0] - 2025-03-22
 
 ### Added
@@ -23,4 +37,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **HTML formatting** — all output uses Telegram HTML parse mode for reliable rendering
 - **Zero Telegram SDK** — all API calls use native `fetch`
 
+[0.2.0]: https://github.com/alexnodeland/claude-telegram/releases/tag/v0.2.0
 [0.1.0]: https://github.com/alexnodeland/claude-telegram/releases/tag/v0.1.0

package/README.md

@@ -4,6 +4,7 @@
 
 **Control Claude Code from Telegram — run tasks, review diffs, and ship code from your phone.**
 
+[![npm](https://img.shields.io/npm/v/@alexnodeland/claude-telegram?color=cc785c)](https://www.npmjs.com/package/@alexnodeland/claude-telegram)
 [![GitHub Release](https://img.shields.io/github/v/release/alexnodeland/claude-telegram?style=flat&color=cc785c)](https://github.com/alexnodeland/claude-telegram/releases)
 [![CI](https://img.shields.io/github/actions/workflow/status/alexnodeland/claude-telegram/ci.yml?branch=main&label=CI)](https://github.com/alexnodeland/claude-telegram/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -54,19 +55,54 @@ Claude Telegram gives you full Claude Code access from any Telegram client — p
 
 ## Quick start
 
-**1. Create a Telegram bot** — message [@BotFather](https://t.me/BotFather), send `/newbot`, copy the token.
+### Prerequisites
 
-**2. Install and run:**
+- [Bun](https://bun.sh) >= 1.1
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) >= 2.1
+- A Telegram bot token (message [@BotFather](https://t.me/BotFather), send `/newbot`, copy the token)
+
+### Install and run
 
 ```bash
-git clone https://github.com/alexnodeland/claude-telegram.git
-cd claude-telegram
-bun install
+# Install the package
+bun add -g @alexnodeland/claude-telegram
+
+# Set your bot token
 export TELEGRAM_BOT_TOKEN=your_token_here
-bun run start:orchestrator
+
+# Start the orchestrator
+claude-telegram-orchestrator
 ```
 
-**3. Pair your Telegram account** — send `/start` to your bot, then enter the pairing code shown in your terminal.
+Or run directly without installing:
+
+```bash
+TELEGRAM_BOT_TOKEN=your_token_here bunx @alexnodeland/claude-telegram/src/orchestrator.ts
+```
+
+### Pair your Telegram account
+
+1. Send `/start` to your bot in Telegram
+2. An already-approved user sends `/approve <CODE>` with the 6-character pairing code
+
+To pre-approve users on first run, set `TELEGRAM_ALLOWED_USERS` with comma-separated Telegram user IDs:
+
+```bash
+TELEGRAM_ALLOWED_USERS=783772449 claude-telegram-orchestrator
+```
+
+### Running as a daemon
+
+A built-in script sets up launchd (macOS) or systemd (Linux) automatically:
+
+```bash
+claude-telegram-daemon install    # install and start
+claude-telegram-daemon status     # check if running
+claude-telegram-daemon logs       # tail logs
+claude-telegram-daemon uninstall  # stop and remove
+```
+
+Auto-restarts on crash and starts on login. See the [orchestrator docs](docs/orchestrator-mode.md#running-as-a-daemon) for manual setup options.
 
 > [!TIP]
 > The **orchestrator mode** above is standalone and manages its own Claude sessions. There's also a [channel mode](docs/channel-mode.md) that attaches Telegram to an existing Claude Code session as an MCP plugin.
@@ -173,18 +209,11 @@ Anything that isn't a command is sent as a prompt to Claude.
 | [Channel Mode](docs/channel-mode.md) | MCP channel plugin setup, pairing, access commands, tools |
 | [Architecture](docs/architecture.md) | System design, module map, security model, data flow |
 | [Changelog](CHANGELOG.md) | Release history |
+| [Contributing](CONTRIBUTING.md) | Development setup, code style, testing, pull requests |
 
-## Development
-
-```bash
-just setup             # Install deps + configure git hooks
-just dev-orchestrator  # Watch mode
-just ci                # Typecheck + lint + test (112 tests)
-just fix               # Auto-fix lint/format
-just release 1.1.0    # Tag a release
-```
+## Contributing
 
-See [CLAUDE.md](CLAUDE.md) for architecture details and contributor guidelines.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
 
 ## License
 

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@alexnodeland/claude-telegram",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Claude Code Channel plugin + standalone orchestrator bridging Telegram to Claude Code sessions",
   "module": "src/index.ts",
   "main": "src/index.ts",
   "type": "module",
   "bin": {
     "claude-telegram": "./src/index.ts",
-    "claude-telegram-orchestrator": "./src/orchestrator.ts"
+    "claude-telegram-orchestrator": "./src/orchestrator.ts",
+    "claude-telegram-daemon": "./scripts/daemon.sh"
   },
   "scripts": {
     "start": "bun run src/index.ts",
@@ -36,6 +37,7 @@
   },
   "files": [
     "src/",
+    "scripts/",
     "LICENSE",
     "README.md",
     "CHANGELOG.md"

package/scripts/daemon.sh

@@ -0,0 +1,157 @@
+#!/usr/bin/env bash
+# Install/uninstall claude-telegram as a system daemon.
+# Usage: daemon.sh install | uninstall | status | logs
+set -euo pipefail
+
+# Resolve paths
+BUN="$(which bun 2>/dev/null || echo "$HOME/.bun/bin/bun")"
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+ORCHESTRATOR="$SCRIPT_DIR/src/orchestrator.ts"
+TOKEN="${TELEGRAM_BOT_TOKEN:-}"
+
+if [ -z "$TOKEN" ] && [ "$1" != "uninstall" ] && [ "$1" != "status" ] && [ "$1" != "logs" ]; then
+  echo "Error: TELEGRAM_BOT_TOKEN is not set"
+  echo "  export TELEGRAM_BOT_TOKEN=your_token_here"
+  exit 1
+fi
+
+# ── macOS (launchd) ─────────────────────────────────────────────────────────
+
+PLIST="$HOME/Library/LaunchAgents/com.claude-telegram.plist"
+
+install_launchd() {
+  cat > "$PLIST" << EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.claude-telegram</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>$BUN</string>
+        <string>run</string>
+        <string>$ORCHESTRATOR</string>
+    </array>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>TELEGRAM_BOT_TOKEN</key>
+        <string>$TOKEN</string>
+        <key>PATH</key>
+        <string>/usr/local/bin:/usr/bin:/bin:$HOME/.bun/bin</string>
+    </dict>
+    <key>KeepAlive</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>/tmp/claude-telegram.log</string>
+    <key>StandardErrorPath</key>
+    <string>/tmp/claude-telegram.log</string>
+</dict>
+</plist>
+EOF
+  launchctl load "$PLIST"
+  echo "Daemon installed and started."
+  echo "  Logs: tail -f /tmp/claude-telegram.log"
+  echo "  Stop: $0 uninstall"
+}
+
+uninstall_launchd() {
+  if [ -f "$PLIST" ]; then
+    launchctl unload "$PLIST" 2>/dev/null || true
+    rm -f "$PLIST"
+    echo "Daemon stopped and removed."
+  else
+    echo "No daemon installed."
+  fi
+}
+
+status_launchd() {
+  if launchctl list com.claude-telegram &>/dev/null; then
+    echo "Running"
+    launchctl list com.claude-telegram
+  else
+    echo "Not running"
+  fi
+}
+
+logs_launchd() {
+  tail -f /tmp/claude-telegram.log
+}
+
+# ── Linux (systemd) ─────────────────────────────────────────────────────────
+
+SERVICE_DIR="$HOME/.config/systemd/user"
+SERVICE="$SERVICE_DIR/claude-telegram.service"
+
+install_systemd() {
+  mkdir -p "$SERVICE_DIR"
+  cat > "$SERVICE" << EOF
+[Unit]
+Description=Claude Telegram Orchestrator
+After=network.target
+
+[Service]
+ExecStart=$BUN run $ORCHESTRATOR
+Environment=TELEGRAM_BOT_TOKEN=$TOKEN
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+EOF
+  systemctl --user daemon-reload
+  systemctl --user enable --now claude-telegram
+  echo "Daemon installed and started."
+  echo "  Logs: journalctl --user -u claude-telegram -f"
+  echo "  Stop: $0 uninstall"
+}
+
+uninstall_systemd() {
+  if [ -f "$SERVICE" ]; then
+    systemctl --user disable --now claude-telegram 2>/dev/null || true
+    rm -f "$SERVICE"
+    systemctl --user daemon-reload
+    echo "Daemon stopped and removed."
+  else
+    echo "No daemon installed."
+  fi
+}
+
+status_systemd() {
+  systemctl --user status claude-telegram 2>/dev/null || echo "Not running"
+}
+
+logs_systemd() {
+  journalctl --user -u claude-telegram -f
+}
+
+# ── Dispatch ─────────────────────────────────────────────────────────────────
+
+ACTION="${1:-install}"
+OS="$(uname -s)"
+
+case "$OS" in
+  Darwin)
+    case "$ACTION" in
+      install)   install_launchd ;;
+      uninstall) uninstall_launchd ;;
+      status)    status_launchd ;;
+      logs)      logs_launchd ;;
+      *) echo "Usage: $0 install|uninstall|status|logs"; exit 1 ;;
+    esac
+    ;;
+  Linux)
+    case "$ACTION" in
+      install)   install_systemd ;;
+      uninstall) uninstall_systemd ;;
+      status)    status_systemd ;;
+      logs)      logs_systemd ;;
+      *) echo "Usage: $0 install|uninstall|status|logs"; exit 1 ;;
+    esac
+    ;;
+  *)
+    echo "Unsupported OS: $OS"
+    echo "Use tmux instead: tmux new-session -d -s claude 'claude-telegram-orchestrator'"
+    exit 1
+    ;;
+esac