OpenCode: Complete Guide to the Code Agent with Artificial Intelligence

OpenCode is an open-source AI code agent that runs directly in the terminal. Unlike commercial alternatives like Claude Code, OpenCode offers free models, massive community support, and an excellent value-for-money subscription. In this guide, you will learn everything you need to master it from scratch.

What is OpenCode?

OpenCode is an agent-based coding tool that works in the terminal. Its main advantage over Claude Code is that it is completely open-source, has free models available out of the box, and allows you to connect to multiple AI providers that you might already be paying for.

Requirements and Installation

 The only fundamental requirement is to have a terminal. Some recommended options are:

• Kitty: cross-platform, open-source, well-known
• Ghost: available on Linux and macOS, with GPU acceleration
• Warp: the most recommended, now open-source, available on macOS, Linux, and Windows, with native integration with OpenCode

Or you can use your cmd or terminal.

To install OpenCode, run the following command in your terminal:

$ curl -fsSL https://opencode.ai/install | sh

Once installed, verify the version with:

$  --version

If the command is not recognized, close and reopen the terminal to reload the PATH.

The OpenCode TUI Interface

Running opencode without arguments inside a project folder opens the TUI (Terminal User Interface), an interactive interface inside the terminal. To start your first project:

$ mkdir mi-proyecto-opencode
cd mi-proyecto-opencode
opencode

The TUI shows:

• An input field to write prompts to the agent
• The current path and the version in use
• The model's thought process in real time
• The tool calls executed by the agent
• The active model and the cost in tokens and money for each response
• The percentage of context used

Models and Providers

OpenCode allows connecting to multiple providers. To see the available ones, use:

/connect

And to change the active model:

/models

Free Models

Without registering for any service, you already have access to free models through OpenCode Zen:

• MiniMax M2.5: the best of the free ones, highly recommended
• Big Pickle (GLM 4.6): good alternative
• Hi3 Preview: Chinese model available
• Nemotron 3 SuperFree: Nvidia model

Free models have request limits and can be slower during peak hours, but they don't require a credit card and work surprisingly well.

OpenCode Go Subscription

The recommended subscription for value-for-money. The first month costs $5 and then $10/month. With it, you get access to models like:

• DeepSeek V4
• GLM 5.1
• Qwen 3.6 Plus (equivalent to Claude Sonnet in performance)
• MiniMax 2.5 and 2.7
• Mimo (Xiaomi models)

The most interesting part is that for $10 you get a usage value equivalent to about $60, thanks to the agreements OpenCode has with the model providers.

GitHub Copilot and OpenAI

If you already have a GitHub Copilot or ChatGPT Plus subscription, you can connect them directly:

/connect

Select the provider, authenticate with your browser, and you are good to go. With OpenAI, you will have access to GPT-5.5 and its variants.

Essential Commands in the TUI

OpenCode has three main input modes:

1. The Slash (/) — Internal Commands

Type / to access system commands:

/models      # Change the AI model
/connect     # Connect a provider
/clear       # Clear the current history
/new         # New session
/compact     # Compact the context to save tokens
/themes      # Change the visual theme
/thinking    # Enable/disable the thought process line
/sessions    # View and switch between active sessions
/timeline    # View the history of sent prompts
/share       # Share history as a public URL
/undo        # Undo the last message

2. The Exclamation Mark (!) — Shell Mode

Type ! to run terminal commands without spending tokens:

!git status
!ls -la
!git log --oneline -10
!mkdir nueva-carpeta
!pnpm test

This mode is key to saving tokens. If you need to see the repository status, run the command yourself instead of asking the agent to do it.

3. Tab — Change the Active Agent

Press Tab to toggle between the main agents:

• Build: main agent with disk write permissions. It can modify files.
• Plan: restricted agent only for analyzing and planning, without editing anything.

4. @ — Reference Files

Use @ to include a specific file in the context without the agent having to search for it:

@robots.txt Am I blocking the Google bot?

This is much faster and cheaper in tokens than letting the agent explore the entire project to find the file.

Best Practices to Save Tokens

• Be specific: instead of "explore the project", use @file.ts and ask the specific question
• Use ! for terminal commands that don't need AI
• Use /compact when context exceeds 50%
• Use the Plan agent to explore without spending tokens on modifications
• Write prompts in English: it uses fewer tokens and the AI responds better
• Add specific constraints in your prompts to avoid repeating them

The AGENTS.md File and Initializing Projects

The AGENTS.md file (also compatible with Claude Code, Cursor, Copilot, etc.) is a markdown file that acts as a "guidebook" for the AI. It describes the project, its architecture constraints, and the technical decisions made so the agent doesn't repeat or contradict them.

To generate it automatically:

$ /init

OpenCode will explore the project and create an AGENTS.md with the detected conventions. Content example:

# Project: Running Dashboard

## Stack
- Vanilla HTML, CSS and JavaScript
- No frameworks, no external dependencies
- No build step
- No npm install

## Commands
- Start server: `bun server.js`
- Always use bun, never node

## Architecture
- All code in flat files at the root
- Mocked data in data.js

You can also edit it manually at any time:

modify AGENTS.md and indicate that we have to use always bun instead of node

Remember: even though AGENTS.md defines the rules, the user always has the last word. If you tell it something that contradicts the file, the agent will listen to you.

Upload AGENTS.md to the repository so all contributors work under the same constraints.

Agent Skills: Expanding AI Capabilities

Agent Skills are Markdown files that add specialized knowledge to the agent. They are based on the standard created by Anthropic for Claude.

You can search and install skills from the official repository skills.sh. For example, to install the React skill:

$ opencode skills add react-best-practices

