Skip to content

Module 2: Installing & First Run

Learning Objectives

By the end of this module, you will: - Understand how OpenCode Zen provides free and premium models for coding agents. - Know when to use OpenCode Zen free models vs. OpenCode Go premium models. - Install OpenCode on your machine and connect it to a model. - Understand the OpenCode TUI (text user interface) — how to navigate, send messages, and switch modes. - Run the /init command and read the generated AGENTS.md file to understand project conventions. - Complete your first real task using OpenCode: fix a typo in a code sample.

1. Models in OpenCode

Concept: OpenCode needs a language model to power its agents. Rather than juggling multiple external providers, this course uses OpenCode Zen — OpenCode's built-in model gateway — which gives you immediate access to free and paid models without separate accounts.

Two Ways to Access Models

What it is: OpenCode Zen includes several free models you can use immediately. These are tested and optimized specifically for coding agents.

Free models available: - Big Pickle — A stealth model, free for a limited time - MiniMax M2.5 Free — Free tier for feedback collection - Ling 2.6 Flash Free — Fast, lightweight model - Hy3 Preview Free — Preview model for testing - Nemotron 3 Super Free — NVIDIA's free trial endpoint - GPT 5 Nano — Free lightweight model via OpenCode Zen

How to access it: 1. Go to opencode.ai/auth and create a free account 2. Copy your API key from the dashboard 3. In OpenCode, run /connect → select OpenCode Zen → paste your key 4. Run /models to see available models 5. Pick a free model like opencode/big-pickle

Best for: Learning the course. Zero cost. No credit card required. All labs in Modules 1–8 work great with free models.

In the labs: We will use Zen free models as the default.

OpenCode Go (Premium Models)

What it is: A low-cost subscription ($5 first month, then $10/month) that unlocks premium open-source models with higher quality and generous usage limits.

Premium models included: - GLM-5.1, GLM-5 - Kimi K2.5, Kimi K2.6 - DeepSeek V4 Pro, DeepSeek V4 Flash - MiMo-V2-Pro, MiMo-V2.5 - Qwen3.6 Plus, Qwen3.5 Plus - MiniMax M2.5, MiniMax M2.7

Usage limits: Capped at $12 per 5 hours, $30 weekly, $60 monthly.

How to access it: 1. Subscribe at opencode.ai/go 2. Use the same Zen API key — Go models appear automatically in /models 3. Select a Go model like opencode-go/kimi-k2.6

Best for: When you need more power — complex multi-agent workflows (Module 7+), production-quality output, or when free model limits feel tight.

Our recommendation: Start with Zen free models. Upgrade to Go only if you hit limits or want better results on advanced modules.

2. Free vs. Premium: When to Upgrade

Key distinction:

Zen Free OpenCode Go
Cost $0 $5 first month, then $10/mo
Setup Free account, no billing Subscription, auto-billing
Models 6+ free options 14+ premium models
Best for Learning, labs, exploration Advanced work, production, speed
Limits Varies by model $12/5hr, $30/wk, $60/mo

For this course: Start with Zen free models. Why?

  1. Zero friction: Sign up, copy key, start coding — no billing setup.
  2. Sufficient for learning: All labs through Module 8 work well on free models.
  3. Upgrade when ready: Switch to Go in Module 7–10 if you want smoother multi-agent performance.

If free models feel slow or limited mid-course, upgrade to Go. You can switch back and forth anytime.

3. The OpenCode TUI (Text User Interface)

What is it: OpenCode runs in your terminal and presents a conversation interface similar to ChatGPT or Claude.ai, but with superpowers: it can read files, edit code, run commands, and switch between two agents (plan mode and build mode).

Layout

When you run opencode in a project, you see:

┌─────────────────────────────────────────────────────────────┐
│ OpenCode                                        [plan | build]  │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  > Can you fix the typo in src/index.js?                  │
│                                                             │
│  OpenCode:                                                    │
│  I found it. Line 3 has "consoel" instead of "console".   │
│  Let me fix that.                                          │
│                                                             │
│  [Edited src/index.js]                                     │
│  ✓ File updated.                                           │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│ > _                                                         │
│ Press Tab to switch modes. Type /help for commands.        │
└─────────────────────────────────────────────────────────────┘

Key areas:

  1. Message history (top): Shows the conversation between you and the agent. Your prompts appear as >. The agent's responses show what the agent did, what files changed, and any errors.
  2. Input box (bottom): Where you type your next prompt. The cursor blinks here.
  3. Mode switcher (top-right): Shows [plan | build] or [build | plan]. Current mode is bold.
  4. Status line (below input): Hints for how to use the interface.

Keyboard Basics

Key Action
Enter Send your prompt.
Tab Switch between plan and build mode.
Ctrl+C Interrupt the agent if it's running.
Ctrl+L Clear the screen (history still visible if you scroll up).
↑ / ↓ Cycle through your previous prompts (if supported).
/init Run the /init command (just type /init in the OpenCode input box).

