@codefilabs/tq 0.0.1 → 0.1.0

package/scripts/tq-cron-sync

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Ensure homebrew binaries are available (cron has minimal PATH)
+export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
+
+INTERVAL=20
+
+while [[ $# -gt 0 ]]; do
+  case "${1:-}" in
+    --interval)
+      if [[ $# -lt 2 ]]; then
+        echo "Error: --interval requires a value" >&2; exit 1
+      fi
+      INTERVAL="$2"; shift; shift ;;
+    *) echo "Unknown flag: $1" >&2; exit 1 ;;
+  esac
+done
+
+QUEUES_DIR="${HOME}/.tq/queues"
+LOGS_DIR="${HOME}/.tq/logs"
+mkdir -p "$QUEUES_DIR" "$LOGS_DIR"
+
+# ---------------------------------------------------------------------------
+# Scan ~/.tq/queues/*.yaml for schedule: keys via embedded Python temp file
+# ---------------------------------------------------------------------------
+SCAN_SCRIPT=$(mktemp /tmp/tq-scan-XXXXXX)
+CRONTAB_NEW=$(mktemp /tmp/tq-crontab-XXXXXX)
+trap 'rm -f "$SCAN_SCRIPT" "$CRONTAB_NEW"' EXIT
+
+cat > "$SCAN_SCRIPT" <<'PYEOF'
+import sys, os, re, json, glob
+
+queues_dir = sys.argv[1]
+results = []
+
+for yaml_path in sorted(glob.glob(os.path.join(queues_dir, '*.yaml'))):
+    name = os.path.basename(yaml_path)[:-5]  # strip .yaml
+    schedule = None
+    try:
+        with open(yaml_path) as f:
+            for line in f:
+                m = re.match(r'^schedule:\s*["\']?([^"\'#\n]+?)["\']?\s*$', line)
+                if m:
+                    schedule = m.group(1).strip()
+                    break
+    except Exception:
+        pass
+    if schedule:
+        results.append({'name': name, 'schedule': schedule, 'path': yaml_path})
+
+for r in results:
+    print(json.dumps(r))
+PYEOF
+
+# ---------------------------------------------------------------------------
+# Detect installed tq binary path
+# ---------------------------------------------------------------------------
+if [[ -x "/opt/homebrew/bin/tq" ]]; then
+  TQ_BIN="/opt/homebrew/bin/tq"
+  SELF_BIN="/opt/homebrew/bin/tq-cron-sync"
+elif [[ -x "/usr/local/bin/tq" ]]; then
+  TQ_BIN="/usr/local/bin/tq"
+  SELF_BIN="/usr/local/bin/tq-cron-sync"
+else
+  echo "Error: tq not found in /opt/homebrew/bin or /usr/local/bin" >&2
+  exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Read existing crontab, strip all tq-managed lines into temp file
+# ---------------------------------------------------------------------------
+{ crontab -l 2>/dev/null || true; } | grep -v '# tq-managed:' > "$CRONTAB_NEW" || true
+
+# ---------------------------------------------------------------------------
+# Append new managed lines for each scheduled queue
+# ---------------------------------------------------------------------------
+while IFS= read -r JSON_LINE; do
+  [[ -z "$JSON_LINE" ]] && continue
+  NAME="$(python3 -c "import sys,json; print(json.loads(sys.argv[1])['name'])" "$JSON_LINE")"
+  SCHEDULE="$(python3 -c "import sys,json; print(json.loads(sys.argv[1])['schedule'])" "$JSON_LINE")"
+  YAML_PATH="$(python3 -c "import sys,json; print(json.loads(sys.argv[1])['path'])" "$JSON_LINE")"
+  echo "${SCHEDULE} ${TQ_BIN} ${YAML_PATH} >> ${LOGS_DIR}/tq.log 2>&1 # tq-managed:${NAME}:run" >> "$CRONTAB_NEW"
+  echo "*/30 * * * * ${TQ_BIN} --status ${YAML_PATH} >> ${LOGS_DIR}/tq.log 2>&1 # tq-managed:${NAME}:status" >> "$CRONTAB_NEW"
+done < <(python3 "$SCAN_SCRIPT" "$QUEUES_DIR")
+
+# Self-watcher entry
+echo "*/${INTERVAL} * * * * ${SELF_BIN} >> ${LOGS_DIR}/tq-cron-sync.log 2>&1 # tq-managed:tq-cron-sync" >> "$CRONTAB_NEW"
+
+# Write merged crontab
+crontab "$CRONTAB_NEW"
+echo "tq-cron-sync: crontab synced ($(grep -c '# tq-managed:' "$CRONTAB_NEW" || true) managed entries)"

package/scripts/tq-install.sh

@@ -5,10 +5,10 @@ set -euo pipefail
 # Step 1: Register marketplace and install Claude plugin
 # ---------------------------------------------------------------------------
 if command -v claude &>/dev/null; then
-  echo "Adding tq marketplace..."
-  claude plugin marketplace add kevnk/tq
+  echo "Adding codefilabs marketplace..."
+  claude plugin marketplace add codefilabs/marketplace
   echo "Installing tq plugin..."
-  claude plugin install tq@tq
+  claude plugin install tq@codefilabs
 else
   echo "Warning: 'claude' CLI not found — skipping plugin registration." >&2
   echo "  Install Claude Code first: https://claude.ai/code" >&2
@@ -24,11 +24,11 @@ elif [[ -n "${BASH_SOURCE[0]:-}" && -f "${BASH_SOURCE[0]}" ]]; then
   PLUGIN_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 else
   # Running via curl | bash — find the installed plugin cache
-  CACHE_DIR="$HOME/.claude/plugins/cache/tq/tq"
+  CACHE_DIR="$HOME/.claude/plugins/cache/tq/codefilabs"
   PLUGIN_ROOT="$(ls -d "$CACHE_DIR"/*/ 2>/dev/null | sort -V | tail -1)"
   if [[ -z "${PLUGIN_ROOT:-}" ]]; then
     echo "Error: could not locate tq plugin files in $CACHE_DIR" >&2
-    echo "  Try running: claude plugin marketplace add kevnk/tq && claude plugin install tq@tq" >&2
+    echo "  Try running: claude plugin marketplace add codefilabs/marketplace && claude plugin install tq@codefilabs" >&2
     exit 1
   fi
 fi
@@ -48,7 +48,7 @@ else
   exit 1
 fi
 
-for SCRIPT in tq tq-message tq-setup tq-telegram-poll tq-telegram-watchdog; do
+for SCRIPT in tq tq-message tq-setup tq-telegram-poll tq-telegram-watchdog tq-cron-sync tq-converse; do
   SRC="$PLUGIN_ROOT/scripts/$SCRIPT"
   DEST="$INSTALL_DIR/$SCRIPT"
   if [[ -L "$DEST" ]]; then
@@ -63,11 +63,21 @@ done
 
 mkdir -p ~/.tq/queues ~/.tq/logs ~/.tq/config
 
+# Run initial cron sync to pick up any existing queue schedules
+# Use $INSTALL_DIR directly — PATH may not reflect the just-created symlink yet
+"$INSTALL_DIR/tq-cron-sync" --interval 20
+
+echo ""
+echo "tq installed. Cron schedules are managed automatically."
 echo ""
-echo "tq installed. Crontab example (crontab -e):"
+echo "Add a schedule: key to any queue file in ~/.tq/queues/ to auto-schedule it:"
 echo ""
-echo "  0 9 * * * /opt/homebrew/bin/tq ~/.tq/queues/morning.yaml >> ~/.tq/logs/tq.log 2>&1"
-echo "  */30 * * * * /opt/homebrew/bin/tq --status ~/.tq/queues/morning.yaml >> ~/.tq/logs/tq.log 2>&1"
+echo "  schedule: \"0 9 * * *\"   # runs daily at 9am"
+echo "  cwd: /path/to/project"
+echo "  tasks: ..."
+echo ""
+echo "tq-cron-sync runs every 20 minutes and syncs all queue schedules to crontab."
+echo "To change the sync interval: tq-cron-sync --interval <minutes>"
 echo ""
 echo "To configure Telegram notifications:"
 echo "  tq-setup"
@@ -76,3 +86,7 @@ echo "Or from Claude Code: /setup-telegram"
 echo ""
 echo "To relay Telegram messages as tq tasks, add to crontab:"
 echo "  * * * * * /opt/homebrew/bin/tq-telegram-poll >> ~/.tq/logs/tq-telegram.log 2>&1"
+echo ""
+echo "Conversation mode (interactive Telegram <-> Claude Code):"
+echo "  tq-converse start [--cwd /path/to/project]"
+echo "  Or send /converse from Telegram"

package/scripts/tq-message

@@ -8,6 +8,7 @@ QUEUE_FILE=""
 MESSAGE_TEXT=""
 SESSION=""
 EXPLICIT_STATE_FILE=""
+REPLY_TO_MSG_ID=""
 
 while [[ $# -gt 0 ]]; do
   case "${1:-}" in
@@ -16,15 +17,18 @@ while [[ $# -gt 0 ]]; do
     --message)    MESSAGE_TEXT="${2:-}";       shift 2 ;;
     --session)    SESSION="${2:-}";            shift 2 ;;
     --state-file) EXPLICIT_STATE_FILE="${2:-}"; shift 2 ;;
+    --reply-to)   REPLY_TO_MSG_ID="${2:-}";    shift 2 ;;
     --) shift; break ;;
     -*) echo "Unknown flag: $1" >&2; exit 1 ;;
     *)  break ;;
   esac
 done
 
