OpenCode is Claude Code’s open-source alternative, which is a terminal-based AI coding agent that lets you interact with LLMs directly from your command line to write, edit, and reason about code across your entire project.

Basics

Overview

• OpenCode is an open-source AI coding agent available as a terminal-based TUI, desktop app, or IDE extension. It lets you interact with LLMs to explore, build, and modify code within your projects.

• Install via:

  curl -fsSL <https://opencode.ai/install> | bash
  # or
  npm install -g opencode-ai
  brew install anomalyco/tap/opencode
  

• Configure a provider by running /connect in the TUI and selecting your provider (e.g., OpenCode Zen, Anthropic, OpenAI). API keys are stored in ~/.local/share/opencode/auth.json.

• If you have your own llama.cpp server you can use below configuration written at ~/.config/opencode/opencode.json

  {
    "$schema": "https://opencode.ai/config.json",
    "provider": {
      "llama-local": {
        "npm": "@ai-sdk/openai-compatible",
        "name": "Qwen3.6-35B (local)", # Change
        "options": {
          "baseURL": "http://localhost:8080/v1" # Change
        },
        "models": {
          "Qwen3.6-35B-A3B-UD-Q6_K": { # Change
            "name": "Qwen3.6-35B (local)", # Change
            "limit": {
              "context": 24576, # Change
              "output": 4096 # Change
            }
          }
        }
      }
    },
    "model": "llama-local/Qwen3.6-35B-A3B-UD-Q6_K" # Change
  }
  

  • Register the provider using opencode auth login and choose Other, ID llama-local and key set to none
  • Create a new directory and execute opencode in it then test

• https://opencode.ai/docs/

Tools

• Tools are functions the LLM can call to interact with your codebase and environment. All built-in tools are enabled by default and require no explicit permission to run.
• Key built-in tools: bash (run shell commands), edit (modify existing files), write (create or overwrite files), read (read file contents), grep (regex search), glob (find files by pattern), webfetch (fetch web content), todowrite (manage task lists during a session), skill (load a skill on-demand), question (ask the user a question mid-task).
  • websearch is only available when using the OpenCode provider or when OPENCODE_ENABLE_EXA=1 is set in the environment.
• Tools like grep and glob use ripgrep under the hood and respect .gitignore by default. To include ignored paths, create a .ignore file in your project root with entries like !node_modules/.
• https://opencode.ai/docs/tools/

AGENTS.md (System Prompt for Your Repo)

• AGENTS.md is a Markdown file you place in your project (or home directory) that acts as a persistent system prompt for the AI. It tells the agent how to behave in your specific codebase — think of it as onboarding docs that exist so you don't have to re-explain your project every session.

  • Benefits: consistency between sessions and across team members, keeping the context window minimal (agent doesn't need to re-scan the repo every time), better accuracy, and lower token cost.
  • You should commit your AGENTS.md to Git so the whole team benefits from it.

• Typical contents: build/lint/test commands, architecture overview, repo structure quirks, coding conventions, and references to existing rule files.

  # My Project
  
  ## Commands
  - Build: `npm run build`
  - Test: `npm test`
  
  ## Code Standards
  - TypeScript strict mode
  - Shared logic goes in `packages/core/`
  

• File locations and precedence (first match wins per category):

  • Project: AGENTS.md in your project root (or traversed up to git root).
  • Global: ~/.config/opencode/AGENTS.md — personal rules applied to all sessions, not shared with your team.
  • Claude Code compatibility: CLAUDE.md (project) and ~/.claude/CLAUDE.md (global) are used as fallbacks if no AGENTS.md exists.

• You can also point to multiple instruction files from opencode.json using the instructions field, which supports glob patterns and even remote URLs:

  {
    "$schema": "<https://opencode.ai/config.json>",
    "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", "packages/*/AGENTS.md"]
  }