The Two Modes

Plan mode (plan agent): - Read-only: Can read files but cannot edit, delete, or run bash commands that change the system. - Safe to explore: Use this to ask questions, investigate bugs, or review code without risk. - No approval prompts: Since the agent cannot change anything, you do not need to approve each action.

Build mode (build agent): - Full access: Can read files, edit them, run bash commands, create new files. - Approval prompts: For dangerous operations (like git push or rm), the agent will ask for your permission. - Use after planning: First switch to plan, understand the problem, then switch to build and make changes.

4. The /init Command and AGENTS.md

What is /init?

/init is a built-in OpenCode command that analyzes your current project and generates a file called AGENTS.md. This file contains:

  1. Project context: What type of project this is (Node.js app? Python? Rust? Markdown course?).
  2. Key files and folders: Which directories should agents focus on (src/, tests/, docs/) and which to ignore (node_modules/, .git/).
  3. Conventions: How your team (or this project) expects agents to work. Examples:
  4. "Always run tests before committing."
  5. "Never edit package.json without asking."
  6. "Use Prettier for formatting."
  7. Permissions boundaries: What agents are allowed to do in this project.

Why run it?

Running /init teaches the agent about your project without you having to manually describe it every time. After /init runs, when you ask the agent to "add a test file," it will: - Know where tests live (likely tests/ or __tests__/). - Know what testing framework you use (Jest, pytest, Vitest, etc.). - Know your code style (2 spaces vs. 4 spaces, semicolons yes/no, etc.). - Respect project-specific boundaries (e.g., "don't touch package.json").

What Does AGENTS.md Look Like?

A generated AGENTS.md file typically has this structure:

# Project Conventions for [My Project]

## Context
This is a Node.js application for [purpose].

## Key Directories
- `src/` — Source code (main entry: src/index.js)
- `tests/` — Test files (framework: Jest)
- `docs/` — Documentation

## Conventions
- Code style: ESLint + Prettier (run `npm run lint` to check)
- Testing: Jest (run `npm test` to verify)
- Git: Always write descriptive commit messages. No direct main-branch commits; use feature branches.

## Out of Bounds
- Do not modify package.json without explicit instruction.
- Do not run `npm install` unless told.

## Suggested Workflow
1. Use plan mode to understand the issue.
2. Switch to build mode and make changes.
3. Run tests to verify nothing broke.
4. Ask for approval before git push.

Reading AGENTS.md:

After you run /init, read the generated file aloud (or write a summary). This teaches you: - What the agent knows about your project. - What it thinks is important. - Whether it got anything wrong (e.g., if it guessed the wrong test framework).

If it gets something wrong, you can edit AGENTS.md to correct it. The agent will re-read it on the next command.

5. Your First Task: Fix a Typo

Now you will put it all together.

Scenario

A small Node.js project has a typo: the file src/index.js says consoel.log() instead of console.log(). Your job is to fix it using OpenCode.

Steps

  1. Install OpenCode (Lab 1 will walk you through this in detail for your OS).
  2. Get a Zen API key (Lab 1 covers this — it's free and takes 2 minutes).
  3. Connect OpenCode to Zen: 
    opencode
    Then type /connect, select OpenCode Zen, and paste your key.
  4. Navigate to a project: 
    cd ~/my-project
  5. Start OpenCode: 
    opencode
  6. Send your first prompt (in plan mode): 
    Find the typo in src/index.js and show me what needs to be fixed.
  7. Switch to build mode (press Tab) and say: 
    Fix the typo.
  8. Verify the fix: 
    grep console.log src/index.js
    You should see console.log(), not consoel.log().

6. Common Questions

"Can I use OpenCode without paying?"

Yes. Zen free models like Big Pickle, MiniMax M2.5 Free, and GPT 5 Nano cost $0. No credit card required. All labs through Module 8 work well on free models.

"Do I pay for every keystroke?"

No. You only pay when the agent actually calls the model to send a message. You can type, edit, and switch modes for free. You pay when you press Enter and send a prompt.

"How much will this course cost?"

If you use Zen free models: $0 for the entire course.

If you upgrade to OpenCode Go: - $5 for your first month, then $10/month - Generous limits: $12 per 5 hours, $30 weekly, $60 monthly - Most learners never hit the monthly cap

Our recommendation: Start free. Upgrade to Go only if you want better performance on advanced modules.

"What if I'm offline?"

You can set up a local provider like Ollama. Download a model (ollama pull mistral), run ollama serve, and configure OpenCode to connect to localhost:11434. This is advanced — most learners use Zen online models.

"Can I switch models mid-course?"

Yes. Run /models in OpenCode anytime to see available models and pick a different one. Your Zen API key works for both free and Go models.

7. What's Next?

In Module 3, you will learn to use plan mode deeply — how to explore a codebase safely before making changes, and when to stay in plan mode for tasks like code review or security audits.

For now: install OpenCode, set up a provider, and complete Lab 1 and Lab 2 to get hands-on.