-if [[ -z "$TASK_HASH" && -z "$QUEUE_FILE" ]]; then
+# Allow --message without --task/--queue (conversation mode)
+if [[ -z "$TASK_HASH" && -z "$QUEUE_FILE" && -z "$MESSAGE_TEXT" ]]; then
   echo "Usage: tq-message --task <hash> --queue <file.yaml> [--message <text>] [--session <name>]" >&2
   echo "       tq-message --queue <file.yaml> [--message <text>]" >&2
+  echo "       tq-message --message <text> [--reply-to <msg_id>]" >&2
   exit 1
 fi
 
@@ -36,7 +40,7 @@ if [[ -n "$QUEUE_FILE" ]]; then
   fi
 fi
 
-CONFIG_SCRIPT=$(mktemp /tmp/tq-message-config-XXXXXX.py)
+CONFIG_SCRIPT=$(mktemp /tmp/tq-message-config-XXXXXX)
 trap 'rm -f "$CONFIG_SCRIPT"' EXIT
 
 cat > "$CONFIG_SCRIPT" <<'PYEOF'
@@ -165,21 +169,25 @@ build_message() {
   if [[ -f "$state_file" ]]; then
     status="$(grep '^status=' "$state_file" | cut -d= -f2)"
     started="$(grep '^started=' "$state_file" | cut -d= -f2)"
+    completed_epoch="$(grep '^completed=' "$state_file" | cut -d= -f2)"
   else
     status="done"
     started=""
+    completed_epoch=""
   fi
 
-  # Calculate duration in minutes
+  # Calculate duration using completed epoch (avoids timezone skew from ISO string parsing)
   duration=""
   if [[ -n "$started" ]]; then
-    start_epoch="$(python3 -c "import datetime; print(int(datetime.datetime.fromisoformat('${started}').timestamp()))" 2>/dev/null || echo "")"
-    if [[ -n "$start_epoch" ]]; then
-      now_epoch="$(date +%s)"
-      elapsed=$(( now_epoch - start_epoch ))
-      duration="${elapsed}s"
-      if (( elapsed >= 60 )); then
-        duration="$(( elapsed / 60 ))m $(( elapsed % 60 ))s"
+    start_epoch="$(date -j -f "%Y-%m-%dT%H:%M:%S" "${started}" "+%s" 2>/dev/null || echo "")"
+    end_epoch="${completed_epoch:-$(date +%s)}"
+    if [[ -n "$start_epoch" && -n "$end_epoch" ]]; then
+      elapsed=$(( end_epoch - start_epoch ))
+      if (( elapsed > 0 )); then
+        duration="${elapsed}s"
+        if (( elapsed >= 60 )); then
+          duration="$(( elapsed / 60 ))m $(( elapsed % 60 ))s"
+        fi
       fi
     fi
   fi
@@ -271,16 +279,50 @@ send_telegram() {
   local token="$1"
   local chat_id="$2"
   local text="$3"
+  local reply_to="${4:-}"
+
+  local curl_args=()
+  curl_args+=(-s -X POST "https://api.telegram.org/bot${token}/sendMessage")
+  curl_args+=(-d "chat_id=${chat_id}")
+  curl_args+=(--data-urlencode "text=${text}")
+  curl_args+=(-d "parse_mode=Markdown")
+
+  # Add reply threading if a reply_to message ID is provided
+  if [[ -n "$reply_to" ]]; then
+    curl_args+=(-d "reply_to_message_id=${reply_to}")
+    curl_args+=(-d "allow_sending_without_reply=true")
+  fi
 
   local response
-  response="$(curl -s -X POST \
-    "https://api.telegram.org/bot${token}/sendMessage" \
-    -d "chat_id=${chat_id}" \
-    --data-urlencode "text=${text}" \
-    -d "parse_mode=Markdown" 2>&1)"
-
-  if echo "$response" | python3 -c "import sys,json; d=json.load(sys.stdin); exit(0 if d.get('ok') else 1)" 2>/dev/null; then
-    echo "[tq-message] sent via Telegram"
+  response="$(curl "${curl_args[@]}" 2>&1)"
+
+  # Extract the sent message ID for reply threading tracking
+  local sent_msg_id
+  sent_msg_id="$(echo "$response" | python3 -c "
+import sys, json
+try:
+    d = json.load(sys.stdin)
+    if d.get('ok'):
+        print(d.get('result', {}).get('message_id', ''))
+    else:
+        sys.exit(1)
+except:
+    sys.exit(1)
+" 2>/dev/null || true)"
+
+  if [[ -n "$sent_msg_id" ]]; then
+    echo "[tq-message] sent via Telegram (msg_id=$sent_msg_id)"
+    # Track outgoing message ID in registry for reply threading
+    if [[ -n "$sent_msg_id" ]] && command -v tq-converse &>/dev/null; then
+      # Try to detect which slug this message belongs to
+      local slug_file="$HOME/.tq/conversations/latest-reply-slug"
+      if [[ -f "$slug_file" ]]; then
+        local slug
+        slug="$(cat "$slug_file")"
+        tq-converse track-msg "$slug" "$sent_msg_id" 2>/dev/null || true
+        rm -f "$slug_file"
+      fi
+    fi
   else
     echo "[tq-message] Telegram error: $response" >&2
     exit 1
@@ -290,29 +332,56 @@ send_telegram() {
 deliver() {
   local service="$1"
   local msg="$2"
+  local reply_to="${3:-}"
   case "$service" in
-    telegram) send_telegram "$TG_TOKEN" "$TG_CHAT" "$msg" ;;
+    telegram) send_telegram "$TG_TOKEN" "$TG_CHAT" "$msg" "$reply_to" ;;
     *) echo "[tq-message] unknown service: $service" >&2; exit 1 ;;
   esac
 }
 
