@codefilabs/tq 0.0.1

package/skills/tq/SKILL.md

@@ -0,0 +1,108 @@
+---
+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
+---
+
+# tq — Claude Task Queue Runner
+
+Script: `${CLAUDE_PLUGIN_ROOT}/scripts/tq`
+
+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.
+
+## Queue File Format
+
+Location: `~/.tq/queues/<name>.yaml`
+
+```yaml
+cwd: /path/to/working/directory   # optional — where claude runs for each task
+tasks:
+  - prompt: fix the login bug in auth service
+  - prompt: write unit tests for payment module
+```
+
+Queue files are **read-only** — tq never modifies them.
+
+## State
+
+State dir: `~/.tq/queues/.tq/<queue-basename>/`
+One file per task, named by 8-char shasum of the prompt:
+
+```
+status=running
+session=fix-the-login-23451
+window=fix-the
+prompt=fix the login bug in auth service
+started=2026-03-05T10:00:00
+```
+
+Statuses: `pending` → `running` → `done`
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/todo <natural language>` | Create/update queue + optionally schedule |
+| `/schedule <natural language>` | Add/update cron schedule for a queue |
+| `/pause <queue>` | Remove run line, keep status-check (resume with `/schedule`) |
+| `/unschedule <queue>` | Remove all cron lines for a queue |
+| `/jobs [filter]` | List all scheduled tq cron jobs |
+| `/health [queue]` | System-wide diagnostics |
+| `/install` | Symlink tq binaries to PATH |
+
+## CLI Usage
+
+```bash
+tq <queue.yaml>           # spawn pending tasks in tmux; skip running/done
+tq --status <queue.yaml>  # print status table; flip dead sessions to done
+```
+
+## Crontab Pattern
+
+```cron
+0 9 * * * /opt/homebrew/bin/tq ~/.tq/queues/morning.yaml >> ~/.tq/logs/tq.log 2>&1
+*/30 * * * * /opt/homebrew/bin/tq --status ~/.tq/queues/morning.yaml >> ~/.tq/logs/tq.log 2>&1
+```
+
+The `tq --status` cron runs every 30 min to reap dead sessions and flip their state to `done`.
+
+## Queue Name Inference
+
+When using `/todo` without an explicit queue name:
+
+- Schedule keyword present → use it: "every morning" → `morning`, "daily" → `daily`, "weekly" → `weekly`
+- No schedule → use `basename` of current working directory
+
+## Reset
+
+- One task: delete its state file from `.tq/<queue-basename>/`
+- Entire queue: `rm -rf ~/.tq/queues/.tq/<queue-basename>/`
+
+## Chrome Integration
+
+tq launches claude with `--chrome` and opens **Chrome Profile 5** (halbotkirchner@gmail.com) automatically before connecting.
+
+### Multiple Chrome profiles / extensions
+
+If you need to interact with a Chrome profile that has a different Claude extension instance (e.g. different account), use the `chrome-devtools` MCP with the `--isolated` flag to run isolated browser extension sessions that don't conflict across profiles.
+
+### Setting the browser display name
+
+The Claude extension stores the browser name as `bridgeDisplayName` in the extension's `chrome.storage.local`. To set it for the first time on a profile:
+- 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
+
+## Additional Resources
+
+- **`references/session-naming.md`** — Session/window name generation algorithm and examples
+- **`references/cron-expressions.md`** — Natural language → cron expression mapping table

package/skills/tq/references/cron-expressions.md

@@ -0,0 +1,67 @@
+# tq Cron Expression Reference
+
+## Natural Language → Cron Mapping
+
+| Natural Language | Cron Expression | Notes |
+|-----------------|-----------------|-------|
+| "every morning" / "daily at 9am" | `0 9 * * *` | Default morning time |
+| "every night" / "nightly" | `0 22 * * *` | 10pm |
+| "every weekday" | `0 9 * * 1-5` | Mon–Fri at 9am |
+| "every weekday at 6pm" | `0 18 * * 1-5` | Mon–Fri at 6pm |
+| "every monday" / "weekly on mondays" | `0 9 * * 1` | 9am Monday |
+| "every monday at 8am" | `0 8 * * 1` | 8am Monday |
+| "every hour" / "hourly" | `0 * * * *` | Top of each hour |
+| "every 4 hours" | `0 */4 * * *` | Every 4 hours |
+| "every 30 minutes" | `*/30 * * * *` | Every 30 min |
+| "daily" | `0 9 * * *` | Default to 9am |
+| "weekly" | `0 9 * * 1` | Default to Monday 9am |
+
+## Day-of-Week Numbers
+
+| Number | Day |
+|--------|-----|
+| 0 or 7 | Sunday |
+| 1 | Monday |
+| 2 | Tuesday |
+| 3 | Wednesday |
+| 4 | Thursday |
+| 5 | Friday |
+| 6 | Saturday |
+
+## Standard tq Crontab Block
+
+Every scheduled queue gets two cron lines:
+
+```cron
+# Run queue (spawn pending tasks)
+<cron> /opt/homebrew/bin/tq ~/.tq/queues/<name>.yaml >> ~/.tq/logs/tq.log 2>&1
+
+# Status sweep (reap dead sessions every 30 min)
+*/30 * * * * /opt/homebrew/bin/tq --status ~/.tq/queues/<name>.yaml >> ~/.tq/logs/tq.log 2>&1
+```
+
+## Updating Crontab
+
+Replace existing lines for the same queue:
+
+```bash
+(crontab -l 2>/dev/null | grep -v "tq.*<name>.yaml"; \
+  echo "<cron> /opt/homebrew/bin/tq ~/.tq/queues/<name>.yaml >> ~/.tq/logs/tq.log 2>&1"; \
+  echo "*/30 * * * * /opt/homebrew/bin/tq --status ~/.tq/queues/<name>.yaml >> ~/.tq/logs/tq.log 2>&1") | crontab -
+```
+
+The `grep -v` removes all existing lines referencing this queue before appending the new ones, ensuring no duplicates.
+
+## Queue Name → Schedule Name Inference
+
+When no queue name is given, infer from the schedule keyword:
+
+| Schedule keyword | Queue name |
+|-----------------|------------|
+| "morning" / "9am" | `morning` |
+| "daily" | `daily` |
+| "weekday" / "weekdays" | `weekday` |
+| "weekly" / "monday" | `weekly` |
+| "hourly" / "every hour" | `hourly` |
+| "nightly" / "night" | `nightly` |
+| no schedule | `basename` of current working directory |

package/skills/tq/references/session-naming.md

@@ -0,0 +1,50 @@
+# tq Session Naming Reference
+
+## Algorithm
+
+Given a prompt string, derive a tmux session name and window name as follows:
+
+### Session Name
+1. Take the first 3 words of the prompt
+2. Lowercase everything
+3. Replace any non-`[a-z0-9]` character with `-`
+4. Strip trailing `-` characters
+5. Truncate to 20 characters
+6. Append `-<epoch-suffix>` (last 6 digits of Unix epoch)
+
+### Window Name
+1. Take the first 2 words of the prompt
+2. Same lowercasing and character replacement as above
+3. Truncate to 15 characters (no epoch suffix)
+
+## Examples
+
+| Prompt | Session | Window |
+|--------|---------|--------|
+| `fix the login bug in auth service` | `fix-the-login-<epoch>` | `fix-the` |
+| `write unit tests for payment module` | `write-unit-tests-<epoch>` | `write-unit` |
+| `Refactor Auth Module` | `refactor-auth-module-<epoch>` | `refactor-auth` |
+| `check LinkedIn saved posts` | `check-linkedin-saved-<epoch>` | `check-linkedin` |
+
+## Bash Implementation
+
+```bash
+EPOCH_SUFFIX="$(date +%s | tail -c 6)"
+SESSION_BASE="$(echo "$PROMPT" | awk '{print $1" "$2" "$3}' \
+  | tr '[:upper:]' '[:lower:]' \
+  | tr -cs 'a-z0-9' '-' \
+  | sed 's/-*$//' \
+  | cut -c1-20)"
+SESSION="${SESSION_BASE}-${EPOCH_SUFFIX}"
+WINDOW="$(echo "$PROMPT" | awk '{print $1" "$2}' \
+  | tr '[:upper:]' '[:lower:]' \
+  | tr -cs 'a-z0-9' '-' \
+  | sed 's/-*$//' \
+  | cut -c1-15)"
+```
+
+## Notes
+
+- Epoch suffix prevents collision when the same prompt is re-queued after a reset
+- tmux session names must not contain `.` or `:` — the character replacement handles this
+- The `-` separator between base and epoch is always present; if the base ends with `-`, it gets stripped first to avoid `--`