(Day-to-day git work with Claude Code — commits, PRs, rescue situations — is covered by the Git and GitHub cheat sheet for Claude Code. This is the layer above it: multiple machines, one project.)

The foundation: the remote as the single source of truth

First, what not to do: don't copy folders over USB, and don't put the repo inside a folder synced by iCloud, Dropbox, or OneDrive. A sync client doesn't see .git atomically — it transfers files one by one, mid-write, and lock files and half-transferred objects can corrupt a repository in ways that only surface a week later. Git should be the one doing the syncing — a sync client just gets in its way.

The rest is a two-command discipline:

git pull --ff-only   # before I start working
# ... work, commits ...
git push             # before I leave the machine

--ff-only means a pull never silently manufactures a merge commit. If the machines have genuinely diverged — commits on both sides — the command fails and I deal with it consciously, instead of discovering it later in a weird history.

Which yields the one hard rule: never walk away from a machine with unpushed commits. A commit can absolutely be unfinished — that's what branches and wip: prefixes are for. But an unpushed commit is a commit that doesn't exist on the other machine.

The second layer: sync the context, not just the code

If this were only about code, the article would have ended a paragraph ago. But with Claude Code, the repo carries more than code:

• CLAUDE.md — instructions for the agent: conventions, project structure, workflow rules
• memory/ — the agent's persistent memory, plain markdown files: decisions, section specs, feedback, work in progress
• .claude/settings.json — shared hooks (more on those in a moment)
• tools/ — the scripts those hooks run

When all of this is versioned together with the code, the second machine isn't a clean install. I sit down at the MacBook and the agent knows what we decided on Wednesday at the Windows desktop — because it reads it from the same files it wrote there.

One condition: a private repo. The agent's memory contains internal project notes, decisions and their reasoning — none of which belongs in a public repository.

And one exception: paths don't sync. C:\Users\... on Windows is not /Users/... on a Mac. Per-machine settings therefore live in a gitignored local config (.claude/settings.local.json), generated by an init script that runs once after cloning:

./claude-init.sh   # writes local paths, installs the per-machine bits

The split is then simple: everything shared between machines is versioned (instructions, memory, hooks, scripts); everything per-machine is gitignored (local paths, builds, node_modules).

Automating the ritual

The "pull before work, push after" ritual has one weakness: it relies on me. And after a weekend, I won't remember. Claude Code can run commands on session events — and two of those events map exactly onto the two ends of the ritual:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [{ "type": "command", "command": "bash tools/sync-pull.sh" }]
      }
    ],
    "Stop": [
      { "hooks": [{ "type": "command", "command": "bash tools/unpushed-check.sh" }] }
    ]
  }
}

SessionStart pulls for me. The core of the script:

git fetch --prune origin
git merge --ff-only '@{u}'   # silent when there's nothing to do; shouts only on real divergence

Stop — the end of an agent response — counts unpushed commits and nags:

n=$(git log --oneline @{u}.. 2>/dev/null | wc -l | tr -d ' ')
[ "$n" != "0" ] && echo "📌 You have $n unpushed commits — git push so the other machine sees them."

The effect in practice: I open a session on the MacBook and the repo is current before I've typed the first prompt. And since the settings.json with the hooks is itself part of the repo, every machine behaves this way automatically — the automation syncs through the same channel as everything else.

Mac ↔ Windows traps

The things you don't learn from documentation — only from being bitten.

Line endings. Windows git with core.autocrlf=true checks out text files with CRLF — including bash scripts. A trivial script survives that; a script with conditionals and functions dies on an invisible \r at the end of a line. And since a script committed from Windows will also run via a hook on the Mac, it's a trap with a delayed trigger. The once-and-for-all fix, in the repo:

# .gitattributes
*.sh text eol=lf

Git identity on a new machine. My first commit on a fresh MacBook ended with "Author identity unknown". Nothing dramatic, but it belongs in the new-machine checklist, not in mid-task debugging:

git config --global user.name "Firstname Lastname"
git config --global user.email "mail@example.com"

A branch deleted on the remote. A feature branch merged and deleted from the other machine: on the first machine I'm still standing on it, and git pull fails with "no such ref was fetched". It looks like a conflict, but it's just a dead reference:

