Start With OpenCode: Set It Up, Change One Line, and Undo It

T08-L01 · Write code · Level 1 User · 15-minute read, plus 60 minutes of doing

Almost what you need

A colleague left you a small search page. In the lab it finds reagents; in a company it finds stock. It only matches the start of a name, so "buffer" finds nothing, although Tris buffer and HEPES buffer are on the list.

The fix is one line. In this book you set up OpenCode and let it find, change and undo that line, one step and one screenshot at a time. You are at Level 1 User: you work on your own copy, so only you are affected if something goes wrong.

After this you can

• Install OpenCode Desktop, open a project folder and choose a free model that keeps no copy of your prompts.
• Set up the safety net (Git) so that Undo really restores your files.
• Use Plan to have OpenCode explain code without changing it, and Build to make one narrow change.
• Read the change in the Review panel and check it against a before-and-after table.
• Undo the change and bring it back with Redo.

Before you start

• Books: T01-L01 · From Idea to Working Result: The Four-Quadrant Method for the four-quadrant method.
• A Windows or Mac computer you may install software on. If IT controls installs on your work computer, ask them to install OpenCode and Git.
• Notepad or TextEdit, and a web browser.
• About 75 minutes: 15 to read, 60 to do. Steps 1 to 6 take 20 minutes, once.

Last verified 18 October 2026, with OpenCode Desktop 2.0.32. OpenCode Desktop and its ten built-in models are free. A new install picks Big Pickle, which may learn from your prompts; this book switches to Space Bunny, which keeps none. Since version 2, OpenCode no longer asks before it reads files outside your project; step 2 makes it ask. Details for experts at the end.

The idea in one page

• OpenCode works in one folder. Unlike a chat assistant, it opens, changes and runs the files in the folder you give it. Out of the box it may also read files outside that folder without asking; one small settings file (step 2) makes it ask first.
• Plan explains, Build changes. In Plan, OpenCode can only read. Ask there first, then switch to Build for the change.
• The Review panel shows what really changed: removed lines in red, added lines in green. Trust it more than OpenCode's own summary.
• Git is the way back. It's a free program that keeps saved versions of a folder. OpenCode's Undo needs it, and it has to be in the folder before OpenCode first opens it. Step 9 shows how.
• Ask narrowly: the file, what happens now, what you want instead (with one example) and what must stay the same.

Watch it once (73 seconds)

The pointer shows every button this book uses, in the order you'll use them. It was recorded live with the free model and the same made-up page.

The video has no sound; the captions at the bottom explain each scene. Read the tour as text (opens in a new tab).

Set up OpenCode (steps 1 to 6, once)

Step 1: Install OpenCode Desktop. Go to opencode.ai/download and choose Desktop. Windows: pick x64 (almost every PC). Mac: pick Apple silicon, or Intel if Apple menu → About This Mac names an Intel processor. Run the download and start OpenCode.

You should see: the home screen with Projects and Add project on the left, and Nothing here yet on the right.

Step 2: Make your OpenCode folder, make it ask, and add it. In File Explorer (Windows) or Finder (Mac), create a folder OpenCode in Documents. In Notepad or TextEdit, paste this one line and save it in that folder as opencode.json (in Notepad, set Save as type to All files; in TextEdit, choose Format → Make Plain Text first):

{"permissions":[{"action":"external_directory","resource":"*","effect":"ask"}]}

It tells OpenCode to ask before it touches anything outside the project it works in, for every project you'll keep in this folder. Then, in OpenCode, click Add project, choose the new folder and confirm.

You should see: OpenCode in the Projects list. (This picture is from later, when a second project has been added.) This folder is your workbench: you'll keep every project inside it and use it only to prepare them.

Step 3: Start a session on the workbench. Click OpenCode in the Projects list, then New session at the top right. A session is one conversation about one project.

You should see: a large message box, with OpenCode named below it.

Step 4: Choose the free model. Click the model name under the message box. A new install has Big Pickle ticked. Choose Space Bunny instead; OpenCode remembers your choice.

You should see: Space Bunny Free under the message box. It keeps none of your prompts; stay with it. The small Default button next to it chooses how hard some models think; leave it.

Step 5: Turn on the Plan/Build switch. Press Ctrl+, (Cmd+, on a Mac) to open Settings. Under Preferences, turn on Show agent. Leave Auto-accept permissions off. Click Back to app.

You should see: Build with a small arrow under the message box. Click it to switch to Plan; Ctrl+. does the same.

Step 6: Learn the ten parts of the screen.

1. Home: projects and sessions (Ctrl+B).
2. Session tab: one per open session. Closing it doesn't delete the session.
3. ⋯: rename, export or delete the session.
4. Context: how much of the model's memory the session uses, and what it cost ($0.00 on free models).
5. Session details: the project, its branch, the changed files.
6. Review panel (Ctrl+Shift+R).
7. Message box: Enter sends, Shift+Enter adds a line.
8. +: attach a file or a picture.
9. Mode: Plan or Build.
10. Model.

On a Mac, use Cmd wherever this book says Ctrl. Grey lines such as Used 1 Read only list what OpenCode did; you can let them pass.

