| 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 |
Claude Code Background Agents and Tasks
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.
Quick Summary
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.
Background Bash Commands
When: Long builds, test suites, dev servers, file watches.
How to invoke:
- Press
Ctrl+B during a Bash tool call to move it to background.
- Or: Claude sets
run_in_background=true on the Bash tool parameter.
Behavior:
- Command runs asynchronously. Claude gets back task ID immediately.
- Output written to file in session directory.
- Claude reads output later with Read tool (no blocking).
- Max 30,000 chars per command before file save + preview. 5GB hard output cap before auto-termination.
- Auto-cleaned on session exit.
- List and stop:
/tasks command.
- Disable:
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 Prompts
Scope: Session-local. Expires 7 days or Esc. Restored on --resume if unexpired.
Three modes:
Mode 1: Fixed Interval + Prompt
/loop 5m check if deployment finished
- Interval:
s, m, h, d. Converts to cron; Claude confirms actual schedule.
- Fires between turns, never mid-response. If Claude busy, waits for turn end.
- Jitter: up to 30 minutes after scheduled time (deterministic per task ID to prevent API thundering).
Mode 2: Prompt Only (Self-Paced)
/loop check whether CI passed and address review comments
- Claude chooses delay 1m–1h after each iteration based on observed work.
- May use Monitor tool instead to avoid re-polling.
- Respects 7-day expiry.
- Bedrock/Vertex/Foundry: unsupported; falls back to fixed 10m instead.
Mode 3: Bare /loop (Fixed Built-in Maintenance)
/loop
/loop 15m
- Bare
/loop = built-in maintenance prompt on fixed cron (NOT self-paced). Customizable via .claude/loop.md or ~/.claude/loop.md.
- Bedrock/Vertex/Foundry: bare
/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.
Monitor Tool
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.
Agent View: Background Sessions
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:
- From agent view: type prompt, press Enter.
- From inside session:
/background [prompt] or /bg [prompt].
- From shell:
claude --bg "<prompt>".
Behavior:
- Each session isolated (edits go to separate worktree under
.claude/worktrees/).
- You hand off; Claude runs autonomously.
- Status at a glance. Attach/peek/reply without leaving agent view.
- Supervisor process keeps sessions alive after terminal exit. Restart machine requires
claude respawn <id> recovery.
Subagents (In-Session Delegation)
Scope: Inside one conversation. Spawned by Claude or via /agents command.
Permission behavior (critical distinction):
- Foreground subagents: Show permission prompts as they run (same as main session).
- Background subagents: Don't show prompts; inherit permissions already granted; auto-deny unpermitted calls and keep going.
Behavior:
- Runs in own context.
- Returns summary to main conversation.
- Does not accept new user input mid-task.
- Can inherit full tool access or restricted set.
When: Side research, exploration, parallel investigation.
Dynamic Workflows
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 Routines
Scope: 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 Looping
What: 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.
Comparison Table: When to Use
| 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 |
Polling Without Re-Running Claude
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.
Key Constraints
- Background Bash does not re-invoke Claude. Poll with
/loop, Monitor, or read file.
- Subagents: foreground shows prompts; background doesn't. Critical for permission handling.
- Agent view sessions are discrete. Separate worktrees; don't see main conversation.
- Scheduled tasks (cron) expire 7 days. Extend by recreating, or use
/schedule for durable cloud tasks.
/loop fires between turns, never mid-response. If Claude busy, waits for turn end.- Jitter deterministic per task ID. Prevents API thundering at wall-clock moments.
- Monitor not on Bedrock/Vertex/Foundry. Use
/loop instead.
Common Patterns
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
Monitoring Active Work
- Background Bash:
/tasks command shows running tasks.
/loop: /tasks shows scheduled tasks.- Agent view:
claude agents opens UI.
- Subagents:
/agents shows Running tab.
- Workflows:
/workflows shows phases, agent counts, token totals.
Token Costs
- Background Bash: runs locally, no ongoing tokens.
/loop fixed: one prompt per fire, cache reuse./loop self-paced: one prompt per iteration, Claude chooses delay.- Monitor: streaming; efficient vs polling.
- Agent view: each session fresh context, multiplies tokens.
- Subagents: separate context per agent.
- Workflows: many agents; estimate before large run.
/schedule (cloud): billed separately, runs independently.
