opencode README

The project's README from github.com/opencode-ai/opencode. As one markdown file: README.md.

Archived: Project has Moved

This repository is no longer maintained and has been archived for provenance.

The project has continued under the name Crush, developed by the original author and the Charm team.

Please follow Crush for ongoing development.

⌬ OpenCode

⚠️ Early Development Notice: This project is in early development and is not yet ready for production use. Features may change, break, or be incomplete. Use at your own risk.

A powerful terminal-based AI assistant for developers, providing intelligent coding assistance directly in your terminal.

Overview

OpenCode is a Go-based CLI application that brings AI assistance to your terminal. It provides a TUI (Terminal User Interface) for interacting with various AI models to help with coding tasks, debugging, and more.

For a quick video overview, check out OpenCode + Gemini 2.5 Pro: BYE Claude Code! I'm SWITCHING To the FASTEST AI Coder!

Features

Installation

Using the Install Script

# Install the latest version
curl -fsSL https://raw.githubusercontent.com/opencode-ai/opencode/refs/heads/main/install | bash

# Install a specific version
curl -fsSL https://raw.githubusercontent.com/opencode-ai/opencode/refs/heads/main/install | VERSION=0.1.0 bash

Using Homebrew (macOS and Linux)

brew install opencode-ai/tap/opencode

Using AUR (Arch Linux)

# Using yay
yay -S opencode-ai-bin

# Using paru
paru -S opencode-ai-bin

Using Go

go install github.com/opencode-ai/opencode@latest

Configuration

OpenCode looks for configuration in the following locations:

Auto Compact Feature

OpenCode includes an auto compact feature that automatically summarizes your conversation when it approaches the model's context window limit. When enabled (default setting), this feature:

You can enable or disable this feature in your configuration file:

{
  "autoCompact": true // default is true
}

Environment Variables

You can configure OpenCode using environment variables:

Environment Variable Purpose
ANTHROPIC_API_KEY For Claude models
OPENAI_API_KEY For OpenAI models
GEMINI_API_KEY For Google Gemini models
GITHUB_TOKEN For Github Copilot models (see Using Github Copilot)
VERTEXAI_PROJECT For Google Cloud VertexAI (Gemini)
VERTEXAI_LOCATION For Google Cloud VertexAI (Gemini)
GROQ_API_KEY For Groq models
AWS_ACCESS_KEY_ID For AWS Bedrock (Claude)
AWS_SECRET_ACCESS_KEY For AWS Bedrock (Claude)
AWS_REGION For AWS Bedrock (Claude)
AZURE_OPENAI_ENDPOINT For Azure OpenAI models
AZURE_OPENAI_API_KEY For Azure OpenAI models (optional when using Entra ID)
AZURE_OPENAI_API_VERSION For Azure OpenAI models
LOCAL_ENDPOINT For self-hosted models
SHELL Default shell to use (if not specified in config)

Shell Configuration

OpenCode allows you to configure the shell used by the bash tool. By default, it uses the shell specified in the SHELL environment variable, or falls back to /bin/bash if not set.

You can override this in your configuration file:

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

This is useful if you want to use a different shell than your default system shell, or if you need to pass specific arguments to the shell.

Configuration File Structure

{
  "data": {
    "directory": ".opencode"
  },
  "providers": {
    "openai": {
      "apiKey": "your-api-key",
      "disabled": false
    },
    "anthropic": {
      "apiKey": "your-api-key",
      "disabled": false
    },
    "copilot": {
      "disabled": false
    },
    "groq": {
      "apiKey": "your-api-key",
      "disabled": false
    },
    "openrouter": {
      "apiKey": "your-api-key",
      "disabled": false
    }
  },
  "agents": {
    "coder": {
      "model": "claude-3.7-sonnet",
      "maxTokens": 5000
    },
    "task": {
      "model": "claude-3.7-sonnet",
      "maxTokens": 5000
    },
    "title": {
      "model": "claude-3.7-sonnet",
      "maxTokens": 80
    }
  },
  "shell": {
    "path": "/bin/bash",
    "args": ["-l"]
  },
  "mcpServers": {
    "example": {
      "type": "stdio",
      "command": "path/to/mcp-server",
      "env": [],
      "args": []
    }
  },
  "lsp": {
    "go": {
      "disabled": false,
      "command": "gopls"
    }
  },
  "debug": false,
  "debugLSP": false,
  "autoCompact": true
}

