YouTip LogoYouTip

Home > AI Agent > Opencode Coding Agent

Opencode Coding Agent

📅 2026-06-22 | 📂 AI Agent
OpenCode Getting Started Tutorial |

OpenCode is an open-source AI coding agent that supports interacting with AI in the terminal, desktop applications, and mainstream IDEs (such as VS Code) to complete code-related tasks.

OpenCode can help us understand codebases, write new features, refactor code, fix bugs, and more, significantly improving development efficiency.

OpenCode is similar to Claude's Code mode or Cursor's Agent functionality, but it is fully open-source, privacy-focused, supports multiple large language models (LLMs), and emphasizes terminal experience.

OpenCode supports over 75 model providers, includes free models like GLM-4.7 and MiniMax M2.1, can connect to commercial models from OpenAI, Anthropic, Google, and also configure local models (like Llama 3), adapting to different scenarios such as lightweight scripts or complex architectures.

Complete OpenCode tutorial reference:

Image 1

Key Features

  • Two Built-in Agent Modes:
    • Build Mode: Full permissions, can directly edit files and execute commands.
    • Plan Mode: Read-only planning, default rejects editing, requires confirmation.
  • Toolset: Bash execution, file read/write, grep search, LSP diagnostics, etc.
  • Context Awareness: Automatically analyzes project structure and generates an AGENTS.md guide.
  • Sharing & Collaboration: One-click generation of session sharing links.

Installing OpenCode

OpenCode supports multi-platform installation on macOS / Windows / Linux.

The universal one-click installation script is the simplest method:

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

After installation, you should be able to run via command line:

opencode --version

If the output shows a version number like 1.1.19, the installation was successful.

Package Manager Installation

macOS / Linux

brew install opencode

Or:

npm install -g opencode-ai

Windows

choco install opencode

Or:

scoop bucket add extras scoop install extras/opencode

Arch Linux

paru -S opencode-bin

OpenCode runs in the terminal. We can use the default system terminal or some modern terminal tools:

Desktop Application

OpenCode also provides a desktop application that can be downloaded directly from the release page or opencode.ai/download.

System Platform Download Package
macOS (Apple Silicon) opencode-desktop-darwin-aarch64.dmg
macOS (Intel) opencode-desktop-darwin-x64.dmg
Windows opencode-desktop-windows-x64.exe
Linux .deb, .rpm, or AppImage format

Launching and Using

To start OpenCode, simply enter the launch command in the terminal:

opencode

The first launch will guide you through basic configuration:

  • Model Selection: By default, available models are displayed; you can select free models (e.g., MiniMax M2.1, GLM-4.7) marked with Free without needing an API key.
  • Login Option: You can choose to skip login and configure the API key later when connecting to commercial models, or log in to a Claude Code Pro account to use exclusive models.

After successful startup, enter the TUI interface to begin using core features.

We can view available free models by typing /models in the terminal:

Image 2

The popup shows Free-labeled models:

Image 3

Configure API Key and Model

If you're connecting to an AI provider's API key, such as OpenAI or Anthropic Claude, run:

opencode auth login

Or after launching in the terminal:

/connect

Select a model. Follow the prompts to log in and paste your API Key.

Image 4

You can also use the Zen model collection (officially recommended and tested high-quality models by OpenCode) to avoid managing multiple external accounts.

If you no longer want to use it, exit with:

/exit

Basic Usage

Launch OpenCode

Navigate to the project directory you want to work on:

cd /path/to/your/project
opencode

For example, we create a directory called opencode-tutorial-test:

mkdir opencode-tutorial-test
cd opencode-tutorial-test

Then execute:

opencode

If there are permission issues, use:

sudo opencode

This opens OpenCode’s terminal interactive interface (TUI).

Project Initialization

In the OpenCode interface, run:

/init

Image 5

This generates a .opencode/ folder for storing project vectorized indexes and custom instructions.

It scans the current directory's code structure and generates an AGENTS.md file to record project information.

Image 6

Under the opencode-tutorial-test directory, you'll see the AGENTS.md file:

Image 7

Then describe your needs in natural language to initiate a task:

Create a login page in the current directory

The large model will then think and create the login page:

Image 8

Generated files:

Image 9

Asking for Code Explanation

You can directly ask OpenCode questions about codebase details in natural language:

What features does the file @index.html contain?

The @ symbol refers to file paths within the project.

Image 10

Daily Interaction

  • Direct question: e.g., "Explain the authentication logic in src/main.ts".
  • Add feature: describe requirements, e.g., "Add user registration API with email verification support".
  • Switch modes: press Tab to toggle between Plan/Build modes (Plan is safer for planning).
  • Undo changes: /undo
  • Redo: /redo
  • Share session: /share

Interactive Mode (Scripted):

opencode -p "Fix the bug in the login function"

Introduction to Built-in Tools

OpenCode's AI Agent operates on codebases through the following tools (permissions can be controlled in opencode.json: allow/deny/ask):

  • bash: Execute shell commands (e.g., git status, npm test).
  • write/edit/patch: Create/modify/patch files.
  • read: Read file contents (supports line ranges).
  • grep/glob/list: Search and list files (respects .gitignore).
  • webfetch: Fetch web content (for documentation).
  • lsp (experimental): Code navigation, hover hints, etc.
  • question: Ask you for confirmation.
  • todo: Maintain a task list.

