OpenCode Sessions

The message mode enables turn-based agent discussion. Agents work together in the same conversation, passing the torch back and forth. This is ideal for workflows like code review (build $\rightarrow$ review $\rightarrow$ build) or research handoffs.

Note: This mode is not recommended when using agents from different providers (e.g., mixing Claude and GPT-4). It is primarily tested with Sonnet 4.5.

// Agent implements, then hands to review agent
session({
  mode: "message",
  agent: "review",
  text: "Review this authentication implementation",
})

The compact mode allows you to trigger manual compaction to manage long conversations approaching token limits. It compresses the history while injecting a handoff context message and your actual message.

What survives compaction:

• The handoff context message: [Compacting session - plan agent will respond after completion]
• Your actual message
• A compacted summary of previous work

session({
  mode: "compact",
  agent: "plan",
  text: "Continue architecture review",
})

The fork mode allows you to branch into independent sessions to explore multiple architectural or design approaches simultaneously. Each fork is a live session with full conversational context that you can discuss and refine before committing to one direction.

Best Practice: Use fork for design/architectural exploration rather than parallel implementations of the same system.

// Exploring architectural approaches
session({
  mode: "fork",
  agent: "plan",
  text: "Design this as a microservices architecture",
})

session({
  mode: "fork",
  agent: "plan",
  text: "Design this as a modular monolith",
})

The new mode is used for clean phase transitions. It completes one work phase and hands off to another agent with a fresh slate, ensuring no context baggage or 'context bleed' from previous work influences the new phase.

Typical Workflow: Research $\rightarrow$ Planning $\rightarrow$ Implementation $\rightarrow$ Validation.

// Fresh session, clean context
session({
  mode: "new",
  agent: "researcher",
  text: "Research API design best practices for 2025",
})

When using message or compact modes, the plugin follows an Agent Relay Pattern to prevent deadlocks and ensure structured collaboration:

1. Queueing: The tool stores your message in a pending queue.
2. Completion: The current agent finishes its turn naturally.
3. Trigger: The session.idle event fires once the session unlocks.
4. Relay: The plugin sends the queued message to the target agent.
5. Response: The target agent receives the message as a USER message and responds in the same conversation.

This ensures agents do not interrupt each other and each agent gets a complete turn to see history and make tool calls.

To check the currently installed version, inspect the package.json in the OpenCode cache:

cat ~/.cache/opencode/node_modules/opencode-sessions/package.json | grep version

To force an update to the latest version, remove the cache directory and restart OpenCode:

rm -rf ~/.cache/opencode && opencode

To use opencode-sessions, you must have OpenCode version 0.15.18 or higher installed. Add the plugin to your opencode.json or ~/.config/opencode/opencode.json file. OpenCode will automatically install the plugin on startup.

To pin to a specific version, use the package@version syntax.

{
  "plugin": ["opencode-sessions"]
}

Or for version pinning:

{
  "plugin": ["opencode-sessions@x.y.z"]
}

If you encounter issues using OpenCode Sessions, check the following common scenarios:

Tool not appearing

• Ensure your OpenCode version is 0.15.18 or higher.
• Verify the plugin is actually installed by checking the cache directory: ls ~/.cache/opencode/node_modules/opencode-sessions.
• Restart OpenCode after installation to ensure the new tool is loaded.

Agent switching not working

• Use the Tab key to see a list of available agents and verify the name exists.
• Check for typos; agent names are case-sensitive.
• Ensure your OpenCode SDK is up to date.

Session operations failing

• Monitor the OpenCode TUI for specific error notifications.
• Confirm that you are currently in an active session.

The session() tool is the primary interface for managing multi-agent workflows. It allows you to switch agents, create new sessions, fork existing ones, or compress conversation history.

Important: Agents do not use this tool automatically. You must explicitly mention the tool in a /command or during conversation to trigger session management.

session({
  text: string,      // Required - message to send
  mode: string,      // Required - "message" | "new" | "compact" | "fork"
  agent?: string     // Optional - target agent name
})

The plugin automatically discovers your configured agents. Built-in agents always available include:

• build: Full development capabilities with all tools.
• plan: Analysis and planning (read-only tools).
• researcher: Research and investigation.
• implement: Implementation-focused.

You can use Tab in OpenCode to see all available agents.

The mode parameter determines how the session is managed: