Is it safe to let Claude run git commands on my repo?

Yes, with the discipline this playbook is built around: make it explain the state and what a command would do before it runs anything, and never let it run a destructive command (reset --hard, push --force, clean -fd) you don't understand. In Claude Desktop you approve each action, and the open folder is your boundary. Read-and-explain is always safe; anything that rewrites or deletes history gets a human's eyes first.

Should I rebase or merge to catch up with main?

It depends on who else has the branch. A feature branch only you have can rebase onto main for a clean, linear history. A branch others have already pulled is safer to merge, because rebasing rewrites commits they're building on. When in doubt, ask Claude to explain the trade-off for your specific situation and walk the steps — don't let it blind-run a rebase on a shared branch.

Can Claude write my commit messages?

Yes, and it's good at it — but you own the message. Have it draft a subject plus a body that explains why the change was needed, then read and adjust it before committing. A message that captures the why is what makes git blame useful later; "fix stuff" helps no one. Capture your team's commit convention in CLAUDE.md once and every draft follows it.

What about a merge conflict I don't understand?

That's exactly when you stop and make Claude explain it. Ask it to show both sides of the conflict — what main changed and what your branch changed — and what each was trying to accomplish, in plain English, not just diff markers. A conflict you can't read is one you shouldn't resolve yet; understanding it first is how you avoid silently dropping someone's work. A human owns the merge.

Untangle the git mess and commit in clean, logical chunks

when to reach for this

You looked up at 5pm and the working tree is a mess: a bug fix, a config tweak, and a half-typed feature all tangled in the same uncommitted changes, plus a merge you started this morning and never finished. The lazy move is git add -A && git commit -m "stuff" — one commit that mixes three concerns, a git blame your future teammates will curse, and a merge resolved by guessing. The discipline is the opposite: have Claude explain the state before it touches anything, then commit each concern on its own with a message that says why, so the history reads like a story instead of a landslide.

gather this first

The repo open in Claude Desktop — open the project folder so Claude can read the actual working tree, and approve each read in the 'Ask permissions' prompt. The open folder is your boundary.
The current state visible to you too: git status and the diff in front of you, so you can sanity-check Claude's read of it against your own eyes. (Power Track: git status / git diff in the terminal.)
A rough sense of which logical concerns are actually tangled together — the bug fix, the config change, the half-finished feature. You don't need it perfect; surfacing the split is step one.

the workflow

Make it explain the state — before it touches anything

The non-negotiable first move: understanding before action. Ask Claude to read the working tree and narrate it back in plain English — what's staged, what's unstaged, and what that half-finished merge actually is — and explicitly tell it not to run anything yet. You're checking its read against your own before a single command runs.

you ask

Read the working tree in this repo. In plain English, tell me what's staged, what's unstaged, what the in-progress merge is and which files still conflict — and how many distinct, unrelated concerns these changes actually represent. Don't run any git commands or change anything yet.

what you get back A plain-English map of the mess: "three concerns — a session bug fix in auth/, a config bump in .env.example, and a half-done feature in dashboard/ — plus an unfinished merge of main with two files still conflicting." Now you can act from understanding, not from a blind add -A.

"Don't run anything yet" is the load-bearing instruction. You never want a destructive git command to run before a human has read and agreed with the plan.
Group the changes into separate concerns

Now turn that read into a plan: which hunks belong to which concern. This is the part that makes the history readable — one commit per idea, not one commit per afternoon.

you ask

Group the unstaged changes into the separate logical concerns you just identified. For each concern, list the files (and the specific hunks, if a file spans two concerns) that belong to it, and suggest a one-line summary of what that concern is. Don't stage anything yet — just show me the grouping.

what you get back A clean grouping — concern by concern, the files (and partial-file hunks) under each, with a one-liner per group. Where a single file holds two concerns, it flags the split so you can stage by hunk, not by whole file.

If a file genuinely mixes two concerns, this is where you catch it — staging a whole file would smuggle the config tweak into the bug-fix commit.
Stage and commit each concern, reviewing every diff

Walk the groups one at a time. For each: stage just that concern, read the diff Claude shows you, then commit with a message that explains why, not just what. In Claude Desktop you see each change as a visual diff to accept or reject before it lands — read it, don't rubber-stamp it.

you ask

Let's commit the first concern — the session bug fix. Stage only those files, show me the diff to confirm it's just that change, then draft a commit message: a short subject plus a body that explains *why* the change was needed, not just what it does. Show me the message before you commit, and I'll approve.

what you get back One concern staged, its diff shown for you to confirm, and a commit message whose body answers why ("sessions expired early because the TTL was read in ms but set in s") — the context a future reader, or git blame, actually needs. Repeat for each remaining concern.

You approve every commit. Claude drafts and stages; you read the diff and own the message — small, logical commits that explain the why are what keep history reviewable.
Resolve the merge deliberately — understand each conflict

Back to the half-finished merge. The trap is letting it auto-resolve conflicts you haven't read. Make Claude explain both sides of each conflict and what each change was trying to do, then resolve with intent — never blind-accept 'theirs' or 'ours'.

you ask

Now the in-progress merge. For each conflicting file, show me both sides — what `main` changed and what my branch changed — and explain what each was trying to accomplish. Recommend a resolution for each and tell me which ones you're confident about and which need my call. Don't finalize the merge until I've signed off on every conflict.

what you get back A conflict-by-conflict walkthrough: both sides explained in intent, not just diff markers, with a recommended resolution and an honest "this one's your call" on the ambiguous ones — so you merge with understanding, not by accepting whatever the tool offered first.

A conflict you can't read is a conflict you don't resolve yet. Make it explain both sides until you genuinely understand the choice — a human owns the merge.
Draft the PR description — in the reviewer's language

Close the loop with a description your reviewer can actually act on: what changed, why, and how you tested it. On a bilingual team, write it in the language the reviewer reads — code stays English, but the PR description is for a human.

you ask

Draft a PR description for this branch: a short *what* and *why* at the top, a bullet list of the separate concerns (one line each, matching the commits), and a *how I tested it* section. Keep it tight and skimmable. [For a bilingual team: write it in Arabic so my reviewer reads it in their language — keep code, file names, and commands in English.]

what you get back A reviewable PR description — what/why up top, the concerns as a clean bullet list that mirrors your commits, and a tested-it section — ready to paste, in the language your reviewer actually reads.

The PR description is the pair to clean commits: this is the why for the whole change, where each commit body is the why for its piece. It pairs with the ship-a-feature and code-review playbooks — the other half of the loop.

make it your own

Rescue a branch that's behind main: ask Claude to explain rebase vs merge for your situation — a feature branch you alone own usually rebases cleanly for a linear history; a shared branch others have pulled is safer to merge. Have it walk the steps and explain each, never blind-run the rebase.
Interactive history cleanup (Power Track, with care): before review, you may want to squash noise or reword messages with git rebase -i. This rewrites history — only ever on a branch nobody else has pulled. Have Claude explain exactly what each line of the rebase plan does before you run it, and keep a git reflog lifeline in mind.
Capture a convention in CLAUDE.md: if your team uses a commit style (Conventional Commits, a ticket prefix, a body-explains-why rule), write it into the project's CLAUDE.md once. Then every commit Claude drafts follows your house style without you re-explaining it each time.

watch out for

Never hand it a destructive command you don't understand. git reset --hard, git push --force, git clean -fd, a blind rebase — these discard work that's hard or impossible to get back. Make Claude explain what it would do and what you'd lose before it runs anything that rewrites or deletes. Understanding before action is the whole rule of this playbook.
One commit that mixes three concerns is a `git blame` you'll regret. When a future you (or a teammate) bisects a bug to that commit, a tangled commit tells them nothing. Commit each concern separately — it costs two minutes now and saves an afternoon later.
A human owns the merge. Claude drafts, stages, and resolves; you read every diff and approve every commit and conflict resolution. You are the author of record on what lands — treat its output like a PR from a fast junior: usually right, occasionally confidently wrong.
Don't auto-resolve a conflict you can't read. Blind-accepting 'theirs' or 'ours' silently drops one side's work. If you don't understand both sides of a conflict, that's the signal to slow down and make Claude explain it, not to accept and move on.

you'll end up with A tangled working tree becomes a clean, reviewable history — each concern its own commit with a message that explains *why*, the merge resolved with understanding instead of guesswork, and a PR description ready for your reviewer. The next person to read `git blame` thanks you.

Questions people ask

Is it safe to let Claude run git commands on my repo?: Yes, with the discipline this playbook is built around: make it *explain the state and what a command would do before it runs anything*, and never let it run a destructive command (`reset --hard`, `push --force`, `clean -fd`) you don't understand. In Claude Desktop you approve each action, and the open folder is your boundary. Read-and-explain is always safe; anything that rewrites or deletes history gets a human's eyes first.
Should I rebase or merge to catch up with main?: It depends on who else has the branch. A feature branch only you have can rebase onto `main` for a clean, linear history. A branch others have already pulled is safer to merge, because rebasing rewrites commits they're building on. When in doubt, ask Claude to explain the trade-off for your specific situation and walk the steps — don't let it blind-run a rebase on a shared branch.
Can Claude write my commit messages?: Yes, and it's good at it — but you own the message. Have it draft a subject plus a body that explains *why* the change was needed, then read and adjust it before committing. A message that captures the *why* is what makes `git blame` useful later; "fix stuff" helps no one. Capture your team's commit convention in `CLAUDE.md` once and every draft follows it.
What about a merge conflict I don't understand?: That's exactly when you stop and make Claude explain it. Ask it to show both sides of the conflict — what `main` changed and what your branch changed — and what each was trying to accomplish, in plain English, not just diff markers. A conflict you can't read is one you shouldn't resolve yet; understanding it first is how you avoid silently dropping someone's work. A human owns the merge.