-# Summary mode with a live session: ask Claude to generate and send
+# Summary mode with a live session: ask Claude to write summary via slash command
 if [[ "$CONTENT" == "summary" && -n "$SESSION" && -z "$MESSAGE_TEXT" ]]; then
   if tmux has-session -t "$SESSION" 2>/dev/null; then
-    # Pass hash and queue path as arguments to the slash command
+    HANDSHAKE_FILE="/tmp/tq-summary-${TASK_HASH}.txt"
+    rm -f "$HANDSHAKE_FILE"
+
+    # Tell Claude to generate summary (slash command calls tq-message --message which writes handshake file + delivers)
     tmux send-keys -t "$SESSION" "/tq-message ${TASK_HASH} ${QUEUE_FILE}" Enter
-    # Give Claude time to summarize and call back tq-message --message
-    sleep 45
-    # Close the session
-    tmux send-keys -t "$SESSION" "" Enter
-    exit 0
+
+    # Poll for the handshake file (max 90 seconds, check every 3s)
+    WAITED=0
+    while [[ ! -f "$HANDSHAKE_FILE" && "$WAITED" -lt 90 ]]; do
+      sleep 3
+      WAITED=$(( WAITED + 3 ))
+    done
+
+    if [[ -f "$HANDSHAKE_FILE" ]]; then
+      # Slash command already delivered the message — just clean up
+      rm -f "$HANDSHAKE_FILE"
+      exit 0
+    else
+      # Timed out — fall back to details
+      MESSAGE_TEXT="$(build_message "details" "$TASK_HASH" "$STATE_FILE" "$PROMPT_FILE" "")"
+    fi
   else
     # Session gone — fall back to details
     MESSAGE_TEXT="$(build_message "details" "$TASK_HASH" "$STATE_FILE" "$PROMPT_FILE" "")"
   fi
 fi
 
