Skip to main content

​
Overview

Background agents let you run multiple specialized agents simultaneously. While one agent writes code, another researches patterns, another checks documentation—like having a full development team.
Background execution is the secret weapon that makes Oh My OpenCode feel 10x faster than traditional single-threaded AI assistants.

​
Quick Start

1

Launch background agent

task(
  category="deep",
  prompt="Analyze authentication patterns in the codebase",
  run_in_background=true
)
2

Continue working

The agent runs in the background. You (or the main agent) can continue other work immediately.
3

Retrieve results

background_output(task_id="bg_abc123")
Or wait for automatic notification when complete.

​
How Background Agents Work

​
Architecture

​
Lifecycle

1

Pending

Task created, waiting for concurrency slot
2

Running

Agent actively working on task
3

Completion

Task finishes with one of:
  • ✅ completed - Successful completion
  • ❌ error - Failed with error
  • ⏹️ cancelled - Manually cancelled
  • 🛑 interrupt - Stale timeout (180s no activity)

​
Using Background Agents

​
The task() Tool

task(
  category: string,              // "deep", "quick", "visual-engineering", etc.
  prompt: string,                 // Detailed task description
  run_in_background: boolean,     // Set to true for background
  load_skills?: string[],         // Optional skills to load
  subagent_type?: string          // Override with specific agent
)

// Deep codebase analysis
task(
  category="deep",
  prompt="Find all authentication flows and document patterns",
  run_in_background=true
)

// Documentation lookup
task(
  subagent_type="librarian",
  prompt="Search for OAuth 2.0 PKCE examples in official docs",
  run_in_background=true
)

// Pattern exploration
task(
  subagent_type="explore",
  prompt="Find all error handling patterns used in services/",
  run_in_background=true
)

​
Retrieving Results

// Get result by task ID
background_output(task_id="bg_abc123")

// Cancel running task
background_cancel(task_id="bg_abc123")
Retrieve results promptly. Background task data is cleared after retrieval.

​
Concurrency Management

By default, Oh My OpenCode allows 5 concurrent tasks per provider/model. This prevents overwhelming API rate limits.

​
Default Limits

{
  "background_task": {
    "defaultConcurrency": 5,
    "staleTimeoutMs": 180000  // 3 minutes
  }
}

​
Per-Provider Limits

{
  "background_task": {
    "providerConcurrency": {
      "anthropic": 3,    // Limit expensive providers
      "openai": 3,
      "opencode": 10,    // Allow more for cheap/free providers
      "zai-coding-plan": 10
    }
  }
}

​
Per-Model Limits

{
  "background_task": {
    "modelConcurrency": {
      "anthropic/claude-opus-4-6": 2,   // Very limited for expensive models
      "opencode/gpt-5-nano": 20         // Allow many for cheap models
    }
  }
}
Priority order: modelConcurrency > providerConcurrency > defaultConcurrency

​
Visual Monitoring with Tmux

See background agents work in real-time using tmux integration.

​
Setup

1

Enable tmux in config

{
  "tmux": {
    "enabled": true,
    "layout": "main-vertical",
    "main_pane_size": 60,
    "main_pane_min_width": 120,
    "agent_pane_min_width": 40
  }
}
2

Run OpenCode in tmux

# Start tmux session
tmux new -s dev

# Run OpenCode with port
opencode --port 3000
3

Watch agents spawn

When background agents run, new panes appear automatically:
┌─────────────────────┬──────────────┐
│                     │              │
│   Main Agent        │  Explore #1  │
│   (Sisyphus)        │              │
│                     ├──────────────┤
│                     │              │
│                     │  Librarian   │
│                     │              │
└─────────────────────┴──────────────┘

​
Layout Options

LayoutDescriptionBest For
main-verticalMain pane left, agents stack rightWide monitors, many agents
main-horizontalMain pane top, agents stack bottomStandard monitors
tiledEqual-size gridFew agents (2-4)
even-horizontalEqual columnsComparing agents side-by-side
even-verticalEqual rowsStacking sequential work

​
Minimum Sizes

{
  "tmux": {
    "main_pane_size": 60,           // Main pane % (20-80)
    "main_pane_min_width": 120,     // Minimum columns for main
    "agent_pane_min_width": 40      // Minimum columns per agent
  }
}
If terminal is too small, agents run without visual panes (background mode continues to work).

​
Real-World Patterns

​
Pattern 1: Research While Building

// Fire research agents immediately
const authPatterns = task(
  subagent_type="explore",
  prompt="Find all auth implementations in the codebase",
  run_in_background=true
)

