@codefilabs/tq 0.0.1

package/README.md

@@ -0,0 +1,296 @@
+# tq — Task Queue for Claude
+
+A lightweight task queue runner that spawns Claude AI tasks as independent tmux sessions.
+
+## What It Does
+
+`tq` lets you define a list of Claude prompts in a YAML file and run them all as independent background jobs. Each prompt gets its own named tmux session running the `claude` CLI — you can attach to any session to watch progress, and detach without interrupting the work.
+
+Tasks are idempotent: running `tq queue.yaml` again skips tasks that are already `done` or have a live `running` session. Task identity is derived from a SHA-256 hash of the prompt content, so changing a prompt text treats it as a new task while re-running unchanged prompts is always a no-op.
+
+The tool is designed for macOS with cron scheduling in mind: drop a queue YAML in `~/.tq/queues/`, add a crontab line, and tasks run automatically every morning (or on whatever schedule you choose). Run `tq --status` to reap dead sessions and print a status table.
+
+## Requirements
+
+- macOS (uses `security` CLI for keychain access to Claude OAuth tokens)
+- tmux (`brew install tmux`)
+- `claude` CLI — [Claude Code](https://claude.ai/code) (`npm install -g @anthropic-ai/claude-code` or similar)
+- python3 (macOS system Python is sufficient — stdlib only, no pip installs needed)
+- Google Chrome with Claude Code extension installed
+- `reattach-to-user-namespace` (optional, `brew install reattach-to-user-namespace` — fixes keychain access in tmux)
+
+## Installation
+
+Run this in your terminal:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/kevnk/tq/main/scripts/tq-install.sh | bash
+```
+
+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.
+
+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`.
+
+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.
+
+5. **Creates `~/.tq/queues/` and `~/.tq/logs/`** — the default directories for queue files and log output.
+
+If `claude` is not on your PATH, steps 2–3 are skipped with a warning and only the CLI tools are installed.
+
+To install the CLI tools to a custom location instead:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/kevnk/tq/main/scripts/tq-install.sh | TQ_INSTALL_DIR=/usr/local/bin bash
+```
+
+## Quick Start
+
+Create a queue file:
+
+```yaml
+# ~/.tq/queues/morning.yaml
+cwd: /Users/yourname/projects/myapp
+
+tasks:
+  - prompt: fix the login bug in the auth service
+  - prompt: write unit tests for the payment module
+  - prompt: |
+      Review the README and update it to reflect
+      the current API endpoints and authentication flow
+```
+
+Run it:
+
+```bash
+tq ~/.tq/queues/morning.yaml
+```
+
+Output:
+
+```
+  [spawned] tq-fix-the-login-451234 -- fix the login bug in the auth service
+  [spawned] tq-write-unit-test-451235 -- write unit tests for the payment module
+  [spawned] tq-review-the-readme-451236 -- Review the README and update it to reflect
+```
+
+Check status:
+
+```bash
+tq --status ~/.tq/queues/morning.yaml
+```
+
+Output:
+
+```
+STATUS     SESSION                   STARTED                PROMPT
+---------- ------------------------- ---------------------- ------
+done       tq-fix-the-login-451234   2026-03-06T09:01:02    fix the login bug in the auth service
+running    tq-write-unit-test-451235 2026-03-06T09:01:03    write unit tests for the payment module
+running    tq-review-the-readme-451236 2026-03-06T09:01:04  Review the README and update it to reflect
+```
+
+## Queue File Format
+
+Queue files are standard YAML:
+
+```yaml
+cwd: /path/to/working/directory   # sets working directory for each claude task
+
+tasks:
+  # Inline prompt (single line)
+  - prompt: fix the login bug in auth service
+
+  # Named task — human-readable label for tmux session naming
+  - name: write-tests
+    prompt: write unit tests for the payment module
+
+  # Block literal (|) — preserves line breaks exactly
+  - prompt: |
+      Write comprehensive unit tests for the payment module.
+      Cover happy path and all error cases.
+      Use jest and mock the Stripe API.
+
+  # Block folded (>) — newlines become spaces (like a paragraph)
+  - prompt: >
+      Refactor the authentication service to use JWT tokens
+      instead of session cookies, updating all dependent endpoints.
+
+  # Quoted inline
+  - prompt: "update the README's installation section"
+```
+
+Queue files are **never modified** by `tq` — they are read-only inputs.
+
+### Notifications (optional)
+
+Add a `message:` block to receive a notification when each task completes:
+
+```yaml
+cwd: /Users/yourname/projects/myapp
+message:
+  service: telegram       # telegram | slack
+  content: summary        # summary | status | details | log
+tasks:
+  - prompt: refactor the auth module
+```
+
+**Content types:**
+- `summary` — Claude writes a 2–3 sentence digest of what it accomplished
+- `status` — task name, done/failed, duration (no live Claude session needed)
+- `details` — prompt first line, status, duration, hash
+- `log` — last 200 lines of tmux pane scrollback
+
+The `message:` block overrides the global config for that queue. Global credentials (bot tokens etc.) live in `~/.tq/config/message.yaml` — never in queue files. Run `/setup-telegram` to configure Telegram notifications interactively.
+
+## Commands
+
+### `tq <queue.yaml>`
+
+Parses the queue file and spawns a new tmux session for each pending task.
+
+- Skips tasks with `status=done`
+- Skips tasks with `status=running` that have a live tmux session
+- Flips tasks with `status=running` but a dead tmux session to `done`, then skips them
+- Spawns all remaining (pending) tasks as new tmux sessions
+
+```bash
+tq ~/.tq/queues/morning.yaml
+```
+
+### `tq --status <queue.yaml>`
+
+Prints a formatted status table for all tasks in the queue. Also reaps any dead tmux sessions by flipping their state from `running` to `done`.
+
+```bash
+tq --status ~/.tq/queues/morning.yaml
+```
+
+Run this via cron every 30 minutes to keep state accurate even if sessions die unexpectedly.
+
+### `tq --prompt <text>`
+
+Run a single ad-hoc prompt without a queue file. Useful for one-off tasks.
+
+```bash
+tq --prompt "fix the login bug in auth service" --cwd ~/projects/myapp --name fix-login
+```
+
+Options:
+- `--prompt <text>` — the prompt to run (required for this mode)
+- `--cwd <dir>` — working directory (defaults to `~/.tq/workspace`)
+- `--name <name>` — label for tmux session naming (defaults to `adhoc`)
+- `--notify <type>` — completion notification: `macos`, `bell`, or a path to a shell script
+
+## How It Works
+
+**Step 1 — Parse**: `tq` runs an embedded Python script (written to a temp file) that reads the queue YAML and generates three files per task, all named by an 8-character SHA-256 hash of the prompt:
+
+- `<hash>.prompt` — the raw prompt text
+- `<hash>.launch.py` — a small Python launcher that `execvp`s into `claude` (replacing itself with the claude process so the tmux window ends up running claude directly)
+- `~/.tq/sessions/<hash>/settings.json` — Claude settings registering a Stop hook
+
+**Step 2 — Auth capture**: The Python parser reads the Claude OAuth token from the macOS keychain (`security find-generic-password -s 'Claude Code-credentials'`) and bakes it into the launcher script. This means each task has its credentials embedded and can run unattended even in a cron context.
+
+**Step 3 — Spawn**: For each pending task, `tq` creates a named tmux session (`tq-<slug>-<epoch>`) and sends `python3 <hash>.launch.py` to it via `tmux send-keys`. The launcher runs inside the tmux window, then `execvp`s into `claude --dangerously-skip-permissions --chrome <prompt>`, replacing itself so the window ends up running a live `claude` session.
+
+**Step 4 — Completion**: When `claude` finishes, the Stop hook (`on-stop.sh`) fires automatically and updates the task's state file: `status=running` → `status=done`. The next `tq` run will skip this task.
+
+## Claude Code Plugin
+
+`tq` ships with a Claude skill definition at `skills/tq/SKILL.md`. Install it into Claude by copying or symlinking the `skills/tq/` directory into `~/.claude/skills/tq/`.
+
+Once installed, Claude can manage your task queues via slash commands:
+
+| Command | Purpose |
+|---------|---------|
+| `/init [dirs...]` | Scan workspace directories and build a project catalog for `cwd:` lookup |
+| `/todo <natural language>` | Create or update a queue and optionally schedule it |
+| `/schedule <natural language>` | Add or update a cron schedule for a queue |
+| `/pause <queue>` | Remove the run cron line (keep status-check) |
+| `/unschedule <queue>` | Remove all cron lines for a queue |
+| `/jobs` | List all scheduled tq cron jobs |
+| `/health` | System-wide diagnostics |
+| `/setup-telegram` | Interactive wizard to configure Telegram notifications |
+| `/install` | Symlink tq binaries to PATH |
+
+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.
+
+### `/init` — Workspace setup
+
+Run `/init` once per machine to tell tq where your projects live:
+
+```
+/init ~/Sites ~/Projects
+```
+
+This scans the given directories for git repositories, writes `~/.tq/config/workspaces.yaml` (which directories to scan), and generates `~/.tq/workspace-map.md` (a catalog of every discovered project with its path and type). Re-run `/init` anytime to refresh after cloning new repos.
+
+Once initialized, `/todo` uses the workspace map to resolve project names in natural language — e.g. "fix the login bug in myapp" will automatically set `cwd:` to myapp's full path.
+
+## State Files
+
+State is stored in `.tq/` directories adjacent to the queue YAML file:
+
+```
+~/.tq/queues/
+├── morning.yaml              ← your queue file
+└── .tq/
+    └── morning/
+        ├── a1b2c3d4          ← task state file (key=value)
+        ├── a1b2c3d4.prompt   ← raw prompt text
+        ├── a1b2c3d4.launch.py ← generated launcher (contains OAuth token)
+        └── ...
+```
+
+Each state file looks like:
+
+```
+status=done
+session=tq-fix-the-login-451234
+window=fix-the
+prompt=fix the login bug in auth service
+started=2026-03-06T09:01:02
+```
+
+**Resetting tasks:**
+
+```bash
+# Reset one task (tq will re-run it next time)
+rm ~/.tq/queues/.tq/morning/a1b2c3d4
+
+# Reset entire queue
+rm -rf ~/.tq/queues/.tq/morning/
+```
+
+## Security Notes
+
+The `.tq/` directories contain live OAuth tokens written in plaintext into `*.launch.py` launcher files at runtime. These files are ephemeral and local-only, but:
+
+- **Never commit `.tq/` directories to git** — they contain your Claude auth tokens
+- Add `.tq/` to your `.gitignore` if your queue files are inside a git repository
+
+The `--dangerously-skip-permissions` flag is passed to every Claude session. This is required for unattended automation — without it, Claude would prompt for permission confirmations that no human is present to answer.
+
+## Scheduling
+
+Add cron entries to run your queues automatically:
+
+```bash
+crontab -e
+```
+
+```cron
+# Run morning queue at 9am daily
+0 9 * * * /opt/homebrew/bin/tq ~/.tq/queues/morning.yaml >> ~/.tq/logs/tq.log 2>&1
+
+# Sweep dead sessions every 30 minutes (keeps status accurate)
+*/30 * * * * /opt/homebrew/bin/tq --status ~/.tq/queues/morning.yaml >> ~/.tq/logs/tq.log 2>&1
+```
+
+Logs accumulate in `~/.tq/logs/tq.log`.
+
+See `skills/tq/references/cron-expressions.md` for a natural language → cron expression reference.

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@codefilabs/tq",
+  "version": "0.0.1",
+  "description": "A lightweight task queue runner that spawns Claude AI tasks as independent tmux sessions",
+  "keywords": [
+    "claude",
+    "ai",
+    "tmux",
+    "queue",
+    "automation",
+    "task-runner",
+    "cron"
+  ],
+  "homepage": "https://github.com/CodefiLabs/tq#readme",
+  "bugs": {
+    "url": "https://github.com/CodefiLabs/tq/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CodefiLabs/tq.git"
+  },
+  "license": "MIT",
+  "bin": {
+    "tq": "./scripts/tq",
+    "tq-message": "./scripts/tq-message",
+    "tq-setup": "./scripts/tq-setup",
+    "tq-telegram-poll": "./scripts/tq-telegram-poll",
+    "tq-telegram-watchdog": "./scripts/tq-telegram-watchdog"
+  },
+  "files": [
+    "scripts/",
+    "skills/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}