OpenCode Agent Plugin

Run OpenCode AI coding assistant (experimental support)

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

Activity state always shows 'unknown'

Cause: OpenCode does not provide per-session activity tracking

Solution: 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

No cost or token usage data

Cause: OpenCode does not expose this data per session

Solution: Track costs manually via:

• API provider’s billing dashboard (OpenAI, etc.)
• Global OpenCode database queries (requires SQLite knowledge)
• Third-party monitoring tools

Cannot resume sessions

Cause: OpenCode does not support native session resumption

Solution: Start a new session instead. Previous context is lost.

Multiple sessions interfere with each other

Cause: Shared global database

Solution: Run OpenCode sessions sequentially, not in parallel. Or use workspace-scoped agents like Claude Code or Codex.

Comparison with Other Agents

Feature	OpenCode	Claude Code	Codex	Aider
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.