OpenCode-Native

[!NOTE] Fork of now archived https://github.com/MerrukTechnology/OpenCode-Native The focus is changed towards headless experience oriented towards autonomous agents.

⌬ OpenCode

OpenCode is a powerful CLI tool that brings AI assistance directly to your terminal. It provides both an interactive Terminal User Interface (TUI) for human users and a headless non-interactive mode ideal for scripting and autonomous agents. OpenCode acts as an intelligent coding assistant that can read, edit, and create files, execute shell commands, search through codebases, and integrate with various AI language models.

Designed for developers who prefer command-line workflows, OpenCode offers deep integration with popular AI providers while maintaining a seamless terminal experience. Whether you need help debugging code, implementing new features, or automating repetitive development tasks, OpenCode provides the tools and flexibility to get the job done efficiently.

Features

• Interactive TUI built with Bubble Tea
• Non-interactive mode for headless automation and autonomous agents
• Flows: deterministic multi-step agent workflows defined in YAML (guide)
• Subagents: highly customizable agents calling another agents to do work [[#Agents]]
• Multiple AI providers: Anthropic, OpenAI, Google Gemini, AWS Bedrock, VertexAI, KiloCode, Mistral, and self-hosted
• Tool integration: file operations, shell commands, code search, LSP code intelligence
• Structured output: enforce final agent's output with json schema, perfect for automated pipelines
• MCP support: extend capabilities via Model Context Protocol servers
• Agent skills: reusable instruction sets loaded on-demand (guide)
• Custom commands: predefined prompts with named arguments (guide)
• Session management with SQLite or MySQL storage (guide)
• LSP integration with auto-install for 30+ language servers (guide)
• File change tracking during sessions

Installation

Install Script

curl -fsSL https://raw.githubusercontent.com/MerrukTechnology/OpenCode-Native/refs/heads/main/install | bash

# Specific version
curl -fsSL https://raw.githubusercontent.com/MerrukTechnology/OpenCode-Native/refs/heads/main/install | VERSION=0.1.0 bash

Homebrew

brew install MerrukTechnology/tap/opencode

AUR (Arch Linux)

yay -S opencode-native-bin

Go

go install github.com/MerrukTechnology/OpenCode-Native@latest

Usage

opencode                        # Start TUI
opencode -d                     # Debug mode
opencode -c /path/to/project    # Set working directory
opencode -a hivemind            # Start with a specific agent
opencode -s <session-id>        # Resume or create a session
opencode -s <session-id> -D     # Delete session and start fresh

Non-Interactive Mode

opencode -p "Explain context in Go"           # Single prompt
opencode -p "Explain context in Go" -f json   # JSON output
opencode -p "Explain context in Go" -q        # Quiet (no spinner)
opencode -p "Refactor this module" -t 5m      # With 5-minute timeout

Non-Interactive Flow Mode

opencode -p "Explain context in Go" -F review-code -A hash=93706ee  # Run review-uncommited flow with args
opencode -p "Explain context in Go" -F ralph-does -s wiggum         # Run flow with the pinned session data

All permissions are auto-approved in non-interactive mode.

Command-Line Flags

Configuration

OpenCode looks for .opencode.json in:

1. ./.opencode.json (project directory)
2. $XDG_CONFIG_HOME/opencode/.opencode.json
3. $HOME/.opencode.json

Full Config Example

{
  "data": {
    "directory": ".opencode"
  },
  "providers": {
    "openai": { "apiKey": "..." },
    "anthropic": { "apiKey": "..." },
    "gemini": { "apiKey": "..." },
    "vertexai": {
      "project": "your-project-id",
      "location": "us-central1"
    }
  },
  "agents": {
    "coder": {
      "model": "vertexai.claude-opus-4-6",
      "maxTokens": 5000,
      "reasoningEffort": "high"
    },
    "explorer": {
      "model": "claude-4-5-sonnet[1m]",
      "maxTokens": 5000
    },
    "summarizer": {
      "model": "vertexai.gemini-3.0-flash",
      "maxTokens": 5000
    },
    "descriptor": {
      "model": "claude-4-5-sonnet[1m]",
      "maxTokens": 80
    }
  },
  "shell": {
    "path": "/bin/bash",
    "args": ["-l"]
  },
  "mcpServers": {
    "example": {
      "type": "stdio",
      "command": "path/to/mcp-server",
      "args": []
    }
  },
  "lsp": {
    "gopls": {
      "initialization": { "codelenses": { "test": true } }
    }
  },
  "sessionProvider": { "type": "sqlite" },
  "skills": { "paths": ["~/my-skills"] },
  "permission": {
    "skill": { "*": "ask" },
    "rules": {
      "bash": { "*": "ask", "git *": "allow" },
      "edit": { "*": "allow" }
    }
  },
  "autoCompact": true,
  "debug": false
}

Agents

Each built-in agent can be customized:

Agent fields:

Custom Agents via Markdown

Define custom agents as markdown files with YAML frontmatter. Discovery locations (merge priority, lowest to highest):

1. ~/.config/opencode/agents/*.md — Global agents
2. ~/.agents/types/*.md — Global agents
3. .opencode/agents/*.md — Project agents
4. .agents/types/*.md — Project agents
5. .opencode.json config — Highest priority

Example .opencode/agents/reviewer.md:

---
name: Code Reviewer
description: Reviews code for quality and best practices
mode: subagent
model: vertexai.claude-opus-4-6
color: info
tools:
  bash: false
  write: false
---

You are a code review specialist...

The file basename (without .md) becomes the agent ID. Custom agents default to subagent mode.

Auto Compact

When enabled (default), automatically summarizes conversations approaching the context window limit (95%) and continues in a new session.

{ "autoCompact": true }

Shell

Override the default shell (falls back to $SHELL or /bin/bash):

{
  "shell": {
    "path": "/bin/zsh",
    "args": ["-l"]
  }
}

MCP Servers

{
  "mcpServers": {
    "stdio-example": {
      "type": "stdio",
      "command": "path/to/server",
      "env": [],
      "args": []
    },
    "sse-example": {
      "type": "sse",
      "url": "https://example.org/mcp",
      "headers": { "Authorization": "Bearer token" }
    },
    "http-example": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer token" }
    }
  }
}

LSP

OpenCode auto-detects and starts LSP servers for your project's languages. Over 30 servers are built-in with auto-install support. See the full LSP guide for details.

{
  "lsp": {
    "gopls": {
      "env": { "GOFLAGS": "-mod=vendor" },
      "initialization": { "codelenses": { "test": true } }
    },
    "typescript": { "disabled": true },
    "my-lsp": {
      "command": "my-lsp-server",
      "args": ["--stdio"],
      "extensions": [".custom"]
    }
  },
  "disableLSPDownload": false
}

Disable auto-download of LSP binaries via config ("disableLSPDownload": true) or env var (OPENCODE_DISABLE_LSP_DOWNLOAD=true).

Self-Hosted Models

Local endpoint:

export LOCAL_ENDPOINT=http://localhost:1235/v1
export LOCAL_ENDPOINT_API_KEY=secret

{
  "agents": {
    "coder": {
      "model": "local.granite-3.3-2b-instruct@q8_0"
    }
  }
}

LiteLLM proxy:

{
  "providers": {
    "vertexai": {
      "apiKey": "litellm-api-key",
      "baseURL": "https://localhost/vertex_ai",
      "headers": {
        "x-litellm-api-key": "litellm-api-key"
      }
    }
  }
}

Environment Variables

Architecture

OpenCode is organized into several key packages that work together to provide a seamless AI coding experience:

internal/
├── agent/           # Agent registry and management
├── app/             # Application setup and LSP integration
├── completions/    # Shell completions
├── config/          # Configuration management
├── db/              # Database providers (SQLite, MySQL)
├── diff/            # Diff/patch functionality
├── fileutil/        # File utilities
├── format/          # Code formatting
├── history/         # File change tracking
├── llm/
│   ├── agent/       # Agent implementation and tool execution
│   ├── models/      # Model definitions and metadata
│   ├── prompt/      # System prompts for different agents
│   ├── provider/   # LLM provider implementations
│   └── tools/      # Tool implementations (edit, bash, grep, etc.)
├── logging/        # Logging infrastructure
├── lsp/             # LSP client and language server management
├── message/        # Message types and content handling
├── permission/     # Permission system for tool access
├── session/         # Session management
├── skill/          # Agent skills system
└── tui/             # Terminal User Interface

Key Components

For a detailed architecture overview, see the Providers and Models Guide.

Supported Models

OpenCode supports a wide range of LLM providers and models:

For a complete list of supported models and their configurations, see the Providers and Models Guide.

Tools

File & Code

System & Search

Keyboard Shortcuts

Global

Editor

Dialogs

Extended Documentation

Development

Prerequisites

• Go 1.24.0 or higher

Building from Source

git clone https://github.com/MerrukTechnology/OpenCode-Native.git
cd opencode
make build

Docker

Build and run OpenCode in a container:

# Build the Docker image (cross-compiles a Linux binary automatically)
make docker-build

All CLI arguments are passed through directly:

# Non-interactive prompt
docker run opencode:latest -p "Explain context in Go" -f json -q

# Run a flow
docker run opencode:latest -F my-flow -A key1=value1 -A key2=value2

# With timeout
docker run opencode:latest -p "Refactor this module" -t 5m -q

Mount your configuration and workspace as volumes:

docker run -ti --rm \
  -e LOCAL_ENDPOINT_API_KEY="${LOCAL_ENDPOINT_API_KEY}" \
  -e LOCAL_ENDPOINT="${LOCAL_ENDPOINT}" \
  -e VERTEXAI_PROJECT="${VERTEXAI_PROJECT}" \
  -e VERTEXAI_LOCATION="${VERTEXAI_LOCATION:-global}" \
  -e VERTEXAI_LOCATION_COUNT="${VERTEXAI_LOCATION_COUNT:-us-east5}" \
  -v ~/.opencode.json:/workspace/.opencode.json \
  -v $(pwd):/workspace \
  --network opencode_default \
  opencode:latest  # you can pass args here, e.g. -p "Analyze this codebase"

To run non interactivly (you can pass [[#Command-Line Flags]])

docker run --rm \
  -v ~/.opencode.json:/workspace/.opencode.json \
  -v $(pwd):/workspace \
  --network opencode_default \
  opencode:latest -p "Analyze this codebase" -q

The container uses /workspace as its working directory. Mount .opencode.json there to provide configuration — it is not baked into the image.

Release

make release SCOPE=patch
# or
make release SCOPE=minor

Acknowledgments

• @isaacphi — mcp-language-server, foundation for the LSP client
• @adamdottv — Design direction and UI/UX architecture
• @kujtimiihoxha – Original OpenCode implementation

License

MIT — see LICENSE.

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Open a Pull Request