ai-workflow-course/modules/04-getting-the-ai-out-of-the-browser/README.md

Module 4 — Getting the AI Out of the Browser

The copy-paste loop from Module 1 ends here. You stop being the integration layer between a chat tab and your files — the AI reads the whole repo and edits the files directly, and you review what it did as a diff. This is the literal answer to Module 1, and it's safe only because of the net you built in Module 2.

---

Prerequisites

• Module 1 — you have the tasks-app project, an editor, and a terminal, and you've felt the three seams where copy-paste breaks. This module closes seam 1 (more than one file) for good.
• Module 2 — this is the load-bearing prerequisite. You have a Git repo with commits, and you've personally watched git diff show you a change and git restore throw one away. Do not do this module without that. Letting an AI edit your real files directly is only sane because you can see and revert exactly what it did. The safety net comes first; the trapeze act comes second.
• Module 3 is helpful but not required — you've already practiced the branch / diff / review / commit rhythm on low-stakes documents. Here you point that same rhythm at code, with the AI doing the editing.

---

Learning objectives

By the end of this module you can:

1. Name the two categories of "AI out of the browser" tooling — editor-integrated assistants and agentic command-line tools — and choose between them on criteria that don't depend on a vendor.
2. Install, authenticate, and point one of them at a real repository, then confirm it can actually read the project.
3. Run the agentic edit → review → iterate loop: let the AI change real files, read the change as a git diff, and either keep it or revert it.
4. Set the tool's permissions deliberately — what it may read, edit, and execute without asking.
5. Explain precisely why this is safe, in terms of Module 2's restore.

---

Key concepts

What "out of the browser" actually means

In the browser-chat loop, the AI is blindfolded and handcuffed. It can't see your files unless you paste them in, and it can't change them — it can only hand you text to copy back. You are the integration layer: you decide which files it sees, you apply its output, you are the one who notices it forgot to update the second file. That's seam 1 from Module 1, and no smarter model fixes it, because it isn't an intelligence problem — it's an access problem.

Getting the AI out of the browser means giving it two things it never had in the chat tab:

1. Read access to the whole project — it can open any file, search the repo, and see how the pieces fit, without you pasting anything.
2. Write access to the files — it edits tasks.py and cli.py directly, in place, instead of printing a new version for you to paste.

Everything in this module follows from those two capabilities. They're also exactly why Module 2 had to come first: write access to your files is only acceptable when every edit is visible and reversible.

The two categories

There are two shapes this tooling comes in. They overlap, and plenty of products do both, but the distinction is real and worth understanding before you pick.

Editor-integrated assistants. These live inside a code editor (the graphical kind — VS Code and its forks, the JetBrains IDEs, and others). They show up as a side panel you chat with, inline suggestions as you type, and — the part that matters here — an "agent" or "edit" mode that proposes changes across files, which you accept or reject in the editor's own diff view. The win is that the review surface is right there: the editor highlights every changed line, and accepting a change is a click. If you already work in a graphical editor, this is the lowest-friction on-ramp.

Agentic command-line tools. These run in your terminal as a standalone program you talk to in plain language. You launch the tool inside your project directory, and it reads files, runs commands, and edits files on its own, reporting back what it did. They tend to be more autonomous — better at "go do this multi-step thing" — and they're editor-independent, so they work the same whether you use a graphical editor, a terminal editor, or none. The review surface is git diff itself (Module 2), which is the same review surface you'll use for everything else in this course.

	Editor-integrated assistant	Agentic CLI tool
Lives in	Your graphical editor	Your terminal
Review surface	The editor's diff view (and git diff)	git diff
Best at	Tight inline edits, in-editor review	Multi-step, multi-file, autonomous work
Tied to	A specific editor	Nothing — works anywhere
On-ramp if you…	Already live in a graphical editor	Live in the terminal, or run agents headless later

You do not have to choose forever, and you'll likely end up using both. Pick one to learn the loop with. The rest of this course is written to work with either.

How to choose (without crowning a winner)

This space moves fast and the "best" tool changes by the quarter, so evaluate on properties, not brand:

