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 CLI tool that brings AI assistance to your terminal. It provides both a TUI (Terminal User Interface) and a headless non-interactive mode for scripting and autonomous agents.

Features

• Interactive TUI built with Bubble Tea
• Non-interactive mode for headless automation and autonomous agents
• Multiple AI providers: OpenAI, Anthropic, Google Gemini, AWS Bedrock, VertexAI, KiloCode, Mistral, and self-hosted
• Tool integration: file operations, shell commands, code search, LSP code intelligence
• 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 obukhovaa/tap/opencode

AUR (Arch Linux)

yay -S obukhovaa-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)

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

Supported Models

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

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

License

MIT — see LICENSE.

Contributing

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