@codefilabs/tq 0.0.2 → 0.1.0

package/README.md

@@ -1,6 +1,6 @@
 # tq — Task Queue for Claude
 
-A lightweight task queue runner that spawns Claude AI tasks as independent tmux sessions.
+A lightweight task queue runner and conversation manager that spawns Claude AI tasks as independent tmux sessions. Supports both one-off batch queues and persistent interactive conversations via Telegram.
 
 ## What It Does
 
@@ -31,9 +31,9 @@ Here's exactly what that command does:
 
 1. **Downloads the install script** from this repo over HTTPS (`-fsSL` = fail on error, silent, follow redirects) and pipes it directly to `bash` — nothing is saved to disk.
 
-2. **Registers the tq marketplace** with Claude Code by running `claude plugin marketplace add kevnk/tq`. This clones the tq repo into `~/.claude/plugins/marketplaces/tq/` so Claude knows where to find it.
+2. **Registers the codefilabs marketplace** with Claude Code by running `claude plugin marketplace add codefilabs/marketplace`. This clones the marketplace repo into `~/.claude/plugins/marketplaces/codefilabs/` so Claude knows where to find it.
 
-3. **Installs the tq plugin** by running `claude plugin install tq@tq`. This caches the plugin files into `~/.claude/plugins/cache/tq/tq/<version>/` and registers the plugin's skills and slash commands with Claude Code. After this, Claude will recognize commands like `/todo`, `/schedule`, `/jobs`, and `/health`.
+3. **Installs the tq plugin** by running `claude plugin install tq@codefilabs`. This caches the plugin files into `~/.claude/plugins/cache/tq/codefilabs/<version>/` and registers the plugin's skills and slash commands with Claude Code. After this, Claude will recognize commands like `/todo`, `/schedule`, `/jobs`, and `/health`.
 
 4. **Symlinks `tq`** into `/opt/homebrew/bin` (Apple Silicon) or `/usr/local/bin` (Intel Mac) so the command is available in your shell and in cron jobs.
 
@@ -216,6 +216,8 @@ Once installed, Claude can manage your task queues via slash commands:
 | `/health` | System-wide diagnostics |
 | `/setup-telegram` | Interactive wizard to configure Telegram notifications |
 | `/install` | Symlink tq binaries to PATH |
+| `/converse [start\|stop\|status]` | Manage Telegram conversation sessions |
+| `/tq-reply` | Send a response back to Telegram (used by Claude in conversation mode) |
 
 Claude will infer the queue name from context: "every morning" → `morning.yaml`, "daily" → `daily.yaml`, or the current directory's basename if no schedule keyword is present.
 
@@ -294,3 +296,98 @@ crontab -e
 Logs accumulate in `~/.tq/logs/tq.log`.
 
 See `skills/tq/references/cron-expressions.md` for a natural language → cron expression reference.