Supported AI Models

OpenCode supports a variety of AI models from different providers:

OpenAI

Anthropic

GitHub Copilot

Google

AWS Bedrock

Groq

Azure OpenAI

Google Cloud VertexAI

Usage

# Start OpenCode
opencode

# Start with debug logging
opencode -d

# Start with a specific working directory
opencode -c /path/to/project

Non-interactive Prompt Mode

You can run OpenCode in non-interactive mode by passing a prompt directly as a command-line argument. This is useful for scripting, automation, or when you want a quick answer without launching the full TUI.

# Run a single prompt and print the AI's response to the terminal
opencode -p "Explain the use of context in Go"

# Get response in JSON format
opencode -p "Explain the use of context in Go" -f json

# Run without showing the spinner (useful for scripts)
opencode -p "Explain the use of context in Go" -q

In this mode, OpenCode will process your prompt, print the result to standard output, and then exit. All permissions are auto-approved for the session.

By default, a spinner animation is displayed while the model is processing your query. You can disable this spinner with the -q or --quiet flag, which is particularly useful when running OpenCode from scripts or automated workflows.

Output Formats

OpenCode supports the following output formats in non-interactive mode:

Format Description
text Plain text output (default)
json Output wrapped in a JSON object

The output format is implemented as a strongly-typed OutputFormat in the codebase, ensuring type safety and validation when processing outputs.

Command-line Flags

Flag Short Description
--help -h Display help information
--debug -d Enable debug mode
--cwd -c Set current working directory
--prompt -p Run a single prompt in non-interactive mode
--output-format -f Output format for non-interactive mode (text, json)
--quiet -q Hide spinner in non-interactive mode

Keyboard Shortcuts

Global Shortcuts

Shortcut Action
Ctrl+C Quit application
Ctrl+? Toggle help dialog
? Toggle help dialog (when not in editing mode)
Ctrl+L View logs
Ctrl+A Switch session
Ctrl+K Command dialog
Ctrl+O Toggle model selection dialog
Esc Close current overlay/dialog or return to previous mode

Chat Page Shortcuts

Shortcut Action
Ctrl+N Create new session
Ctrl+X Cancel current operation/generation
i Focus editor (when not in writing mode)
Esc Exit writing mode and focus messages

Editor Shortcuts

Shortcut Action
Ctrl+S Send message (when editor is focused)
Enter or Ctrl+S Send message (when editor is not focused)
Ctrl+E Open external editor
Esc Blur editor and focus messages

Session Dialog Shortcuts

Shortcut Action
↑ or k Previous session
↓ or j Next session
Enter Select session
Esc Close dialog

Model Dialog Shortcuts

Shortcut Action
↑ or k Move up
↓ or j Move down
← or h Previous provider
→ or l Next provider
Esc Close dialog

Permission Dialog Shortcuts

Shortcut Action
← or left Switch options left
→ or right or tab Switch options right
Enter or space Confirm selection
a Allow permission
A Allow permission for session
d Deny permission

Logs Page Shortcuts

Shortcut Action
Backspace or q Return to chat page

AI Assistant Tools

OpenCode's AI assistant has access to various tools to help with coding tasks:

File and Code Tools

Tool Description Parameters
glob Find files by pattern pattern (required), path (optional)
grep Search file contents pattern (required), path (optional), include (optional), literal_text (optional)
ls List directory contents path (optional), ignore (optional array of patterns)
view View file contents file_path (required), offset (optional), limit (optional)
write Write to files file_path (required), content (required)
edit Edit files Various parameters for file editing
patch Apply patches to files file_path (required), diff (required)
diagnostics Get diagnostics information file_path (optional)

Other Tools

