OpenCode Tutorial 2026: Your First Project and Safe Workflow

Key Takeaways

• One-command install, multiple provider options: Install with curl -fsSL https://opencode.ai/install | bash, then choose between Claude, Anthropic, OpenAI, Google, or local models via Ollama, or OpenCode's own curated Zen models.
• Plan mode before Build mode: Start complex features in Plan mode, where edits and shell commands ask for approval by default to outline your approach, then switch to Build mode (Tab key) for implementation — this prevents costly mistakes.
• Open-source client, separate model costs: Hosted providers may charge for usage; a local model avoids per-request API billing but uses your hardware.
• Works inside any IDE with a terminal: OpenCode integrates with VS Code, Cursor, Zed, and any terminal-supporting IDE — it runs in the integrated terminal and edits files directly in your open project.

OpenCode Tutorial 2026: Complete Beginner's Guide to AI Coding in Terminal

OpenCode is an open-source coding agent available in a terminal, desktop app, and IDE extension. Its current provider directory lists Anthropic, OpenAI, Google, Ollama, and others. An older claim that Anthropic models are categorically unavailable in OpenCode is inaccurate; use the documented provider connection and check the terms of the specific account you connect. This tutorial begins after installation and follows a small project through planning, editing, and verification.

For operating-system commands and troubleshooting, use the dedicated OpenCode install guide. Keeping install details there lets this tutorial focus on the first repository workflow.

The steps below use a disposable Git branch and existing project tests. They are instructions you can reproduce, not a claim that NxCode ran a benchmark of models or providers.

---

What is OpenCode?

OpenCode is an open-source AI coding agent that runs in your terminal. Think of it as having a senior developer sitting next to you, ready to help with:

• Writing and debugging code
• Understanding existing codebases
• Refactoring and optimization
• Answering technical questions
• Automating repetitive tasks

Unlike cloud-based coding assistants, OpenCode is local-first—your code stays on your machine unless you choose otherwise.

Key Features

Feature	Description
Open-source client	Provider usage may still be billed
Provider choice	See the current official provider directory
Terminal Native	Beautiful TUI (Terminal User Interface)
IDE Integration	Works with VS Code, Cursor, and any terminal-supporting IDE
GitHub Integration	Automate issues and PRs directly from comments

---

Before Your First Project

If OpenCode is not installed, follow the dedicated installation guide and verify the installed command. The official intro documents its installer and the npm package opencode-ai; avoid an older npm install -g opencode command. This section intentionally keeps installation short so setup instructions have one maintained home.

Choose a repository with existing tests, then create a disposable branch. Confirm git status is clean before an agent changes files. Keep secrets and production credentials out of example prompts. If you have never used the project, run its test suite once without AI so later results have a baseline.

Connect a Model Provider

OpenCode separates the client from the model service. The provider documentation describes /connect for credentials and /models for choosing an available model. OpenCode Zen is optional and has its own terms. Anthropic, OpenAI, and local-model providers appear in the directory, but your account and provider determine access and cost.

cd /path/to/your/test-project
opencode

Inside OpenCode, run /connect, select your provider, follow its authentication flow, and then run /models. Do not paste an API key into a repository file or an article example. If you use a paid API, set a spending cap in the provider account first. If you choose a local model, check hardware and memory requirements for that specific model rather than assuming local inference is free of all costs.

For project-specific settings, use the official configuration reference and version the file only if it contains no secrets. OpenCode can generate an AGENTS.md from /init; review the generated instructions before committing them. The file should describe the real repository, its tests, and its boundaries rather than generic boilerplate.

---

Core Concepts: Plan vs Build Mode

OpenCode has two primary modes you can switch between using the Tab key:

🧠 Plan Mode

• Restricted by default - File edits and shell commands require approval; check your configured permissions
• Analyzes and explores your codebase
• Suggests implementation strategies
• Perfect for understanding before modifying

🔨 Build Mode (Default)

• Full access - Can read, write, and modify files
• Executes code changes
• Runs commands
• Best for actual development work

Pro Tip: Always start complex features in Plan mode to outline your approach, then switch to Build mode for implementation.

---

Essential Commands

Command	Description
/undo	Undo the last change
/redo	Redo an undone change
@	Fuzzy search for files in your project
Tab	Switch between Plan and Build mode
Cmd+Esc	Open OpenCode in IDE split view (Mac)
Ctrl+Esc	Open OpenCode in IDE split view (Windows/Linux)

---

Creating an AGENTS.md File

For best results, create an AGENTS.md file in your project root. This helps OpenCode understand:

• Your project structure
• Coding conventions
• Preferred patterns
• Technology stack

