OpenCode Usage ​

This section describes common ways to use OpenCode directly in the terminal. OpenCode is the agent framework that powers Witty CLI and provides a complete CLI and headless server.

Regular users should use Witty CLI Shell direct input or the REPL, see Using Witty CLI; calling OpenCode commands directly is not required.

Common Commands ​

CommandPurpose
opencodeStart the interactive TUI in the current directory
opencode serveStart the headless opencode server (HTTP + SSE)
opencode run [message..]Run opencode with a single message, non-interactive
opencode agent listList all available agents with primary / subagent markers
opencode agent createCreate a new agent
opencode providersManage AI providers and credentials, alias opencode auth
opencode models [provider]List available models
opencode mcpManage MCP servers
opencode sessionSession management
opencode plugin <module>Install a plugin and update the configuration
opencode upgradeUpgrade to the latest version

Starting the Interactive TUI ​

bash
opencode

The TUI loads the agent / skill / mcp configuration from /etc/opencode/opencode.json by default. Switch agents in the TUI with commands such as /agent; see the OpenCode official documentation for the available / commands.

Headless Server ​

bash
opencode serve --port 4096

opencode serve exposes the following endpoints, which Witty depends on:

  • GET /global/health — health check
  • GET /session, POST /session — session management
  • POST /session/{id}/message — send a message
  • GET /event?directory=<cwd> — SSE event stream, shared by all sessions and filtered by sessionID
  • GET /agent, GET /provider, GET /mcp — metadata
  • GET /doc — OpenAPI documentation

Viewing and Using Agents ​

bash
opencode agent list

Example output, excerpted from a test on openEuler 24.03:

text
build (primary)
explore (subagent)
general (subagent)
plan (primary)
summary (primary)
title (primary)
baize (subagent)
witty-builtin-agent (primary)

witty-builtin-agent is the default primary agent of Witty; build and plan are OpenCode built-in agents.

Agent Configuration ​

OpenCode agents are configured through /etc/opencode/opencode.json, or the user-level ~/.config/opencode/opencode.json and the project-level opencode.json. Typical fields:

json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "witty-builtin-agent": {
      "description": "Knowledge Q&A, command lookup, fault diagnosis, solution planning, and visual reports",
      "mode": "primary",
      "prompt": "{file:/usr/share/witty/opencode/agents/witty-builtin-agent/witty-builtin-agent.md}",
      "color": "#5F87FF",
      "permission": {
        "*": "ask",
        "read": { "*": "allow" },
        "bash": "allow"
      }
    }
  }
}
  • mode: primary for the main agent, subagent for a subagent, all for both;
  • prompt: the role prompt, supporting {file:...} references to local files;
  • permission: authorization policies for tools, files, and shell, with the behaviors allow / ask / deny.

Field semantics follow opencode.ai/docs.

Using Skills ​

Skills are loaded from the directories specified by skills.paths, which Witty manages as /usr/share/witty/opencode/skills. See the OpenCode official documentation for loading details and commands.

Using MCP ​

MCP is configured through the mcp field and supports the local type for local commands and the remote type for SSE/HTTP. The Witty built-in openeuler_portal uses the local npx -y openeuler-portal-mcp to query openEuler official site data.

bash
opencode mcp

Permission Interaction ​

When an agent requests to call a tool, read a file, or run a shell command, OpenCode emits a permission.asked event according to the permission policy; the TUI shows a confirmation request. Witty handles this interaction in the terminal through its own authorization prompts.