+
+## Conversation Mode (Telegram)
+
+Conversation mode enables interactive, back-and-forth conversations with Claude Code via Telegram. An orchestrator Claude session routes your messages to the appropriate conversation, automatically creating new sessions for new topics and resuming existing ones.
+
+### Setup
+
+1. Configure Telegram: run `/setup-telegram` in Claude Code (or `tq-setup`)
+2. Add the polling cron job:
+   ```bash
+   * * * * * /opt/homebrew/bin/tq-telegram-poll >> ~/.tq/logs/tq-telegram.log 2>&1
+   ```
+
+### Starting Conversations
+
+Send `/converse` from Telegram (or run `tq-converse start` from CLI). This launches the orchestrator.
+
+Once the orchestrator is running, just send messages normally. The orchestrator will:
+- **New topic** → create a new conversation session with a descriptive slug (e.g., `fix-auth-bug`)
+- **Related to existing** → route to the appropriate session
+- **Telegram reply** → automatically route to the conversation that sent the original message
+- **Explicit routing** → prefix with `#slug-name` to target a specific session
+
+### Example Flow
+
+```
+You:     "fix the login bug in the auth module"
+tq:      [new: fix-auth] Started conversation: Fix login bug in auth module
+
+You:     "what did you find?"
+tq:      [fix-auth] Found 3 issues in src/auth.py: ...
+
+You:     "refactor the payment service to use Stripe v2"
+tq:      [new: refactor-payments] Started conversation: Refactor payment service for Stripe v2
+
+You:     #fix-auth "also check the password reset flow"
+tq:      [fix-auth] Checking password reset flow...
+```
+
+### Telegram Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/converse` | Start the orchestrator |
+| `/stop` | Stop the orchestrator |
+| `/stop <slug>` | Stop a specific conversation |
+| `/status` | Show all sessions |
+| `/list` | List active conversations |
+
+### How It Works
+
+1. **tq-telegram-poll** runs every minute via cron, fetches new Telegram messages
+2. **3-tier routing** determines where each message goes:
+   - Tier 1: Telegram reply → deterministic lookup via registry message ID mapping
+   - Tier 2: `#slug` prefix → route directly to named session
+   - Tier 3: Send to orchestrator Claude for smart routing
+3. **Orchestrator** (a persistent Claude Code session) reads the conversation registry, decides whether to route to an existing session or spawn a new one
+4. **Child sessions** (each a persistent Claude Code interactive session) process messages and respond via `/tq-reply`
+5. **Responses** are sent back to Telegram as threaded replies, with the session slug as a label
+
+### State
+
+Conversation state lives in `~/.tq/conversations/`:
+
+```
+~/.tq/conversations/
+├── registry.json           ← session registry (slugs, descriptions, message IDs)
+├── orchestrator/           ← orchestrator Claude settings and instructions
+│   ├── .tq-orchestrator.md
+│   ├── settings.json
+│   └── hooks/
+└── sessions/
+    ├── fix-auth/           ← per-session state
+    │   ├── .tq-converse.md
+    │   ├── settings.json
+    │   ├── current-slug
+    │   ├── reply-to-msg-id
+    │   ├── inbox/          ← received messages (timestamped)
+    │   └── outbox/         ← sent responses (timestamped)
+    └── refactor-payments/
+        └── ...
+```
+
+### CLI Commands
+
+```bash
+tq-converse start                    # start orchestrator
+tq-converse spawn <slug> [opts]      # create a child session
+tq-converse route <slug> <message>   # send to a session
+tq-converse send <message>           # send to orchestrator
+tq-converse list                     # list active sessions
+tq-converse status                   # show all session details
+tq-converse stop [<slug>]            # stop session or orchestrator
+tq-converse registry                 # dump the session registry
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codefilabs/tq",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "description": "A lightweight task queue runner that spawns Claude AI tasks as independent tmux sessions",
   "keywords": [
     "claude",
@@ -37,5 +37,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "postpublish": "node tools/update-marketplace.js"
   }
 }

package/scripts/tq

@@ -10,6 +10,7 @@ PROMPT_TEXT=""
 TASK_NAME="adhoc"
 TASK_CWD=""
 NOTIFY=""
+CHROME=1
 
 while [[ $# -gt 0 ]]; do
   case "${1:-}" in
@@ -18,6 +19,7 @@ while [[ $# -gt 0 ]]; do
     --name)   TASK_NAME="${2:-}"; shift 2 ;;
     --cwd)    TASK_CWD="${2:-}"; shift 2 ;;
     --notify) NOTIFY="${2:-}"; shift 2 ;;
+    --no-chrome) CHROME=0; shift ;;
     --) shift; break ;;
     -*) echo "Unknown flag: $1" >&2; exit 1 ;;
     *)  break ;;
@@ -92,6 +94,7 @@ if [[ "$STATUS_MODE" == "1" ]]; then
     if [[ "$STATUS" == "running" ]]; then
       if ! tmux has-session -t "$SESSION" 2>/dev/null; then
         sed -i '' 's/^status=running/status=done/' "$STATE_FILE"
+        echo "completed=$(date +%s)" >> "$STATE_FILE"
         STATUS="done"
       fi
     fi
@@ -125,7 +128,7 @@ fi
 # (Using a temp file avoids bash 3.2 bug: single quotes inside <<'HEREDOC'
 #  inside $() are incorrectly scanned by the quote counter.)
 # ---------------------------------------------------------------------------
-PARSE_SCRIPT=$(mktemp /tmp/tq-parse-XXXXXX.py)
+PARSE_SCRIPT=$(mktemp /tmp/tq-parse-XXXXXX)
 trap 'rm -f "$PARSE_SCRIPT"' EXIT
 
 cat > "$PARSE_SCRIPT" <<'PYEOF'
@@ -136,7 +139,7 @@ os.makedirs(sessions_dir, exist_ok=True)
 
 # Support direct prompt mode: --prompt <text> <state_dir> [cwd]
 if len(sys.argv) > 1 and sys.argv[1] == '--prompt':
-    tasks = [(sys.argv[2].strip(), sys.argv[4] if len(sys.argv) > 4 else '')]
+    tasks = [(sys.argv[2].strip(), sys.argv[4] if len(sys.argv) > 4 else '', '', '')]
     state_dir = sys.argv[3]
 else:
     queue_file = sys.argv[1]
@@ -155,11 +158,62 @@ else:
             cwd = m.group(1).strip().strip('"\'')
             break
 
+    # Extract top-level reset policy
+    reset_mode = ''
+    for line in lines:
+        m = re.match(r'^reset:\s*(.+)$', line)
+        if m:
+            reset_mode = m.group(1).strip().strip('"\'')
+            break
+
+    # Handle queue-level resets before task evaluation.
+    # Clears task state files (and .queue-notified) so tasks re-run.
+    #   daily   — reset once per calendar day
+    #   weekly  — reset once per ISO week (Mon–Sun)
+    #   hourly  — reset once per hour
+    #   always  — reset on every tq run
+    if reset_mode in ('daily', 'weekly', 'hourly', 'always'):
+        import datetime
+        now = datetime.datetime.now()
+        if reset_mode == 'daily':
+            period = now.date().isoformat()       # e.g. '2026-03-11'
+        elif reset_mode == 'weekly':
+            period = now.strftime('%G-W%V')       # e.g. '2026-W11'
+        elif reset_mode == 'hourly':
+            period = now.strftime('%Y-%m-%dT%H')  # e.g. '2026-03-11T17'
+        else:  # always
+            period = None
+        last_reset_file = os.path.join(state_dir, '.last_reset')
+        last_reset = ''
+        if period is not None and os.path.exists(last_reset_file):
+            with open(last_reset_file) as f:
+                last_reset = f.read().strip()
+        if period is None or last_reset != period:
+            for fname in os.listdir(state_dir):
+                fpath = os.path.join(state_dir, fname)
+                if not fname.startswith('.') and '.' not in fname:
+                    os.remove(fpath)           # task state file (bare hash)
+                elif fname == '.queue-notified':
+                    os.remove(fpath)           # clear so completion fires fresh
+            if period is not None:
+                with open(last_reset_file, 'w') as f:
+                    f.write(period)
+
     # Parse tasks -- handle inline, block literal (|), block folded (>), quoted
     tasks = []
+    current_name = ''
     i = 0
     while i < len(lines):
-        m = re.match(r'^  - prompt:\s*(.*)', lines[i])
+        # Reset name at start of each new list item
+        if re.match(r'^  - ', lines[i]) and not re.match(r'^  - prompt:', lines[i]):
+            current_name = ''
+            m_name = re.match(r'^  - name:\s*(.*)', lines[i])
+            if m_name:
+                current_name = m_name.group(1).strip().strip('"\'')
+            i += 1
+            continue
+
+        m = re.match(r'^(?:  - |    )prompt:\s*(.*)', lines[i])
         if not m:
             i += 1
             continue
@@ -209,9 +263,10 @@ else:
 
         prompt = prompt.strip()
         if prompt:
-            tasks.append((prompt, cwd))
+            tasks.append((prompt, cwd, current_name, reset_mode))
+            current_name = ''
 
-for (prompt, cwd) in tasks:
+for (prompt, cwd, name, reset_mode) in tasks:
     h = hashlib.sha256(prompt.encode()).hexdigest()[:8]
     first_line = prompt.split('\n')[0][:80]
 
@@ -252,8 +307,15 @@ for (prompt, cwd) in tasks:
     stop_script += 'set -euo pipefail\n'
     stop_script += '# Mark tq task done\n'
     stop_script += 'STATE_FILE=' + json.dumps(state_file) + '\n'
+    stop_script += 'RESET_MODE=' + json.dumps(reset_mode) + '\n'
     stop_script += 'if [[ -f "$STATE_FILE" ]]; then\n'
-    stop_script += "  sed -i '' 's/^status=running/status=done/' \"$STATE_FILE\"\n"
+    stop_script += '  if [[ "$RESET_MODE" == "on-complete" ]]; then\n'
+    stop_script += '    # on-complete: tq-message runs first, then state is cleared for re-run\n'
+    stop_script += '    : # state deletion happens after tq-message below\n'
+    stop_script += '  else\n'
+    stop_script += "    sed -i '' 's/^status=running/status=done/' \"$STATE_FILE\"\n"
+    stop_script += '    echo "completed=$(date +%s)" >> "$STATE_FILE"\n'
+    stop_script += '  fi\n'
     stop_script += 'fi\n'
     if notify:
         stop_script += '\n# Notification (--notify)\n'
@@ -283,6 +345,10 @@ for (prompt, cwd) in tasks:
     stop_script += '  SESSION="$(grep \'^session=\' "$STATE_FILE" | cut -d= -f2)"\n'
     stop_script += '  tq-message --task "$TQ_HASH" --queue "$TQ_QUEUE_FILE" --state-file "$STATE_FILE" --session "$SESSION"\n'
     stop_script += 'fi\n'
+    stop_script += '# on-complete: delete state file so next tq run re-spawns this task\n'
+    stop_script += 'if [[ "$RESET_MODE" == "on-complete" && -f "$STATE_FILE" ]]; then\n'
+    stop_script += '  rm -f "$STATE_FILE"\n'
+    stop_script += 'fi\n'
     with open(stop_hook, 'w') as f:
         f.write(stop_script)
     os.chmod(stop_hook, stat.S_IRWXU | stat.S_IRGRP | stat.S_IXGRP | stat.S_IROTH | stat.S_IXOTH)
@@ -322,23 +388,34 @@ for (prompt, cwd) in tasks:
             f.write('os.environ[' + json.dumps(k) + '] = ' + json.dumps(v) + '\n')
         f.write('if cwd:\n')
         f.write('    os.chdir(cwd)\n')
+        use_chrome = os.environ.get('TQ_CHROME', '1') == '1'
+
         f.write('import shutil, subprocess, time\n')
         f.write('prompt = open(prompt_file).read()\n')
-        f.write('# Open Chrome with Profile 5 (halbotkirchner@gmail.com) before connecting\n')
-        f.write('subprocess.Popen(["open", "-a", "Google Chrome", "--args", "--profile-directory=Profile 5"])\n')
-        f.write('time.sleep(2)\n')
+        if use_chrome:
+            f.write('# Open Chrome with Profile 5 (halbotkirchner@gmail.com) before connecting\n')
+            f.write('subprocess.Popen(["open", "-a", "Google Chrome", "--args", "--profile-directory=Profile 5"])\n')
+            f.write('time.sleep(2)\n')
+
+        # Build claude args
+        claude_args = "['claude', '--settings', settings_file, '--dangerously-skip-permissions'"
+        if use_chrome:
+            claude_args += ", '--chrome'"
+        claude_args += ", prompt]"
+
         f.write('# Use reattach-to-user-namespace if available (macOS tmux keychain fix)\n')
         f.write('reattach = shutil.which("reattach-to-user-namespace")\n')
         f.write('if reattach:\n')
-        f.write("    os.execvp(reattach, [reattach, 'claude', '--settings', settings_file, '--dangerously-skip-permissions', '--chrome', prompt])\n")
+        f.write("    os.execvp(reattach, [reattach, " + claude_args[1:] + ")\n")
         f.write('else:\n')
-        f.write("    os.execvp('claude', ['claude', '--settings', settings_file, '--dangerously-skip-permissions', '--chrome', prompt])\n")
+        f.write("    os.execvp('claude', " + claude_args + ")\n")
 
-    print(json.dumps({'hash': h, 'first_line': first_line}))
+    print(json.dumps({'hash': h, 'first_line': first_line, 'name': name, 'reset': reset_mode}))
 
 PYEOF
 
 export TQ_NOTIFY="$NOTIFY"
+export TQ_CHROME="$CHROME"
 
 if [[ "$PROMPT_MODE" == "1" ]]; then
   TASK_CWD="${TASK_CWD:-$HOME/.tq/workspace}"
@@ -363,6 +440,8 @@ fi
 while IFS= read -r JSON_LINE; do
   HASH="$(python3 -c "import sys,json; print(json.loads(sys.argv[1])['hash'])" "$JSON_LINE")"
   FIRST_LINE="$(python3 -c "import sys,json; print(json.loads(sys.argv[1])['first_line'])" "$JSON_LINE")"
+  TASK_NAME_FIELD="$(python3 -c "import sys,json; print(json.loads(sys.argv[1]).get('name', ''))" "$JSON_LINE")"
+  RESET_MODE="$(python3 -c "import sys,json; print(json.loads(sys.argv[1]).get('reset', ''))" "$JSON_LINE")"
   STATE_FILE="$STATE_DIR/$HASH"
   LAUNCHER="$STATE_DIR/$HASH.launch.py"
 
@@ -370,8 +449,33 @@ while IFS= read -r JSON_LINE; do
   if [[ -f "$STATE_FILE" ]]; then
     STATUS="$(grep '^status=' "$STATE_FILE" | cut -d= -f2)"
     if [[ "$STATUS" == "done" ]]; then
-      echo "  [done]    $FIRST_LINE"
-      continue
+      if [[ -n "$RESET_MODE" && "$RESET_MODE" != "on-complete" ]]; then
+        COMPLETED="$(grep '^completed=' "$STATE_FILE" | cut -d= -f2)"
+        NOW="$(date +%s)"
+        TTL_SECONDS="$(python3 -c "
+import sys
+s = sys.argv[1]
+if s.endswith('h'):
+    print(int(s[:-1]) * 3600)
+elif s.endswith('d'):
+    print(int(s[:-1]) * 86400)
+elif s.endswith('m'):
+    print(int(s[:-1]) * 60)
+else:
+    print(0)
+" "$RESET_MODE")"
+        if [[ -n "$COMPLETED" && "$TTL_SECONDS" -gt 0 && $(( NOW - COMPLETED )) -gt "$TTL_SECONDS" ]]; then
+          rm -f "$STATE_FILE"
+          echo "  [reset]   $FIRST_LINE (TTL expired)"
+          # Fall through to spawn logic below
+        else
+          echo "  [done]    $FIRST_LINE"
+          continue
+        fi
+      else
+        echo "  [done]    $FIRST_LINE"
+        continue
+      fi
     fi
     if [[ "$STATUS" == "running" ]]; then
       SESSION="$(grep '^session=' "$STATE_FILE" | cut -d= -f2)"
@@ -387,11 +491,16 @@ while IFS= read -r JSON_LINE; do
     fi
   fi
 
-  # Generate session/window names from first line of prompt
+  # Generate session/window names: prefer YAML name field, fall back to prompt words
   EPOCH_SUFFIX="$(date +%s | tail -c 6)"
-  SESSION_BASE="$(echo "$FIRST_LINE" | awk '{print $1" "$2" "$3}' | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-' | sed 's/^-*//' | sed 's/-*$//' | cut -c1-20)"
+  if [[ -n "$TASK_NAME_FIELD" ]]; then
+    SESSION_BASE="$(echo "$TASK_NAME_FIELD" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-' | sed 's/^-*//' | sed 's/-*$//' | cut -c1-20)"
+    WINDOW="$(echo "$TASK_NAME_FIELD" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-' | sed 's/^-*//' | sed 's/-*$//' | cut -c1-15)"
+  else
+    SESSION_BASE="$(echo "$FIRST_LINE" | awk '{print $1" "$2" "$3}' | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-' | sed 's/^-*//' | sed 's/-*$//' | cut -c1-20)"
+    WINDOW="$(echo "$FIRST_LINE" | awk '{print $1" "$2}' | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-' | sed 's/^-*//' | sed 's/-*$//' | cut -c1-15)"
+  fi
   SESSION="tq-${SESSION_BASE}-${EPOCH_SUFFIX}"
-  WINDOW="$(echo "$FIRST_LINE" | awk '{print $1" "$2}' | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-' | sed 's/^-*//' | sed 's/-*$//' | cut -c1-15)"
 
   # Write state file
   cat > "$STATE_FILE" <<EOF