Background Agents

Background agents let you offload independent tasks to separate agent instances that run in the background. Each background agent gets its own conversation loop with full tool access — it can read files, write code, run commands, and complete multi-step tasks without blocking your main session.

Spawning a Background Agent

/bg run all the tests and fix any failures

The agent starts immediately and runs in the background. You’ll see:

• A system message confirming the agent started
• A status indicator in the sidebar (▶ while running)
• A completion message when it finishes, with token usage

Managing Background Agents

/bg list              # show all agents with IDs, status, and tokens
/bg kill <id>         # stop a running agent
/bg clear             # remove finished agents from the list

Agent IDs are simple incrementing numbers (0, 1, 2…) shown in both /bg list output and the sidebar.

Model Override

By default, background agents use your active provider and model. Use --model to override:

/bg --model claude-haiku-4-5 summarize all the TODO comments in this repo

LLM-Initiated Background Agents

The model can also spawn background agents on its own when it recognizes an opportunity for parallel work. For example, if you ask it to “refactor the auth module and update the tests,” it might run the test updates as a background agent while it works on the refactor in the main conversation.

This uses the same spawn_background tool that powers /bg, with system prompt guidance on when parallelism is appropriate.

Sidebar Status

The sidebar shows all background agents with status icons:

Icon	Status
▶	Running
✓	Completed
✗	Failed or killed
$	Budget exceeded

Budget Enforcement

Background agents respect per-agent and global token budgets configured in [background_agents]:

[background_agents]
max_agents = 3           # max concurrent agents (default: 3)
per_agent_budget = 50000  # max tokens per agent (default: 50,000)
global_budget = 200000    # max total tokens across all agents (default: 200,000)

When a budget is hit, the agent stops and its status changes to “budget exceeded.”

Session Scope

Background agents are scoped to the current session. Starting a new session (/new) or quitting Caboose stops all running background agents.