const oauthDocs = task(
  subagent_type="librarian",
  prompt="Find OAuth 2.0 best practices and examples",
  run_in_background=true
)

// Start implementation with what we know
// Incorporate research results as they arrive

​
Pattern 2: Parallel Implementation

// Split work across multiple agents
const frontend = task(
  category="visual-engineering",
  load_skills=["frontend-ui-ux"],
  prompt="Build the dashboard UI",
  run_in_background=true
)

const backend = task(
  category="deep",
  prompt="Implement the dashboard API endpoints",
  run_in_background=true
)

const tests = task(
  category="quick",
  prompt="Write integration tests for dashboard",
  run_in_background=true
)

// Wait for all to complete

​
Pattern 3: Massive Exploration

// Fire 10+ explore agents to map the codebase
const areas = [
  "authentication flows",
  "database schemas",
  "API routes",
  "test patterns",
  "error handling",
  "configuration",
  "build process",
  "deployment scripts"
]

areas.forEach(area => {
  task(
    subagent_type="explore",
    prompt=`Analyze ${area} in the codebase`,
    run_in_background=true
  )
})
With proper concurrency limits, this pattern is safe and effective for rapid codebase understanding.

​
Pattern 4: Verification Pipeline

// Sequential but parallel verification
task(
  category="quick",
  prompt="Run linter and fix auto-fixable issues",
  run_in_background=true
)

task(
  category="quick",
  prompt="Run type checker and report errors",
  run_in_background=true
)

task(
  category="quick",
  prompt="Run tests and report failures",
  run_in_background=true
)

​
Advanced: Background Notifications

Get OS notifications when background tasks complete.

​
Automatic Notifications

Enabled by default via background-notification hook: 
┌─────────────────────────────┐
│ Background Task Complete    │
│ ────────────────────────    │
│ explore (2.3s)              │
│ Found 15 auth patterns      │
└─────────────────────────────┘

​
Configuration

{
  "notification": {
    "force_enable": true  // Force enable even with other notification plugins
  },
  "disabled_hooks": [
    // "background-notification"  // Disable if unwanted
  ]
}

​
Stale Task Handling

Tasks with no activity for 180 seconds are marked as interrupt. 
{
  "background_task": {
    "staleTimeoutMs": 180000  // 3 minutes (minimum: 60000)
  }
}
Why this matters:
  • Prevents hung agents from blocking concurrency slots
  • Automatically recovers from stuck tool calls
  • Allows retry without manual intervention

​
Debugging Background Tasks

​
View All Active Tasks

// In the main session
"What background tasks are running?"
The agent can introspect its own background task queue.

​
Check Task Status

Logs are written to /tmp/oh-my-opencode.log: 
tail -f /tmp/oh-my-opencode.log | grep background

​
Common Issues

Cause: Concurrency limit reached.Solution: Wait for other tasks to complete, or increase limits:
{
  "background_task": {
    "providerConcurrency": { "anthropic": 5 }
  }
}
Cause: No activity for 180 seconds.Solution:
  • Check logs for hung tool calls
  • Increase timeout if task legitimately needs more time:
{
  "background_task": {
    "staleTimeoutMs": 300000  // 5 minutes
  }
}
Cause: Category not configured.Solution: Set category model explicitly:
{
  "categories": {
    "deep": { "model": "openai/gpt-5.3-codex" }
  }
}

​
Best Practices

Do: Spawn early

Fire background agents immediately, don’t wait until you need results.
// ✅ Good
task(..., run_in_background=true)
// Start other work

// ❌ Bad
// Do everything sequentially
// Then spawn agent

Do: Use cheap models

Background exploration doesn’t need Opus-level intelligence.
{
  "agents": {
    "explore": { "model": "github-copilot/grok-code-fast-1" }
  }
}

Don't: Wait unnecessarily

Let background agents complete naturally.
// ❌ Bad
task(..., run_in_background=true)
wait_for_completion()  // Don't do this

// ✅ Good
task(..., run_in_background=true)
// Continue work, check results when needed

Don't: Ignore concurrency

Setting limits too high overwhelms APIs.
// ❌ Bad
{ "defaultConcurrency": 50 }

// ✅ Good
{ 
  "providerConcurrency": {
    "anthropic": 3,
    "opencode": 10
  }
}

Ultrawork Mode

Automatic parallel agent spawning

Agent Model Matching

Choose the right model for each agent

Categories

Domain-specific agent presets

Prometheus Planning

Strategic planning with parallel execution

Build docs developers (and LLMs) love

Get started for freeTalk to us