Queue long-running tasks (transcoding, API calls, batch processing) to run in background at low priority when user is active, normal priority when idle. Use when scripts take minutes/hours and shouldn't impact PC performance during active use.
Queue long-running tasks (transcoding, API calls, batch processing) to run in background at low priority when user is active, normal priority when idle. Use when scripts take minutes/hours and shouldn't impact PC performance during active use.
/plugin marketplace add theflysurfer/claude-skills-marketplace/plugin install theflysurfer-claude-skills-marketplace@theflysurfer/claude-skills-marketplaceThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Queue manager that runs jobs at low priority when user is active, and normal priority when idle (5min inactivity).
Verified behavior: When user is active, jobs run at IDLE priority (4) - your PC stays responsive. After 5 minutes idle, priority increases for faster execution. Only 1 job runs when active.
# 1. Start the service (keep this terminal open)
qm start --foreground
# 2. In another terminal, add a job
qm add "python my_script.py" --name "My Task"
# 3. Monitor
qm list
qm logs 1
qm start # Background (daemon)
qm start --foreground # With dashboard at http://127.0.0.1:8742
# Create shortcut in startup folder
# Target: pythonw -m idle_queue.cli start
# Or add to Task Scheduler
qm status # Shows service status
curl http://127.0.0.1:8742/api/status # API check
All commands via python -m idle_queue.cli or qm (if installed):
# Add a job to queue
qm add "python script.py" --name "My Task"
qm add "ffmpeg -i in.mp4 out.webm" --name "Transcode" --cwd "C:/videos"
qm add "node build.js" --force # Run even when user active
# List jobs
qm list # All jobs
qm list --status pending # Filter by status
# Job details
qm status <id> # Full job info
qm logs <id> # View stdout/stderr
qm logs <id> --follow # Stream logs live
# Job management
qm cancel <id> # Cancel pending/running job
qm retry <id> # Retry failed job
qm force <id> # Force pending job to run now
# Service control
qm start # Start as background service
qm start --foreground # Start with dashboard
qm stop # Stop service
# Configuration
qm config show # Show current config
qm config set workers.max_when_idle 4
Base URL: http://127.0.0.1:8742/api/
| Method | Endpoint | Description |
|---|---|---|
| GET | /status | Service status (running, activity_state, job counts) |
| GET | /jobs | List all jobs |
| POST | /jobs | Create job {command, name?, cwd?, force?} |
| GET | /jobs/{id} | Job details |
| DELETE | /jobs/{id} | Cancel job |
| POST | /jobs/{id}/retry | Retry failed job |
| POST | /jobs/{id}/force | Force pending job |
| GET | /jobs/{id}/logs | Get job logs |
| GET | /jobs/{id}/logs/stream | SSE log stream |
pending - Waiting in queuerunning - Currently executingcompleted - Finished successfully (exit_code=0)failed - Finished with error (exit_code!=0)cancelled - Manually cancelledqm add "python process_data.py --input data.csv" --name "Process CSV"
qm add "npm run build" --name "Build Project" --cwd "C:/projects/myapp"
qm add "python urgent.py" --name "Urgent Task" --force
qm status 42
qm logs 42
import requests
# Add job
r = requests.post("http://127.0.0.1:8742/api/jobs", json={
"command": "python long_task.py",
"name": "Background Task"
})
job_id = r.json()["id"]
# Check status
status = requests.get(f"http://127.0.0.1:8742/api/jobs/{job_id}").json()
print(status["status"]) # pending, running, completed, failed
qm start before adding jobshttp://127.0.0.1:8742/ when service runs%APPDATA%\idle-queue\logs\%APPDATA%\idle-queue\config.yaml--force-duplicate| User State | Max Workers | CPU Priority | I/O Priority |
|---|---|---|---|
| Active | 1 | IDLE (4) | VERY_LOW |
| Idle (5min) | Unlimited | BELOW_NORMAL | NORMAL |
Tested: Process shows Priority: 4 (IDLE_PRIORITY_CLASS) when user is active.
Problem: Shell escaping issues with special characters in file paths.
| Character | Issue | CLI workaround |
|---|---|---|
! | Escaped to \! | Use API or --cwd |
' (single quote) | Breaks quoting | Use double quotes, escape with '\'' |
" (double quote) | Needs escaping | Use \" inside double-quoted strings |
(space) | Needs quoting | Always quote paths with spaces |
& | Shell interprets as background | Quote the entire command |
() | Shell interprets as subshell | Quote or escape |
$ | Variable expansion | Use single quotes or escape \$ |
| Accents (é, ü) | Encoding issues | Ensure UTF-8, use API |
Recommended approach by complexity:
# SIMPLE - paths without special characters
qm add "ffmpeg -i input.mp4 output.mp4"
# MEDIUM - use --cwd to avoid path issues
qm add "ffmpeg -i input.mp4 output.mp4" --cwd "C:/Movies/My Folder"
# COMPLEX - use API for any special characters
python -c "
import requests
requests.post('http://127.0.0.1:8742/api/jobs', json={
'command': 'ffmpeg -i \"C:/Movies/What\\'s Up!.mp4\" out.mp4',
'name': 'Transcode'
})
"
Why API is safest: The API receives JSON directly without shell parsing, so special characters are preserved exactly as-is.
# Check if port is already in use
netstat -ano | findstr 8742
# Kill process using port
taskkill /F /PID <pid>
# Retry
qm start --foreground
qm startqm force <id># Check logs for error
qm logs <id>
# Common causes:
# - Command not found → check PATH or use full path
# - Working directory doesn't exist → verify --cwd path
# - Permission denied → run as admin if needed
qm startqm config show for api.port%APPDATA%\idle-queue\logs\Bash (usage: run qm commands)WebFetch (usage: API calls if needed)Scenario: User asks to transcode videos
Command:
qm add "ffmpeg -i input.mp4 -c:v libx265 output.mp4" --name "Transcode to H265"
Result: Job queued, runs at low priority, notifications on completion
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.