git fetch --prune            # clean up references to deleted remote branches
git checkout main && git pull --ff-only

That's why the sync script above distinguishes three states: a live upstream (pull it), a branch fully contained in origin/main (say "switch to main"), and a genuine divergence (the only case where it should shout).

Tools missing on the other platform. lsof is absent from git-bash on Windows; netstat behaves differently on a Mac. Scripts shared across platforms need a guard — command -v lsof >/dev/null || exit 0 — so that a missing tool means silent degradation, not a broken hook.

Checklist: a new machine in ten minutes

gh repo clone <user>/<repo>          # 1. outside iCloud/OneDrive/Dropbox folders!
cd <repo>
git config --global user.name "..."  # 2. identity, if the machine is fresh
git config --global user.email "..."
./claude-init.sh                     # 3. local config, per-machine installs
npm install                          # 4. project dependencies

And a fifth step worth not skipping: a verification round-trip. Commit from the new machine, push, pull on the old one — and the same in reverse. Once both directions pass, hooks included, the machine is a full citizen. Mine caught both the missing identity and the CRLF in scripts.

Conclusion

I'm not syncing files, I'm syncing a workplace. The measure of success is simple — I sit down at the other machine, open a session, and the first prompt can be "let's continue". No explaining where we left off. Git carries the code, the repo carries the context, and the hooks carry the discipline I could never rely on myself to keep.

Commits and messages

The thing I ask for most often. A plain "commit this" is enough, and under the hood this runs:

git status                 # what changed, what's untracked
git diff                   # what actually changed
git add build.mjs serve.mjs
git commit -m "fix: dev server did not serve webp from subdirectories"

The message comes from what the diff actually says — not from what I think I did. What has worked for me:

• Conventions belong in CLAUDE.md. Commit message language, prefixes like feat:/fix:, formatting — write it once into the repository instructions and Claude follows it without being reminded.
• Selective commits work reliably. When I have several unrelated things in progress:

commit only the changes in build.mjs, leave the rest alone

Under the hood that's git add build.mjs and a commit — no git add -A that would sweep up the unfinished rest.

• Let it split unrelated changes. "Split this into logical commits" — Claude walks the diff, groups files by what belongs together, and stages group by group (falling back to git add -p for individual hunks if needed).

What I watch: push is always an explicit step. I instruct Claude to never push on its own — a commit is local and reversible, a push is publication.

Reverse gear: amend, restore, stash

The small fixes I used to look up the exact command for on Stack Overflow:

• "Add this to the last commit":

git add build.mjs
git commit --amend --no-edit

Amend rewrites history — it's only safe until the commit is pushed. Claude points that out on its own, but it's worth knowing.

• "Throw away the changes in serve.mjs":

git restore serve.mjs            # discard unstaged changes in the file
git restore --staged serve.mjs   # just unstage, keep the changes

• "Stash my work in progress, I need a hotfix":

git stash push -m "wip: new footer"
git stash list
git stash pop

One caveat: when git stash pop hits a conflict, it applies the changes but keeps the stash — on purpose, so you can't lose work. Once the conflict is resolved, clean it up yourself: git stash drop.

Since I started using worktrees, I stash less — see the next section.

Branches and worktrees

Creating a branch is trivial — "create a branch for the footer rework":

git switch -c feat/footer

The more interesting tool is worktrees: a second working copy of the repository on a different branch, in a sibling directory.

git worktree add ../project-fix fix/commission-rounding
git worktree list
git worktree remove ../project-fix   # once it's done

Why this matters with an AI tool: I can run two Claude Code sessions side by side — one building a feature, the other fixing a bug — and they never step on each other's files, because each works in its own directory. No branch switching, no git stash acrobatics.

Two things worktrees won't tell a newcomer: the same branch can't be checked out in two worktrees at once (git refuses — rightly so). And node_modules don't clone: every copy lives its own life, so git worktree add is followed by another npm install.

(Worktrees solve parallel work on one machine. Keeping one project — Claude Code context included — in sync across two computers is covered by One repo, two keyboards.)

Pull requests via the gh CLI

Claude Code talks to GitHub through the official gh CLI. One-time setup:

brew install gh            # macOS
winget install GitHub.cli  # Windows
sudo apt install gh        # Debian/Ubuntu
gh auth login              # one-time sign-in

