Background Task Engine
Relevant source files
The following files were used as context for generating this wiki page:
The Background Task Engine is a core architectural component of the OhMyOpenCode system designed to facilitate asynchronous, parallel processing of complex software engineering tasks. Its primary purpose is to reduce latency by allowing "Primary" or "Orchestrator" agents (such as Sisyphus or Atlas) to offload intensive research, exploration, and documentation tasks to specialized background agents while simultaneously performing direct tool operations or managing the main session.
The engine operates on a non-blocking execution model where tasks are triggered with a specific run_in_background=true flag. This enables a "two-track" parallel context gathering strategy: a Direct Track for instant wins via local tools (grep, LSP, file reads) and a Background Track for deep search and external documentation retrieval via async subagents.
Sources: src/hooks/keyword-detector/ultrawork/gpt.ts:11-14, src/hooks/keyword-detector/ultrawork/gpt.ts:84-110, src/agents/sisyphus.ts:160-165
Architecture and Components
The engine's architecture relies on the interaction between a master orchestrator and a fleet of specialized subagents. The orchestrator manages the lifecycle of background tasks, from initialization to result collection and eventual cleanup.
Parallel Execution Model
The system is designed to "Parallelize EVERYTHING." Independent tool calls, multiple file reads, and background agent fires are executed simultaneously rather than sequentially to maximize throughput.
The diagram above illustrates how the system bifurcates the workflow into parallel tracks to optimize context gathering speed.
Sources: src/hooks/keyword-detector/ultrawork/gpt.ts:86-93, src/agents/sisyphus/default.ts:251-260
Core Subagent Types
The engine utilizes specific subagent types for background operations:
| Subagent Type | Purpose | Primary Use Case |
|---|---|---|
explore | Internal Codebase Search | Finding patterns, directory structures, and naming conventions within the repository. |
librarian | External Research | Retrieving official documentation, API references, and OSS examples for libraries. |
Sources: src/hooks/keyword-detector/ultrawork/gpt.ts:64-70, src/agents/prometheus/gpt.ts:79-95
Task Lifecycle Management
The lifecycle of a background task is managed through specific API calls and system hooks. Orchestrators must follow a strict protocol to ensure results are properly integrated.
1. Spawning Tasks
Tasks are initiated using the task() function. A substantive prompt following a 4-field structure (Context, Goal, Downstream, Request) is mandatory to ensure the background agent has sufficient guidance.
task(
subagent_type="explore",
run_in_background=true,
load_skills=[],
description="Analysis task",
prompt="[CONTEXT]: ... [GOAL]: ... [DOWNSTREAM]: ... [REQUEST]: ..."
)
Sources: src/agents/sisyphus.ts:182-192, src/agents/sisyphus/default.ts:262-273
2. Processing and Retrieval
While background agents work asynchronously, the main orchestrator continues with non-overlapping work or ends its turn.
- System Reminder: When a task completes, the system sends a
<system-reminder>to the orchestrator. - Collection: Orchestrators call
background_output(task_id="...")only after receiving the reminder. Calling it prematurely is considered a "blocking anti-pattern."
Sources: src/agents/sisyphus/default.ts:285-290, src/agents/sisyphus.ts:205-210
3. Cleanup and Cancellation
To prevent resource leakage, disposable tasks must be cancelled individually once their output is no longer needed.
- Command:
background_cancel(taskId="..."). - Restriction: Using
background_cancel(all=true)is strictly forbidden as it may terminate tasks whose results have not been collected by the orchestrator yet.
Sources: src/agents/atlas/gpt-prompt-sections.ts:168-171, src/agents/sisyphus/default.ts:291-292
Dynamic Scaling and Concurrency
The Background Task Engine supports dynamic agent spawning based on project scale. For instance, the /init-deep command calculates thresholds to determine the number of additional background agents required.
Scaling Thresholds
| 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 (>500 lines) | > 10 files | +1 for hotspots |
Sources: src/features/builtin-commands/templates/init-deep.ts:46-55
The sequence diagram shows the asynchronous handshake between the Orchestrator and the Background agents via the System Registry.
Sources: src/agents/sisyphus.ts:200-213, src/agents/sisyphus/default.ts:280-295
Operational Constraints
To maintain reliability, the Background Task Engine enforces several "Hard Constraints":
- Execution Restriction: Only research and exploration agents (explore/librarian) may run in the background. Implementation or code-writing tasks (
category="...") must never userun_in_background=true. - Persistence: Subagents receive a
session_id. Orchestrators must reuse this ID for follow-up interactions (e.g., fixing an error found in background analysis) to preserve context and save tokens. - Redundancy Check: Orchestrators are forbidden from repeating the same search themselves once it has been delegated to a background agent.
Sources: src/agents/atlas/gpt-prompt-sections.ts:153-157, src/agents/sisyphus.ts:223-235, src/agents/hephaestus/gpt.ts:117-119
Conclusion
The Background Task Engine enables the project's agents to perform deep, multi-threaded codebase analysis without stalling the user experience. By strictly separating "Direct" and "Background" tracks and enforcing a robust lifecycle of spawning, collection, and cancellation, the system ensures that implementation plans are grounded in high-fidelity, comprehensive context gathered across the entire repository and external documentation.