OpenCode Background Processes Plugin

A flexible background process management plugin for OpenCode, offering robust process tracking and lifecycle management.

Installation

Create or edit your OpenCode configuration file (typically ~/.config/opencode/config.json):

{
  "plugins": ["@rsaulo/opencode-background"]
}

Usage

Example 1: Build Pipeline Management

I need to run and monitor multiple background processes for a build pipeline:

1. Start a long-running build process tagged as ["build", "critical"] that runs: `bun build ./src/index.ts --outdir dist --target bun`
2. Start a test runner tagged as ["test", "validation"] that runs: `bun test --watch`
3. Start a global process tagged as ["lint"] for linting: `mise run lint` (should persist across sessions)
4. List all current processes and show me their statuses
5. List only the processes tagged with "critical" or "validation"
6. Kill the test runner process, then list remaining processes
7. Show all currently running processes one more time to verify

Walk me through each step so I can see how the plugin handles concurrent processes, filtering, and termination.

Demonstrates:

• Creating multiple background processes
• Using tags for categorization
• Global vs session-specific processes
• Listing and filtering by tags
• Process termination
• Real-time status tracking

Example 2: Web Server and Concurrent Testing

Let's test running a web server in the background using json-server:
- Start a json-server instance with: bunx json-server --watch db.json
- Tag it as ["server", "json-api"] for easy management
- Test that it's still running
- Execute a sync cmd (without background) to curl results from the server
- Test that it's still running
- Run a subagent that runs cmds to test the server too
- Confirm the subagent's results

Demonstrates:

• Long-running background services (JSON API server)
• Interleaving background processes with foreground commands
• Process monitoring across concurrent operations
• Subagent coordination with background processes
• Data persistence through process lifecycle
• Full CRUD operations validation while service runs continuously
• Real-time process status verification

Features

• 🚀 Create background processes with real-time output tracking
• 🏷️ Tag and categorize processes
• 🔍 Advanced process filtering
• 🔪 Selective process termination
• 🌐 Global and session-specific process support
• 🖥️ Optional TUI sidebar monitor for currently running background processes
• 💬 Process-to-chat notifications through OPENCODE_NOTIFY: output markers
• :recycle: Automatic cleanup on session end and application close

Usage in OpenCode

TUI Sidebar Monitor

OpenCode versions that support TUI plugins can load this package's ./tui target. When one or more background processes are running, the right sidebar shows a Background section below LSPs. The section lists only processes with running status for the current session, plus global processes. It hides automatically when there are no running processes.

Creating a Background Process

⚙ createBackgroundProcess
  command=/tmp/long-process.sh
  name="Long Running Process"
  tags=["long-process", "processing"]
  global=false  # Optional: default is false

Sending Notifications From a Background Process

A background process can send a message back to the OpenCode session that created it by printing a line that starts exactly with OPENCODE_NOTIFY:.

printf '%s\n' 'OPENCODE_NOTIFY: tests finished; inspect the output and fix any failure'

The text after OPENCODE_NOTIFY: is sent to the originating chat session as an active prompt. This is not just a toast: the agent can respond and take action from the message.

The marker works on both stdout and stderr:

printf '%s\n' 'OPENCODE_NOTIFY: build reached checkpoint 1'
printf '%s\n' 'OPENCODE_NOTIFY: build failed; read this process output and repair it' >&2

Rules for process authors:

• OPENCODE_NOTIFY: must be at the start of the line. Leading spaces prevent notification.
• Empty messages are ignored.
• The marker line is still recorded in the process output and remains available through getBackgroundProcess.
• There is no hard notification limit. Long-running processes can emit signals for hours or days until they exit.
• Keep messages actionable. Avoid high-frequency telemetry unless you intentionally want to flood the chat session.
• Notifications target the session that created the process. If that session no longer exists, notification delivery is best-effort and the process keeps running.

Example watcher script:

#!/usr/bin/env bash
set -euo pipefail

while true; do
  if bun test; then
    printf '%s\n' 'OPENCODE_NOTIFY: tests passed; continue with the next planned step'
  else
    printf '%s\n' 'OPENCODE_NOTIFY: tests failed; inspect the background process output and fix the failure' >&2
  fi

  sleep 30
done

Process Types

• Session-Specific Processes (default):

  • Automatically terminated when the session ends
  • Useful for temporary, session-bound operations
  • Tracked in-memory for the current session

• Global Processes:

  • Persist across sessions
  • Continues running until explicitly stopped
  • Useful for long-running services or background operations

Listing Processes

# List processes in current session
⚙ listBackgroundProcesses
  sessionId=current_session_id

# List processes with specific tags
⚙ listBackgroundProcesses
  tags=["processing"]

Killing Processes

# Kill a specific process
⚙ killProcesses
  processId=specific-process-id

# Kill all processes in a session
⚙ killProcesses
  sessionId=current_session_id

Plugin Methods

createBackgroundProcess

• command: Shell command to execute
• name (optional): Descriptive name for the process
• tags (optional): List of tags to categorize the process
• global (optional):
  • false (default): Session-specific process
  • true: Process persists across sessions

listBackgroundProcesses

• sessionId (optional): Filter processes by session
• status (optional): Filter processes by status
• tags (optional): Filter processes by tags

killProcesses

• processId (optional): Kill a specific process
• sessionId (optional): Kill processes in a specific session
• status (optional): Kill processes with a specific status
• tags (optional): Kill processes with specific tags

Considerations

• Processes are tracked in-memory using a singleton BackgroundProcessManager
• Output stream captures up to the last 100 lines of process output
• Processes can be in states: pending, running, completed, failed, cancelled
• Processes include detailed metadata: start/completion times, error tracking
• ALL processes are killed when OpenCode closes
• Processes generate unique IDs automatically if not specified

Contributing

Contributions are welcome! Please file issues or submit pull requests on the GitHub repository.

License

MIT License. See the LICENSE file for details.