Auto Skills: Automatic Installation

To automatically detect which skills your project needs, use Auto Skills, a community tool that analyzes project dependencies:

$ npx auto-skills list

This detects the project's stack and recommends the appropriate skills. To install them:

$ npx auto-skills install

Skills are saved in .agents/ inside the project and cover areas like:

• Accessibility (a11y)
• Frontend design
• SEO
• React, Vue, Angular
• Testing

Once the SEO skill is installed, the agent automatically uses it when it detects you need it:

I want to improve my project's SEO

The result automatically includes title, meta description, robots, canonical, Open Graph, Twitter Cards, and structured data.

Subagents: Parallelism in OpenCode

OpenCode includes built-in subagents like Explore and General, and allows you to create your own. Subagents execute tasks in parallel without blocking the main session.

Create Your Own Subagent

Create the file in .opencode/agents/security.md:

---
description: Project security auditor
model: qwen-3.6-plus
temperature: 0.2
tools:
  - read
  - bash:
      allow:
        - git diff
        - git log
---

You are a web application security expert.
Identify vulnerabilities like XSS, CSRF, SQL injection,
credential exposure, and outdated dependencies.
You cannot edit files, only report findings.

And another one in .opencode/agents/reviewer.md:

---
description: Code reviewer without making changes
model: qwen-3.6-plus
tools:
  - read
  - bash:
      allow:
        - git status
        - git diff
        - git log
---

You are a pragmatic code reviewer.
Look for bugs, regressions, and performance issues.
Do not comment on style preferences unless they affect maintenance.
You cannot edit files.

To use multiple agents in parallel, describe the task indicating what each one does:

Divide the investigation in parallel:
- Explore: find the CSS managing the background color
- General: assess performance risks in the project
- Security: review potential vulnerabilities in the forms
- Reviewer: check if pending changes are ready to commit

The main agent must wait for the results and prepare a consolidated plan.

To navigate between active subagents, use Ctrl+X and then the left/right arrow keys.

Custom Commands

You can create reusable commands for frequent tasks. Create the file .opencode/commands/supercommit.md:

---
description: Groups changes into semantic commits and pushes
---

Inspect the repository with git status and git diff.
Group changes by context and create semantic commits.
Use the format: type(scope): description

If arguments are passed ($1), take them into account before committing.
Make sure not to include tokens, secrets, or environment variables.
Push when finished.

Use it from the TUI:

$ /supercommit
$ /supercommit make the commits in Spanish

To make a command available across all projects, copy it to the global folder:

cp .opencode/commands/supercommit.md ~/.config/opencode/commands/

Positional arguments are referenced as $1, $2, etc. The full text passed to the command is available as $arguments.

Session Management

OpenCode allows working with multiple sessions in parallel, like tabs:

/sessions          # View and switch between sessions
Ctrl+X then L      # Keyboard shortcut to switch session

If you close OpenCode and want to pick up where you left off, when closing it shows the command to continue the session:

$ opencode --continue "session-name"

To see a session's prompt history:

$ /timeline

From the timeline, you can search for previous prompts, revert to a specific point, or fork the session from that moment.

Automation with OpenCode Run

OpenCode can run without a graphical interface, ideal for scripts and CI/CD:

$ opencode run "explain this project in 5 points"

To focus it on a specific file:

$ opencode run --file README.md "improve the project description"

To specify the agent and the model:

$ opencode run --agent plan --model qwen-3.6-plus "analyze the risks of this PR"

OpenCode Serve: Remote Access

OpenCode can be exposed as an HTTP server:

$ opencode serve

By default, it opens port 4096. To add authentication:

$ opencode serve --password my-secret-password

The default credentials are user opencode and the password you configure. This allows you to access your sessions and projects from anywhere in the world.

OpenCode Web: Graphical Interface

If you prefer not to use the terminal, OpenCode includes a web interface with the same features:

$ opencode web

It includes file view, file-by-file change diff, session history, and the integrated terminal.

Sharing Sessions

To share a session's complete history as a public URL:

$ /share

It generates a link where anyone can see the model used, prompt history, responses, modified files, and diffs.

The DESIGN.md File

Google has published a new specification called design.md, complementary to AGENTS.md. While AGENTS.md describes technical constraints, design.md describes the visual system: colors, typography, borders, shadows, accessibility, and component guides. OpenCode automatically detects it and respects it in all frontend tasks.

Subscription Comparison

The most recommended combination is OpenCode Go + OpenAI: use GPT-5.5 for planning and analysis, and OpenCode Go models (Qwen, Mimo) for execution.

Keep in mind that free models are used to train providers' models. If you work with proprietary or sensitive code, consider a paid subscription.

Model Recommendations per Task

• Best for frontend and design: MiniMax M2.7
• Best for logic and tools/MCPs: Qwen 3.6 Plus
• Best free speed/quality balance: MiniMax M2.5 Free
• Avoid currently: GLM 5.1, Kimika 2.5 (older versions that feel outdated)
• For deep thinking: GPT-5.5 X-High (slower but better final result)
• For quick tasks: GPT-5.5 Non (no thought process, immediate results)

Conclusion

OpenCode is one of the most comprehensive and accessible tools in the AI code agent ecosystem. Its open-source nature, the ability to use free models from day one, integration with existing subscriptions like ChatGPT and GitHub Copilot, and advanced features such as parallel subagents, custom commands, specialized knowledge skills, and CLI automation make it the most versatile choice on the market.

If you are getting started, install OpenCode, use the free models with MiniMax, create your first AGENTS.md with /init, and install the recommended skills with npx auto-skills list. With that, you will already have a professional-grade AI-assisted development environment without spending a single euro.