Background Agents & Concurrency
Relevant source files
The following files were used as context for generating this wiki page:
The background agent system in Oh-My-OpenCode is a core architectural feature designed to maximize developer throughput by offloading specialized tasks to autonomous subagents. Instead of the main orchestrator (such as Sisyphus) performing linear explorations, it dispatches multiple background agents in parallel to perform codebase mapping, documentation research, and pattern discovery.
This concurrency model allows the system to operate as a coordinated dev team rather than a single linear process. By leveraging background tasks, the primary agent maintains a lean context while specialized agents like explore and librarian perform high-latency search operations asynchronously.
Sources: src/features/background-agent/manager.ts, sisyphus-prompt.md, README.md
Core Orchestration Logic
The system follows a "delegate-by-default" philosophy. When a non-trivial task is identified, the orchestrator determines if it can be broken down and parallelized across specialized categories or subagents.
The Delegation Workflow
The background execution flow typically involves launching agents with the run_in_background=true flag. This immediately returns a task_id, allowing the main session to continue processing while results are gathered.
The diagram above illustrates the non-blocking nature of background task dispatching.
Sources: src/agents/sisyphus.ts, sisyphus-prompt.md
Parallel Wave Execution
For larger projects, such as those initialized via /init-deep, the system organizes background agents into "Execution Waves." Tasks within a single wave run in parallel, while waves themselves are processed sequentially based on dependencies.
| Component | Responsibility | Typical Usage |
|---|---|---|
| Explore Agent | Contextual grep for internal codebase | Parallel pattern discovery |
| Librarian Agent | External reference/doc research | Multi-repo analysis, best practices |
| Execution Waves | Dependency management | Grouping independent tasks for speedup |
Sources: src/features/builtin-commands/templates/init-deep.ts, src/agents/hephaestus.ts
Dynamic Agent Spawning
Background agent counts are not static; they scale based on project complexity. During deep initialization or large refactorings, the system calculates the number of additional agents needed based on file counts, lines of code, and directory depth.
Scaling Thresholds
| Factor | Threshold | Action |
|---|---|---|
| Total Files | >100 | +1 agent per 100 files |
| Total Lines | >10k | +1 agent per 10k lines |
| Directory Depth | ≥4 | +2 for deep exploration |
| Large Files (>500 lines) | >10 | +1 for complexity hotspots |
Sources: src/features/builtin-commands/templates/init-deep.ts
Spawning Strategy
When initialized, the system immediately fires multiple exploration agents to perform specific background tasks:
- Structure Prediction: Predicting patterns for the detected language.
- Entry Point Discovery: Finding main files and organization deviations.
- Convention Analysis: Scanning for
.eslintrc,pyproject.toml, etc. - Anti-pattern Detection: Finding forbidden patterns in comments (e.g., "NEVER", "DEPRECATED").
Sources: src/features/builtin-commands/templates/init-deep.ts
Task Management & Concurrency Control
Concurrency is managed through a lifecycle system that ensures resources are utilized efficiently without overwhelming the underlying providers.
Task Lifecycle
The sequence shows the standard communication pattern between the orchestrator and the background management layer.
Sources: src/agents/sisyphus.ts, src/features/background-agent/manager.ts
Persistence and Session Continuity
Background agents can be resumed to maintain context across multiple turns. By providing a session_id, subagents preserve their internal conversation history, which significantly reduces token usage (up to 70%) and prevents redundant file reads.
Sources: src/agents/sisyphus.ts, src/agents/hephaestus.ts
Summary of Background Commands
The following tools are primarily used to interact with the concurrency system:
| Tool | Action | Description |
|---|---|---|
delegate_task | Dispatch | Launches a specialized agent (subagent_type: explore/librarian). |
background_output | Retrieve | Fetches the results of a completed background task. |
background_cancel | Cleanup | Terminate running background tasks to conserve resources. |
Sources: src/agents/sisyphus.ts, sisyphus-prompt.md
Conclusion
The Background Agent & Concurrency system transforms the LLM from a simple chat interface into a multi-agent dev team. By offloading high-latency exploration and research to parallel subagents, it allows the primary orchestrator to maintain focus on high-level logic and implementation, resulting in a documented "speedup" of approximately 40% compared to sequential execution.
Sources: src/agents/sisyphus.ts, src/features/builtin-commands/templates/init-deep.ts