Getting started

This chapter takes you from nothing installed to one real, reviewed change shipped in a working repository. By the end you will have installed OpenCode, connected a model you already have a key for (or a local endpoint), watched one question-only turn of its loop, fixed a date-parsing bug with every edit-tool change approved by you, and docked the agent next to your editor so it stays there.

OpenCode is an open-source, terminal-first coding agent: you type a task, it reads your code, proposes a change, and applies it once you approve. That approval gate is something this chapter sets up on purpose, because it is not what ships in the box: out of the box the default build agent (one of OpenCode’s built-in named agent configurations) runs with every tool enabled - most permissions default to allow (as of October 2026; see the permissions documentation). The chapter’s safeguards have two pieces: the first turn runs in the plan agent, which denies the edit tools (it can still write plan files) and does not gate bash unless you add a rule, and the first fix sets permission.edit to ask in config before anything is written. That gate covers the edit tools only; bash stays allow unless you also set permission.bash.

The course’s illustrative project is feedmill: a small self-hosted feed aggregator - a Go CLI plus an HTTP sync server that pulls dozens of RSS, Atom, and JSON feeds, dedupes them, and serves a reading queue you read from the terminal and could run unattended on a cron. It mostly works, it’s thin on docs, and one feed type is suspected of parsing its dates wrong. The site ships no starter repository for it; every page restates the facts it needs, so you can map them onto a repo of your own or read along.

If you already live in an editor - a typed codebase open in the gutter, the language server drawing red squiggles under anything that doesn’t compile - you can eye a terminal agent with reasonable suspicion and still be in the right place. You don’t have to give any of that up. OpenCode is terminal-first, but by the end of the chapter it’s sitting next to your editor, not replacing it, and you’ve used it to fix a real bug with your eyes on every diff.

If you’ve used a single-vendor agent before, OpenCode’s first surprise is that it has no opinion about which model you run. It speaks to 75+ providers (as of October 2026; see the providers documentation), and the model is a setting you choose - so connecting one is its own deliberate stop early in the chapter, not a footnote in the install.

The chapter in five moves

feedmill ingests feeds from many differently-shaped sources, and one of them is suspected of mishandling dates: an entry that clearly published on one day lands in the reading queue stamped as another. That’s the chapter’s working exercise - small, real, and verifiable against a feed you can read with your own eyes. The chapter goes from zero to that fix shipped, in five moves:

• Install it and meet the TUI (OpenCode’s full-screen terminal interface) - and the small local server it starts behind the scenes (the engine the TUI talks to) - Install OpenCode and meet the TUI
• Bring your own model, because the provider is yours to pick and the choice is worth making on purpose - Bring your own model
• Watch one question-only turn of the loop - from plan, which denies the edit tools but does not gate bash, see how the agent gathers context before it writes anything - Understand one turn of the loop
• Hand it the date bug and watch that loop close on a real fix you review before it lands - Ship your first reviewed change
• Dock it next to your editor so this becomes a daily habit, not a detour - Put OpenCode next to your editor

The plan behavior described on this page is as of October 2026 (v1.18.32), per the plan definition in agent.ts; the agents documentation describes edits and bash as ask.

None of it is hard. The point of doing it as one continuous task is that the habits you pick up here are the same ones every later chapter leans on: read before you edit, approve before it writes, and commit the moment a change is green and reviewed. On code you’re still learning to trust, those habits aren’t optional polish. They’re the whole game.

And there’s one detail that can earn the skeptic’s attention early: feedmill is typed Go, and OpenCode can read the same kind of LSP diagnostics your editor turns into red squiggles. There’s a setup step to know up front: LSP is disabled by default, so you turn it on in your config, and you bring your own Go toolchain - the built-in gopls server’s documented requirement is the go command being available, and if gopls itself is missing OpenCode fetches it with go install unless you set OPENCODE_DISABLE_LSP_DOWNLOAD=true (as of October 2026; see the LSP documentation and the Go server definition in lsp/server.ts). OpenCode auto-detects .go files by extension and, once LSP is on, starts its own gopls for you. Make sure the Go toolchain is available before debugging the OpenCode configuration. With that in place, the agent isn’t guessing about your types: after it writes an edit, it gets the same kind of gopls diagnostics you see, read from the saved file, and it can fix what they flag before you commit. That’s the difference between an agent that hopes the code compiles and one that checks. OpenCode documents several built-in LSP servers, Go among them. You’ll feel it when you ship the date fix, and lean on it in later chapters.