acp-loop: Recurring Prompt Scheduler
Schedule AI agent prompts to run at intervals or cron schedules.
When to Use This Skill
Use this skill when the user:
- Wants to run a prompt repeatedly at fixed intervals
- Needs cron-style scheduling for agent tasks
- Wants to automate recurring AI workflows
- Asks about scheduling, looping, or periodic execution of prompts
Installation
npm install -g acp-loop
Quick Start
Interval Mode
Run prompts at fixed intervals:
# Every 5 minutes
acp-loop --interval 5m "check logs for errors"
# Every 30 seconds, stop after 10 iterations
acp-loop --interval 30s --max 10 "quick health check"
# Every hour, timeout after 8 hours
acp-loop --interval 1h --timeout 8h "hourly report"
Cron Mode
Run prompts on cron schedules:
# Daily at 3am
acp-loop --cron "0 3 * * *" "nightly cleanup"
# Every Monday at 9am
acp-loop --cron "0 9 * * 1" "weekly standup summary"
# Every 5 minutes (cron style)
acp-loop --cron "*/5 * * * *" "monitor status"
Options Reference
| Option | Description | Example |
|---|---|---|
--interval <duration> | Fixed interval (30s, 5m, 1h) | --interval 5m |
--cron <expression> | Cron expression | --cron "0 9 * * *" |
--agent <name> | Agent to use (default: codex) | --agent claude |
--max <n> | Max iterations | --max 10 |
--timeout <duration> | Max total runtime | --timeout 2h |
--until <string> | Stop when output contains | --until "DONE" |
--quiet | Minimal output | --quiet |
Common Patterns
Conditional Stop
# Run until task reports completion
acp-loop --interval 1m --until "All tests passed" "run test suite"
Limited Runs
# Run exactly 5 times
acp-loop --interval 10s --max 5 "check deployment status"
Time-Boxed Execution
# Run for max 1 hour
acp-loop --interval 5m --timeout 1h "monitor build"
Daily Scheduled Task
# Every day at midnight
acp-loop --cron "0 0 * * *" "generate daily report"
Using Different Agents
# Use Claude instead of Codex
acp-loop --interval 10m --agent claude "review code changes"
# Use Gemini CLI
acp-loop --interval 5m --agent gemini-cli "check status"
Important Notes
- Mutually exclusive: Use either
--intervalOR--cron, not both - Cron library: Uses
croner(handles laptop sleep/wake better than node-cron) - Stop: Press Ctrl+C to stop the loop
- Agent support: Works with any ACP-compatible agent (codex, claude, gemini-cli)
Why acp-loop?
- Claude Code's built-in
/loopcommand has bugs - Works with any ACP-compatible agent, not just Claude
- Proper cron expression support
- Better handling of laptop sleep/wake cycles