How to Use OpenCode: The Beginner's Guide

CodexFuse Team · 2026-10-30T13:57:26.428Z · 11 min read

Install OpenCode, connect a model provider, run /init for AGENTS.md, and master Plan vs Build, /undo, and opencode run — a complete beginner's guide.

Learning how to use OpenCode is the fastest way to get comfortable with a terminal-based AI coding agent. OpenCode is an open-source coding agent that lives in your terminal: you describe what you want in plain English, and it reads your files, drafts a plan, edits the code, and runs the tests for you. If you would rather work inside an editor than a terminal, our Cline beginner's guide covers the VS Code-based alternative; this guide is for the terminal lane. The one gotcha every beginner hits: installing OpenCode does not give you model access. You must connect a provider and billing before your first real task, and this guide walks you through exactly that, then on to your first plan, your first build, and the safety net that lets you undo a bad change.

What is OpenCode?

OpenCode is an open-source AI coding agent, available as a terminal interface, a desktop app (in beta at the time of writing), and an IDE extension, that connects a large language model of your choice to your repository, your terminal, and your tools. The distinction that clarifies everything else: OpenCode is not a model. The model reads your prompt and produces the response; OpenCode supplies the file tools, shell access, session history, permission rules, and the interface around it. That split means you can change the model without changing anything else — provider prices move and a better model ships, and the agent stays where it is while you swap what sits behind it. The project is MIT-licensed and, as of mid-2026, sat at roughly 190,000 GitHub stars with around 950 contributors, which reads as evidence the project is not going to be abandoned next quarter. (Source: AnalyticsVidhya, "OpenCode Explained," September 2026.)

How do I install OpenCode?

You install OpenCode 1 with one of the routes below, verified from the official documentation at opencode.ai/docs on October 30, 2026. Pick the route that matches your machine, then move on — the provider step is where the real setup happens.

1. macOS or Linux (easiest): run curl -fsSL https://opencode.ai/install | bash in your terminal. This is the fastest route on most Unix-like systems.
2. Through a package manager: npm i -g opencode-ai@latest, or brew install anomalyco/tap/opencode on macOS and Linux. Windows users can use scoop install opencode or choco install opencode, though OpenCode's own documentation recommends WSL on Windows because some file-system and shell behavior works better there.
3. Confirm it installed: run opencode --version (or just opencode) in a terminal. If the command is not found, the install script's binary path is not on your PATH — close and reopen the terminal first.

One version warning from the docs: the install script, npm, and the tap above all install OpenCode 1, and those binaries can conflict with or replace an OpenCode 2 installation. Homebrew's plain brew install opencode formula currently installs V2. If you are following this guide, stick with the V1 routes above so the commands below match.

Which terminal should I run OpenCode in?

OpenCode runs as a full-screen terminal UI, so you want a modern terminal emulator. The official docs list WezTerm and Alacritty (cross-platform) plus Ghostty and Kitty (Linux and macOS). If you are still on a stock terminal, our Ghostty beginner's guide and WezTerm beginner's guide each walk through a first install in minutes. Pick one before your first session — a good terminal makes the TUI genuinely pleasant.

Installing OpenCode does not give you model access — which provider should I connect?

The first time you launch OpenCode, it needs a model provider before it can do anything. This is the step people forget when they read that the tool is free: the software is free, but model usage is billed by whoever serves the model. Run opencode in a project directory, then type /connect inside the TUI to add a provider. Your realistic options, per the official docs and the AnalyticsVidhya breakdown, are:

If you are new to LLM providers, the docs recommend Zen, and that is the honest beginner path: one curated list, one bill. OpenCode Go, a subscription path reported at $5 for the first month then $10 monthly for selected open-weight models, also exists — prices move, so check the current page before relying on that figure. (Sources: opencode.ai/docs intro, fetched October 30, 2026; AnalyticsVidhya "OpenCode Explained," September 2026.)

How do I give OpenCode context about my project?

Run /init inside your first session and let OpenCode analyze the repository — it writes an AGENTS.md file in your project root summarizing the structure and conventions. Try this now: run /init in a repo you know well, then read the file it produces. Whether that file is accurate about your project tells you a lot about how well the agent understands your codebase, and it takes about two minutes. Commit the file and every session on the team starts with the same instructions. Keep it short: the test for every line is whether removing it would cause a mistake — if not, cut it, because a long file gets ignored. There is also a global AGENTS.md for instructions that apply to every project. When you need to point at a specific file in a prompt, the @ symbol pulls it into the prompt instead of making the agent hunt for it. (Sources: opencode.ai/docs; AnalyticsVidhya, September 2026.)

How do Plan and Build modes work in OpenCode?

OpenCode has two modes, and the mental model is simpler than the naming suggests: it is a permission switch, toggled with the Tab key.

The beginner habit is Plan first, Build second. In Plan mode, describe the feature like you would to a junior developer, iterate on the plan until it sounds right, then hit Tab to switch back to Build and say "Sounds good — go ahead and make the changes." Underneath the modes sits a permission system: a project can allow a tool, deny it, or ask each time, and the rules can vary by command pattern. The important caveat, stated plainly in the docs: the permission system is a workflow safeguard, not a security sandbox. It stops the agent surprising you; it does not contain something actively hostile. (Sources: opencode.ai/docs intro; AnalyticsVidhya, September 2026.)

How do I run my first task in OpenCode?

Start with a low-risk read-only task before you let the agent touch anything. The whole first session looks like this:

1. cd into your project and run opencode. The TUI starts.
2. Run /connect and add your provider (Zen is the simplest first pick).
3. Run /init and read the AGENTS.md it writes.
4. Ask an explanation question first: "How is authentication handled in @src/api/index.ts?" This tests understanding with zero risk.
5. Press Tab for Plan mode and describe a small feature. Read the plan, push back on anything fuzzy.
6. Press Tab again for Build mode and tell it to proceed. Watch the diffs as they land.