After that:

create a PR against main, keep the description short

Under the hood:

git log main..HEAD --oneline   # which commits the branch brings
git diff main...HEAD           # the branch's full diff against main
git push -u origin feat/footer
gh pr create --base main --title "..." --body "..."

The PR description is generated from the actual diff of the whole branch against main, not just the last commit — so it stays accurate even after ten fix-up commits. The other direction works too:

fetch the review comments from PR #42 and address them

gh pr view 42 --comments                        # the discussion under the PR
gh api repos/{owner}/{repo}/pulls/42/comments   # inline comments in the code

Claude pulls the comments, goes through them one by one and tells you what it did with each. For comments it disagrees with, I want it to say so — not to comply blindly.

Reviewing someone else's PR — "check out PR #42 and walk me through it":

gh pr checkout 42   # the PR's branch into your local copy
gh pr diff 42       # a quick look without checking out

And the merge, once it's done — "merge PR #42 with a squash":

gh pr merge 42 --squash --delete-branch

I treat merge the same as push: it's publication, so I approve it explicitly.

Issues and CI

The section I left out of the first version of this cheat sheet — even though it's half of what gh does for me daily.

• "List the open issues labeled bug":

gh issue list --label bug --state open
gh issue view 12

• "File an issue for this" — mid-session, when I hit a bug I don't want to deal with right now:

gh issue create --title "..." --body "..." --label bug

Claude writes the description from the session context while it's fresh — so it's concrete: what happened, where, how to reproduce it. An issue filed this way is more useful than the one I'd write from memory three days later.

• "Why did CI fail on this branch?" — possibly the biggest time-saver in this whole cheat sheet:

gh pr checks                        # check status on the PR
gh run list --branch feat/footer    # recent workflow runs
gh run view 1234567890 --log-failed # the log of only what failed

Claude pulls the failure log, finds the cause and proposes a fix right away. No clicking through the web UI, no scrolling a mile-long log.

Reviewing your own diff before the PR

Before I open a PR, I have the diff reviewed locally first — it's cheaper than burning a colleague's time:

review this branch's diff against main — look for bugs and risks, not style

git diff main...HEAD

The three dots are not a typo: diffing against the common ancestor (merge-base) shows only what my branch introduced — not the changes that landed on main in the meantime.

The more specific the brief, the better it works: "focus on error handling", "look for race conditions", "check that no personal data gets logged". A generic "take a look" returns generic answers.

Rescue situations

This is where you find out whether AI helps you or hurts you.

• Merge/rebase conflicts — Claude resolves them, but I want to see the reasoning:

resolve the conflicts; for each file, tell me which side you took and why

git status                      # which files are in conflict
git checkout --ours file.js     # take our whole side
git checkout --theirs file.js   # take their whole side
git rebase --abort              # emergency brake: back to before the rebase

Most of the time, though, Claude edits the conflict blocks by hand — more precise than taking whole files from one side. (And mind the classic trap: during a rebase, the meaning of --ours/--theirs flips.)

• Revert — a safe operation, it creates a new commit and rewrites nothing:

git revert abc123

• Bisect — hunting the commit that broke something is finally painless with AI:

bisect to find the commit that broke the build; test with node build.mjs

git bisect start
git bisect bad                  # HEAD is broken
git bisect good v1.4            # it still worked here
git bisect run node build.mjs   # automated test at every step
git bisect reset

With git bisect run, the whole binary search runs without a single manual step — Claude just reads off the result and points at the culprit.

• Reflog — the last resort for "there was a commit here yesterday and now it's gone":

git reflog                    # a journal of everywhere HEAD has ever been
git reset --hard HEAD@{2}     # return to a specific state

Reading the reflog is safe. The reset --hard at the end is not — which brings us to the point: git reset --hard, force push, and branch deletion I do by hand, or at minimum I want Claude to explicitly ask before running them. Claude Code's permission settings support exactly that: I keep destructive commands on manual approval.

Quick reference

Conclusion

I don't understand git any less because of Claude — quite the opposite: without that understanding, I wouldn't catch it when it gets something wrong. I just don't type the commands I can dictate anymore, and the energy saved goes into checking the results. Git stays the same, it's just someone else doing the typing.