Worked example: fix the reagent finder, step by step

The method is the one from T01-L01 · From Idea to Working Result: The Four-Quadrant Method. Mia, a lab technician, follows it; you do the same steps.

Structure it

Step 7: Write what you want in one sentence.

"When I search 'buffer', I want Tris buffer and HEPES buffer instead of 'Nothing found'. Everything else stays as it is."

Choose tools

OpenCode with Space Bunny, Plan and Build, Git for Undo, the Review panel and your browser. That's all this change needs.

Build it: prepare the project

Step 8: Create the page. Inside your OpenCode folder, create a folder reagent-finder. In Notepad or TextEdit, paste the text below and save it there as index.html, the same way as opencode.json in step 2.

<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Reagent finder</title>
</head>
<body>
<h1>Reagent finder</h1>
<label>Search by name: <input id="search"></label>
<ul id="results"></ul>
<p id="none" hidden>Nothing found.</p>
<script>
const items = [
  { id: "R01", name: "Tris buffer 1 M, pH 8.0", place: "Shelf A2" },
  { id: "R02", name: "PBS 10x", place: "Shelf A3" },
  { id: "R03", name: "Ethanol 70 %", place: "Flammables cabinet" },
  { id: "R04", name: "HEPES buffer 1 M", place: "Fridge 2" },
];

function show() {
  const query = document.getElementById("search").value.trim().toLowerCase();
  const results = document.getElementById("results");
  results.innerHTML = "";
  for (const item of items) {
    if (item.name.toLowerCase().startsWith(query)) {
      const line = document.createElement("li");
      line.textContent = item.id + " · " + item.name + " · " + item.place;
      results.appendChild(line);
    }
  }
  document.getElementById("none").hidden = results.children.length > 0;
}

document.getElementById("search").addEventListener("input", show);
show();
</script>
</body>
</html>

You should see: double-click the file and your browser shows Reagent finder with four reagents. If Windows opens it as text, the name ends in .txt: in File Explorer's View menu, turn on File name extensions and rename it.

Step 9: Set up Git from the workbench. Go to your OpenCode workbench session (not a reagent-finder one), check the mode says Build, and send:

Set up Git in the folder reagent-finder so changes there can be tracked and undone:
create a Git repository inside reagent-finder and save its current files as the first version.
Do not change any file.

You should see: that Git is set up in reagent-finder and index.html is saved as the first version, within half a minute. If it says Git isn't installed: on Windows, install Git for Windows from git-scm.com with its default choices; on a Mac, click Install when macOS offers the command line developer tools. Restart the computer, then repeat this step.

Step 10: Open reagent-finder as its own project. Add the reagent-finder folder with Add project (as in step 2). Click it in Projects, then New session.

You should see: Local and a branch label such as master or main under the message box. That means Undo will work. (Local can also start a New worktree, a separate working copy; stay with Local.)

If you see No Git instead: Undo won't restore files here. Go to the first item in What goes wrong.

Understand it

Step 11: Ask for an explanation in Plan. Switch the mode to Plan and send:

Read index.html. Don't change anything yet.
Explain in plain English, pointing to the exact lines:
1. where the page reads what I type,
2. which line decides whether an item is shown,
3. where it writes the result.
Then tell me why searching "buffer" finds nothing.

You should see: an answer within seconds that points to the line with startsWith, meaning "the name begins with what I typed". Your wording will differ. To check it, search the file for startsWith with Ctrl+F in your text editor.

Mia also notices that an empty search box shows every item. She adds to her sentence: keep that, the order and the Nothing-found message.

Build it: make and check the change

Step 12: Ask for the narrow change in Build. Switch the mode to Build and send:

Change index.html so the search finds the text anywhere in the name,
not only at the start. "buffer" must find R01 and R04.
Change only the line that decides whether an item is shown.
Keep the item list, the order, the "Nothing found." message and the
show-everything-when-empty behaviour exactly as they are.
Show me the changed line.

You should see: a reply showing one changed line with includes, meaning "the name contains what I typed". Ours also listed a few searches it had tried. Build edits files in the project without asking first.

Step 13: Read the change in the Review panel. Click the rightmost icon at the top right of the session (marker 6 in step 6).

You should see: Files Changed 1 and +1 −1, with line 25 in red (before) and green (after). The two buttons at the top right of the panel switch between side by side and one column. If more lines changed, ask: "Why did you change these other lines? Revert everything except the matching rule."

Step 14: Check before and after. Reload the page in your browser and fill in the last column.

You should see: "buffer" now finds both buffers, and the last two rows haven't changed.

Step 15: Undo. Press Ctrl+P, type undo and press Enter on Undo.

You should see: your request back in the message box, and "buffer" finds nothing again after a reload. Close and reopen the Review panel: it now says No file changes yet.

Step 16: Redo. Press Ctrl+P, type redo and choose Redo.

You should see: after a reload, "buffer" finds both buffers again.

What it taught Mia: three lines were enough to judge the change, and the empty-box row protected a behaviour she'd almost forgotten.

Company: the product finder