+# Write handshake file for summary polling (if applicable)
+if [[ -n "$MESSAGE_TEXT" && -n "$TASK_HASH" ]]; then
+  echo "$MESSAGE_TEXT" > "/tmp/tq-summary-${TASK_HASH}.txt"
+fi
+
 # Deliver message if we have one
 if [[ -n "$MESSAGE_TEXT" ]]; then
-  deliver "$SERVICE" "$MESSAGE_TEXT"
+  # If no explicit reply-to, check for latest-msg-id (conversation mode)
+  if [[ -z "$REPLY_TO_MSG_ID" ]]; then
+    LATEST_MSG_FILE="$HOME/.tq/conversations/latest-msg-id"
+    if [[ -f "$LATEST_MSG_FILE" ]]; then
+      REPLY_TO_MSG_ID="$(cat "$LATEST_MSG_FILE")"
+    fi
+  fi
+  deliver "$SERVICE" "$MESSAGE_TEXT" "$REPLY_TO_MSG_ID"
 fi

package/scripts/tq-setup

@@ -32,7 +32,7 @@ read -r _IGNORED
 
 UPDATES="$(curl -s "https://api.telegram.org/bot${BOT_TOKEN}/getUpdates?offset=0&limit=10&timeout=0" 2>&1)"
 
