Skip to content
Nap Joseph Calub

Writing

Your first agent run with OpenCode

Oct 24, 2026

Post 4 — the finish line of Set up your Mac or Windows machine for vibe coding. You need: either track complete — macOS or Windows — meaning ssh -T git@github.com says hi to you, and about 30 minutes. It costs $0: this walkthrough runs on a free model.

From here on, both platforms do the same things; the only differences are which terminal you're in (Terminal.app on Mac, Ubuntu on Windows) and two clearly marked "Mac only / Windows only" moments.

1. OpenCode Console — the account behind the agent

OpenCode's own Console is the model catalog built and benchmarked by the OpenCode team, and it currently carries free models — including the one this series uses. One account, no payment, $0 for this walkthrough.

  1. Create a free account and sign in at opencode.ai/console.
  2. Copy your API key from the console. (Free models are used through OpenCode itself — the thing you'll install in step 2.)
  3. Keep that tab open; you'll paste the key in step 4.

What an API key is: a password for a program instead of a person. It lets OpenCode act as you against the model catalog — paste it where it's asked, never post it anywhere.

What this will cost: $0 — models bill per token (roughly a chunk of a word) when they bill at all, and the walkthrough runs on GLM 5.3 Flash (Free), which OpenCode lists at zero while it's featured. Free models come and go; if this one has retired by the time you read this, /models in step 4 shows whichever free models are current — every step here works the same. (Later, if you want paid flagship models, the console takes small credit top-ups, and OpenRouter is the one-key, hundreds-of-vendors alternative.)

Source: opencode.ai/v2/docs/console (Models, Free models) · checked 2026-10-24 · ⏳ clean-VM stamp pending

2. Install OpenCode — in your terminal, not from a website

OpenCode is a free, open-source agent: a program that reads your project, proposes changes, and edits files when you approve. The official install is one line, identical on Mac and Ubuntu:

curl -fsSL https://opencode.ai/install | bash
opencode --version

Deliberately not brew install opencode: at the time of writing that formula delivers OpenCode v2, while the script above delivers v1 — the version this series documents — and the two can't coexist under one command. If you already ran the brew version, uninstall it (brew uninstall opencode) and use the script.

When this goes wrong: command not found: opencode — the installer put it on your PATH (the shell's list of places to look), but your open window predates that. Close the terminal, open a fresh one, retry opencode --version.

When this goes wrong: the interface looks scrambled or garbled — some older terminal apps render it badly. OpenCode's docs recommend modern terminals (e.g. Ghostty or WezTerm); on a Mac brew install --cask ghostty and run opencode there instead.

Source: opencode.ai/docs · checked 2026-10-24 · ⏳ clean-VM stamp pending

3. Clone the starter site — the key's final exam

mkdir -p ~/projects/github.com
cd ~/projects/github.com
git clone git@github.com:napjoseph/vibe-starter.git
cd vibe-starter

If the clone ran without a password prompt, your SSH key just proved itself end-to-end — that's the setup series' last dependency, retired. Have a look inside:

  • ls — you should see index.html and a few supporting files.
  • Mac only: open index.html — your browser opens the site. Keep the tab open; you'll watch it change.
  • Windows only: explorer.exe . — Windows Explorer opens on your Linux folder; double-click index.html. Keep the tab open.

(On Windows this works because ~/projects/… lives in Ubuntu's own filesystem — one of the reasons the track kept your projects out of C:\.)

Source: docs.github.com — cloning a repository · checked 2026-10-24 · ⏳ clean-VM stamp pending

4. Connect OpenCode to your model catalog

From inside the vibe-starter folder:

opencode

A full interface takes over the terminal. Three commands to know, all typed at its input line:

  1. /connect — a picker appears; choose opencode (the Console provider), and paste the key from step 1. (This saves it to ~/.local/share/opencode/auth.json — the private half of what you just showed GitHub's public half.)
  2. /models — pick the model for today. The series default is GLM 5.3 Flash (Free) — search glm in the picker and take the one with Free in its name: the same fast Flash model as its paid sibling, at $0 while it's featured. Retired by the time you read this? Any model with Free in its name works for this walkthrough — it only makes a handful of requests.
  3. /init — OpenCode reads the project and writes an AGENTS.md: a small instruction file that helps the agent understand this specific repo. Let it.

Source: opencode.ai/docs (Configure, Initialize) · checked 2026-10-24 · ⏳ clean-VM stamp pending

5. The prompt — and the moment this series was built for

At OpenCode's input line, type this (with your own name), and press Enter:

In index.html, find the main headline and change its text to
"YOUR NAME builds things with AI." Make the headline steel blue.
Change nothing else.

Pay attention to what happens next, because it's the part worth learning:

What a permission prompt is: before the agent edits a file or runs a command, it shows exactly what it intends and waits for your yes or no. This is the whole safety model, and it works because of two things you already have: git (everything it does is a change since your last commit, reviewable with git diff, reversible with one command) and the price tag (today's model is free, so it cannot cost you anything). Approve the edit — reading first is the habit that makes this safe.

When it says it's done, it means it.

6. Look. It's real.

Switch to the browser tab from step 3 and refresh.

Your name is in the headline, in steel blue, on a page that came from a command line, changed by a sentence. That's the exit state — you're done.

7. Snapshot your win; learn the undo button

Leave OpenCode (/exit), then use the four verbs from the primer for real:

git status
git diff
git add -A
git commit -m "My first agent edit"

git diff is the one to build a reflex around: it's exactly what the agent changed, nothing more. And if a future run goes sideways, the undo is git restore . (older tutorials write the same idea as git checkout -- .) — plus OpenCode's own /undo while a session is still open.

Where next

  • Make your own repo and push — sharing your work to GitHub is the natural sequel and will get its own post.
  • Naming UI components — the difference between "make it nicer" and "turn this card into a modal" is vocabulary. A queued post teaches card, modal, accordion, toast, tabs straight from real design systems, with the success test: you write a one-line prompt and get exactly what you pictured.
  • Re-run /models any time — the console's catalog gains models constantly (free ones included), and that menu is the point of the stack you just built. When you outgrow free, small console credit top-ups or OpenRouter unlock the paid flagships.

Did this work? Did step 4 betray you? Open an issue at github.com/napjoseph/napjose.ph with the step number and the exact error text — it goes straight into the verification log.