# OpenCode

### What is OpenCode? <a href="#what-is-opencode" id="what-is-opencode"></a>

OpenCode is an open-source AI coding agent designed to bring powerful AI assistance directly to your development workflow. It's a Go-based CLI application that brings AI assistance to your terminal, providing a TUI (Terminal User Interface) for intelligent coding assistance. It's available as a terminal-based interface, desktop application, or IDE extension, helping developers write, understand, and improve code more efficiently.

**Key features:**

* **Multi-Platform Support**\
  Available as a terminal-based interface, desktop application, or IDE extension to fit your preferred development environment.
* **Flexible LLM Provider Support**\
  Works with any LLM provider by configuring API keys, including Claude, GPT, Gemini, and any OpenAI-compatible endpoints.
* **Intelligent Code Generation**\
  Produces high-quality code snippets, functions, and modules based on natural-language prompts.
* **Built-in Agents**\
  Comes with two built-in primary agents (Build and Plan) that you can customize or extend with your own.
* **Custom Tools Support**\
  Define your own functions that the LLM can call through custom tools in your config file.
* **Custom Rules & Instructions**\
  Provide custom instructions through an AGENTS.md file, similar to Cursor's rules.
* **GitHub Integration**\
  Install the GitHub agent directly in your repository for CI/CD workflows.

***

### Integrating OpenCode with [nexos.ai](http://nexos.ai/) <a href="#integrating-opencode-with-nexos.ai" id="integrating-opencode-with-nexos.ai"></a>