-DISCOVER_SCRIPT=$(mktemp /tmp/tq-setup-discover-XXXXXX.py)
+DISCOVER_SCRIPT=$(mktemp /tmp/tq-setup-discover-XXXXXX)
 trap 'rm -f "$DISCOVER_SCRIPT"' EXIT
 
 cat > "$DISCOVER_SCRIPT" <<'PYEOF'

package/scripts/tq-telegram-poll

@@ -5,13 +5,14 @@ export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
 
 CONFIG_FILE="$HOME/.tq/config/message.yaml"
 OFFSET_FILE="$HOME/.tq/telegram-poll-offset"
+ORCHESTRATOR_SESSION="tq-orchestrator"
 
 # --- Read config ---
 if [[ ! -f "$CONFIG_FILE" ]]; then
   exit 0
 fi
 
-CONFIG_SCRIPT=$(mktemp /tmp/tq-poll-config-XXXXXX.py)
+CONFIG_SCRIPT=$(mktemp /tmp/tq-poll-config-XXXXXX)
 trap 'rm -f "$CONFIG_SCRIPT"' EXIT
 
 cat > "$CONFIG_SCRIPT" <<'PYEOF'
@@ -68,8 +69,8 @@ fi
 # --- Fetch updates ---
 UPDATES="$(curl -s "https://api.telegram.org/bot${BOT_TOKEN}/getUpdates?offset=${OFFSET}&limit=10&timeout=0" 2>&1)"
 
-# --- Process updates ---
-PROCESS_SCRIPT=$(mktemp /tmp/tq-poll-process-XXXXXX.py)
+# --- Process updates (extract msg_id, chat_id, reply_to_msg_id, text) ---
+PROCESS_SCRIPT=$(mktemp /tmp/tq-poll-process-XXXXXX)
 trap 'rm -f "$CONFIG_SCRIPT" "$PROCESS_SCRIPT"' EXIT
 
 cat > "$PROCESS_SCRIPT" <<'PYEOF'
@@ -100,8 +101,10 @@ for update in results:
     if text:
         chat_id = msg['chat']['id']
         message_id = msg['message_id']
-        # Output as tab-separated: chat_id<TAB>message_id<TAB>text
-        messages.append(f"{chat_id}\t{message_id}\t{text}")
+        # Extract reply_to_message_id if present
+        reply_to = msg.get('reply_to_message', {}).get('message_id', '')
+        # Output: chat_id<TAB>message_id<TAB>reply_to<TAB>text
+        messages.append(f"{chat_id}\t{message_id}\t{reply_to}\t{text}")
 
 if new_offset is not None:
     with open(offset_file, 'w') as f:
