acp-loop
Website: https://github.com/femto/acp-loop CLI Tool: acp-loop Repository: https://github.com/femto/acp-loop Protocol: Agent Client Protocol (ACP)
Description
acp-loop is a recurring prompt scheduler for ACP agents. Inspired by Claude Code's /loop command, it runs prompts on a recurring interval or cron schedule, enabling automated monitoring, polling, and scheduled AI agent tasks.
Install
npm install -g acp-loop
Or use without installing:
npx acp-loop@latest
Usage
Basic Interval Scheduling
# Run every 5 minutes
acp-loop --interval 5m "check if deploy succeeded"
# Run every hour
acp-loop --interval 1h "review open PRs"
# Run every 30 seconds
acp-loop --interval 30s "check build status"
Cron Scheduling
# Every 10 minutes
acp-loop --cron "*/10 * * * *" "summarize new issues"
# Daily at 9am
acp-loop --cron "0 9 * * *" "generate daily report"
# Every Monday at 8am
acp-loop --cron "0 8 * * 1" "weekly PR review"
Agent Selection
# Use acpx's default agent
acp-loop --interval 5m "check status"
# Use a specific agent alias
acp-loop --interval 5m -a claude "check status"
acp-loop --interval 5m -a codex "check status"
# Use a raw ACP agent command
acp-loop --interval 5m --agent "npx -y @zed-industries/claude-agent-acp" "check status"
Unattended Mode (Auto-approve)
# Auto-approve all permission requests
acp-loop --interval 5m -a claude --approve-all "check latest Twitter mentions"
# Auto-approve reads only
acp-loop --interval 5m -a claude --approve-reads "summarize new issues"
CLI Options
| Option | Description |
|---|---|
--interval <duration> |
Run on fixed interval (30s, 5m, 1h) |
--cron <expression> |
Run on cron schedule |
-a, --agent-name <name> |
Use acpx agent alias (claude, codex) |
--agent <command> |
Pass raw ACP agent command to acpx |
--approve-all |
Auto-approve all permissions |
--approve-reads |
Auto-approve reads, prompt for others |
--deny-all |
Deny all permissions |
--max <n> |
Stop after n iterations |
--timeout <duration> |
Stop after total elapsed time |
--until <string> |
Stop when output contains string |
--quiet |
Suppress loop logs, stream agent output only |
Stop Conditions
# Run until condition met
acp-loop --until "deploy succeeded" --interval 1m "check deploy status"
# Max iterations
acp-loop --max 10 --interval 5m "check status"
# Timeout
acp-loop --timeout 1h --interval 5m "monitor build"
# Combine conditions
acp-loop --max 20 --timeout 2h --until "success" --interval 5m "check build"
Use Cases
Monitoring
# Health checks every minute
acp-loop --interval 1m "check if API is responding"
# Monitor deployment
acp-loop --until "deployed" --interval 30s "check deployment status"
Polling
# Watch for new issues
acp-loop --interval 10m "check for new GitHub issues and summarize"
# Monitor PR updates
acp-loop --interval 5m "check if my PR has new comments"
Scheduled Tasks
# Daily summary
acp-loop --cron "0 9 * * *" "summarize yesterday's commits"
# Weekly report
acp-loop --cron "0 8 * * 1" "generate weekly progress report"
Long-Running Workflows
# Auto-retry failed tasks
acp-loop --max 5 --interval 2m "retry the failed test suite"
# Progress monitoring
acp-loop --timeout 1h --interval 5m "check migration progress"
Examples
Deploy Watcher
acp-loop --until "deploy succeeded" --timeout 30m --interval 1m \
"check if the production deploy completed successfully"
CI Monitor
acp-loop --max 10 --interval 2m --approve-reads \
"check GitHub Actions status for my latest commit"
Issue Triage
acp-loop --cron "0 */2 * * *" -a claude --approve-all \
"review new issues and add appropriate labels"
Agent Selection Rules
- Omit
--agentand-ato use acpx's configured default agent - Use
-a claudefor acpx short aliases - Use
--agent "npx ..."for custom ACP agent commands --agentand-aare mutually exclusive--approve-all,--approve-reads, and--deny-allare mutually exclusive
Troubleshooting
Stalls at "initialize (running)"
Check your acpx config:
acpx config show
Use explicit ACP adapter if needed:
acp-loop --interval 5m --agent "npx -y @zed-industries/claude-agent-acp" "hello"
Loop exits on permission request
Pass permission flags for unattended runs:
acp-loop --interval 5m -a claude --approve-all "task requiring permissions"
Notes
- Built on top of
acpx- requires acpx to be installed or available via npx - Each loop iteration runs as a one-shot
acpx execcommand - Supports all acpx permission flags for unattended operation
- Graceful shutdown on Ctrl+C
Comments (0)
Add a Comment
No comments yet. Be the first to comment!