Example:

## Project: My SaaS App

## Tech Stack
- Next.js 14 with App Router
- TypeScript
- Tailwind CSS
- PostgreSQL with Prisma

## Conventions
- Use functional components
- Prefer server components when possible
- Follow REST API naming conventions
- Write tests for all new features

## Structure
- /app - Next.js app router pages
- /components - Reusable UI components
- /lib - Utility functions and helpers
- /prisma - Database schema and migrations

---

Practical Examples

Example 1: Understanding a Codebase

You: Explain the authentication flow in this project

OpenCode will analyze your files and provide a detailed explanation of how authentication works.

Example 2: Adding a Feature

You: Add a dark mode toggle to the settings page

OpenCode will:

1. Find the settings page
2. Identify the theme system
3. Implement the toggle
4. Update necessary styles

Example 3: Debugging

You: The login form is not submitting. Here's the error: [paste error]

OpenCode will trace the issue and suggest fixes.

Example 4: Refactoring

You: Refactor the UserService class to use dependency injection

OpenCode will modernize your code while maintaining functionality.

---

IDE Integration

VS Code / Cursor

1. Open your terminal in the IDE
2. Run opencode
3. Use Cmd+Esc (Mac) or Ctrl+Esc (Windows/Linux) to open in split view

Non-Interactive Mode

For scripting and automation:

opencode -p "Explain the use of context in this Go project"

This processes your prompt, prints the result, and exits.

---

GitHub Integration

OpenCode can work directly in your GitHub workflow:

1. Mention /opencode or /oc in an issue or PR comment
2. OpenCode runs in your GitHub Actions runner
3. It creates a new branch and submits a PR with changes

Example comment:

/opencode Fix the bug described in this issue

---

Model Availability and Cost

OpenCode's provider directory is the source of truth for available providers. A promotional free model can disappear, change its quota, or have different terms later. The previous list of temporary model names was not a durable way to choose a setup. Run /models in your own account, inspect the provider's current price and limits, and note the model you selected in your project notes. If a provider is not available to your account, choose another documented provider instead of assuming a particular trial is still active.

A local model through Ollama can avoid a hosted API charge, but it uses your computer's RAM, processing time, and electricity. A cloud provider may bill input, output, and cached tokens differently. To compare two models, keep the prompt and code state fixed, then record both task success and actual provider usage. A low price per token is not automatically a low cost per accepted change if the model needs several retries.

Terms to Know

• Provider means the service that runs the model. OpenCode is the client; Anthropic, OpenAI, OpenCode Zen, or a local Ollama server can be providers. This definition separates the client license from inference billing.
• Primary agent means the mode you interact with directly. The official agent guide documents Build and Plan. Build can use editing and shell tools; Plan's edits and shell commands ask for permission by default. Check your own configuration before assuming a mode is read-only.
• Project rule means a repository instruction such as AGENTS.md. The official /init flow can generate one, but an auto-generated file should be reviewed like any other code or documentation change.
• Acceptance criteria are observable conditions for success. For a bug fix, they include a reproduced failure, a passing test after the change, and no unrelated file edits. This definition prevents a persuasive answer from being mistaken for a verified fix.

Practical Workflow: One First-Project Change

This walkthrough is a procedure the reader can repeat, not a claim that NxCode measured a particular provider's performance. Use a sample repository with a small test suite and no production secrets. Create a branch, run the tests, and note the baseline failure. If the tests already pass, choose a narrow enhancement whose expected result you can state clearly.

1. Plan the change. Switch to Plan and ask: “Which files implement this behavior? Explain the current flow and propose the smallest fix. Do not edit yet.” Check the answer against the actual code. If it names a nonexistent file or invents a failing test, correct the context before moving on.
2. Authorize a bounded edit. Switch to Build and request one implementation change plus one test. State which files are in scope and which are not. Read any command approval prompt; a request to install packages or run a deployment command is a separate decision from editing a local test.
3. Verify the result. Run the project's existing test command and lint command. Inspect git diff for unrelated changes and confirm the new test would fail without the fix. Use /undo if the change is wrong, but still inspect the repository state afterward; a tool's undo function does not replace Git review.
4. Record cost and outcome. Write down the selected model, prompts used, elapsed time, tests passed, manual corrections, and actual usage shown by the provider. If you retry, include the failed attempt. This makes a later provider comparison honest.

Example scenario: A login form accepts an empty email. The acceptance criteria are that the submit handler rejects the empty value, the UI shows a clear message, and the existing happy-path test still passes. Plan should identify the handler and test file. Build should change only those files. The final check is the test output and diff, not a confident explanation in chat.