Tool Description Parameters
bash Execute shell commands command (required), timeout (optional)
fetch Fetch data from URLs url (required), format (required), timeout (optional)
sourcegraph Search code across public repositories query (required), count (optional), context_window (optional), timeout (optional)
agent Run sub-tasks with the AI agent prompt (required)

Architecture

OpenCode is built with a modular architecture:

Custom Commands

OpenCode supports custom commands that can be created by users to quickly send predefined prompts to the AI assistant.

Creating Custom Commands

Custom commands are predefined prompts stored as Markdown files in one of three locations:

  1. User Commands (prefixed with user:):

    $XDG_CONFIG_HOME/opencode/commands/

    (typically ~/.config/opencode/commands/ on Linux/macOS)

    or

    $HOME/.opencode/commands/

  2. Project Commands (prefixed with project:):

    <PROJECT DIR>/.opencode/commands/

Each .md file in these directories becomes a custom command. The file name (without extension) becomes the command ID.

For example, creating a file at ~/.config/opencode/commands/prime-context.md with content:

RUN git ls-files
READ README.md

This creates a command called user:prime-context.

Command Arguments

OpenCode supports named arguments in custom commands using placeholders in the format $NAME (where NAME consists of uppercase letters, numbers, and underscores, and must start with a letter).

For example:

# Fetch Context for Issue $ISSUE_NUMBER

RUN gh issue view $ISSUE_NUMBER --json title,body,comments
RUN git grep --author="$AUTHOR_NAME" -n .
RUN grep -R "$SEARCH_PATTERN" $DIRECTORY

When you run a command with arguments, OpenCode will prompt you to enter values for each unique placeholder. Named arguments provide several benefits:

Organizing Commands

You can organize commands in subdirectories:

~/.config/opencode/commands/git/commit.md

This creates a command with ID user:git:commit.

Using Custom Commands

  1. Press Ctrl+K to open the command dialog
  2. Select your custom command (prefixed with either user: or project:)
  3. Press Enter to execute the command

The content of the command file will be sent as a message to the AI assistant.

Built-in Commands

OpenCode includes several built-in commands:

Command Description
Initialize Project Creates or updates the OpenCode.md memory file with project-specific information
Compact Session Manually triggers the summarization of the current session, creating a new session with the summary

MCP (Model Context Protocol)

OpenCode implements the Model Context Protocol (MCP) to extend its capabilities through external tools. MCP provides a standardized way for the AI assistant to interact with external services and tools.

MCP Features

Configuring MCP Servers

MCP servers are defined in the configuration file under the mcpServers section:

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

MCP Tool Usage

Once configured, MCP tools are automatically available to the AI assistant alongside built-in tools. They follow the same permission model as other tools, requiring user approval before execution.

LSP (Language Server Protocol)

OpenCode integrates with Language Server Protocol to provide code intelligence features across multiple programming languages.

LSP Features

Configuring LSP

Language servers are configured in the configuration file under the lsp section:

{
  "lsp": {
    "go": {
      "disabled": false,
      "command": "gopls"
    },
    "typescript": {
      "disabled": false,
      "command": "typescript-language-server",
      "args": ["--stdio"]
    }
  }
}

LSP Integration with AI

The AI assistant can access LSP features through the diagnostics tool, allowing it to:

While the LSP client implementation supports the full LSP protocol (including completions, hover, definition, etc.), currently only diagnostics are exposed to the AI assistant.

Using Github Copilot

Copilot support is currently experimental.

Requirements

If using one of the above plugins or cli tools, make sure you use the authenticate the tool with your github account. This should create a github token at one of the following locations:

If using an explicit github token, you may either set the $GITHUB_TOKEN environment variable or add it to the opencode.json config file at providers.copilot.apiKey.

Using a self-hosted model provider

OpenCode can also load and use models from a self-hosted (OpenAI-like) provider. This is useful for developers who want to experiment with custom models.

Configuring a self-hosted provider

You can use a self-hosted model by setting the LOCAL_ENDPOINT environment variable. This will cause OpenCode to load and use the models from the specified endpoint.