• Bring-your-own-model vs. locked model. Some tools let you point at whichever model/provider you want; some bundle one. The course thesis applies directly — the model is the swappable part — so a tool that lets you swap models is hedging in your favor. (You may still pick a bundled one for other reasons; just know what you're trading.)
• Reads a committed, repo-level instructions file. You'll want this in Module 5. Most serious tools read a project-level instructions file from the repo root. A tool that supports this lets you version your AI's configuration like code.
• Shows diffs before applying, and has an approval mode. Non-negotiable. You need to see what it wants to change and control what it's allowed to do without asking (next section).
• Works with your editor / OS / shell. Obvious, but check. Agentic CLIs are the most portable.
• Cost and where your code goes. Read the tool's data policy. For work code, know whether your files are used for training and whether a self-hosted or local-model path exists (a real concern for this audience; it returns in later units).

Don't agonize. Any tool that shows diffs and has an approval mode is good enough to learn the loop. The loop is the durable skill; the tool is swappable, same as the model.

Wiring it up: from browser to repo

The exact clicks differ per tool and drift over time, so here is the shape every one of them follows. Do these four steps and you're connected.

1. Install it. Editor-integrated assistants install from your editor's extension/plugin marketplace — search, install, reload. Agentic CLIs install as a command-line program (commonly via a package manager like npm/pip/brew, or a download) and then exist as a command you run, e.g.:

your-agent --version      # confirm the tool is on your PATH

2. Authenticate. On first run the tool will send you through a sign-in — usually a browser-based login that drops a token back onto your machine, or a paste-in API key from your provider account. This is a one-time setup; the credential is stored locally for next time. If the tool lets you choose a model/provider here, this is where the BYO-model choice from above gets made.

3. Point it at the repo. This is the step that has no equivalent in the browser, and it's the whole point. The convention is the current working directory is the project:

cd ~/workflow-course/tasks-app   # the repo from Modules 1–2
your-agent                       # launch it from inside the project

For an editor-integrated assistant, the equivalent is open the project folder (code . or File → Open Folder), exactly as you did in Module 1 — the assistant scopes itself to the folder that's open. Either way, the tool now treats this directory as its world: it can see every file in it without you pasting a thing.

4. Confirm it can actually read the project. Don't assume — verify, the same instinct you'd apply to any new integration. Ask it a question only something that has read your files could answer:

"What does this project do, which files is it split across, and what commands does the CLI support?"

A correct answer names tasks.py and cli.py, describes the task app, and lists add / list / done — pulled from the actual files, not guessed. If it asks you to paste code, or describes a generic to-do app it clearly invented, it is not connected to the repo. Stop and fix the wiring before going further; everything downstream assumes it can read.

A power move you already know from Module 2: ask it to read the repo's state, not just the files — "run git log, git status, and git diff and tell me where this project is." An agentic tool can run those itself. Now its first act is reading the durable memory you've been building, which is exactly the "where were we?" reconstruction from Module 2, except the AI does the reading.

Operating it: the edit → review → iterate loop

Connection is half the module. The other half is what you actually do once connected, and it replaces the entire copy-paste loop with this:

1. Describe the change in plain language. Not "here's a file, rewrite it" — "add a command that deletes a task by its index." The tool decides which files that touches.

2. The AI edits the files directly. It opens what it needs, makes the changes in place, and tells you what it did. No copying, no pasting, no you-as-integration-layer. This is the moment seam 1 dies: when the change spans tasks.py and cli.py, the tool edits both, because it can see both.

3. Review the diff. This is the load-bearing step, and it's the Module 2 habit, unchanged:

   git diff
   

   Read exactly what changed — every line, across every file it touched. An editor-integrated tool shows you the same thing in its diff view. You are reviewing the AI's work, not trusting it. (The deep version of this skill — spotting the plausible-but-wrong change — is Module 10. Here, just build the reflex: nothing gets committed unread.)

4. Iterate or revert.

   • If it's right: run it, then commit (git add . && git commit -m "…"). New checkpoint.
   • If it's close: tell the AI what to fix and loop back to step 2. It already has the context.
   • If it's wrong: git restore . and you're back to your last checkpoint, byte for byte. The mess is gone. Try a different prompt.

That fourth step is the entire reason this is safe, so let's be explicit about it.

Why this is safe: the Module 2 hinge

Letting an AI write to your files directly sounds reckless, and in Module 1's world — no version control, no checkpoints — it would be. The thing that makes it safe is not that the AI is careful. It isn't, reliably. The thing that makes it safe is that you committed first, so every edit it makes is a visible, reversible delta from a known-good state.

Concretely, the safety contract is:

• Before you let it loose: your work is committed (git status is clean). That's your restore point.
• While it works: every change is on disk, and git diff shows you all of it. Nothing is hidden.
• If it goes wrong: git restore . discards every uncommitted edit it made and you're back at the checkpoint, with zero retyping. Module 2's "undo for the AI," now pointed at an AI that edits files itself.

This is the promise Module 2 made cashing out. Module 2 said every later module asks you to let the AI do something bolder, and you can say yes because you can always get back to a checkpoint. This is the first of those bolder things. The downside of any AI edit is now "throw away a few minutes and re-prompt" — never "lose work" — and that asymmetry is what lets you move fast.

The one rule: start from a clean commit. If git status shows uncommitted work before you turn the AI loose, you've blurred the line between your work and its work — and git restore . will throw away both. Commit your stuff first. Then the diff is purely the AI's, and restore is purely an undo of the AI.

Permissions: what it may do without asking

Out of the browser, the AI can do more than edit files — an agentic tool can also run commands (tests, linters, the app itself, git). That's powerful and worth controlling. Every serious tool has an approval model, usually some version of:

• Read-only / ask-first — it proposes every edit and command and waits for your yes. Slowest, safest. Start here while you learn a tool's behavior.
• Auto-edit, ask-to-run — it edits files freely (you'll review the diff anyway) but asks before running commands. A good default once you trust the diff-review habit.
• Full auto / "just go" — it edits and runs without asking. Fast, and appropriate only when the blast radius is contained — a clean commit to restore to, and ideally an isolated branch (Module 6) or a sandbox (Module 16) for anything you don't fully trust.

The right setting is a function of your safety net, not your nerve. With a clean commit you can afford a looser setting for edits, because the diff is reversible. Be more conservative about letting it run commands unattended — a deleted file is restorable; a command that hits a real external system may not be. Match the leash to what you can undo.

---

The AI angle

This module is the AI angle of Unit 1 — it's where the whole "get out of the chat window" premise pays off. Map it straight back to Module 1's three seams:

• Seam 1 (more than one file) — solved here. The tool reads the whole repo, so a change that spans tasks.py and cli.py gets made in both. You are no longer the integration layer holding two files in your head.
• Seam 2 (more than one day) — solved by Module 2, used here. A fresh agentic session reconstructs "where were we?" by reading git log / status / diff itself — the durable-memory reframe from Module 2, now executed by the AI instead of pasted by you.
• Seam 3 (no undo) — solved by Module 2, required here. Direct file edits would be reckless without git restore. The safety net isn't a nice-to-have for this module; it's the precondition.

The deeper point: notice that none of this is model-specific. You didn't get a smarter model. You gave the same model access and wrapped it in review and revert. That's the course thesis in miniature — the leverage came from the workflow around the model, not the model. Swap the model underneath this loop and the loop is unchanged.

---

Hands-on lab

Lab language: shell + a small Python change made by the AI, not by you. You'll drive an agentic tool; the tool writes the Python.

The goal: wire an agentic editor or CLI tool to the tasks-app repo, confirm it can read the project, and make one real, reviewed, multi-file change with it — the exact change that broke the copy-paste loop back in Module 1, now done right.

You'll need:

• The tasks-app repo from Modules 1–2, as a Git repo with at least one commit.
• One AI-out-of-the-browser tool of your choice — either an editor-integrated assistant or an agentic CLI. Use the "How to choose" criteria above; any tool that shows diffs and has an approval mode is fine.
• Your model/provider credentials for that tool.
• The verify script in this module's lab/verify.sh.

Part A — Wire it up and confirm it can read

1. Install the tool and authenticate it (steps 1–2 in "Wiring it up").

2. Point it at the repo (step 3): cd ~/workflow-course/tasks-app and launch the agentic CLI from there, or open that folder in your editor and open the assistant's agent panel.

3. Confirm read access (step 4). Ask:

   "What does this project do, which files is it split across, and what commands does the CLI support?"

   You're connected only if it names tasks.py and cli.py and lists add / list / done from the real files. If it asks you to paste code, fix the wiring before continuing.

Part B — Start from a clean checkpoint

4. This is the one rule. Make sure your work is committed so the AI's change is the only thing in the next diff:

   git status        # must be clean ("nothing to commit, working tree clean")
   

   If it isn't clean, commit your current work first (git add . && git commit -m "…"). Now you have a known-good restore point, and anything that appears in git diff next is purely the AI's.

Part C — Make a real multi-file change

5. Ask the tool — in plain language, letting it decide which files to touch — for the change that needs both files:

   "Add a delete <index> command to the task app that removes the task at the given index. Put the removal logic in the TaskList class in tasks.py and wire the command up in cli.py. Match the existing code style and update the usage string."

   Let it edit the files directly. Do not copy anything by hand — if you find yourself pasting, the tool isn't actually wired to the repo (back to Part A).

6. Review the diff before you trust a line of it:

   git diff
   

   Confirm with your own eyes: a new method on TaskList in tasks.py, a new delete branch in cli.py's command dispatch, the usage string updated — and nothing touched that shouldn't be. This is the review reflex. Two files changed, and you didn't merge them by hand. That's seam 1, gone.

7. Verify it runs. Use the provided script, which exercises the new command end to end across both files:

   bash lab/verify.sh
   

   It should add tasks, delete one by index, and confirm the right task remains. If it fails, don't hand-fix it — tell the AI what broke and let it iterate (step 4 of the loop), then re-run.

8. Commit the reviewed change — this is your new checkpoint. It passed your own eyes and it passes the check, so lock it in:

   git add .
   git commit -m "Add delete command (made via editor/CLI agent)"
   git log --oneline
   

   You just shipped a reviewed, multi-file change made by an AI editing your files directly — and the copy-paste loop never entered into it. This commit is now the clean state git restore . falls back to in the next part.

Part D — Practice the revert (do this even though it works)

9. You only trust an undo you've used. Your tree is clean — you just committed in Part C, which is exactly the safe setup the one rule demands. Prove the net is under you: ask the tool for a deliberately throwaway change —

   "Rename every variable in tasks.py to single letters."

   — let it apply it, glance at git diff to see the damage, then throw it away:

   git restore .
   git diff           # empty — the AI's mess is gone, byte for byte
   bash lab/verify.sh # still passes — you're back at your good state
   

   That's the Module 2 safety net catching a Module 4 mistake. Internalize how cheap that was.

Part E — Confirm you're back at your good state

10. Nothing left to commit — the delete feature went in back in Part C, and Part D's throwaway is already gone. Confirm the reviewed multi-file commit is your latest and the tree is clean:

    git log --oneline   # "Add delete command…" is the latest commit
    git status          # clean — the throwaway left no trace
    

    That's the whole loop closed: a reviewed, multi-file change the AI made across both files is committed, and the mess you made on purpose vanished without touching it.

---

Where it breaks

Be honest about the limits of working this way:

• Access is not judgment. The AI reading your whole repo makes it informed, not correct. It will still make confident, plausible, wrong changes — now across multiple files at once, which is a bigger mess to read. The diff review in step 3 of the loop is not optional, and the deep version of that skill is a whole module of its own (Module 10). The tool removed the copy-paste; it did not remove the reviewing.
• git restore . only saves you if you committed first. This is the one rule for a reason. If you let the AI loose on a dirty tree, restore can't tell your work from its work and throws away both. The discipline that makes this module safe is commit before you turn it loose — the same "commit often" lesson from Module 2, now with teeth.
• It can do more than edit — watch what it runs. An agentic tool that can run commands can do things git restore cannot undo: delete files outside the repo, hit a network service, mutate a database. Restore covers versioned files only (Module 2's honest limit, still true). Keep the run-commands leash tighter than the edit-files leash until you've built the heavier isolation later (branches in Module 6, containers in Module 16).
• Big autonomous changes outrun your review. A tool set to "just go" can produce a 12-file diff faster than you can read it, and an unread diff is just copy-paste with extra steps. Keep changes small enough to actually review. Scoping work into small, reviewable pieces is a skill the rest of the course leans on hard.
• The wiring drifts. Install steps, auth flows, approval-mode names, and model pickers change between tool versions. The four-step shape (install → authenticate → point at repo → confirm it reads) is stable; the exact clicks are not. When in doubt, the "confirm it can read" test tells you truthfully whether you're connected.

---

Check for understanding

You're done when:

• An agentic editor or CLI tool is wired to your tasks-app repo and correctly answers "what does this project do and which files is it in?" from the actual files — no pasting.
• You have a committed delete command that you watched the AI write across both tasks.py and cli.py, that you reviewed with git diff before committing, and that bash lab/verify.sh passes.
• You have, on purpose, let the AI make a change and then erased it with git restore ., watching git diff go empty.
• You can explain, in one sentence, why letting an AI edit your files directly is safe — and your sentence mentions the clean commit you start from and the restore you can fall back to.

When making a multi-file change feels like "describe it, read the diff, keep it or restore it" — and the browser copy-paste loop feels like a thing you used to do — you've got it. Module 5 takes the next step: now that the AI is operating in your repo, you commit its configuration into the repo too, so the setup you just did becomes a durable, shared, reviewable artifact instead of something every teammate re-tunes by hand.

---

Verify-before-publish

This is durable-core, but the wiring instructions touch tool surfaces that drift. Re-check at build time:

• The two categories (editor-integrated assistants; agentic CLI tools) still describe the market, and no single tool has become so dominant that "agnostic" reads as evasive — if so, name it as the common default the way the syllabus treats GitHub in Module 8, without crowning it.
• The four-step wiring shape (install → authenticate → point at repo → confirm it reads) still matches how current tools onboard; update the install-command examples if package-manager conventions have shifted.
• The approval/permission model still maps to roughly read-only / auto-edit / full-auto across current tools; update the labels if the common terminology has moved.
• lab/verify.sh still passes against the Module 1 tasks-app after an AI implements delete.