Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/lnardev/opencode-config-agent/llms.txt

Use this file to discover all available pages before exploring further.

The tui.json file configures OpenCode’s terminal user interface. While opencode.json controls AI behavior — agents, prompts, MCP servers, and permissions — tui.json controls what you see in the terminal: the visual layout, status indicators, and UI plugins that render information about what agents are doing in real time.

​
Current configuration

OpenCode Config Agent ships with the following tui.json: 
{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": ["opencode-subagent-statusline"]
}
​
$schema
string
Points to the OpenCode TUI JSON schema for editor validation and autocompletion.
​
plugin
string[]
An array of TUI plugin names to load. TUI plugins render UI elements in the terminal interface. These are separate from the AI-layer plugins configured in opencode.json.

​
opencode-subagent-statusline plugin

The opencode-subagent-statusline plugin adds a live status line to the OpenCode TUI that shows background agent activity as it happens. When the sdd-orchestrator delegates work to subagents, those agents run in the background while the orchestrator waits for results. Without visibility into this, the terminal appears idle even while multiple subagents are actively working. The statusline plugin surfaces that activity:
  • How many subagents are currently running — shows a count of active background delegations
  • What each agent is doing — shows the name and status of each running subagent
  • Completion state — updates in real time as agents finish their work and return results
This is powered by the BackgroundAgents plugin inside OpenCode and gives you confidence that the orchestrator is making progress even during long-running phases like sdd-apply or sdd-explore.
The statusline only shows activity when the sdd-orchestrator (or another agent with delegate tool access) is actively running background delegations. It stays quiet during normal single-agent conversations.

​
plugin field

The plugin array in tui.json is a list of TUI plugin names to activate. Each entry is a plugin identifier — the same name used when the plugin was installed or registered. 
{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": ["opencode-subagent-statusline"]
}
TUI plugins (tui.json) and AI-layer plugins (opencode.json) are different systems. A TUI plugin only affects what you see in the terminal; it does not give agents new tools or change their behavior. Do not add TUI plugin names to the plugin array in opencode.json, or vice versa.

​
Adding TUI plugins

To add additional TUI plugins, append their names to the plugin array: 
{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": [
    "opencode-subagent-statusline",
    "your-tui-plugin"
  ]
}
1

Find a TUI plugin

TUI plugins are distributed as npm packages or registered plugins compatible with the OpenCode TUI plugin API.
2

Add the plugin name to tui.json

Open ~/.config/opencode/tui.json and add the plugin identifier to the plugin array.
{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": [
    "opencode-subagent-statusline",
    "your-tui-plugin"
  ]
}
3

Restart OpenCode

Reload your OpenCode session to activate the new TUI plugin.

​
tui.json vs opencode.json

tui.jsonopencode.json
ControlsTerminal UI appearance and widgetsAgent behavior, prompts, MCP servers
Plugin typeUI rendering pluginsAI capability plugins
Schemahttps://opencode.ai/tui.jsonhttps://opencode.ai/config.json
Affects agentsNoYes
Affects displayYesNo
Keep both files at ~/.config/opencode/. OpenCode loads them from the same directory automatically — no additional path configuration is needed.

Build docs developers (and LLMs) love

Get started for freeTalk to us