Menu
Use when needing to understand or manage background agents, long-running tasks, polling, scheduling, or async work in Claude Code without blocking the session.
Based on SOC occupation classification
Use when unsure which Claude Code capability fits a task, when about to single-thread large/cross-cutting/repetitive work, or when you or the user ask what Claude Code can do — loads the full capability map (signal → capability) and points to the deep-dive skills.
Use when building custom AI agents headlessly, embedding Claude Code tools in an app, or running scripted/cron agents—need SDK package names, setup, core API entry points, supported languages, and relation to Claude Code CLI and Messages...
Use when you need to undo code edits, explore alternatives without losing a starting point, recover from a bad edit path, or restore previous conversation state — press Esc Esc or run /rewind to open checkpoints menu.
Use when a task is too big for one context — broad audits, multi-file migrations, multi-source research, or parallel multi-dimension review — and you want to fan out and orchestrate many subagents deterministically with the Workflow tool (requires ultracode / explicit opt-in).
Use when deciding how to work on a task - choosing effort level, model, or fast mode to balance reasoning depth, speed, and token cost.
Use when setting up or debugging Claude Code GitHub Actions automation, or deciding whether to route CI/CD tasks to GitHub Actions vs local session.
| name | claude-code-background-agents |
| description | Use when needing to understand or manage background agents, long-running tasks, polling, scheduling, or async work in Claude Code without blocking the session. |
| user-invocable | true |
When to use: Background Bash via Ctrl+B or run_in_background=true, /loop with fixed or self-paced intervals, Monitor tool for streaming output, Agent view (claude agents) for parallel sessions, subagents for side tasks, workflows for multi-agent orchestration, /schedule (cloud routines), and /goal for turn-by-turn looping.
Background Bash: Run a shell command asynchronously. Press Ctrl+B during a Bash tool call, or Claude sets run_in_background=true. Command runs; output written to file in session directory. Claude reads output with Read tool. Returns task ID. List and stop with /tasks.
/loop: Recurring prompt on a session-scoped schedule. Fixed interval (5m, 30s) or self-paced. Behind the scenes uses CronCreate/CronList/CronDelete tools. Expires 7 days or when you Esc.
Monitor: Built-in tool; streams background script output line-by-line as each line arrives. Claude reacts mid-conversation without polling. Not available on Bedrock/Vertex/Foundry. More token-efficient than /loop on fixed cron.
Agent view (claude agents): Dispatch and monitor independent background sessions in a dedicated terminal UI. Each session isolated, gets its own worktree. Survives terminal exit (supervisor process keeps them alive). You hand off work; Claude runs autonomously.
Subagents: Spawn a worker inside conversation with separate context. Foreground subagents show permission prompts as they run; background subagents don't and auto-deny unpermitted calls. Returns summary. Does not block main turn.
Workflows: JavaScript script runs in background, orchestrates many subagents. Script holds plan; intermediate results stay out of context. Resumable. Invoke via /workflows or ultracode effort level.
/schedule (cloud routines): Create a task on Anthropic infra. Cron or API trigger. Persists independently of any session.
/goal: Keep session looping turn-by-turn until a condition is met. Session stays active.
When: Long builds, test suites, dev servers, file watches.
How to invoke:
Ctrl+B during a Bash tool call to move it to background.run_in_background=true on the Bash tool parameter.Behavior:
/tasks command.CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1.Key constraint: Background Bash does NOT re-invoke Claude on completion. You or a scheduled /loop must poll or read the output file.
/loop: Local Recurring PromptsScope: Session-local. Expires 7 days or Esc. Restored on --resume if unexpired.
Three modes:
/loop 5m check if deployment finished
s, m, h, d. Converts to cron; Claude confirms actual schedule./loop check whether CI passed and address review comments
/loop (Fixed Built-in Maintenance)/loop
/loop 15m
/loop = built-in maintenance prompt on fixed cron (NOT self-paced). Customizable via .claude/loop.md or ~/.claude/loop.md./loop prints usage instead.Stop: Press Esc (works only during wait). Fixed-cron tasks keep running. Self-paced /loop may stop itself if work complete.
Under the hood: CronCreate, CronList, CronDelete tools. Max 50 tasks per session.
What: Streams background script output line-by-line without polling.
When: More token-efficient alternative to /loop fixed intervals. Claude may choose Monitor for self-paced /loop instead of cron.
How: Claude runs script in background; yields each output line as it arrives. Claude reacts to each line immediately.
Availability: Not on Bedrock/Vertex/Foundry.
Command: claude agents (opens dedicated terminal UI).
What: One screen for all dispatched background sessions. Each is a full Claude Code session, independent, with its own worktree.
How to dispatch:
/background [prompt] or /bg [prompt].claude --bg "<prompt>".Behavior:
.claude/worktrees/).claude respawn <id> recovery.Scope: Inside one conversation. Spawned by Claude or via /agents command.
Permission behavior (critical distinction):
Behavior:
When: Side research, exploration, parallel investigation.
What: JavaScript script orchestrates many subagents in background. Script holds plan; intermediate results stay out of context.
When: Large audits, 500-file migrations, cross-checked research, multi-angle planning.
How: Mention ultracode keyword or ask Claude to write workflow. Script executes in background. Monitor with /workflows. Final report to session when done.
Resumable: Pause/resume within same session. Exit Claude Code = fresh restart next session.
/schedule: Cloud RoutinesScope: Persists on Anthropic infra, independent of any session. Survives machine restart.
Triggers: Cron schedule, API call, GitHub event.
vs /loop: /loop session-local, fires only while Claude running locally. /schedule runs in cloud.
/goal: Turn-by-Turn LoopingWhat: Keep session actively looping until condition is met.
How: /goal all tests pass and code is deployed
Behavior: Claude evals condition after each turn. Session stays awake.
| Use case | Tool | Scope | Blocking? | Survives exit? | Multi-agent? |
|---|---|---|---|---|---|
| Long build/test, check later | Background Bash | Session | No | No | No |
| Poll CI every 5m while working | /loop 5m | Session | No | 7d | No |
| Stream real-time output | Monitor | Session | No | No | No |
| Dispatch independent task | Agent view | Session | No | Yes (supervisor) | Many |
| Side research, return summary | Subagent | Conversation | No | No | Few |
| Codebase audit, 100s of agents | Workflow | Session | No | 7d | Many |
| Cron on cloud, no machine needed | /schedule | Cloud | No | Yes | No |
| Active loop until done | /goal | Session | Partially | No | No |
Pattern: Bash loop + file writes → Claude reads file periodically.
while true; do
curl https://api.example.com/status > /tmp/status.json
sleep 30
done
Claude runs in background. Claude reads /tmp/status.json later. No re-invocation.
Better: Use Monitor or /loop if Claude should react, or /goal for tight feedback.
/loop, Monitor, or read file./schedule for durable cloud tasks./loop fires between turns, never mid-response. If Claude busy, waits for turn end./loop instead.Watch a deploy: /loop 2m did deployment finish? if so, run smoke tests
Babysit a PR: /loop check CI status and new review comments; address them
Audit entire codebase: ultracode: audit every function in src/ for missing error handling
Parallel research: Dispatch three independent investigations via agent view, review findings.
Continuous improvement: /goal all tests pass and code is deployed
/tasks command shows running tasks./loop: /tasks shows scheduled tasks.claude agents opens UI./agents shows Running tab./workflows shows phases, agent counts, token totals./loop fixed: one prompt per fire, cache reuse./loop self-paced: one prompt per iteration, Claude chooses delay./schedule (cloud): billed separately, runs independently.