> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ComposioHQ/agent-orchestrator/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Warning>
  This plugin is experimental. OpenCode lacks session-scoped tracking, making activity detection and cost tracking unavailable.
</Warning>

## 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

<Note>
  For production use, consider Claude Code or Codex plugins which offer full session introspection.
</Note>

## Installation

```bash theme={null}
# 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`:

```yaml theme={null}
plugins:
  agent: opencode

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

### Configuration Options

<ParamField path="prompt" type="string">
  Task description passed to `opencode run`
</ParamField>

<ParamField path="model" type="string">
  Model identifier passed via `--model` flag
</ParamField>

<Info>
  OpenCode does not support system prompts, permission modes, or many of the configuration options available in other agents.
</Info>

## How It Works

### Launch Command

OpenCode is launched with the prompt as a positional argument:

```bash theme={null}
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

<Warning>
  Activity detection is not supported and returns `null`.
</Warning>

**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

```bash theme={null}
ao spawn my-project "Add unit tests for auth module"
```

### Check Process Status

```bash theme={null}
ao status my-project/agent-123
# Output: running or exited (no other states)
```

### Attach to Session

```bash theme={null}
# Get attach command
ao attach my-project/agent-123

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

## Troubleshooting

<Accordion title="Activity state always shows 'unknown'">
  **Cause**: OpenCode does not provide per-session activity tracking

  **Solution**: This is expected behavior. Check process status instead:

  ```bash theme={null}
  ao status my-project/agent-123
  ```

  Or attach to the session to view actual state:

  ```bash theme={null}
  tmux attach -t agent-123
  ```
</Accordion>

<Accordion title="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
</Accordion>

<Accordion title="Cannot resume sessions">
  **Cause**: OpenCode does not support native session resumption

  **Solution**: Start a new session instead. Previous context is lost.
</Accordion>

<Accordion title="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.
</Accordion>

## 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 |

<Warning>
  OpenCode is not recommended for production use with Agent Orchestrator. Use Claude Code or Codex for full feature support.
</Warning>

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

<ParamField path="AO_SESSION_ID" type="string" required>
  Session identifier (for orchestrator use only)
</ParamField>

<ParamField path="AO_PROJECT_ID" type="string">
  Project identifier (set by caller, not the plugin)
</ParamField>

<ParamField path="AO_ISSUE_ID" type="string">
  Issue/ticket identifier if applicable
</ParamField>

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.