Give the agent enough detail to understand what you want — the official docs' own advice is to talk to it like a junior developer on your team. Vague prompts produce vague diffs.

What if OpenCode makes changes I don't want?

Run /undo. The undo and redo commands move through Git-based file snapshots, so /undo reverts the changes and shows your original message again — then you can tweak the prompt and ask it to try again, or run /redo to re-apply them. Combined with Plan mode, that gives you the same try-something-risky-and-roll-it-back workflow that makes checkpoints useful in other agents. The snapshots are Git-based, which is one more reason your project should live in version control from day one — if you are new to that side of things, our GitHub beginner's guide walks through your first repository, first push, and first pull request. (Sources: opencode.ai/docs intro; AnalyticsVidhya, September 2026.)

How do I run a one-off task without opening the terminal UI?

Use opencode run with your prompt as an argument — for example, opencode run "Summarise this repo and propose next steps". The agent executes the task and exits without entering the TUI, which is the pattern you reach for when you want the agent in a script or a CI step rather than an interactive session. Beyond that, OpenCode's architecture is a local server with multiple clients: opencode serve runs the server with no TUI for headless use, opencode attach connects to a session on another machine, and opencode web adds a browser client. There is also a documented OpenAPI 3.1 specification behind it, which generates the official @opencode-ai/sdk package. If you only ever use the terminal interface, none of this changes your day — it matters when you want to run the agent somewhere other than the machine you are sitting at. (Source: AnalyticsVidhya, September 2026.)

OpenCode vs Claude Code — which should a beginner choose?

They solve the same problem with opposite philosophies. Here is the honest comparison, sourced from the AnalyticsVidhya architecture breakdown:

The plain-English version: if you already pay for Claude Code and mainly want the fastest good result on one model, OpenCode is not an upgrade. If you want to switch models on cost or capability without changing tools, run an agent on a remote box or drive it from scripts, keep code on local infrastructure, or read and extend the agent itself, OpenCode does things the proprietary options do not. And if your daily work lives inside an editor rather than a terminal, our Zed beginner's guide covers the AI-native editor lane of this same cluster.

What are OpenCode's honest limits?

Three worth knowing before you commit. First, permissions are a workflow safeguard, not a sandbox — never treat them as isolation. Second, small local models genuinely struggle: more invalid tool calls, more missed links between files, and you need enough memory for both the model and the context sent with each request. Third, the release pace is extreme — over 800 versions in the first year per AnalyticsVidhya, and there is no public roadmap, so anything written about this tool more than a few months old is worth re-checking. One specific command deserves a pause: /share uploads your session to a public link and it stays public until you unshare it — useful for showing a colleague what happened, not something to reach for on a private codebase. Finally, networked server use should set OPENCODE_SERVER_PASSWORD and bind to localhost; server mode must never be publicly reachable without authentication. (Source: AnalyticsVidhya, September 2026.)

Sources

• OpenCode official documentation — Intro (opencode.ai/docs, fetched October 30, 2026): install routes (script, npm, Homebrew tap, Scoop, Chocolatey, Docker, Mise, Arch), /connect with OpenCode Zen, /init and AGENTS.md, Plan/Build modes via Tab, @ file references, /undo and /redo.
• AnalyticsVidhya, "OpenCode Explained: The Open-Source AI Coding Agent" (September 2026, fetched October 30, 2026): MIT license, ~190,000 stars / ~950 contributors mid-2026, agent-vs-model architecture, client-server design (serve/attach/web), OpenAPI SDK, billing paths (Zen, BYO key, Go, Copilot/ChatGPT login, Ollama), Git-based /undo snapshots, permission-system caveats, /share warning, 800+ releases in year one, Claude consumer-plan block (January 2026).
• Warp, "Set up OpenCode" (fetched October 30, 2026): 75+ LLM providers, install routes, Tab toggles Plan/Build, /init creates AGENTS.md.
• Together AI, "How to Use OpenCode" (fetched October 30, 2026): opencode auth login provider setup with Together AI models.

Frequently asked questions

Is OpenCode really free?

The MIT-licensed software is free, but model usage is not. You pay through provider tokens, OpenCode Zen, OpenCode Go, or in hardware if you run models locally through Ollama. A free tool can still produce a monthly provider bill. (Source: AnalyticsVidhya, September 2026.)

Can I use my Claude Pro or Max subscription with OpenCode?

No. Anthropic blocked third-party tools from using consumer Claude subscriptions through unofficial channels in January 2026. Claude models still work in OpenCode, but through a metered Anthropic API key billed at API rates. Copilot and ChatGPT logins are unaffected. (Source: AnalyticsVidhya, September 2026.)

Does OpenCode work offline?

Yes, through Ollama or another OpenAI-compatible local endpoint. Expect more invalid tool calls and weaker reasoning across files than a large hosted model, and make sure the machine has memory for both the model and the context you send it. (Source: AnalyticsVidhya, September 2026.)

What is OpenCode Zen?

OpenCode Zen is the curated path through /connect: a list of models tested and verified by the OpenCode team, billed pay-as-you-go through OpenCode's gateway instead of a provider you manage yourself. The docs recommend it for anyone new to LLM providers. (Source: opencode.ai/docs intro, fetched October 30, 2026.)

How is OpenCode different from Cline?

Both are open-source AI coding agents; the difference is where they live. OpenCode is terminal-first (TUI, desktop app, headless server), while Cline runs inside VS Code as an editor extension with Plan-vs-Act modes. If your day happens in the terminal, start here; if it happens in the editor, start with our Cline beginner's guide.