Experimental Features Overview

OpenCode's experimental features are under active development and may change at any time. This page summarizes all available experimental features and how to enable them.

What are Experimental Features?

Experimental features are new capabilities that the OpenCode team is developing, allowing users to experience and provide feedback before official release.

Characteristics:

Features may be incomplete
APIs may change at any time
Some features require additional dependencies

Enabling Principles:

Enable only what you need, not everything
Disable if you encounter issues
Follow the changelog to stay updated

Quick Enable

Option 1: Enable All at Once

bash

# macOS / Linux: Add to ~/.zshrc or ~/.bashrc
export OPENCODE_EXPERIMENTAL=true

# Then reload
source ~/.zshrc

Option 2: Enable Individual Features

bash

# Enable only the features you need
export OPENCODE_EXPERIMENTAL_LSP_TOOL=true
export OPENCODE_EXPERIMENTAL_PLAN_MODE=true
export OPENCODE_EXPERIMENTAL_CODE_MODE=true
export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true

Experimental Features List

🌐 Web Search

Variable	Description	Related Tutorial
`OPENCODE_ENABLE_EXA`	Enable websearch tool, allowing AI to search the internet	5.23 Web Search & Fetch

How to Enable:

bash

export OPENCODE_ENABLE_EXA=true

Use Cases:

Look up the latest technical documentation and API usage
Search for solutions to error messages
Learn about the latest version features of libraries

Zen Users

If you use OpenCode Zen hosted models, websearch is automatically enabled with no configuration needed.

🔧 LSP Enhancements

Variable	Description	Related Tutorial
`OPENCODE_EXPERIMENTAL_LSP_TOOL`	Enable LSP tools (go to definition, find references, etc.)	5.19 LSP Code Intelligence
`OPENCODE_EXPERIMENTAL_LSP_TY`	Enable experimental ty Python server (replaces pyright)	5.19 LSP Code Intelligence

How to Enable:

bash

export OPENCODE_EXPERIMENTAL_LSP_TOOL=true
export OPENCODE_EXPERIMENTAL_LSP_TY=true

Use Cases:

Allow AI to perform LSP operations like "go to definition" and "find all references"
Use a faster type checker for Python projects

📋 Workflow Enhancements

Variable	Description	Related Tutorial
`OPENCODE_EXPERIMENTAL_PLAN_MODE`	Expose the experimental `plan_exit` tool in the CLI	3.1 Plan & Build

How to Enable:

bash

export OPENCODE_EXPERIMENTAL_PLAN_MODE=true

Use Cases:

Large refactoring tasks: Let AI research and generate a plan first, then execute after review
Uncertain about best approach: Plan multiple options first, then choose before starting
Need manual review: Plan files can be saved, shared, and iterated

The Build and Plan Agents exist whether or not this variable is set, and you can still switch Agents manually. This variable controls only whether the CLI tool list includes plan_exit.

New Tools:

plan_exit: Plan complete, ask whether to switch to build mode

The target version does not implement a plan_enter tool. Enter the Plan Agent with Tab or your configured Agent-switching key.

MCP Code Mode

Variable	Description	Related Tutorial
`OPENCODE_EXPERIMENTAL_CODE_MODE`	Enable the restricted MCP orchestration `execute` tool	5.7b Advanced MCP

How to Enable:

bash

export OPENCODE_EXPERIMENTAL_CODE_MODE=true

execute appears only when the switch is enabled and at least one MCP tool is visible under the current Agent and session permissions. It runs code in a restricted interpreter and can access only the directory of visible MCP tools. It is not a shell, and every MCP invocation still performs the original tool's permission check.

Source: runtime switch, execute visibility conditions, and restricted execution environment.

Background Subagents

Variable	Description
`OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS`	Allow `task` to use `background: true` and move a running synchronous subagent into the background

How to Enable:

bash

export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true

This switch controls only background execution. Whether a subagent can launch another subagent is controlled by the root-level subagent_depth setting. Its default is 1: a primary Agent can launch one level of subagents, but those subagents cannot launch nested subagents.

jsonc

