🚀 Prompt Scheduler

Version 1.0.2 - Modern TypeScript automation tool for scheduling and executing prompts for AI agents with intelligent usage limit detection. Currently supports Claude Code.

📖 日本語版 README

Related projects

• terminal-scheduler — Prompt automation for terminal-based agents, for VSCode.
• ai-bwrap — Run AI coding agents (Claude Code, opencode, Grok, ...) inside a bubblewrap sandbox — one wrapper, any agent.
• agent.txtar — Portable text block for giving structured context to AI agents — embed anywhere, parse anywhere
• opencode-bwrap — Run opencode inside a bubblewrap sandbox — confine AI file access to your current working directory
• claude-code-jsonl-editor — 🚀 Interactive JSONL editor for Claude Code conversation files with real-time file system synchronization. Efficient prompt engineering through…
• cli — CLI tool for managing AI prompts with search and organization capabilities. Personal, secure prompt library with YAML storage and metadata filtering.
• notification-cli — Minimalistic Command Line Notification Application under 50 Lines
• node-cron-cli — Command Line Implementation for Node Cron Under 20 Lines.

✨ Features

• 🎯 Smart Automation: Sequential prompt execution with customizable wait times
• ⏱️ Usage Limit Detection: Automatically detects and waits for AI agent usage limit resets
• 📊 Status Tracking: Real-time progress monitoring with timestamps
• 🎨 Modern UI: Colorful, emoji-rich terminal interface
• 🖥️ Tmux Integration: Direct tmux session control for seamless workflow
• 🔄 Skip Logic: Automatically skips already sent prompts
• ⏰ Time Control: Stop execution at specific times or after duration limits

🛠️ Installation

Quick Install (Recommended)

curl -fsSL https://raw.githubusercontent.com/prompt-scheduler/cli/main/install.sh | bash

Upgrade to Latest Version

To upgrade to the latest version, simply run the same installation command:

# Upgrade to latest version (same command as installation)
curl -fsSL https://raw.githubusercontent.com/prompt-scheduler/cli/main/install.sh | bash

The installer will automatically detect and upgrade your existing installation.

Manual Installation

# Clone the repository
git clone https://github.com/prompt-scheduler/cli.git
cd cli

# Install dependencies
npm install

# Set up your prompts configuration
cp prompts/prompts.jsonl.sample prompts/prompts.jsonl
# Edit prompts/prompts.jsonl with your actual tmux session paths and prompts

Requirements

• Node.js 16+ and npm
• tmux (for automation)
• git (for installation)

🎨 Usage

Quick Commands (via npm scripts)

npm run run      # Execute all unsent prompts
npm run next     # Execute next unsent prompt
npm run status   # Show prompt status
npm run reset    # Reset all prompts to unsent
npm run help     # Show help

Status Monitoring

Track your prompt execution progress with detailed status information:

Advanced Options

# Stop execution at specific time
tsx src/claude-schedule.ts run --stop-at 5pm
tsx src/claude-schedule.ts run --stop-at 17:30

# Run for specific duration
tsx src/claude-schedule.ts run --hours 3
tsx src/claude-schedule.ts run --hours 2.5

# Use custom prompt file
tsx src/claude-schedule.ts run --prompt-file ~/my-prompts.jsonl
tsx src/claude-schedule.ts status --prompt-file ~/custom/prompts.jsonl

# Use sequential execution mode (direct prompt sending)
tsx src/claude-schedule.ts run --mode sequential

# Ignore "Approaching usage limit" messages
tsx src/claude-schedule.ts run --ignore-approaching-limit

Direct TypeScript Execution

tsx src/claude-schedule.ts run     # Start automation
tsx src/claude-schedule.ts status  # Check progress  
tsx src/claude-schedule.ts next    # Execute one prompt
tsx src/claude-schedule.ts 3       # Execute prompt #3

# With custom options
tsx src/claude-schedule.ts run --prompt-file ~/my-prompts.jsonl --mode sequential --ignore-approaching-limit

📋 Commands

Command	Description
run	Execute all unsent prompts sequentially with auto-wait
run --stop-at TIME	Execute prompts until specific time (e.g., 5pm, 17:30)
run --hours N	Execute prompts for N hours
run --prompt-file PATH	Use custom prompt file instead of default
run --mode MODE	Set execution mode: repeat (default) or sequential
run --ignore-approaching-limit	Ignore "Approaching usage limit" messages
next	Execute only the next unsent prompt
status	Show status of all prompts with timestamps
reset	Reset all prompts to unsent status
help	Show help message
[1-n]	Execute specific prompt by index

📁 Configuration

Default Configuration

Copy prompts/prompts.jsonl.sample to prompts/prompts.jsonl and edit it to configure your automation tasks. Each line represents a prompt configuration:

Custom Prompt Files

You can use custom prompt files with the --prompt-file option:

# Create a custom prompt file
cp prompts/prompts.jsonl.sample ~/my-project-prompts.jsonl

# Use it with any command
tsx src/claude-schedule.ts run --prompt-file ~/my-project-prompts.jsonl
tsx src/claude-schedule.ts status --prompt-file ~/my-project-prompts.jsonl

{"prompt": "Create a responsive login form with validation", "tmux_session": "/path/to/your/claude/session", "sent": "false", "sent_timestamp": null, "default_wait": "15m"}
{"prompt": "Add error handling to the login form",