Skip to main content
The OpenCode agent plugin provides basic integration with the OpenCode AI coding assistant. This is a minimal implementation due to OpenCode’s limited introspection capabilities.
This plugin is experimental. OpenCode lacks session-scoped tracking, making activity detection and cost tracking unavailable.

​
Overview

OpenCode is an AI coding assistant that stores session data in a global SQLite database. The plugin:
  • Launches OpenCode with inline prompt delivery
  • Detects process status (running/exited)
  • Does not support activity detection, cost tracking, or metadata updates
For production use, consider Claude Code or Codex plugins which offer full session introspection.

​
Installation

# Install OpenCode (installation method varies)
npm install -g opencode
# OR follow official installation instructions

# Verify installation
which opencode
opencode --version

​
Configuration

Configure in agent-orchestrator.yaml: 
plugins:
  agent: opencode

projects:
  - name: my-project
    path: ~/code/my-project
    agentConfig:
      model: gpt-4
      prompt: "Fix the linting errors"

​
Configuration Options

​
prompt
string
Task description passed to opencode run
​
model
string
Model identifier passed via --model flag
OpenCode does not support system prompts, permission modes, or many of the configuration options available in other agents.

​
How It Works

​
Launch Command

OpenCode is launched with the prompt as a positional argument: 
opencode run "Fix the linting errors" --model gpt-4

​
Process Detection

The plugin checks if the opencode process is running:
  • Tmux runtime: Searches ps output for “opencode” on the session’s TTY
  • Process runtime: Checks if the PID is alive via process.kill(pid, 0)

​
Activity Detection

Activity detection is not supported and returns null.
Reason: OpenCode stores all session data in a single global SQLite database (~/.local/share/opencode/opencode.db) without per-workspace scoping. When multiple OpenCode sessions run in parallel, database modifications from any session would cause all sessions to appear active. Until OpenCode provides per-workspace session tracking, the plugin cannot reliably detect activity state.

​
Limitations

​
No Session Introspection

The plugin returns null for:
  • getSessionInfo(): No summaries, token counts, or cost estimates
  • getRestoreCommand(): No native resume support
  • getActivityState(): Cannot determine if agent is active, idle, or waiting

​
No Metadata Updates

OpenCode does not support hooks or command interception. Session metadata is never automatically updated.

​
Single Database

All sessions share ~/.local/share/opencode/opencode.db, making it impossible to:
  • Track costs per session
  • Distinguish activity between concurrent sessions
  • Resume specific sessions

​
Usage Examples

​
Spawn an Agent

ao spawn my-project "Add unit tests for auth module"

​
Check Process Status

ao status my-project/agent-123
# Output: running or exited (no other states)

​
Attach to Session

# Get attach command
ao attach my-project/agent-123

# Manually attach (tmux runtime)
tmux attach -t agent-123

​
Troubleshooting

Cause: OpenCode does not provide per-session activity trackingSolution: This is expected behavior. Check process status instead:
ao status my-project/agent-123
Or attach to the session to view actual state:
tmux attach -t agent-123
Cause: OpenCode does not expose this data per sessionSolution: Track costs manually via:
  • API provider’s billing dashboard (OpenAI, etc.)
  • Global OpenCode database queries (requires SQLite knowledge)
  • Third-party monitoring tools
Cause: OpenCode does not support native session resumptionSolution: Start a new session instead. Previous context is lost.
Cause: Shared global databaseSolution: Run OpenCode sessions sequentially, not in parallel. Or use workspace-scoped agents like Claude Code or Codex.

​
Comparison with Other Agents

FeatureOpenCodeClaude CodeCodexAider
Session Isolation❌ Global DB✅ Per-workspace✅ Per-workspace✅ Per-workspace
Cost Tracking❌ None✅ Full✅ Full❌ None
Activity Detection❌ None✅ JSONL events✅ File mtime⚠️ Git commits
Auto-metadata❌ None✅ PostToolUse✅ PATH wrappers❌ None
Resume Support❌ None✅ Native✅ Native❌ None
Maturity⚠️ Experimental✅ Production✅ Production✅ Stable
OpenCode is not recommended for production use with Agent Orchestrator. Use Claude Code or Codex for full feature support.

​
When to Use OpenCode

Consider OpenCode if:
  • You’re already invested in the OpenCode ecosystem
  • You only run one agent at a time (no parallelism)
  • You don’t need cost tracking or session introspection
  • You’re experimenting with different agent providers
For production deployments, use Claude Code or Codex instead.

​
Environment Variables

The plugin sets minimal environment variables:
​
AO_SESSION_ID
string
required
Session identifier (for orchestrator use only)
​
AO_PROJECT_ID
string
Project identifier (set by caller, not the plugin)
​
AO_ISSUE_ID
string
Issue/ticket identifier if applicable

​
Future Improvements

For OpenCode to be production-ready, it needs:
  1. Per-workspace session storage: Move away from global SQLite DB
  2. Session introspection API: Expose token counts, costs, summaries
  3. Activity events: JSONL or similar format for state detection
  4. Command hooks: PostToolUse or similar for metadata updates
  5. Resume support: Native thread/session resumption
Until these features are added, the plugin remains experimental.

​
Contributing

If you’re an OpenCode contributor interested in improving orchestrator integration:
  1. Add per-workspace session directories (like Claude’s ~/.claude/projects/{path}/)
  2. Export JSONL event logs for activity tracking
  3. Support --resume <session-id> flag
  4. Provide token count and cost APIs
Reach out to the Agent Orchestrator team for integration guidance.

Build docs developers (and LLMs) love

Get started for freeTalk to us