{
  "subagent_depth": 2
}

Before increasing the depth, confirm the permission boundaries and task cost. Once the limit is reached, task returns an error instead of silently degrading.

Source: background experimental switch, background check and depth limit, and the subagent_depth schema.

🗂️ Workspace Management

Variable	Description
`OPENCODE_EXPERIMENTAL_WORKSPACES`	Enable workspace support in the TUI

How to Enable:

bash

export OPENCODE_EXPERIMENTAL_WORKSPACES=1

Use Cases:

Work on multiple projects or repositories at the same time
Use Git Worktree to switch between branches
Isolate context for different tasks

TUI Operations:

Enter /workspaces to open the workspace list
Or press Ctrl+P to open the command palette, then enter "workspace"
Create, switch, and delete workspaces

Currently Supported Workspace Types:

Type	Description
`worktree`	Git Worktree: different branches of the same repository

🎨 UI & Interaction

Variable	Description
`OPENCODE_EXPERIMENTAL_ICON_DISCOVERY`	Auto-discover project icons (displayed in UI)
`OPENCODE_EXPERIMENTAL_MARKDOWN`	Enable experimental Markdown rendering component
`OPENCODE_EXPERIMENTAL_DISABLE_COPY_ON_SELECT`	Disable auto-copy when selecting text in TUI

How to Enable:

bash

export OPENCODE_EXPERIMENTAL_ICON_DISCOVERY=true
export OPENCODE_EXPERIMENTAL_MARKDOWN=true

⚡ Performance & Formatting

Variable	Description	Related Tutorial
`OPENCODE_EXPERIMENTAL_OXFMT`	Enable oxfmt formatter (written in Rust, high performance)	5.18 Code Formatters
`OPENCODE_EXPERIMENTAL_FILEWATCHER`	Enable file watcher for entire directories
`OPENCODE_EXPERIMENTAL_DISABLE_FILEWATCHER`	Disable file watcher

How to Enable:

bash

export OPENCODE_EXPERIMENTAL_OXFMT=true

Prerequisites for oxfmt:

Project has oxfmt dependency in package.json
Experimental flag is enabled

⏱️ Timeouts & Limits

Variable	Type	Description
`OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS`	number	Default timeout for Bash commands (milliseconds)
`OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX`	number	Maximum output tokens for LLM responses

Example:

bash

# Set bash timeout to 2 minutes
export OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS=120000

# Limit LLM output to max 8192 tokens
export OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX=8192

experimental Configuration in opencode.json

Besides environment variables, opencode.json also has an experimental field for configuring another category of experimental features:

json

{
  "experimental": {
    "batch_tool": true,           // Enable batch operation tools
    "openTelemetry": true,        // Enable OpenTelemetry tracing
    "disable_paste_summary": true, // Disable auto-summary for pasted text
    "continue_loop_on_deny": true, // Continue thinking when tool is denied
    "primary_tools": ["tool1"],   // Tools restricted to Primary Agent
    "mcp_timeout": 30000          // MCP request timeout (milliseconds)
  }
}

Field	Description
`batch_tool`	Enable batch tools for executing multiple operations at once
`openTelemetry`	Enable OpenTelemetry for performance monitoring and tracing
`disable_paste_summary`	Don't auto-generate summaries when pasting large text
`continue_loop_on_deny`	When user denies a tool call, Agent continues thinking instead of stopping
`primary_tools`	Specify a list of tools restricted to Primary Agent
`mcp_timeout`	Global timeout for MCP requests (milliseconds)

Complete Configuration Example

Here's a "full-featured" experimental configuration example. Copy what you need:

bash

# ═══════════════════════════════════════════════════════════════
# OpenCode Experimental Features Configuration
# Add to ~/.zshrc or ~/.bashrc, then source it
# ═══════════════════════════════════════════════════════════════

# Enable all experimental features at once (the individual switches below are automatically included)
# export OPENCODE_EXPERIMENTAL=true

# ───────────────────────────────────────────────────────────────
# Web Search (requires Exa API, or use Zen hosted models for auto-enable)
# ───────────────────────────────────────────────────────────────
export OPENCODE_ENABLE_EXA=true           # Enable websearch tool

