Chapter 5 of 15

Changes, Commits and Pull Requests

The agent says it is done. Freddy has learned that this sentence describes the agent's opinion, not the code. This chapter is the review loop: see exactly what changed, say what is wrong on the line where it is wrong, and when it is right, commit and open the pull request.

The problem

Reviewing an agent's work has two bad habits. One is not doing it: “the tests pass, ship it.” The other is doing it in the wrong place, in a diff of the whole branch that mixes what you wrote this morning with what the agent wrote just now. In both cases the feedback loop is the slow part: you find a problem, switch to the chat, and describe which file and which line you meant.

The hard way

git diff in a terminal, a pager, and a message to the agent that starts “in the export function, a bit below the loop…” Then the same again for the commit message, the push, and a browser tab for the pull request. Every step works. Together they cost you the attention you wanted to spend on the code.

Workspace runs your own git and gh commands, so your Git configuration, hooks and credentials apply. It does not replace Git; it puts a window on it.

The Changes tab

Open it with ⇧⌘G, or with the tools panel (⌥⌘B) and the Changes tab. It shows the Git state of the active thread's folder.

  • Branch menu: the current branch. Pick another branch to switch to it. If your uncommitted changes would conflict, Workspace stashes them first and tells you. New branch… creates a branch from the current one and switches to it.
  • Fetch and refresh. When the branch is behind its upstream, a Pull button appears (fast-forward only).
  • Push pushes the branch. A branch without an upstream is published to the remote.
  • ↓2 ↑1 shows the commits behind and ahead of the upstream.

Files are listed in two groups: STAGED is what the next commit will contain, and CHANGES is everything else. Hover a file to Stage or Unstage it, or Discard changes (it asks first); Stage all and Unstage all act on a whole group. Click a file to see its diff.

The scope menu is the review tool

The scope menu chooses what the diff compares:

  • Working tree: all uncommitted changes (the default).
  • Agent turns: what one turn changed, based on the checkpoint saved before each turn. Use this to review the agent's work one step at a time.
  • Compare with branch or commit…: the working tree against any branch, tag or commit, for example main.

Agent turns is the one that changes how you review. It is the chapter 4 checkpoint put to work: the diff is not “everything on this branch” but “what the agent did in that message.” Freddy asked for two things in one thread; he reviews them as two diffs.

Reading a diff

  • Side by side shows old and new next to each other. Otherwise the diff is unified.
  • Wrap lines and Ignore whitespace can be switched on.
  • ⌥↓ / ⌥↑, or the arrow buttons, jump to the next or previous change. Copy diff copies the patch.
  • Very large diffs are cut off with a notice. Binary files are only listed.

Click a line in a diff to see who last changed it (Git blame: commit, author, date and message). Lines that are not committed yet have no blame.

And here is the part that closes the loop: you can also write a comment about the line and press Add to chat. The comment and the line's location are added to the thread's message box, so you can collect several and send them to the agent together. Freddy leaves three, on three lines, none of which needs a sentence explaining where it is, and sends them as one message.

Committing

  • Commit staged / Commit all commits the staged files, or everything when nothing is staged.
  • The sparkle button writes a commit message from the diff with the thread's agent. You can edit it before committing.
  • Commit and push (⌃⌘P, from anywhere) commits and pushes in one go.

Commit messages (their first line) and pull request titles are written as Conventional Commits: type(scope): summary, for example fix(nightwatch-exceptions): employee service create.

  • type is one of feat, fix, refactor, perf, test, docs, build, ci, chore, style or revert. feat! or feat(api)! marks a breaking change.
  • scope is the area that changed, in lowercase kebab-case.
  • summary is a short lowercase phrase without a trailing period; the whole line is at most 72 characters.

What the agent generates is written that way and tidied up (lowercase type and scope, no trailing period). Commit says what to fix if your own message does not follow it. If your team does not use the format, turn it off in Settings → Code → Commits and pull requests.

Pull requests

The PR tab works with GitHub through the gh CLI, installed and logged in with gh auth login. If the branch has no pull request yet, you can create one:

  • Write a title and description, or press Generate to have the agent write them from the branch's commits.
  • Titles follow Conventional Commits; Create pull request says what to fix if one does not.
  • Tick Draft to open it as a draft.
  • Press Create pull request. The branch is pushed first if needed.

When the branch has a pull request, the tab is labelled PR #n and shows:

  • status, checks and reviews;
  • review comments, including those on specific lines;
  • Comment to reply;
  • Merge, choosing Squash and merge, Create a merge commit or Rebase and merge;
  • Ready for review (for drafts), Close and Reopen;
  • Ask agent to address feedback, which puts the review comments in the message box as a task for the agent.

That last button is the round trip: a colleague reviews Freddy's pull request, and one click turns their comments into the agent's next task.

The review inbox

⇧⌘R (or the pull request button at the top of the sidebar) opens the inbox: open pull requests and issues from the GitHub repositories of all your projects.

  • Switch between pull requests and issues, and open or closed.
  • Filter by project, or search by title, number, author or label.
  • Select an item to read its description, checks and comments.
  • Send to agent starts a new thread in that project with the pull request or issue already described in the message box, ready to send. Pull requests get a new worktree so the review does not disturb your checkout.
  • Open on GitHub opens it in the browser.
Someone else wrote that text. The text of pull requests and issues is written by other people. Workspace tells the agent to treat it as reference, not as instructions. That is a sensible precaution, not a guarantee: read what you send to an agent that has write access.
Try it: ask the agent for two small changes in two messages. Open Changes, set the scope to Agent turns, and read them one at a time. Leave a comment on one line, press Add to chat, and send it.

What you learned

  • How the Changes tab shows the state of the thread's folder, and what staging means here
  • Why the Agent turns scope is the review tool, and how it uses the checkpoint from chapter 4
  • How to comment on a line and send several comments to the agent at once
  • How commit messages and pull request titles follow Conventional Commits, and how to turn that off
  • How to open, merge and follow up a pull request without leaving the window
  • What the review inbox does and why pull request text is treated as reference
Next: in Chapter 6 you run several threads in one project: the sidebar, pinning, archiving, forks, handoff and side chat.