@@ -113,17 +116,166 @@ PYEOF
 
 MESSAGES="$(python3 "$PROCESS_SCRIPT" "$UPDATES" "$USER_ID" "$OFFSET_FILE")"
 
-# --- Spawn tq --prompt for each message ---
+# --- Check if orchestrator is running ---
+ORCHESTRATOR_ACTIVE=0
+if tmux has-session -t "$ORCHESTRATOR_SESSION" 2>/dev/null; then
+  ORCHESTRATOR_ACTIVE=1
+fi
+
+# --- Handle Telegram commands ---
+handle_command() {
+  local cmd="$1"
+  local chat_id="$2"
+
+  case "$cmd" in
+    /converse|/converse\ *)
+      if [[ "$ORCHESTRATOR_ACTIVE" == "1" ]]; then
+        curl -s -X POST "https://api.telegram.org/bot${BOT_TOKEN}/sendMessage" \
+          -d "chat_id=${chat_id}" \
+          --data-urlencode "text=Orchestrator already running. Just send messages — they'll be routed automatically." \
+          > /dev/null 2>&1 || true
+      else
+        if command -v tq-converse &>/dev/null; then
+          tq-converse start 2>&1 || true
+          ORCHESTRATOR_ACTIVE=1
+          curl -s -X POST "https://api.telegram.org/bot${BOT_TOKEN}/sendMessage" \
+            -d "chat_id=${chat_id}" \
+            --data-urlencode "text=Orchestrator started. Send messages and they'll be routed to the right conversation." \
+            > /dev/null 2>&1 || true
+        fi
+      fi
+      return 0
+      ;;
+    /stop)
+      if command -v tq-converse &>/dev/null; then
+        tq-converse stop 2>&1 || true
+        ORCHESTRATOR_ACTIVE=0
+        curl -s -X POST "https://api.telegram.org/bot${BOT_TOKEN}/sendMessage" \
+          -d "chat_id=${chat_id}" \
+          --data-urlencode "text=Orchestrator stopped." \
+          > /dev/null 2>&1 || true
+      fi
+      return 0
+      ;;
+    /stop\ *)
+      local SLUG="${cmd#/stop }"
+      if command -v tq-converse &>/dev/null; then
+        tq-converse stop "$SLUG" 2>&1 || true
+        curl -s -X POST "https://api.telegram.org/bot${BOT_TOKEN}/sendMessage" \
+          -d "chat_id=${chat_id}" \
+          --data-urlencode "text=Session '$SLUG' stopped." \
+          > /dev/null 2>&1 || true
+      fi
+      return 0
+      ;;
+    /status)
+      if command -v tq-converse &>/dev/null; then
+        local STATUS_TEXT
+        STATUS_TEXT="$(tq-converse status 2>&1 || true)"
+        curl -s -X POST "https://api.telegram.org/bot${BOT_TOKEN}/sendMessage" \
+          -d "chat_id=${chat_id}" \
+          --data-urlencode "text=${STATUS_TEXT}" \
+          > /dev/null 2>&1 || true
+      fi
+      return 0
+      ;;
+    /list)
+      if command -v tq-converse &>/dev/null; then
+        local LIST_TEXT
+        LIST_TEXT="$(tq-converse list 2>&1 || true)"
+        curl -s -X POST "https://api.telegram.org/bot${BOT_TOKEN}/sendMessage" \
+          -d "chat_id=${chat_id}" \
+          --data-urlencode "text=${LIST_TEXT}" \
+          > /dev/null 2>&1 || true
+      fi
+      return 0
+      ;;
+  esac
+  return 1
+}
+
+# --- Route messages ---
 mkdir -p "$HOME/.tq/workspace"
 