Second example: A project has a broken import after a file rename. Ask Plan to list the import sites. In Build, request the rename and a type-check run. If the agent changes unrelated naming conventions, reject that part of the diff. This task exercises file navigation and verification without requiring a large benchmark suite.

Checklist for Teams and Repeat Work

For a team repository, put stable facts in AGENTS.md: test commands, lint command, architecture boundaries, and a short rule about secrets. Do not put API keys or environment values in the file. Use the rules documentation to understand how project guidance is loaded. Review the guidance when the build system changes; stale project instructions can make an otherwise capable agent repeatedly run the wrong command.

Use the permissions documentation to decide which commands require approval. An agent that can run shell commands can also install dependencies or contact external services if allowed. For a first project, keep external side effects behind an explicit prompt and use a disposable branch. Before merging any generated patch, run the same review process as for a human contribution: diff, tests, secrets check, and code review.

If you use multiple providers, record a model ID alongside each result. A change in model may explain an improvement or regression that has nothing to do with OpenCode. For recurring work, document the exact task and expected artifact, then check the output. “The agent ran” is not the same as “the work passed review.”

When to Use a Different Workflow

OpenCode is useful for developers who want to inspect and change code. If your main goal is to create an app without maintaining a codebase or model provider, NxCode offers a different path. Compare the delivered app, database behavior, deployment, and ability to change it later; do not compare only the number of prompts. If you prefer a visual AI editor, see the AI code editor comparison. If you still need operating-system install steps, return to the OpenCode install guide.

Troubleshooting

If opencode is not found, check the installed package and your PATH against the official installation page. If a model is missing, use /models and the provider's own account page; provider access can differ by region and plan. If a request fails, the OpenCode troubleshooting guide is a better starting point than an old social-media workaround. If an edit is incorrect, inspect git status and the diff before using /undo or resetting a disposable branch.

Avoid treating a model refusal or authentication error as proof that an entire provider has been removed. The current official provider list includes Anthropic. The account, API key, model, and provider terms must be checked separately. If you use a local model, verify that its server is running and that the selected model is installed; a client error may simply be a connection problem.

A first-week practice schedule

On day one, use OpenCode only to ask questions about a repository. Have it identify the command that runs unit tests, the directory that contains application code, and the file that defines one route. Verify each answer yourself. This small exercise reveals whether the project guidance and file search are working before you grant edit permissions. If the answers are vague, name the relevant files in the prompt and update the repository's guidance with facts you confirmed.

On day two, try one bounded edit with a test. Keep the request short enough to review in a single diff. Save the original test output, then ask Build to make the change. If it proposes a dependency upgrade for a simple validation fix, ask why that upgrade is necessary before accepting it. Run the original test command rather than a new command invented in the response. Record whether the resulting test covers the actual failure case. If the test passes only because assertions were removed, revert the patch and clarify the acceptance criteria.

On day three, repeat the same type of task with a different provider or a local model. Use a fresh branch from the same commit. Hold the task, input files, and time limit constant. Note what changed in context selection, number of corrections, and billed tokens. A cheaper model that requires twice as many retries may have a higher cost per accepted patch. If local inference is slow, include that elapsed time in the comparison. This is how to compare provider choices without presenting one anecdote as a universal ranking.

On day four, practice recovery. Ask the agent for a change that you can safely reject, inspect the diff, then use its undo flow and inspect git status. A trustworthy workflow includes a clear way back from an unwanted edit. Also test what happens when a shell command needs approval. You should know exactly which commands are permitted before using OpenCode on a repository that contains secrets or deployment credentials.

On day five, decide whether the workflow belongs in your daily development process. Keep the parts that saved reviewable time, document the model and provider you chose, and set a usage budget. If you manage a team, have another developer follow the same instructions and compare outcomes; an individual setup that only its creator understands is fragile. For an app idea that does not require code ownership, compare this developer workflow with an end-to-end builder such as NxCode using the same acceptance criteria and deployment requirements. The practical result, rather than a marketing feature list, should determine the choice.

Sources and Verification Date

Official documentation checked on 2026-10-10. Commands and provider terms may change. This article is a workflow guide, not an independent measurement of model quality.

• OpenCode introduction and install — supported interfaces, installer, /init, and undo.
• OpenCode providers — current provider directory and connection flow.
• OpenCode agents — Build, Plan, and permissions.
• OpenCode configuration — project and global configuration.
• OpenCode rules — repository guidance.
• OpenCode permissions — approval boundaries for files and commands.
• OpenCode models — model selection and identifiers.
• OpenCode CLI — command-line usage.
• OpenCode troubleshooting — error diagnosis.