Custom tools and MCP (Model Context Protocol) servers support extensions (e.g., database connections).

Advanced Usage

  • Custom Commands: Create Markdown files in ~/.config/opencode/commands/, e.g., prime-context.md, containing preloaded instructions.
  • Themes & Keybindings: Customize appearance and shortcuts in settings.
  • Multiple Sessions: Run multiple Agents simultaneously for different tasks.
  • IDE Integration: Currently supports VS Code extension (search for OpenCode extension) or remote control via client/server architecture.
  • Permission Control: Set tools to ask in config files for manual confirmation of sensitive operations.

Create a Simple Node.js API

  1. New directory: mkdir my-api && cd my-api
  2. Initialize: npm init -y
  3. Start OpenCode: opencode
  4. Type /init
  5. Ask: Create an Express.js service that returns JSON { message: 'Hello World' } at route /hello, and add a README.

oh-my-opencode

oh-my-opencode is a powerful plugin/extension layer designed for OpenCode. It upgrades a single AI agent into a multi-agent collaborative team, providing out-of-the-box advanced features.

GitHub Repository: https://github.com/code-yeongyu/oh-my-opencode

Core highlights include:

  • Sisyphus Main Agent: Responsible for continuously executing complex tasks until completion.
  • Supports parallel execution of specialized sub-agents (e.g., Oracle Prophet, Librarian Documentation Expert, Frontend Engineer, Explore Explorer).
  • Built-in LSP/AST tools (code refactoring), MCP (model calling plugins like search, documentation retrieval), hook system (25+ event triggers).
  • Multi-model scheduling: Automatically assigns tasks to the most suitable model (e.g., Gemini handles frontend, Claude handles planning).
  • Keyword-triggered full automation (e.g., ultrawork or ulw), supporting background tasks, Todo enforcement, context injection, etc.
  • Fully compatible with Claude Code workflows, emphasizing performance, automation, and customization.

Installation

It is recommended to let OpenCode automatically complete the installation. Copy the following prompt and paste it into your OpenCode chatbox:

Follow the instructions below to install and configure oh-my-opencode: https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/refs/heads/master/docs/guide/installation.md

After installation, it works out-of-the-box with minimal configuration needed to experience most features.

Basic Trigger

Include the keyword ultrawork (or shorthand ulw) in your OpenCode prompt, e.g.:

ultrawork: Help me implement a React component with dark mode support.

This activates full mode: Sisyphus main agent takes over, automatically assigning subtasks to professional agents, running them in parallel (background mapping codebase, deep exploration, auto-refactoring, etc.), until task completion at 100%.

OpenCode TUI Common Slash Command Reference

OpenCode's Slash commands (starting with /) are primarily used in the terminal user interface (TUI) for quickly controlling sessions, configurations, and operations.

Core Configuration and Initialization

Command Description Alias/Shortcut
/connect Add or configure LLM providers (API Key) None
/init Create or update project AGENTS.md file (analyze codebase) Ctrl+X I
/models List available models and switch Ctrl+X M

Session Management

Command Description Alias/Shortcut
/new Start a new session (clear current) /clear / Ctrl+X N
/sessions List and switch sessions /resume / /continue / Ctrl+X L
/share Share current session (generate link) Ctrl+X S
/unshare Unshare current session None
/compact Compress/summarize current session /summarize / Ctrl+X C

Editing and Undo

Command Description Alias/Shortcut
/undo Undo last operation (requires Git repo, supports file change rollback) Ctrl+X U
/redo Redo undone operation (requires Git repo) Ctrl+X R

View and Assistance

Command Description Alias/Shortcut
/details Toggle tool execution detail display Ctrl+X D
/thinking Toggle thinking/reasoning process visibility None
/theme List and switch themes Ctrl+X T
/help Show help dialog Ctrl+X H
/editor Use external editor to compose messages Ctrl+X E
/export Export current conversation as Markdown and open in editor Ctrl+X X

Exit

Command Description Alias/Shortcut
/exit Exit OpenCode /quit / /q / Ctrl+X Q

Note:

  • These commands are entered directly in the TUI chat interface by typing / + command name (auto-completion pops up).
  • /undo and /redo require the project to be a Git repository to roll back file changes.
  • You can create custom Slash commands (placed in ~/.config/opencode/commands/ or project directory), which override built-in commands.
  • More details in official docs: https://opencode.ai/docs/tui

OpenCode CLI Common Parameters Reference

The OpenCode command-line interface (CLI) is mainly used to launch TUI (terminal interface), run prompts non-interactively, or set basic options. Running opencode by default starts the interactive TUI.

Below are common global flags:

Flag Short Description Example
--help -h Show help info (lists all available parameters) opencode --help
--debug -d Enable debug mode (more logs for troubleshooting) opencode -d
--cwd -c Specify current working directory (switch to path on startup) opencode -c /path/to/your/project
--prompt -p Non-interactive mode: run a single prompt and output response (suitable for scripts/automation) opencode -p "fix this bug"
--output-format -f Non-interactive mode
← Vue3 Taskhub SplitClaude Code Practical →

📂 Categories