LOCAL_ENDPOINT=http://localhost:1235/v1

Configuring a self-hosted model

You can also configure a self-hosted model in the configuration file under the agents section:

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

Development

Prerequisites

Building from Source

# Clone the repository
git clone https://github.com/opencode-ai/opencode.git
cd opencode

# Build
go build -o opencode

# Run
./opencode

Acknowledgments

OpenCode gratefully acknowledges the contributions and support from these key individuals:

Special thanks to the broader open source community whose tools and libraries have made this project possible.

License

OpenCode is licensed under the MIT License. See the LICENSE file for details.

Contributing

Contributions are welcome! Here's how you can contribute:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Please make sure to update tests as appropriate and follow the existing code style.

opencode (opencode-ai/opencode)

Searching Database…

13.8K ·GitHub
Opencode
archived
这是干什么的？这是一个运行在终端里的 AI 编程助手：一个 Go 编写的命令行工具，带有交互式 TUI 界面，AI 模型可以帮你写代码、调试和执行命令，全程不用离开终端。
这是桌面应用还是运行在终端里的工具？只能在终端里用。OpenCode 是一个带 Bubble Tea TUI 的命令行应用——有类似 vim 的编辑器、会话和模型的对话框，以及完整的快捷键——没有图形界面。
怎么把它装到我的电脑上？用 README 里的一行安装脚本安装，或在 macOS/Linux 上用 Homebrew、在 Arch 上用 AUR，或者用 go install；然后可以在你的主目录或项目目录里放一个 .opencode.json 配置文件（可选）。
需要我自己准备 API 密钥或模型访问权限吗？是的——为你的服务商设置对应的环境变量：Claude 用 ANTHROPIC_API_KEY，OpenAI 用 OPENAI_API_KEY，Google 用 GEMINI_API_KEY，另外还支持 GitHub Copilot、AWS Bedrock、Azure OpenAI、Groq 和 Vertex AI。
它稳定到可以放心用在日常工作中吗？还不行：README 标明它还处于早期开发阶段，“尚未可用于生产环境”，并提醒功能可能变化、出错或不完整——请自行承担使用风险。
所有东西都必须经过云端服务商吗，还是可以接入我自己的模型？你并不局限于云端 API：通过 LOCAL_ENDPOINT 可以让 OpenCode 指向自己部署的模型。如果用托管服务商，你的代码和提示词自然会经过该服务商。
可以接入哪些 AI 服务商和模型？支持的很多：OpenAI（GPT-4.1/4o、o 系列）、Anthropic Claude 4、3.7 和 3.5、Google Gemini 2.x、GitHub Copilot、AWS Bedrock、Azure OpenAI、Google VertexAI、Groq（Llama 4、QWEN QWQ、DeepSeek R1 distill）以及 OpenRouter。
这个智能体在我的代码仓库里具体能做什么？内置工具包括：用 glob、grep 和 ls 查找代码；用 view、write、edit 和 patch 修改文件；用 bash 执行 shell 命令；用 fetch 访问网址；用 Sourcegraph 搜索公开仓库；LSP 诊断；还有一个 agent 工具用于处理子任务。
当对话超出模型的上下文窗口时会发生什么？自动压缩（auto compact，默认开启）会监控 token 用量，当达到模型上下文窗口的 95% 时，会把对话总结成一个新会话，让你继续工作而不会遇到超出上下文的错误。
这个仓库已经归档了——项目去哪了？开发以 Crush 的名义继续进行，由原作者和 Charm 团队共同打造；本仓库仅作为出处记录保留归档状态，请关注 Crush 获取更新。
What are similar projects?crush, oh-my-pi, ordewell, claude-code, ralph, casbin-gateway, Raven, claurst
Which topics is it in?code, lsp, agentic-coding, github-copilot, bash, tui, shell, gemini, sqlite, anthropic, coding-agent, claude
Creator
opencode-ai
Size
1.3 MB
Stars
13.8K
Updated
CommitSep 18Releasev0.0.55Jun 27
Age
1y
Commits · 90 Days