Why a PoC looks finished in a week

With a proof of concept, one thing is easy to forget: it performs on scenarios its author picked. Ten showcase cases go smoothly, the audience is impressed, and everyone feels all that's left is "just deploying it".

But a PoC usually runs on curated data, with no real permissions, no audit trail, and a human sitting next to it quietly fixing the small slips. You'll have none of that in production. A PoC answers the question "can this work?" — production asks what happens when it stops working.

Klarna showed what that difference looks like in practice. In February 2024 it announced that its AI assistant had handled two-thirds of customer-support chats in its first month — "the work of 700 people". A year later the CEO admitted the AI-driven cuts had gone too far, quality had dropped, and the company was hiring people again. The press release measured how many conversations the agent handled. How well — that only came up a year later.

What the enterprise adds

In a regulated environment, requirements show up that the demo never had to deal with:

• Audit trail. Every decision the agent makes has to be traceable: what it saw, why and how it decided, what it did. "The model judged it that way" won't satisfy an auditor or a regulator.
• Accountability. When the agent makes a mistake, it has to be clear in advance who's responsible and how it gets fixed. That's a process question — and you want the answer before you let the agent into production, not after the first incident. The courts already have an opinion on this: in February 2024 a Canadian tribunal made Air Canada pay for a discount its chatbot had invented. The airline argued the chatbot was "a separate legal entity that is responsible for its own actions" — the tribunal called that a remarkable submission and upheld the claim. It was 812 Canadian dollars, but the case has been cited ever since as a precedent: the company answers for its chatbot's output.
• Data governance. In a PoC it's convenient to let the agent see everything. In production, data access has to match purpose — a claims-handling agent has no business reading payroll data, even if it would improve its answers.
• Security. An agent is a new attack surface: inputs it trusts can be forged (prompt injection is just the best-known case), and the more actions it's allowed to take, the more damage a forged input can do. For a long time this was illustrated mostly by curiosities, like the dealership chatbot promising a Chevrolet Tahoe for one dollar. Then in June 2025 came EchoLeak: the first zero-click prompt injection against a production enterprise agent (Microsoft 365 Copilot, CVSS 9.3). One ordinary-looking e-mail in the inbox was enough — the agent pulled it into context on its own, and sensitive data leaked without the user clicking anything. Luckily, security researchers found it first.

And it's not just internal caution. Under the EU AI Act, AI used for risk assessment and pricing in life and health insurance lands straight in the high-risk category, with obligations from August 2026 (Brussels is debating a delay, but the direction stands). So a good part of the bullets above will sooner or later simply be the law.

Where the agent may act on its own

The most important design decision of the whole solution: which actions the agent may take on its own, and where a human has to be in the loop. I use a simple grid for this — two axes, reversibility and impact:

• Reversible + low impact → the agent acts alone (drafting a reply, categorising, preparing materials).
• Reversible + high impact → the agent acts, humans check samples and metrics.
• Irreversible + low impact → the agent prepares, a human confirms with one click.
• Irreversible + high impact → the agent only recommends; a human decides (paying out a claim, terminating a policy).

And that boundary isn't fixed. It pays off to start conservative and give the agent more authority as the production numbers come in — that's cheaper than starting bold and locking everything down again after the first incident.

The agent as a new participant in the process

Agents often get treated as just another system to "integrate". What works better for me is the picture of a new colleague: fast, never bored, but occasionally reading the assignment their own way.

That picture leads to the practical questions you'd ask about any new colleague: who assigns their work, and in what form? Who takes their output? How do they know they're out of their depth, and who do they tell? And what happens to the process when they just "don't show up for work"? A process with no answers to these questions isn't ready for an agent — no matter how good the agent is.

What to measure so you can say "it works"

Without metrics, the debate about an agent runs on anecdotes: one person remembers a brilliant answer, another remembers a disaster. This is the minimum set I want from day one:

1. End-to-end success rate — not "the agent replied" but "the case was handled correctly", measured by the same yardstick as humans. That's exactly where the McDonald's drive-thru AI ended: two years of testing across a hundred-plus restaurants, yet order accuracy sat around 80% by franchisees' accounts, against a target of 95. The viral video with 260 nuggets in one order was just the most visible case of it.
2. Escalation rate — how often the agent hands work to a human. A low number isn't automatically good news: an agent that never escalates probably can't tell when it's out of its depth.
3. Cost per handled case — including the cost of checking and fixing the agent's work. Leave those out and the number looks better than reality.
4. Correction trend — how many of the agent's outputs people had to redo, and how that develops. This is the number that moves the autonomy boundary from the previous section.

