OpenCode Agent Canvas Plugin

A view-only OpenCode plugin that adds a command-driven toggle between the normal OpenCode TUI and a live fullscreen graph view showing agent and subagent relationships.

Features

• In-App Toggle: Switch between normal OpenCode view and fullscreen graph view using a command
• Live Graph Visualization: See agent/subagent relationships, models, statuses, and runtimes in real-time
• Auto-Fit Layout: Graph automatically adjusts to terminal viewport size
• Native-First Ingestion: Uses documented OpenCode events when available, falls back to parsing for complete coverage
• Degraded State Handling: Explicit visual indicators for missing or conflicting metadata
• Crash Recovery: Safe fallback to native OpenCode view if graph rendering fails

Installation

Compatibility Target

This plugin targets exactly one OpenCode baseline:

• OpenCode commit: c529529f84ef60f93ae187b2d89824852b365508
• OpenCode plugin package: @opencode-ai/[email protected]
• Runtime: Bun 1.3.10
• OS: macOS only
• Terminal: Standard macOS terminal environment

V1 Scope

Supported:

• View-only graph visualization (no interaction, filtering, or editing)
• Command-driven toggle between native and graph views
• Auto-fitting terminal graph rendering
• Live updates from agent/subagent events
• Degraded state handling for missing metadata

NOT Supported (V1 Non-Goals):

• Separate monitor window, pane, or companion process
• Interactive features (node inspection, filtering, search, playback)
• Node editing, pinning, or collapse/expand behavior
• Cross-platform support (Linux, tmux-specific features)
• Color-only communication of error states

Install Methods

JN|#### 1. npm Package (Recommended) KT| Install via npm for easiest setup: VJ| YP|json XS|{ YR| "plugin": [ YZ| "[email protected]" NV| ] BN|} BP| TW| BX|Contract: XR|- OpenCode automatically installs npm packages PM|- Simplest installation method PR|- Recommended for most users HQ|

RQ|#### 2. Local Development RJ| SZ|For development or if you want to modify the plugin: XZ| YP|json SW|{ YR| "plugin": [ NP| "file:///absolute/path/to/opencode-copter" RZ| ] BY|} NY| SV| BX|Contract: RP|- Useful during active development WJ|- Requires manual updates for new versions HN|- Same plugin entrypoint shape as npm mode

1. Local Plugin Path (Recommended for Development)

Use a local file:// plugin entry in your OpenCode config:

{
  "plugin": [
    "file:///absolute/path/to/opencode-copter"
  ]
}

Contract:

• Plugin package lives in this repository
• OpenCode loads it from a local absolute path
• Default workflow during active development

2. Package Install (Future)

After package publication, install via package name:

{
  "plugin": [
    "[email protected]"
  ]
}

Contract:

• Use only after package scaffold exists and smoke tests pass
• Keep version pinned, not floating
• Mirrors same plugin entrypoint shape as local-path mode

Configuration

Enable Plugin

To enable the plugin, add it to your ~/.config/opencode/opencode.jsonc:

{
  "plugin": [
    "file:///absolute/path/to/opencode-copter"
  ]
}

Then restart OpenCode for the change to take effect.

Disable Plugin

To disable the plugin without removing it:

1. Comment out or remove the plugin entry from ~/.config/opencode/opencode.jsonc:

{
  "plugin": [
    // "file:///absolute/path/to/opencode-copter"
  ]
}

2. Restart OpenCode

3. Plugin will be disabled but files remain for re-enable

Rollback to Previous Version

If you encounter issues after updating:

1. Git rollback (for local development):

cd /path/to/opencode-copter
git log --oneline -5  # Find previous working commit
git checkout <previous-commit-hash>

2. Restart OpenCode to load the rolled-back version

3. Verify functionality by toggling graph mode

Permissions

The plugin requires standard OpenCode plugin permissions. No additional permissions are needed beyond normal plugin operation.

Usage

Graph Toggle Command

Once installed, use the following command to toggle between native and graph views:

# Enter fullscreen graph view
HB|/graph:toggle

# Exit graph view (returns to native OpenCode)
HB|/graph:toggle

Graph View Features

While in graph view, you'll see:

• Agent Nodes: Parent/child agent relationships with names and models
• Status Indicators: Visual status (active, idle, error) with explicit symbols
• Runtime Labels: Model names and runtime information when available
• Connection Lines: Parent-child relationships between agents
• Auto-Fit: Graph automatically adjusts to your terminal size

Degraded States

The plugin handles missing data explicitly:

• Missing Parent: Shows as root node with inferred marker
• Unknown Model: Displays as "unknown" with explicit symbol
• Conflicting Data: Shows higher-confidence value with conflict indicator
• Missing Runtime: Omits runtime field with visual gap

Resize Handling

• Terminal resize automatically recomputes graph layout
• Graph remains within viewport bounds with padding
• No manual intervention required

Troubleshooting

Plugin Loading Issues

1. Verify OpenCode Version: Ensure you're running OpenCode commit c529529f84ef60f93ae187b2d89824852b365508
2. Check File Path: Confirm absolute path in config is correct
3. Restart OpenCode: Plugin changes require restart to take effect
4. Check Permissions: Ensure standard plugin permissions are available

Graph View Issues

JJ|1. Blank Screen: Exit graph mode immediately using /graph:toggle 2. Clipped Layout: Try resizing terminal or exiting/entering graph mode 3. No Data: Plugin requires active agent sessions to show content 4. Frozen Input: Force exit graph mode if input becomes unresponsive

Uninstall/Remove

1. Remove plugin entry from ~/.config/opencode/opencode.jsonc
2. Restart OpenCode
3. Plugin will no longer be loaded or available

API Dependencies

⚠️ STABILITY WARNING: This plugin relies on internal OpenCode TUI APIs for fullscreen rendering. These internal APIs are not part of the public API contract and may change without notice in future OpenCode versions.

What this means:

• The plugin may break when you upgrade OpenCode
• Internal API changes could cause rendering failures or crashes
• We pin to a specific OpenCode commit (c529529f84ef60f93ae187b2d89824852b365508) to minimize this risk

Risk Mitigation:

• V1 is pinned to a specific OpenCode commit for stability
• Internal dependencies are documented and isolated
• Safe fallback to native view prevents TUI corruption
• If the plugin breaks after OpenCode upgrade, disable it immediately

Before upgrading OpenCode:

1. Check if the plugin still works with the new version
2. If not, disable the plugin until we release a compatible update
3. Report compatibility issues in the project repository

Development

Running Tests

# Run all tests
bun test

# Run integration tests only
bun run test:integration

# Run smoke tests
bun run scripts/smoke-toggle.ts

Evidence Generation

Tests generate deterministic evidence files in test/evidence/ for:

• Toggle cycle behavior
• Resize handling
• Degraded state rendering
• Crash recovery scenarios

Contributing

1. Respect V1 scope guardrails
2. Test against pinned OpenCode version
3. Include evidence for new behavior
4. Document internal API dependencies
5. Maintain crash-safe fallbacks

Version History

V1.0.0

• Initial release with view-only graph visualization
• Native-first event ingestion with fallback parsing
• Auto-fit terminal graph rendering
• Command-driven toggle interface
• Explicit degraded state handling
• Crash recovery and safe fallbacks