To connect your [nexos.ai](http://nexos.ai/) **API Gateway** with **OpenCode**, follow these steps:

#### 1. Install OpenCode <a href="#id-1.-install-opencode" id="id-1.-install-opencode"></a>

OpenCode can be installed using multiple methods:

&#x20;**Using the install script (recommended):**

```
curl -fsSL https://opencode.ai/install | bash
```

**Using Homebrew (macOS/Linux):**

We recommend using the OpenCode tap for the most up-to-date releases. The official `brew install opencode` formula is maintained by the Homebrew team and may lag behind:

```
brew install anomalyco/tap/opencode
```

**Using npm:**

```
npm install -g opencode
```

**Desktop Application:**

OpenCode is also available as a desktop application. Install via Homebrew cask:

```
brew install --cask opencode-desktop
```

Or download directly from [opencode.ai/download](https://opencode.ai/download).

***

#### 2. Configuration <a href="#id-2.-configuration" id="id-2.-configuration"></a>

OpenCode uses JSON configuration files to manage providers and settings. **The configuration file is not created automatically during installation** — you need to create it manually. The configuration supports both JSON and JSONC (JSON with Comments) formats.

**Configuration file locations (in order of precedence):**

* `$HOME/.opencode.json`
* `$XDG_CONFIG_HOME/opencode/.opencode.json`
* `./.opencode.json` (project root — highest precedence)

You can also specify a custom config directory using the `OPENCODE_CONFIG_DIR` environment variable.

**To create the global config:**

```
mkdir -p ~/.config/opencode
touch ~/.config/opencode/opencode.json
```

Then add the [nexos.ai](http://nexos.ai/) provider configuration:

```
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "nexosai": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "nexos.ai",
      "options": {
        "baseURL": "https://api.nexos.ai/v1"
      },
      "models": {
        "Claude Opus 4.5": {},
        "claude-haiku-4-5-20251001": {},
        "gpt-4.1": {},
        "gpt-4o-mini": {},
        "gemini-2.5-pro": {}
      }
    }
  },
  "model": "nexosai/Claude Opus 4.5",
  "small_model": "nexosai/claude-haiku-4-5-20251001"
}

```

**Configuration breakdown:**

* `npm`: The SDK package to use — `@ai-sdk/openai-compatible` is used for any OpenAI-compatible API
* `name`: The display name for the provider in the UI
* `options.baseURL`: The endpoint for the API ([nexos.ai](http://nexos.ai/) gateway)
* `models`: An object where each key is a model name; values can be empty `{}` or include optional properties like `maxTokens` (defaults to 32000)
* `model`: The active model in format `provider-key/model-name`
* `small_model`: Model used for lighter tasks to optimize costs

> **Tip:** The config file has a schema defined at `opencode.ai/config.json` — your editor should be able to validate and autocomplete based on the schema.

> **Finding Available Models:** You can fetch all available models from your [nexos.ai](http://nexos.ai/) gateway using the API endpoint `GET /v1/models`. See the <https://docs.nexos.ai/gateway-api#get-v1-models> for details.

***

#### 3. Configure API Credentials <a href="#id-3.-configure-api-credentials" id="id-3.-configure-api-credentials"></a>

API keys are securely stored separately from your configuration. To add your [nexos.ai](http://nexos.ai/) API key, use the `/connect` command within OpenCode:

```
opencode
```

Once OpenCode starts, run:

```
/connect
```

1. Select **"Other"** to add a custom provider
2. Enter `nexosai` as the provider name (must match the key in your config)
3. Paste your [nexos.ai](http://nexos.ai/) team/user API key

The key will be securely stored in `~/.local/share/opencode/auth.json`.

**Alternative: Manual auth.json configuration**

You can also manually create or edit the auth file:

```
mkdir -p ~/.local/share/opencode
touch ~/.local/share/opencode/auth.json
```

Then add your API key:

```
{
  "nexosai": "{YOUR_TEAM_API_KEY}"
}
```

***

#### 4. Start Using OpenCode with [nexos.ai](http://nexos.ai/) <a href="#id-4.-start-using-opencode-with-nexos.ai" id="id-4.-start-using-opencode-with-nexos.ai"></a>

Launch OpenCode in your terminal:

```
opencode
```

OpenCode will now route all AI requests through the [nexos.ai](http://nexos.ai/) API Gateway, giving you access to multiple LLM providers through a single, unified endpoint.

***

### Advanced Configuration <a href="#advanced-configuration" id="advanced-configuration"></a>

#### Built-in Agents Configuration <a href="#built-in-agents-configuration" id="built-in-agents-configuration"></a>

OpenCode comes with two built-in primary agents: **Build** and **Plan**.

* **Build:** The default primary agent with all tools enabled. It can read and write files, run commands, and make changes to your codebase.
* **Plan:** A restricted agent that handles planning and code analysis without making changes. Tool access is limited so it can only suggest how to implement features.

You can customize the built-in agents using the `agent` field (singular) in your configuration. Each agent supports the following options:

| Option          | Description                                                        |
| --------------- | ------------------------------------------------------------------ |
| `model`         | The model to use for this agent (e.g., `nexosai/Claude Opus 4.5`)  |
| `prompt`        | Custom system prompt for the agent                                 |
| `prompt_append` | Additional text to append to the default prompt                    |
| `temperature`   | Sampling temperature for the model                                 |
| `top_p`         | Top-p sampling parameter                                           |
| `tools`         | Object to enable/disable specific tools (set to `true` or `false`) |
| `disable`       | Set to `true` to disable this agent entirely                       |
| `description`   | Description shown in the UI                                        |

**Example configuration with agent customization:**

```
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "nexosai": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "nexos.ai",
      "options": {
        "baseURL": "https://api.nexos.ai/v1"
      },
      "models": {
        "Claude Opus 4.5": {},
        "claude-haiku-4-5-20251001": {},
        "gpt-4.1": {}
      }
    }
  },
  "model": "nexosai/claude-haiku-4-5-20251001",
  "small_model": "nexosai/gpt-4o-mini",
  "agent": {
    "plan": {
      "model": "nexosai/Claude Opus 4.5",
      "description": "Strategic planning with high-capability model",
      "prompt_append": "Always consider security implications in your plans."
    }
  }
}

```

#### Custom Agents with Markdown Files <a href="#custom-agents-with-markdown-files" id="custom-agents-with-markdown-files"></a>

For creating entirely new custom agents, use markdown files placed in dedicated directories:

* **Global:** `~/.config/opencode/agents/`
* **Per-project:** `.opencode/agents/`

The markdown file name becomes the agent name. For example, `code-reviewer.md` creates a `code-reviewer` agent.

Example `~/.config/opencode/agents/code-reviewer.md`:

```
---
model: nexosai/Claude Opus 4.5
description: Senior code reviewer focusing on security
tools:
  write: false
  bash: false
---

You are a senior code reviewer focusing on security and performance.
Review code for potential vulnerabilities, performance bottlenecks, and best practices.
Do not make changes directly - only provide recommendations.
```

***

### Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

#### Configuration Validation Errors <a href="#configuration-validation-errors" id="configuration-validation-errors"></a>

**Error:** `Invalid input: expected record, received array provider.nexosai.models`

This error occurs when the `models` field is defined as an array instead of an object. Each model must be a key-value pair where:

* The key is the model name (string)
* The value is an object (can be empty `{}` or contain optional properties like `maxTokens`)

**Incorrect:**

```
"models": ["Claude Opus 4.5", "gpt-4.1"]
```

**Correct:**

```
"models": {
  "Claude Opus 4.5": {},
  "gpt-4.1": {}
}
```

**Error:** `Invalid input: expected record, received string provider`

This error occurs when the `provider` field is a string instead of an object. The provider must be an object containing your provider configuration.

**Error:** `Unrecognized key: "agents"`

The correct field name is `agent` (singular), not `agents` (plural). For custom agents, use markdown files in the agents directory instead.

#### Base URL Issues <a href="#base-url-issues" id="base-url-issues"></a>

If you're getting connection errors, verify that the `baseURL` in your config matches includes full url (including /v1): <https://api.nexos.ai/v1>

#### Model Reference Format <a href="#model-reference-format" id="model-reference-format"></a>

Ensure your model references use the format `provider-key/model-name` (e.g., `nexosai/Claude Opus 4.5`).

***

### Verification <a href="#verification" id="verification"></a>

To verify your [nexos.ai](http://nexos.ai/) integration is working:

1. Start OpenCode: `opencode`
2. Run the `/models` command to see available models
3. Press `Tab` to switch between Plan and Build agents
4. Try a simple prompt to confirm connectivity

You should see your configured [nexos.ai](http://nexos.ai/) models available and responses coming through the [nexos.ai](http://nexos.ai/) gateway, with all the benefits of load balancing, cost tracking, and observability that the platform provides.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.nexos.ai/gateway-api/integrations/opencode.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.