Background Agents & Concurrency
Relevant source files
The following files were used as context for generating this wiki page:
The Background Agents and Concurrency system in Oh My OpenCode is designed to maximize throughput by executing specialized subtasks asynchronously while the primary agent continues its main workflow. This system allows for parallel codebase exploration, documentation research, and complex implementation tasks without blocking the user-facing session.
The architecture relies on the task() tool to spawn background agents such as explore and librarian. These agents act as asynchronous workers that perform contextual grepping or external reference gathering. The results are later collected using the background_output tool, ensuring that data is synthesized only when needed.
Sources: src/features/background-agent/manager.ts, sisyphus-prompt.md:214-230, src/agents/hephaestus.ts:167-185
Core Concurrency Logic
Concurrency is primarily managed through the task() tool with the run_in_background=true parameter. This triggers the background manager to allocate a task_id and execute the subagent independently.
Background Task Lifecycle
The lifecycle of a background task follows a "Spawn-Continue-Collect" pattern. The orchestrator agent (like Sisyphus or Hephaestus) fires multiple agents for different research angles and proceeds with immediate logic.
The diagram shows the parallel flow where background agents perform research while the main session continues.
Sources: sisyphus-prompt.md:214-234, src/agents/hephaestus.ts:187-200
Concurrent Exploration Patterns
In complex commands like /init-deep, the system utilizes massive concurrency to analyze project structure. It measures project scale (file count, line count, depth) and dynamically calculates the number of additional background agents to spawn.
| Factor | Threshold | Additional Agents |
|---|---|---|
| Total files | >100 | +1 per 100 files |
| Total lines | >10k | +1 per 10k lines |
| Directory depth | ≥4 | +2 for deep exploration |
| Large files | >10 files | +1 for complexity hotspots |
Sources: src/features/builtin-commands/templates/init-deep.ts:41-52
Specialized Background Agents
The project defines specific agents optimized for background execution. These agents are designed to be "peer tools" rather than just fallback mechanisms.
Explore Agent
The explore agent functions as a contextual grep. It is used in the background to find authentication implementations, error handling patterns, or module structures across the codebase.
Sources: sisyphus-prompt.md:154-165, src/agents/sisyphus.ts:192-198
Librarian Agent
The librarian agent performs "Reference Grep" on external resources. It is used to fetch official documentation, find best practices for frameworks, or explore open-source implementation examples.
Sources: sisyphus-prompt.md:167-183, src/agents/librarian.ts:50-80
Multi-Agent Interaction Sequence
The following sequence diagram illustrates how Sisyphus orchestrates background agents to fulfill a research request.
This shows the asynchronous nature of task delegation where the orchestrator is not blocked by the subagent's execution time.
Sources: sisyphus-prompt.md:231-240, src/agents/hephaestus.ts:187-202
Task Management and Synchronization
Synchronization is achieved through explicit tool calls that manage background state and task outputs.
Key Concurrency Tools
| Tool | Purpose | Logic |
|---|---|---|
task | Spawner | Launches agents with specific categories/skills. |
background_output | Collector | Retrieves the results of a finished task using its task_id. |
background_cancel | Cleanup | Terminates all running background agents before final delivery. |
session_id | Continuity | Allows resuming a specific subagent session with full context. |
Sources: src/features/background-agent/manager.ts, sisyphus-prompt.md:231-260, src/agents/sisyphus.ts:241-265
Session Continuity
To improve efficiency, agents use session_id. When a background task fails or requires follow-up, passing the session_id to a new task() call ensures the subagent retains its previous conversation context, saving up to 70% of tokens.
Sources: src/agents/sisyphus.ts:251-267, src/agents/hephaestus.ts:258-271
Execution Discipline
The system enforces a strict "Task Discipline" to prevent drift during complex background operations. Agents must create a detailed TODO list using todowrite (or TaskCreate in newer systems) before starting multi-step background work.
Implementation Workflow
- Pre-Implementation: Create detailed TODO list immediately.
- In Progress: Mark tasks as
in_progressone at a time. - Completion: Mark tasks as
completedimmediately upon finishing a sub-unit. - Verification: Run
lsp_diagnosticsor test commands to provide evidence of completion.
Sources: src/agents/hephaestus.ts:31-72, src/agents/sisyphus.ts:40-85
Conclusion
The Background Agents & Concurrency module provides a robust framework for asynchronous AI operations. By separating exploration and research into background tasks, the system achieves a "senior engineer" workflow—performing deep research and verification in parallel with high-level planning. The use of specialized agents, dynamic scaling, and strict task discipline ensures that background work remains accurate, verifiable, and efficient.