PromptPilot for AI CLI: task scheduler

PromptPilot: A Queue Scheduler for AI CLI Tools

PromptPilot allows you to queue tasks for AI CLI tools like Claude Code, Codex, and Qwen. The tool runs prompts on a schedule via CLI, web interface, or Telegram bot. It supports priorities, retries on rate limits, and session recovery. The worker processes one task at a time, avoiding API limit races.

Real-world scenarios: warming up limits before work, using leftover quotas before month-end, queuing tasks remotely via bot. Tasks are stored in SQLite with WAL mode for concurrency.

Practical Use Cases

The tool solves everyday developer problems:

• Warming up limits: Schedule a light prompt for 5:00 AM so the session starts early. By 9:00 AM, the limit is partially used; at 10:00 AM — it resets.
• Nighttime rate limit: Late at night, queue a task for reset time — the result is ready in the morning.
• Remote launch: From a taxi via bot, send a code audit — upon return, the limit is refreshed, task completed.
• Mobile tweaks: Add validation to payments.py with tests directly from Telegram.
• Claude skills: Invoke a skill like demo-invite.md via /skills in the bot or a button in the UI.

Example CLI launch:

pp add "Write tests for api.py" --dir C:\Projects\PromptPilot -p 1 -a "2026-04-01T05:00"

System Architecture

Interfaces (CLI, Web UI, TG Bot) write to SQLite (~/.promptpilot). The worker polls the queue every 5s, launches a subprocess with the AI CLI.

Interfaces → SQLite (WAL) → Worker (poll 5s) → subprocess (claude.exe | codex | qwen)
Server: FastAPI + JS UI
Bot: Telegram API

Processes are independent:

• Worker: Single-threaded, one task at a time. On rate limit — exponential backoff.
• Server: REST on :8420, vanilla JS UI.
• Bot: Step-by-step dialogs, authorization by phone number.

Crash recovery: On startup, running tasks are rolled back to pending.

Installation and Configuration

Clone the repository, install editable:

git clone https://github.com/your/promptpilot
cd PromptPilot
pip install -e .

Create .env:

PP_CLAUDE_EXE=C:\Users\username\.local\bin\claude.exe
PP_DEFAULT_CLI=claude
PP_PROJECTS_ROOT=C:\Projects
PP_TASK_TIMEOUT=300
PP_BASE_DELAY=60
PP_MAX_DELAY=3600
PP_TG_TOKEN=...
PP_TG_ALLOWED_PHONES=+79001234567
PP_TASK_PASSWORD=12345

Launching Services

CLI mode:

pp worker  # process queue
pp server  # http://127.0.0.1:8420
pp bot     # Telegram
pp start   # worker + server

Tray (.exe for Windows): Double-click — icon in tray (🟢/🟠/⚫). Build: \.build.ps1 → dist/pp.exe (40MB, self-contained).

PowerShell: \.start.ps1 (all services), \.stop.ps1.

Management Interfaces

CLI

pp add "Refactor db.py" --dir /path -p 5
pp add --file prompts.txt
pp list --status pending

Web UI (:8420)

• Prompt + Ctrl+Enter
• Skills for Claude
• Schedule presets
• Status filters
• Details: tokens, cost, model

Auto-refresh 5s, single HTML file.

Telegram Bot

Authorization: share contact (PP_TG_ALLOWED_PHONES). Step-by-step: prompt → provider → priority → dir → schedule.

Commands: /skills, task list with pagination, details with buttons [Reply|Delete].

Handling Rate Limits

Detection via stderr: "rate limit", "429", "quota exceeded".

Exponential backoff:

def compute_next_run(retry_count: int) -> datetime:
    delay = min(BASE_DELAY * (2 ** retry_count), MAX_DELAY)
    jitter = delay * 0.1 * (random.random() * 2 - 1)
    return datetime.now(timezone.utc) + timedelta(seconds=delay + jitter)

Delays: 60s → 120s → ... → 3600s + ±10% jitter. After max_retries — failed.

Continuing Conversations

Claude might ask: "auth.py or auth_v2.py?". Task saves session_id. In bot/UI: 💬 Reply → new task with --resume <session_id>.

Key Points

• Single-threaded worker guarantees no race conditions for API limits.
• WAL SQLite + crash recovery for reliability.
• Three interfaces: CLI for speed, UI/bot for convenience.
• Exponential backoff with jitter for rate limits.
• Support for skills and Claude Code session resumption.

— Editorial Team