Execute prompts from ./prompts/ with various AI models, optional worktree isolation, tmux sessions, and iterative verification loops
Execute prompts from ./prompts/ with different AI models in isolated worktrees or tmux sessions. Use for running tasks with verification loops, parallel processing, or when you need to monitor long-running prompt executions.
/plugin marketplace add cruzanstx/daplug/plugin install daplug@cruzanstx<prompt(s)> [--model claude|codex|gemini|gemini3pro|gemini3flash|zai|local] [--worktree] [--tmux] [--parallel] [--loop]Execute prompts from ./prompts/ directory using various AI models.
| Argument | Description |
|---|---|
<prompt> | Prompt number(s), range(s), or name(s) - defaults to latest |
--model, -m | claude, codex, codex-high, codex-xhigh, gemini, gemini-high, gemini-xhigh, gemini25pro, gemini25flash, gemini25lite, gemini3flash, gemini3pro, zai, local, qwen, devstral |
--worktree, -w | Run in isolated git worktree |
--tmux, -t | Run in tmux session (can monitor/attach later) |
--parallel, -p | Run multiple prompts in parallel |
--loop, -l | Enable iterative verification loop until completion |
--max-iterations <n> | Max loop iterations before giving up (default: 3) |
--completion-marker <text> | Text pattern signaling completion (default: VERIFICATION_COMPLETE) |
123 or fix-bug002-005 (expands to 002, 003, 004, 005)002,005,007002-004,010,015-017IMPORTANT: Get the executor path from Claude's installed plugins manifest:
PLUGIN_ROOT=$(jq -r '.plugins."daplug@cruzanstx"[0].installPath' ~/.claude/plugins/installed_plugins.json)
EXECUTOR="$PLUGIN_ROOT/skills/prompt-executor/scripts/executor.py"
Before spawning monitor agents, verify the required Read permissions exist in ~/.claude/settings.json:
# Check if permissions exist
jq -e '.permissions.allow | map(select(. == "Read(~/.claude/cli-logs/**)" or . == "Read(~/.claude/loop-state/**)")) | length == 2' ~/.claude/settings.json
If permissions are missing, add them:
# Add the required permissions
jq '.permissions.allow = ["Read(~/.claude/cli-logs/**)", "Read(~/.claude/loop-state/**)"] + .permissions.allow' ~/.claude/settings.json > /tmp/settings.json && mv /tmp/settings.json ~/.claude/settings.json
Then inform the user:
Added monitor permissions to ~/.claude/settings.json. Restart Claude Code for changes to take effect.
Required permissions for monitor agents:
Read(~/.claude/cli-logs/**) - Read execution logsRead(~/.claude/loop-state/**) - Read loop state JSON filesFor non-Claude models (codex, gemini, zai, etc):
Use a single executor command that handles everything:
python3 "$EXECUTOR" {PROMPT} --model {MODEL} {--worktree if requested} --run
This single command:
--worktree is passedParse the JSON output to get:
prompts[].worktree.worktree_path - worktree path (if created)prompts[].worktree.branch_name - branch name (if created)prompts[].execution.pid - background process PIDprompts[].execution.log - log file pathprompts[].log - log file pathIf worktree conflict detected (prompts[].worktree.conflict == true):
The executor returns conflict info instead of creating a worktree. Use AskUserQuestion:
AskUserQuestion(
questions: [{
question: "A worktree already exists for this prompt at '{existing_worktree}'. How would you like to proceed?",
header: "Conflict",
options: [
{ label: "Remove & recreate", description: "Delete existing worktree/branch and start fresh" },
{ label: "Reuse existing", description: "Continue using the existing worktree" },
{ label: "Create new branch", description: "Create with incremented suffix (-1, -2, etc.)" }
],
multiSelect: false
}]
)
Based on user choice, re-run executor with --on-conflict:
--on-conflict remove--on-conflict reuse--on-conflict incrementIf executor returns an error (check for error key in JSON):
Common errors and how to handle them:
| Error Message | Cause | Action |
|---|---|---|
No prompts directory: {path} | No prompts/ folder at git root | Report error, suggest: mkdir -p $(git rev-parse --show-toplevel)/prompts |
No prompt found for '{input}' | Prompt number/name doesn't exist | Report error, suggest running /prompts to list available prompts |
No prompt files found | prompts/ exists but is empty | Report error, suggest using /create-prompt to create one |
Ambiguous prompt '{input}' | Multiple prompts match the input | Report matches, ask user to be more specific |
CRITICAL: Do NOT attempt manual CLI execution when the executor fails. Always report the error to the user and suggest fixes.
Example error handling:
If executor output contains {"error": "..."}:
1. Report the error clearly to the user
2. Explain what went wrong
3. Suggest a fix (see table above)
4. STOP - do not try to work around the error
For Claude model:
First get info (no --run), then spawn a Task subagent:
python3 "$EXECUTOR" {PROMPT} --model claude {--worktree if requested}
Then spawn:
Task(
subagent_type: "general-purpose",
description: "Execute prompt {NUMBER}",
run_in_background: true,
prompt: """
{If worktree: You are working in: {WORK_DIR}}
Execute this task completely:
{PROMPT_CONTENT}
After implementation:
1. Make atomic commits with clear messages
2. Verify your changes work
3. Return a summary of what you implemented
{If worktree: Do NOT commit TASK.md}
"""
)
If --tmux flag (for any model):
Get info first, then create tmux session:
python3 "$EXECUTOR" {PROMPT} --model {MODEL} {--worktree if requested}
Then:
SESSION_NAME="prompt-{NUMBER}-$(date +%Y%m%d-%H%M%S)"
tmux new-session -d -s "$SESSION_NAME" -c "{WORK_DIR}"
tmux send-keys -t "$SESSION_NAME" "{CLI_COMMAND} '$(cat {TASK_FILE})' 2>&1 | tee {LOG_FILE}" C-m
THIS STEP HAS TWO MANDATORY PARTS - DO BOTH:
Use the output format defined in <output_format> below. Key elements:
IMMEDIATELY after showing the status table, spawn a monitor for EACH prompt:
Task(
subagent_type: "daplug:readonly-log-watcher",
run_in_background: true,
prompt: """
Monitor prompt {NUMBER} execution:
- Log file: {LOG_FILE}
- State file: ~/.claude/loop-state/{NUMBER}.json (if --loop)
- {If worktree: Worktree: {WORK_DIR}}
Read files every 30 seconds. Report:
- Progress updates (don't spam - every 2-3 checks)
- Completion (success or failure)
- Error summary if failed
Timeout after 60 minutes.
"""
)
For multiple prompts, spawn ALL monitors in a SINGLE message with multiple Task calls.
Example for 3 prompts:
[Message with 3 Task tool calls - one for each prompt's monitor]
DO NOT skip this step. The monitors are how the user gets notified of completion.
The --loop flag enables automatic re-running until the task is genuinely complete. This is inspired by the ralph-wiggum plugin's "self-referential feedback loop" pattern.
Prompts executed with --loop automatically receive these instructions:
<verification_protocol>
**To signal completion:** Output `<verification>VERIFICATION_COMPLETE</verification>` ONLY when:
- All implementation is done
- Tests pass (if applicable)
- Build succeeds (if applicable)
**To signal retry needed:** Output `<verification>NEEDS_RETRY: [reason]</verification>` if:
- Tests are failing
- Build errors exist
- Implementation incomplete
</verification_protocol>
State is tracked in ~/.claude/loop-state/{prompt-number}.json:
{
"prompt_number": "123",
"model": "codex",
"iteration": 3,
"max_iterations": 3,
"status": "running",
"last_updated_at": "2025-12-29T18:30:00",
"history": [
{"iteration": 1, "exit_code": 0, "marker_found": false, "retry_reason": "Tests failing"},
{"iteration": 2, "exit_code": 1, "marker_found": false, "retry_reason": "Lint errors remain"}
],
"suggested_next_steps": [
{"text": "Deploy to staging", "original": "1) Deploy to staging", "source_iteration": 1}
]
}
# Check specific prompt's loop
python3 "$EXECUTOR" 123 --loop-status
# List all active loops
python3 "$EXECUTOR" --loop-status
With --loop flag:
python3 "$EXECUTOR" {PROMPT} --model {MODEL} {--worktree if requested} --run --loop --max-iterations {N}
Parse the JSON output for:
prompts[].execution.status - "loop_running" for background, "completed"/"max_iterations_reached" for foregroundprompts[].execution.loop_log - Log file for the loop processprompts[].execution.state_file - Path to loop state JSONprompts[].execution.iterations - Array of iteration results (foreground mode)prompts[].execution.suggested_next_steps - Suggested follow-ups extracted from logs (foreground mode)When --loop is used, the monitor prompt in Step 2 Part B should include state file info:
Task(
subagent_type: "daplug:readonly-log-watcher",
run_in_background: true,
prompt: """
Monitor prompt {NUMBER} VERIFICATION LOOP:
- State file: ~/.claude/loop-state/{NUMBER}.json
- Loop log: {LOOP_LOG}
- Max iterations: {MAX_ITERATIONS}
Every 15 seconds:
1. Read state file (JSON) - check iteration, status, history
2. Read loop log for recent output
Report:
- ⚠️ When new retry_reason appears in history
- ✅ When status == "completed"
- ❌ When status == "max_iterations_reached"
Timeout after 60 minutes.
"""
)
Remember: This is still part of Step 2 Part B - spawn monitors IMMEDIATELY after showing status.
/daplug:run-prompt 123 # Single prompt with Claude
/daplug:run-prompt 123 --model codex # With Codex
/daplug:run-prompt 123 --model codex --worktree # Codex in isolated worktree
/daplug:run-prompt 123 --tmux # In tmux session
/daplug:run-prompt 123 --worktree --tmux # Worktree + tmux (full isolation)
/daplug:run-prompt 002-005 --parallel --worktree # Range: 002, 003, 004, 005
/daplug:run-prompt 002,005,010 --parallel # Comma list: specific prompts
/daplug:run-prompt 002-004,010 --model codex # Combined range + single
/daplug:run-prompt 123 --model codex --loop # With verification loop
/daplug:run-prompt 123 --model codex --loop --max-iterations 5 # Custom max
/daplug:run-prompt 123 --model codex --worktree --loop # Worktree + loop
For worktree executions, when user says "cleanup" or "merge":
# Get values from the executor output
WORK_DIR="{prompts[].worktree.worktree_path}"
BRANCH_NAME="{prompts[].worktree.branch_name}"
# Ensure not in worktree directory
cd "$(git rev-parse --show-toplevel)"
# Remove TASK.md
rm "$WORK_DIR/TASK.md"
# If merge requested:
git checkout main
git merge --no-ff "$BRANCH_NAME" -m "Merge prompt: {NUMBER}"
# Cleanup worktree
git worktree remove "$WORK_DIR"
git branch -D "$BRANCH_NAME"
git worktree prune
For tmux sessions:
tmux kill-session -t "$SESSION_NAME"
<output_format> Key principle: Tables for info, quick commands for actions.
After launching, show a table with all execution details:
| Prompt | Model | Worktree | Branch | Log |
|--------|-------------|----------------------------------------------------------|---------------------------------------------------|--------------------------------------------------------|
| 289 | codex-xhigh | .worktrees/youtube_summaries-prompt-289-20251228-144050/ | prompt/289-analyze-auto-category-creation | ~/.claude/cli-logs/codex-xhigh-289-20251228-144050.log |
| 303 | codex-xhigh | .worktrees/youtube_summaries-prompt-303-20251228-144052/ | prompt/303-investigate-shorts-generation-workflow | ~/.claude/cli-logs/codex-xhigh-303-20251228-144052.log |
Table columns:
Prompt - Prompt numberModel - CLI model usedWorktree - Path to worktree (if --worktree)Branch - Git branch name (if --worktree)Log - Log file path for monitoringShow running status with emoji indicators:
| Prompt | Status | Monitor |
|-------------------------------------|-------------------------|-----------------------------|
| 289 - Auto Category Analysis | 🟢 Running (PID 278459) | Background agent monitoring |
| 303 - Shorts Workflow Investigation | 🟢 Running (PID 278839) | Background agent monitoring |
Status indicators:
Always include copy-paste ready commands:
Quick check commands:
# Tail logs
tail -f ~/.claude/cli-logs/codex-xhigh-289-20251228-144050.log
tail -f ~/.claude/cli-logs/codex-xhigh-303-20251228-144052.log
# Check worktrees
git worktree list
Command categories to include:
tail -f {LOG} - Monitor live outputgit worktree list - See active worktreestmux attach -t {SESSION} - Attach to tmux (if --tmux)ps -p {PID} - Check if still runningWhen monitor agent reports completion:
✅ Prompt 289 completed
**Summary:** [What was accomplished]
**Files changed:**
- path/to/file1.go (+50, -10)
- path/to/file2.go (+20, -5)
**Next steps:**
# Review changes
cd .worktrees/youtube_summaries-prompt-289-20251228-144050/
git diff main
# Merge if satisfied
git checkout main && git merge --no-ff prompt/289-analyze-auto-category-creation
Or on failure:
❌ Prompt 289 failed
**Errors detected:**
- go: cannot find module providing package...
- build failed: exit status 1
**Log tail:**
[last 20 lines of log]
**Debug:**
# Full log
cat ~/.claude/cli-logs/codex-xhigh-289-20251228-144050.log
# Check worktree state
cd .worktrees/youtube_summaries-prompt-289-20251228-144050/ && git status
</output_format>