​

OpenCode Integration

​

Message Delivery

1. Plugin registers TCP notify endpoint
2. When messages arrive, hcom sends TCP wake to plugin
3. Plugin calls hcom opencode-read --format
4. Messages injected into OpenCode context

​

Plugin Installation

​

Automatic Install

hcom opencode

​

Manual Install

hcom hooks add opencode

​

Verify Installation

hcom status
# Look for: [✓] opencode

hcom hooks status
# Shows plugin installation status

ls ~/.config/opencode/plugins/hcom.ts

​

Launch Modes

​

PTY Mode (Recommended)

# Single instance in current terminal
hcom opencode

# Multiple instances in new windows
hcom 3 opencode

# With initial prompt
hcom opencode --hcom-prompt "Start by checking hcom list"

# With tag for grouping
hcom opencode --tag backend

• Automatic message delivery via plugin
• Terminal screen capture (hcom term)
• Automatic cleanup on kill (hcom kill)
• Fork and resume support

​

Vanilla Mode

​

Hook Types

// Example
const result = await executeCommand('hcom', [
  'opencode-start',
  '--session-id', sessionId,
  '--notify-port', port.toString()
]);

​

Plugin Architecture

​

Plugin File

export default class HcomPlugin implements Plugin {
  name = 'hcom';
  
  // Lifecycle hooks
  async onSessionCreated(session: Session) {}
  async onSessionDeleted(session: Session) {}
  
  // Status tracking
  async onStatusChange(session: Session, status: string) {}
  async onIdle(session: Session) {}
  
  // Message delivery
  async deliverPendingToIdle(session: Session) {}
}

​

TCP Notify Endpoint

1. Plugin starts TCP server on random port
2. Passes port to opencode-start --notify-port
3. hcom stores endpoint in database
4. When messages arrive, hcom sends TCP wake
5. Plugin’s deliverPendingToIdle() fires

• Plugin can’t hook into hcom’s event loop
• Polling would be inefficient
• TCP wake provides instant notification

​

Message Polling

# Check for messages
hcom opencode-read --name <instance> --check
# Output: "true" or "false"

# Fetch messages (JSON array)
hcom opencode-read --name <instance>
# Output: [{"from":"luna","text":"hello"}]

# Fetch formatted messages
hcom opencode-read --name <instance> --format
# Output: formatted text for injection

# Acknowledge messages
hcom opencode-read --name <instance> --ack --up-to 42
# Advances cursor to event_id 42

​

Configuration

​

Default Arguments

hcom config opencode_args "--model o3"

​

System Prompt

​

Session Binding

​

PTY Mode

1. Plugin fires onSessionCreated event
2. Calls hcom opencode-start --session-id <id> --notify-port <port>
3. hcom binds session to process via HCOM_PROCESS_ID
4. Returns JSON: {"name": "luna", "bootstrap": "..."}
5. Plugin injects bootstrap into session

​

Re-binding (Compaction/Resume)

1. opencode-start detects existing binding
2. Re-injects bootstrap
3. Preserves identity across restarts

​

Launch Examples

​

Single Agent

# Current terminal
hcom opencode

# New window
hcom 1 opencode

# With initial prompt
hcom opencode --hcom-prompt "Check hcom list"

​

Multiple Agents

# 3 agents in new windows
hcom 3 opencode

# Tagged group
hcom 3 opencode --tag api

​

Fork and Resume

# Fork active or stopped agent
hcom f luna

# Resume stopped agent
hcom r luna

​

OpenCode Database Path

​

Message Delivery Flow

1. Message arrives: Another agent sends message
2. Event logged: Message stored in hcom database
3. Notify endpoints: hcom sends TCP wake to plugin
4. Plugin wakes: deliverPendingToIdle() fires
5. Check messages: Plugin calls opencode-read --check
6. Fetch messages: Plugin calls opencode-read --format
7. Inject: Plugin adds messages to session context
8. Acknowledge: Plugin calls opencode-read --ack

​

Advanced

​

Plugin Update

1. ensure_plugin_installed() checks if current
2. Compares installed vs embedded source
3. Re-writes plugin if outdated
4. No OpenCode restart needed (auto-reload)

hcom hooks status
# Shows if plugin is current

hcom hooks remove opencode
hcom hooks add opencode

​

Plugin Scan Directories

• ~/.config/opencode/plugin/ (legacy)
• ~/.config/opencode/plugins/ (current)
• $OPENCODE_CONFIG_DIR/plugin/
• $OPENCODE_CONFIG_DIR/plugins/

​

Last Event ID Initialization

1. Check if last_event_id == 0 (new instance)
2. Use HCOM_LAUNCH_EVENT_ID env var if set
3. Otherwise use current max event ID
4. Prevents historical messages from flooding new instance

• Prevents delivering all historical messages
• Preserves message history for resume
• Respects launch event boundary

​

Message Read Modes

hcom opencode-read --name luna
# [{"from":"nova","text":"hi"}]

hcom opencode-read --name luna --format
# [nova]: hi

hcom opencode-read --name luna --check
# true

hcom opencode-read --name luna --ack --up-to 42
# {"acked_to":42}

​

Troubleshooting

​

Plugin not loading

1. Check plugin exists: ls ~/.config/opencode/plugins/hcom.ts
2. Check OpenCode logs for plugin errors
3. Reinstall plugin: hcom hooks add opencode

​

Messages not arriving

1. Check agent status: hcom list shows listening
2. Verify plugin loaded: Check OpenCode plugin manager
3. Check TCP notify: hcom list <name> --json | grep notify
4. Try manual send: hcom send @opencode-instance -- test

​

TCP notify not working

1. Check firewall: TCP wake uses localhost
2. Check port in use: Plugin uses random port
3. Restart OpenCode session

​

Plugin outdated

hcom hooks status
# Shows if plugin needs update

hcom hooks remove opencode
hcom hooks add opencode
# Reinstalls latest plugin

​

Reference

pub fn install_opencode_plugin() -> std::io::Result<bool>
pub fn remove_opencode_plugin() -> std::io::Result<()>
pub fn verify_opencode_plugin_installed() -> bool
pub fn ensure_plugin_installed() -> bool

pub fn dispatch_opencode_hook(hook_name: &str, argv: &[String]) -> (i32, String)

fn handle_start(ctx: &HcomContext, db: &HcomDb, argv: &[String]) -> (i32, String)
fn handle_status(db: &HcomDb, argv: &[String]) -> (i32, String)
fn handle_read(db: &HcomDb, argv: &[String]) -> (i32, String)
fn handle_stop(db: &HcomDb, argv: &[String]) -> (i32, String)