Set up your Mac or Windows machine for vibe coding
Oct 24, 2026
Vibe coding means describing what you want in plain language and letting an AI agent — a program that reads, edits, and runs code for you — do the typing. This series gets a completely ordinary Mac or Windows machine ready for it, in one sitting, with nothing installed that you don't need.
Where you'll end up
By the last post you will have, on your own machine:
- A terminal with a customized, colorful prompt — your machine finally looks like a developer's.
- A small example website downloaded to
~/projects/github.com/napjoseph/vibe-starter. - OpenCode (a free, open-source AI coding agent) connected to the OpenCode Console model catalog, running a free model — $0 spent, nothing on a card.
- The moment this series exists for: you type one sentence, the agent asks your permission, edits a file, and you open that file in your browser and see your name on the page.
Anything that doesn't serve that ending is deliberately not here. Notably, this series does not cover Docker, Node, Python, or pushing to GitHub — none of them are needed for the ending above.
The posts, in order
| # | Post | Time | What it does |
|---|---|---|---|
| 1 | The 15-minute terminal and git primer | ~15 min | Just enough vocabulary to follow the rest without being lost. |
| 2 | Setup for macOS | ~60–75 min | The Mac track: Homebrew, shell, git + SSH keys in Keychain, editor. |
| 3 | Setup for Windows (WSL + Ubuntu) | ~90–120 min | The Windows track: same ending, via a real Linux terminal inside Windows. |
| 4 | Your first agent run with OpenCode | ~30 min, $0 | The two tracks rejoin: connect the agent, make the visible change. |
Pick your path: Mac → 1 → 2 → 4. Windows → 1 → 3 → 4. The only reason the tracks are separate posts is that a handful of steps truly differ (package manager, shell setup, where your passwords are stored). Everything after that is shared on purpose, so there is exactly one place to keep correct.
Four things worth knowing before you start
- What an SSH key is: a pair of files on your computer — one public, one secret — that proves to GitHub it's really you, so you never type a password.
- What an API key is: a password for a program instead of a person; it lets OpenCode act as you against your model account, so treat it like a card number.
- What it costs: $0 for this series — the walkthrough runs on a free model from OpenCode's catalog. When you later want paid models, pre-pay small amounts and set spending caps; never more than you'd lose casually.
- What a permission prompt is: before OpenCode edits a file or runs a command, it shows you what it intends and waits. Read it, approve on purpose, and know that git — which you learn in post 1 — is always the undo button.
How this series is verified
Every step in every post ends with two lines: a link to the official source it was taken from, and a stamp:
Source: docs.brew.sh/Installation · checked 2026-10-24 · ✅ verified 2026-10-24 on macOS 26 (clean VM)
The stamp means: a clean virtual machine was restored to factory state, the post was followed literally, and it reached the end state with zero unlogged surprises. Every mismatch found along the way — real error messages and all — lives in the series' verification log and became one of the "When this goes wrong" boxes you'll meet in the posts. When an install page changes underneath us, a reader-found issue re-triggers that machine run within 90 days, and the stamp is refreshed or the step is fixed.
Why this stack
- Terminal-first, editor-second. Agents live in the terminal, and the terminal is where every installer on earth documents itself. Fighting that is how beginner tutorials go stale.
- OpenCode is free, open source, runs on macOS and Linux (which is what the Windows track sets up), and works with many providers — you're not locked into one company's models.
- The OpenCode Console is the model catalog built and benchmarked by the OpenCode team, and its free models make this series cost $0. When you outgrow free, the same account takes small credit top-ups — and OpenRouter is the one-key, hundreds-of-vendors upgrade.
Ready? Start with the primer — even if you think you don't need it, it's fifteen minutes and it defines the words the other posts use.
Did this series work for you — or trap you? The fastest way to improve it is to say so: open an issue at github.com/napjoseph/napjose.ph with the step number and the exact error text.