# ───────────────────────────────────────────────────────────────
# LSP (Language Server Protocol) Enhancements
# ───────────────────────────────────────────────────────────────
export OPENCODE_EXPERIMENTAL_LSP_TOOL=true  # Enable LSP tools
export OPENCODE_EXPERIMENTAL_LSP_TY=true    # Enable experimental ty Python server

# ───────────────────────────────────────────────────────────────
# UI & Interaction
# ───────────────────────────────────────────────────────────────
export OPENCODE_EXPERIMENTAL_MARKDOWN=true         # Experimental Markdown rendering
export OPENCODE_EXPERIMENTAL_ICON_DISCOVERY=true   # Auto-discover project icons

# ───────────────────────────────────────────────────────────────
# Workflow Enhancements
# ───────────────────────────────────────────────────────────────
export OPENCODE_EXPERIMENTAL_PLAN_MODE=true  # Expose the CLI plan_exit tool
export OPENCODE_EXPERIMENTAL_CODE_MODE=true  # Enable the restricted MCP orchestration tool
export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true  # Enable background subagents

# ───────────────────────────────────────────────────────────────
# Workspace Management
# ───────────────────────────────────────────────────────────────
export OPENCODE_EXPERIMENTAL_WORKSPACES=1    # Enable TUI workspace support

# ───────────────────────────────────────────────────────────────
# Performance & Formatting
# ───────────────────────────────────────────────────────────────
export OPENCODE_EXPERIMENTAL_OXFMT=true      # Enable oxfmt formatter

# ───────────────────────────────────────────────────────────────
# Timeouts & Limits (optional)
# ───────────────────────────────────────────────────────────────
# export OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS=120000
# export OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX=8192

FAQ

No effect after enabling?

Confirm configuration has been reloaded:
bash
```
source ~/.zshrc  # or source ~/.bashrc
```
Confirm OpenCode has been restarted: Environment variables are read at process startup
Confirm variable is set:
bash
```
env | grep OPENCODE
```

Feature is unstable?

Experimental features may have issues:

Check the Changelog for latest changes
Disable the problematic feature if issues occur
Report issues on GitHub Issues

How to disable a feature?

If the master OPENCODE_EXPERIMENTAL switch is not enabled, remove or comment out the dedicated variable. If the master switch is true, an unset dedicated variable falls back to it. In that case, explicitly set the dedicated variable to false, or disable the master switch:

bash

export OPENCODE_EXPERIMENTAL_PLAN_MODE=false
# Or remove/disable OPENCODE_EXPERIMENTAL=true

CLI Environment Variables Reference - Complete list of all environment variables
Configuration Options Reference - opencode.json configuration details
Changelog - Learn about feature changes

Experimental Features Overview ​

What are Experimental Features? ​

Quick Enable ​

Option 1: Enable All at Once ​

Option 2: Enable Individual Features ​

Experimental Features List ​

🌐 Web Search ​

🔧 LSP Enhancements ​

📋 Workflow Enhancements ​

MCP Code Mode ​

Background Subagents ​

🗂️ Workspace Management ​

🎨 UI & Interaction ​

⚡ Performance & Formatting ​

⏱️ Timeouts & Limits ​

experimental Configuration in opencode.json ​

Complete Configuration Example ​

FAQ ​

No effect after enabling? ​

Feature is unstable? ​

How to disable a feature? ​

Related Resources ​

Experimental Features Overview

What are Experimental Features?

Quick Enable

Option 1: Enable All at Once

Option 2: Enable Individual Features

Experimental Features List

🌐 Web Search

🔧 LSP Enhancements

📋 Workflow Enhancements

MCP Code Mode

Background Subagents

🗂️ Workspace Management

🎨 UI & Interaction

⚡ Performance & Formatting

⏱️ Timeouts & Limits

experimental Configuration in opencode.json

Complete Configuration Example

FAQ

No effect after enabling?

Feature is unstable?

How to disable a feature?

Related Resources