Conclusion

Deploying an AI agent in the enterprise mostly means deciding how much trust you'll give it: what it may do on its own, who answers for it, and how you measure that it works. The technology is more ready than most organisations think. What's usually missing are the processes, responsibilities and metrics.

Who needs the answer, and when

The question of which architecture is "better" can't be settled. It's more useful to ask who needs the answer, and when: when the caller can't continue without the result, you need a synchronous call; when the result matters "whenever it's ready", or matters to several consumers, you're in event territory. Most disputes end the moment people stop talking about technology and start talking about the process.

When a synchronous API

A synchronous call is the right choice when:

• The caller can't proceed without the answer. Checking a limit before confirming a deal, computing a price in a quote, verifying permissions. The waiting simply belongs to the operation.
• You want errors handled right away, in context. A synchronous call returns the error to whoever asked, the moment they asked — and they can react right away: fix the input, try again, tell the user.
• The flow should be readable. A chain of synchronous calls reads top to bottom and you see the order of steps at a glance. For processes where order and clarity matter, that's worth a lot.

The price you pay: coupled availability. Every link of a synchronous chain inherits everyone else's outages. Ten services at 99.9% availability in a row come out to 0.999¹⁰ ≈ 99.0% — nine hours of downtime a year just became eighty-seven. And the slowest link sets the pace for everyone.

And then there's the retry storm: a wave of repeated calls blows a small outage up into a big one. That's exactly what happened in the DynamoDB outage of September 2015 — the network recovered in moments, but the wave of synchronous retries kept the metadata service overloaded for almost five hours, and the cascade took SQS, CloudWatch and autoscaling with it. So it wasn't the network that decided how long the outage lasted — it was the architecture around it. And in October 2025 the same thing happened again in the same region, this time for fourteen hours.

When events

An event is the right choice when:

• More consumers care about the result. A closed policy matters to commissions, reporting, documents and marketing alike. Publishing one event beats calling four APIs — and a fifth consumer joins next time without you touching the source.
• The producer shouldn't know its consumers. An event says "this happened", not "do this". The source system doesn't have to change every time someone new wants the result. That's the main thing about the event-driven approach: system lifecycles come apart.
• Load spikes shouldn't pass through. A queue between producer and consumer spreads the surge over time instead of letting it cascade into the systems downstream.
• The process tolerates asynchrony. "Within a few seconds" is fine for most downstream steps — the business just has to know it and sign off on it.

The price this time is operational and mental: events are harder to debug. You don't see the process flow in a single trace, consistency is eventual, duplicate deliveries and dead letters (DLQ) show up. Without proper monitoring and idempotent consumers, the "modern architecture" turns into a system nobody understands.

One thing about duplicates that's better known in advance: at-least-once delivery is part of the contract. SQS and Stripe webhooks both say it plainly in their docs — every now and then the same message simply arrives twice. A consumer that answers a second delivery with a second commission payout has a design flaw; duplicates were to be expected. The fix is old and proven: an idempotency key — the same request with the same key runs once, no matter how many times it arrives.

The grey zone and hybrids

The real world rarely fits cleanly into one box:

• Request-reply over events — the caller posts a request to a queue and waits for a reply event. Your spikes get spread over time, but you pay with more complex correlation. Makes sense for long-running operations, not as a substitute for an ordinary call.
• Outbox pattern — when you need to write to your own database and reliably publish an event, write both in one transaction (the event into an outbox table) and leave publishing to a separate process. Solves the classic "written but never sent" problem.
• Synchronous reads, asynchronous writes — a common and healthy compromise: you ask for current state via API, changes get broadcast as events.

The price of each choice

Neither option is free — they differ only in where and when you pay:

Conclusion

The whole framework fits into three questions: who needs the answer and when, how many consumers there are, and what should happen during an outage. The answer to "API or event?" usually falls out on its own. And when two parts of a process each ask for something different, that's fine — they simply need different things.