Skip to main content
Spacebot integrates with OpenCode for advanced coding workflows. When you need file editing, git operations, or multi-step code changes, spawn an OpenCode worker.

​
What is OpenCode?

OpenCode is a specialized coding agent with:
  • File editing tools (read, edit, write, glob, grep)
  • Git integration (commit, push, branch, PR creation)
  • Code understanding (symbol search, imports, definitions)
  • Multi-step workflows (refactoring, migrations, test generation)
Spacebot delegates coding work to OpenCode subprocesses.

​
Configuration

Enable OpenCode in your agent.toml:
agent.toml
[worker]
opencode_enabled = true
opencode_path = "/usr/local/bin/opencode"  # Optional: auto-detected if in PATH
​
opencode_enabled
boolean
Whether to use OpenCode for interactive coding workers (default: false)
​
opencode_path
string
Path to the opencode binary. If not set, Spacebot checks PATH.
OpenCode must be installed separately. See OpenCode docs for installation.

​
Spawning OpenCode Workers

When opencode_enabled = true, interactive workers with coding-related tasks are routed to OpenCode: 
{
  "task": "Refactor the authentication module to use async/await",
  "mode": "interactive"
}
Spacebot detects coding intent from keywords:
  • refactor, migrate, update, edit, fix
  • implement, add, create (when referring to code)
  • git, commit, branch, PR, pull request
  • File paths or code snippets in the task
If detected, the worker spawns as an OpenCode subprocess instead of a Rig agent.

​
OpenCode vs. Built-in Workers

Tools:
  • shell, file, exec
  • browser, web_search
  • set_status, task_update
Best for:
  • Running tests
  • Executing scripts
  • System administration
  • Web scraping
  • One-shot file operations

​
Lifecycle

1

Spawn

Channel calls spawn_worker with a coding task. Spacebot detects coding intent and spawns an OpenCode subprocess.
2

Initialize

OpenCode receives the task and workspace directory. It loads project context (files, git state, recent changes).
3

Execute

OpenCode works through the task using its coding tools. It can read, edit, run tests, commit, etc.
4

Interact

The channel can send follow-up messages via the route tool. OpenCode responds with progress updates or questions.
5

Complete

OpenCode returns a summary of changes. The subprocess terminates or waits for more input (interactive mode).
OpenCode workers appear in the channel’s status block like any other worker: 
<active_workers>
  Worker abc-123 (interactive, opencode):
    Task: Refactor authentication module
    Status: editing files
    Progress: 3/5 files updated
</active_workers>

​
Communication Protocol

Spacebot and OpenCode communicate via stdio (JSON-RPC-like messages): 
{"type": "task", "content": "Refactor auth module"}
{"type": "message", "content": "What coding style should I use?"}
{"type": "status", "content": "editing src/auth.rs"}
{"type": "result", "content": "Refactoring complete. 5 files updated."}
​
type
string
Message type: task, message, status, result, error
​
content
string
Message payload
Spacebot translates these to ProcessEvents and channel responses.

​
Git Integration

OpenCode has built-in git awareness:
  • Auto-commit: Can commit changes with descriptive messages
  • Branch management: Create, switch, merge branches
  • PR creation: Use gh pr create to open pull requests
  • Diff review: Show changes before committing
OpenCode respects .gitignore and won’t commit secrets or build artifacts.
Example workflow:
1

Make Changes

OpenCode edits files based on the task.
2

Review Diff

Shows git diff output to the channel.
3

Commit

Commits with a generated message based on changes.
4

Create PR

Opens a pull request with summary and context.

​
Error Handling

If the OpenCode subprocess fails:
  1. Crash: Spacebot detects the subprocess exit and marks the worker as failed
  2. Timeout: After the worker timeout, Spacebot kills the subprocess
  3. Parse error: Invalid JSON from OpenCode logs an error and continues
Failed OpenCode workers write logs to logs_dir/failed/ like built-in workers.

​
When to Use OpenCode

Use OpenCode

  • Multi-file refactoring
  • Code generation from specs
  • Git workflows (branch, commit, PR)
  • Complex search-and-replace
  • Adding features across modules

Use Built-in Worker

  • Running test suites
  • Building/compiling
  • System administration
  • File copying/moving
  • One-off script execution

​
Configuration Examples

[worker]
opencode_enabled = true
# Spacebot finds 'opencode' in PATH

[worker]
opencode_enabled = true
opencode_path = "/home/user/.local/bin/opencode"

[worker]
opencode_enabled = false
# All workers use built-in tools

​
Debugging

OpenCode worker logs include:
  • Subprocess spawn command
  • Stdio communication (messages in/out)
  • Exit code and stderr on failure
Enable debug logging: 
RUST_LOG=spacebot::agent::worker=debug spacebot run
Logs show: 
[DEBUG] spawning opencode worker: /usr/local/bin/opencode --workspace /workspace
[DEBUG] -> {"type": "task", "content": "Refactor auth module"}
[DEBUG] <- {"type": "status", "content": "reading files"}
[DEBUG] <- {"type": "message", "content": "Found 3 files to update"}

​
Limitations

  • One OpenCode worker per task: OpenCode processes are stateful. Don’t spawn multiple workers for the same task.
  • No branching from OpenCode: OpenCode workers can’t create branches or spawn sub-workers.
  • Workspace-scoped: OpenCode operates within workspace_dir only.

​
Future Enhancements

Planned features:
  • Skill injection: Pass Spacebot skills to OpenCode for specialized workflows
  • Shared memory: OpenCode can read Spacebot memories for project context
  • Progress streaming: Real-time file edit notifications
  • IDE integration: Connect OpenCode workers to VSCode/Cursor for live editing

Build docs developers (and LLMs) love

Get started for freeTalk to us