Jonas runs a stockroom. His page lists four products, and "mug" finds only "Mug lid, blue". He does steps 7 to 16 with a folder product-finder and these four lines in place of the reagents:

  { id: "P01", name: "Blue coffee mug 300 ml", place: "Aisle 3" },
  { id: "P02", name: "Mug lid, blue", place: "Aisle 3" },
  { id: "P03", name: "Travel mug 450 ml", place: "Aisle 4" },
  { id: "P04", name: "Tea towel, cotton", place: "Aisle 7" },

After the change, "mug" finds P01, P02 and P03, and an empty box still shows all four. Before changing a page other people rely on, he'll ask its maintainer: that's a Level 2 job (T08-L02 · Get a Script Your Colleague Can Rerun, Without Being a Developer).

Working with OpenCode day to day

• One session per task. Start a new one with New session, Ctrl+Shift+S or Ctrl+T; long sessions get slow and vague.
• Point at a file by typing @ and part of its name.

• Answer permission questions. With the file from step 2, OpenCode asks before it goes outside the project folder. Allow once if you expected it; Deny if you didn't, then ask why. Deny stops the answer; the line Interrupted marks where.

• Take back one request with Revert message, which appears when you point at your message, or type /undo. Both do the same as step 15.
• Attach a picture of an error with +, but only what you'd be allowed to paste into any chat (T12-L01 · Decide What You May Paste Into AI at Work).

What goes wrong

Undo leaves the file changed. Symptom: after Undo the page still behaves the new way; a new session shows No Git. Fix: OpenCode opened the folder before it had Git. Change the line back (or ask Build to). Copy the folder inside OpenCode under a new name, set up Git in the copy (step 9) and add the copy as a project (step 10). To remove the old one, open Settings → Projects, click ⋯ and choose Close.

The Review panel is empty or out of date. Symptom: it says No tracked changes with a Create Git repository button, or still shows an undone change. Fix: the first means no Git (see above); out of date means close and reopen it.

It read a file outside the project without asking. Symptom: OpenCode quotes a file from another folder. Fix: the opencode.json from step 2 is missing or not in a folder above the project. Check its name and place, and that the project sits inside the OpenCode folder.

Plan refuses to change the file.

Fix: that's Plan doing its job ("switch agents" means switch the mode). Switch to Build and send "Go ahead and make that change now."

Asking for "better". Symptom: "Improve the search" returns a rewritten page. Fix: name the file, one example, the expected result and what must stay the same.

Trusting the reply instead of the Review panel. Symptom: the reply says "only line 25", the panel shows +7 −3. Fix: ask why each extra line changed and have it revert them.

Checking the old page. Symptom: the change "didn't work". Fix: reload the page, and make sure it's the file from the project folder.

Pasting real data. Symptom: you paste the real reagent or customer list "for context". Fix: everything you send goes to the model provider. Use four made-up rows (T12-L01 · Decide What You May Paste Into AI at Work).

Do it yourself (60 minutes)

Use a small page or script of your own that almost does what you want, or change the reagent finder to search the shelf as well as the name.

1. Set up (20 min, first time only): steps 1 to 6.
2. Structure it (5 min): "When I ___, I want ___ instead of ___."
3. Choose tools and prepare (10 min): put the file in a new folder inside OpenCode, then steps 9 and 10. Write your before-and-after table with five inputs, one of which must not change.
4. Understand it (10 min): step 11 with your file.
5. Build it (15 min): steps 12 to 16.

Exit check

What you hand in: your before-and-after table of five inputs, a screenshot of the Review panel showing the change (Windows+Shift+S, or Cmd+Shift+4 on a Mac), and one sentence on how you undid and redid it.

It passes when all five results match, including the one that must not change, the Review panel shows only the line you asked for, and Undo brought the old behaviour back.

Rule to remember

Explain in Plan, change in Build, read the Review panel, and keep Git as the way back.

Details for experts

Checked on 18 October 2026. You don't need this to follow the book; it's for setting things up or answering a colleague.

Further reading and tools

Next books

• T06-L01 · Build a Small Browser Tool You Will Actually Use: a new one-file tool from a description, with the same Plan-Build-Review habit.
• T20-L01 · Same Model, Different Harness: See What the Program Around the AI Changes: OpenCode is a harness; see what changes when the program around the model changes.
• T08-L02 · Get a Script Your Colleague Can Rerun, Without Being a Developer: scripts for your own data.
• T21-L01 · Start With OpenWork: One Folder, One Task, and a Look at Every Change: the same engine in an app for desk work on files, with no code.
• T08-L04 · Use OpenCode Desktop on Your Organisation's Real Repositories: approved models, permission rules and team set-up.
• T12-L01 · Decide What You May Paste Into AI at Work: what may go into a chat with a coding assistant.

Tools

• OpenCode: Taught. The Desktop app is the course's coding assistant.
• Git: Taught, one request deep. OpenCode uses it to show and undo changes.
• OpenWork: Catalogued. OpenCode's engine in an app for office and lab files.
• Claude Code, Cursor: Catalogued. Other coding assistants with the same explain-change-review workflow.