Skip to content

Week 2: Installing & First Run

Learning Objectives

By the end of this week, you will: - Understand the difference between LLM providers (Anthropic, OpenAI, local Ollama). - Know the difference between API keys (per-request) and subscriptions. - Install OpenCode on your machine and set up a model provider. - 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. What is a "Provider" and Why Does It Matter?

Concept: An LLM provider is a company (or service) that runs a language model and gives you access to it over the internet or locally. OpenCode is provider-agnostic, meaning it works with multiple providers. You choose one based on cost, availability, and which model you trust.

Three Main Provider Categories

1a. Anthropic (Claude)

What it is: Anthropic makes the Claude family of LLMs (Claude 3 Opus, Sonnet, Haiku). Anthropic is known for focusing on AI safety and interpretability.

How to access it: - API Key approach: Pay-as-you-go. You create an account at console.anthropic.com, generate an API key, and pay per token (roughly $0.003 per 1,000 input tokens, $0.015 per 1,000 output tokens for Sonnet as of May 2026). - Subscription: Anthropic also offers Claude.ai subscription ($20/month for web access, not API).

Best for: If you're learning OpenCode and want a stable, well-documented model, Anthropic is the recommended starting point. Claude is trained on data up to April 2024 and excels at coding tasks.

In the labs: We will use Anthropic as the default.

1b. OpenAI (GPT)

What it is: OpenAI makes GPT-4, GPT-4o, and GPT-3.5-turbo. OpenAI is the most widely adopted provider in the industry.

How to access it: - API Key: Pay-as-you-go via platform.openai.com. You create an account, add billing, and generate an API key. Pricing varies by model (GPT-4o is ~$0.005 per 1,000 input tokens, $0.015 per 1,000 output tokens). - ChatGPT Plus subscription: $20/month for web access; the API is separate.

Best for: If you already have an OpenAI account and API key, OpenAI is a valid choice. GPT-4o is powerful but more expensive than Sonnet. Swap at any time — OpenCode will work with any provider.

Trade-off: OpenAI is widely used, but Anthropic's models tend to be better at following detailed instructions (a property called "instruction-following"). For this course, either works.

1c. Local Ollama (Offline, Free)

What it is: Ollama is a local LLM server that runs on your machine without internet. You download a model (e.g., Llama 2, Mistral, Neural Chat) and run it locally. No API key, no cost, no internet after setup.

How to access it: - Install Ollama from ollama.ai. - Download a model: ollama pull mistral (or another model). - Start the Ollama server: ollama serve. - OpenCode connects to http://localhost:11434 (the default Ollama port).

Best for: If you are offline, have a powerful machine, or want zero cost and full privacy. Trade-off: local models are often less capable than Claude or GPT-4o. For learning, Ollama is viable for Week 2–3 but may struggle with Week 6+ multi-agent work.

Our recommendation: Start with Anthropic (or OpenAI if you prefer). Ollama is a valid fallback if you can't access cloud APIs.

1d. Additional Providers — Groq, OpenRouter, and Copilot

Beyond the three main categories, OpenCode supports three more providers:

Groq — Known for extremely fast inference. Groq runs models like Llama and Mixtral on specialized hardware. Best for: lightweight or iterative tasks where speed matters. Setup: get an API key at console.groq.com, set GROQ_API_KEY in your environment.

OpenRouter — A model router that gives you one API key for many models (Claude, GPT, Llama, Mistral, and more). Best for: experimenting with different models without managing multiple accounts. Setup: get a key at openrouter.ai, set OPENROUTER_API_KEY.

Copilot — Uses your GitHub Copilot subscription. No separate billing or API key needed. Best for: learners who already pay for GitHub Copilot and want to avoid extra costs. Setup: authenticate with GitHub in OpenCode's config.

You can switch between any of these providers per agent. The opencode.jsonc config supports all five simultaneously.

2. API Keys vs. Subscription Auth

Key distinction:

  • API Key: A secret token (40+ random characters) that proves you are you and authorizes per-request payment. You paste it in your .env file or shell, and every call to the model costs money. Example: sk-ant-... (Anthropic) or sk-... (OpenAI).
  • Subscription (Web): You pay a flat monthly fee (e.g., Claude.ai for $20/month) and get unlimited web-based chat access. This is not the same as API access — subscriptions do not give you an API key.

For this course: Use an API key, not a web subscription. Why?

  1. Granular control: You see exactly what you spent and on what.
  2. Integration with OpenCode: OpenCode reads your API key from the environment and makes requests on your behalf.
  3. Cost transparency: Starting budget: ~$5–10 for the entire course if you're careful (mostly Weeks 6–10 when you run longer tasks).

If you don't have a credit card or can't set up billing, use Ollama (offline, free).

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 2.1 will walk you through this in detail for your OS).
  2. Get an API key (Anthropic or OpenAI; Lab 2.1 covers this).
  3. Set the environment variable: 
    export ANTHROPIC_API_KEY="sk-ant-..."
    (Or OPENAI_API_KEY if you choose OpenAI.)
  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 an API key?"

Yes, with Ollama (local, offline, free). The trade-off is that local models are less capable. For learning, Ollama is fine through Week 3, but you'll likely want a cloud API (Anthropic or OpenAI) by Week 5+ for more complex tasks.

"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're thoughtful and use the course labs: - Weeks 1–3 (basic use): ~$2–3. - Weeks 4–6 (custom agents, more complex work): ~$5–10. - Weeks 7–10 (multi-agent pipelines, heavy iteration): ~$10–20. - Total: Budget ~$20–30 for the entire course. (Much cheaper if you use Ollama for Weeks 1–3.)

The cost varies by provider and model choice. Sonnet (Anthropic) is cheaper per task than GPT-4o (OpenAI) but slower. You can swap providers mid-course.

"What if I'm offline?"

Use Ollama. Download a model like Mistral (ollama pull mistral) on a machine with internet, then run ollama serve on your offline machine. OpenCode will connect to localhost:11434.

"Can I switch providers mid-course?"

Yes. OpenCode reads the API key from the environment. You can set ANTHROPIC_API_KEY one week and OPENAI_API_KEY the next. The agent will use whichever provider is configured in opencode.jsonc.

7. What's Next?

In Week 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 2.1 and Lab 2.2 to get hands-on.