> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codealive.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenCode

> Connect CodeAlive with OpenCode AI terminal assistant

## Overview

Connect CodeAlive with OpenCode — an open-source AI coding assistant that runs in your terminal. OpenCode uses its own JSON configuration format with a `type: remote` transport for HTTP connections.

<Tip>
  **Quick install:** Run `npx @codealive/installer` to automatically configure CodeAlive for OpenCode.
  See the [Installation Guide](/installation) for details.
</Tip>

## Prerequisites

* OpenCode installed ([github.com/opencode-ai/opencode](https://github.com/opencode-ai/opencode))
* CodeAlive account ([Sign up here](https://app.codealive.ai))
* Indexed repositories in your CodeAlive dashboard

## Setup

<Steps>
  <Step title="Locate Config File">
    OpenCode reads configuration from `opencode.json` in your project root or home directory.
  </Step>

  <Step title="Add CodeAlive Server">
    Add this to your `opencode.json`:

    ```json theme={null}
    {
      "$schema": "https://opencode.ai/config.json",
      "mcp": {
        "codealive": {
          "type": "remote",
          "url": "https://mcp.codealive.ai/api",
          "enabled": true
        }
      }
    }
    ```

    OpenCode discovers OAuth automatically. Restart OpenCode and follow the browser prompt, or run `opencode mcp auth codealive` explicitly.

    <Info>
      OpenCode uses `type: "remote"` for HTTP-based MCP servers, which is different from most other clients that use `type: "http"` or `type: "streamable-http"`.
    </Info>

    <Info>Existing API-key configurations remain supported. To use one intentionally, set `"oauth": false` and add an `Authorization: Bearer ...` header.</Info>
  </Step>

  <Step title="Restart OpenCode">
    Restart OpenCode to load the new MCP configuration.
  </Step>

  <Step title="Verify Integration">
    Try these commands with OpenCode:

    * "Show me all available repositories"
    * "Find authentication code in my codebase"
    * "Explain how the payment flow works"
  </Step>
</Steps>

## Docker Alternative

If you prefer running the MCP server locally:

```json theme={null}
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "codealive": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "CODEALIVE_API_KEY=YOUR_API_KEY_HERE",
        "ghcr.io/codealive-ai/codealive-mcp:main"
      ],
      "enabled": true
    }
  }
}
```

## Usage

Once connected, OpenCode can:

* **Search your codebase** semantically across all indexed repositories
* **Answer architecture questions** with full project context
* **Find patterns and implementations** across multiple services

```
"Find all error handling patterns in the payment service"
"Explain how the user registration flow works"
"Search for database migration code across services"
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="MCP server not detected">
    1. Verify the config file is named `opencode.json`
    2. Check that `type` is set to `"remote"` (not `"http"`)
    3. Ensure `"enabled": true` is set
    4. Restart OpenCode
  </Accordion>

  <Accordion title="Authentication errors">
    1. Run `opencode mcp auth codealive`
    2. Inspect discovery with `opencode mcp debug codealive`
    3. If you intentionally use the API-key fallback, verify the key is active and set `"oauth": false`
  </Accordion>

  <Accordion title="Connection timeouts">
    1. Check your network connection
    2. Try the Docker STDIO option for local access
    3. Verify the URL is `https://mcp.codealive.ai/api`
  </Accordion>
</AccordionGroup>

<Tip>
  For more solutions, see the [Troubleshooting Guide](/troubleshooting).
</Tip>

## Related Resources

* [MCP Overview](/integrations/mcp)
* [Installation Guide](/installation)
* [Self-Hosting Guide](/integrations/mcp/self-hosting)
* [Agent Skills](/integrations/skills)

## Instruct Your Agent

Connecting CodeAlive makes its tools available, but the agent may still default to its built-in search. For reliable results, add a short instruction in the agent's native format telling it to prefer `semantic_search` and `grep_search` when exploring indexed code. See [Instructing Coding Agents](https://docs.codealive.ai/guides/instructing-agents).