-while IFS=$'\t' read -r CHAT_ID MSG_ID MSG; do
-  if [[ -n "$MSG" ]]; then
-    echo "[tq-telegram-poll] prompt: ${MSG:0:60}"
-    # React with 👀 to acknowledge receipt
-    curl -s -X POST "https://api.telegram.org/bot${BOT_TOKEN}/setMessageReaction" \
-      -H "Content-Type: application/json" \
-      --data-raw "{\"chat_id\":${CHAT_ID},\"message_id\":${MSG_ID},\"reaction\":[{\"type\":\"emoji\",\"emoji\":\"👀\"}]}" \
-      > /dev/null 2>&1 || true
-    tq --prompt "$MSG"
+while IFS=$'\t' read -r CHAT_ID MSG_ID REPLY_TO MSG; do
+  if [[ -z "$MSG" ]]; then
+    continue
+  fi
+
+  echo "[tq-telegram-poll] message: ${MSG:0:60}"
+
+  # React with 👀 to acknowledge receipt
+  curl -s -X POST "https://api.telegram.org/bot${BOT_TOKEN}/setMessageReaction" \
+    -H "Content-Type: application/json" \
+    --data-raw "{\"chat_id\":${CHAT_ID},\"message_id\":${MSG_ID},\"reaction\":[{\"type\":\"emoji\",\"emoji\":\"👀\"}]}" \
+    > /dev/null 2>&1 || true
+
+  # Check for Telegram commands first
+  if [[ "$MSG" == /* ]]; then
+    if handle_command "$MSG" "$CHAT_ID"; then
+      continue
+    fi
+  fi
+
+  # --- Routing logic (3-tier) ---
+
+  # Store the latest message ID for reply threading
+  echo "$MSG_ID" > "$HOME/.tq/conversations/latest-msg-id" 2>/dev/null || true
+  echo "$CHAT_ID" > "$HOME/.tq/conversations/latest-chat-id" 2>/dev/null || true
+
+  ROUTED=0
+
+  # Tier 1: Telegram reply → deterministic routing via registry
+  if [[ -n "$REPLY_TO" && "$ORCHESTRATOR_ACTIVE" == "1" ]]; then
+    SLUG="$(tq-converse lookup-msg "$REPLY_TO" 2>/dev/null || true)"
+    if [[ -n "$SLUG" ]]; then
+      CHILD_SESSION="tq-conv-${SLUG}"
+      if tmux has-session -t "$CHILD_SESSION" 2>/dev/null; then
+        echo "[tq-telegram-poll] reply-routing to: $SLUG (via msg $REPLY_TO)"
+        tq-converse track-msg "$SLUG" "$MSG_ID"
+        # Store msg_id for this session's reply threading
+        echo "$MSG_ID" > "$HOME/.tq/conversations/sessions/$SLUG/reply-to-msg-id" 2>/dev/null || true
+        tq-converse route "$SLUG" "$MSG"
+        ROUTED=1
+      fi
+    fi
+  fi
+
+  # Tier 2: Explicit #slug prefix → deterministic routing
+  if [[ "$ROUTED" == "0" && "$MSG" == \#* && "$ORCHESTRATOR_ACTIVE" == "1" ]]; then
+    # Extract slug from #slug-name prefix
+    SLUG="$(echo "$MSG" | sed 's/^#\([a-z0-9-]*\).*/\1/')"
+    ACTUAL_MSG="$(echo "$MSG" | sed 's/^#[a-z0-9-]* *//')"
+    if [[ -n "$SLUG" && -n "$ACTUAL_MSG" ]]; then
+      CHILD_SESSION="tq-conv-${SLUG}"
+      if tmux has-session -t "$CHILD_SESSION" 2>/dev/null; then
+        echo "[tq-telegram-poll] explicit routing to: $SLUG"
+        tq-converse track-msg "$SLUG" "$MSG_ID"
+        echo "$MSG_ID" > "$HOME/.tq/conversations/sessions/$SLUG/reply-to-msg-id" 2>/dev/null || true
+        tq-converse route "$SLUG" "$ACTUAL_MSG"
+        ROUTED=1
+      fi
+    fi
   fi
+
+  # Tier 3: Orchestrator routing (smart, Claude-powered)
+  if [[ "$ROUTED" == "0" && "$ORCHESTRATOR_ACTIVE" == "1" ]]; then
+    echo "[tq-telegram-poll] routing via orchestrator"
+    # Format message with metadata for the orchestrator
+    FORMATTED_MSG="[tq-msg msg_id=${MSG_ID} chat_id=${CHAT_ID}"
+    if [[ -n "$REPLY_TO" ]]; then
+      FORMATTED_MSG="${FORMATTED_MSG} reply_to=${REPLY_TO}"
+    fi
+    FORMATTED_MSG="${FORMATTED_MSG}]
+${MSG}"
+    tq-converse send "$FORMATTED_MSG"
+    ROUTED=1
+  fi
+
+  # Fallback: no orchestrator — spawn one-off task (legacy behavior)
+  if [[ "$ROUTED" == "0" ]]; then
+    echo "[tq-telegram-poll] no orchestrator — spawning one-off task"
+    tq --no-chrome --prompt "$MSG"
+  fi
+
 done <<< "$MESSAGES"

package/skills/tq/SKILL.md

@@ -3,10 +3,11 @@ name: tq
 description: >
   This skill should be used when the user asks to "add to queue", "run queue", "queue these tasks",
   "schedule with tq", "tq status", "check task queue", "create a tq queue", "set up cron for tq",
-  "run claude in background", "batch prompts in tmux", or wants to manage Claude prompts running
-  in tmux sessions via the tq CLI tool. Triggers on phrases like "queue", "tq", "task queue",
-  "tmux queue", "scheduled claude tasks".
-version: 1.0.0
+  "run claude in background", "batch prompts in tmux", "start a conversation", "converse via telegram",
+  "telegram conversation mode", or wants to manage Claude prompts running in tmux sessions via the
+  tq CLI tool. Triggers on phrases like "queue", "tq", "task queue", "tmux queue", "scheduled claude tasks",
+  "conversation mode", "telegram chat", "converse".
+version: 1.1.0
 ---
 
 # tq — Claude Task Queue Runner
@@ -17,8 +18,9 @@ Installed to PATH via `/install`: `/opt/homebrew/bin/tq`
 
 ## Overview
 
-tq batches Claude prompts into YAML queue files and spawns each as an independent tmux session.
-Tasks are idempotent — running `tq` again skips `done` and live `running` tasks.
+tq manages Claude Code sessions via tmux in two modes:
+1. **Queue mode** — batches prompts into YAML queue files, spawns each as an independent tmux session. Idempotent — running `tq` again skips `done` and live `running` tasks.
+2. **Conversation mode** — persistent interactive Claude Code sessions orchestrated via Telegram. An orchestrator routes messages to the right conversation, creating new sessions or resuming existing ones.
 
 ## Queue File Format
 
@@ -59,6 +61,9 @@ Statuses: `pending` → `running` → `done`
 | `/jobs [filter]` | List all scheduled tq cron jobs |
 | `/health [queue]` | System-wide diagnostics |
 | `/install` | Symlink tq binaries to PATH |
+| `/converse [start\|stop\|status]` | Manage Telegram conversation sessions |
+| `/tq-reply` | Send response back to Telegram (conversation mode) |
+| `/setup-telegram` | Configure Telegram bot token and notifications |
 
 ## CLI Usage
 
@@ -102,6 +107,37 @@ The Claude extension stores the browser name as `bridgeDisplayName` in the exten
 - Right-click the Claude extension icon in the Chrome toolbar → **Options**
 - Or open the sidepanel and look for a settings/gear icon with a name field
 
+## Conversation Mode
+
+Start an orchestrator: `tq-converse start` or send `/converse` from Telegram.
+
+The orchestrator routes incoming Telegram messages to the appropriate conversation session:
+- Telegram reply to a known message → routes to that session automatically
+- `#slug message` → routes to the named session
+- New topic → orchestrator spawns a new session with a descriptive slug
+
+Each conversation is a persistent Claude Code interactive session in its own tmux window.
+Child sessions use `/tq-reply` to send responses back to Telegram as threaded replies.
+
+### Conversation CLI
+
+```bash
+tq-converse start                         # start orchestrator
+tq-converse spawn <slug> --cwd <dir>      # new conversation session
+tq-converse route <slug> <message>        # send to a session
+tq-converse list                          # list active sessions
+tq-converse stop [<slug>]                 # stop session or orchestrator
+```
+
+### Telegram Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/converse` | Start the orchestrator |
+| `/stop [slug]` | Stop orchestrator or a specific session |
+| `/status` | Show all sessions |
+| `/list` | List active conversations |
+
 ## Additional Resources
 
 - **`references/session-naming.md`** — Session/window name generation algorithm and examples