​
Safe Git Collaboration With An AI Agent

guide2026-06-0210 min read

Treat Git state as shared state: inspect first, change narrowly, never erase unknown work, and deploy only the snapshot you intend.

codexgitworkflowcollaboration

​
Summary

AI agents are useful in Git repositories because they can read files, make edits, run tests, commit, push, and deploy. That same power can damage a project if the agent treats the working tree as disposable. The safe pattern is to inspect state before acting, separate user changes from agent changes, use narrow staging, avoid destructive commands unless explicitly approved, and verify both the commit and the deployed artifact. This note is the Git safety layer for Use Codex Goal For Long Tasks and Use Takenotes To Turn Debugging Into Blog Posts. /goal explains how to run long tasks; takenotes explains how to turn work into posts. This note explains how not to lose or miscommit work while doing that.

​
What This Solves

Long Codex sessions often happen in a shared working tree:
  • The user has local edits from another task.
  • Mintlify or another tool auto-formats files after validation.
  • A publishing script updates navigation.
  • A deployment command reads the current directory, not just the last commit.
  • The agent wants to “clean up” state before continuing.
Without rules, the agent can accidentally:
  • commit unrelated user changes;
  • deploy uncommitted files;
  • overwrite work it did not create;
  • hide a real problem with git reset or git clean;
  • remove ignored or untracked files that belonged to another task;
  • report that production is updated when only a preview build succeeded.
The working rule is simple: 
inspect -> isolate -> edit -> validate -> stage narrowly -> commit -> push -> deploy intended snapshot -> verify URL
Never treat a dirty worktree as permission to erase state. A dirty worktree is information to inspect.

​
Who This Is For

This is for anyone letting Codex or another coding agent modify a real repository, especially when the task includes writing blog notes, deploying to Vercel, editing LangFlow-related files, or running long /goal sessions. It assumes you know basic Git commands, but want a reliable collaboration protocol between a human and an agent.

​
Prerequisites

  • A Git repository with a remote branch.
  • Codex or another agent with terminal access.
  • A task boundary clear enough to identify which files should change.
  • Local validation commands, such as tests, git diff --check, or Mintlify checks.
  • A rule that destructive Git commands require explicit user approval.
Destructive commands include git reset, git checkout --, git restore, git clean, changing ignore rules, and deleting files. These can discard work the agent did not create.

​
The Workflow

1

Start every session by inspecting Git state

Before editing, run:
git status --short --branch
git diff --stat
git log -3 --oneline
This answers three questions:
  • Is the branch ahead, behind, or synced?
  • Which files are already modified?
  • What was the latest committed context?
If there are existing changes, assume they may belong to the user or another tool until proven otherwise.
2

Classify changes before touching them

Separate files into buckets:
BucketMeaningAction
Target changesFiles required for the current taskRead, edit, stage
Related generated changesTool output caused by this taskInspect before staging
Unrelated user changesExisting or unexpected workLeave untouched
Dangerous stateDeleted files, ignore changes, mass rewritesStop and ask
The key is not whether a change looks useful. The key is whether it belongs to this task.
3

Edit narrowly

Make the smallest set of edits that satisfies the task. In a blog workflow, this often means:
one note file
+ docs.json only if navigation changed
+ images only if the article actually references them
Do not improve surrounding files opportunistically unless they are required for the current article’s quality or safety.
4

Use validation before staging

Run task-specific checks before committing:
git diff --check
git status --short
For Mintlify notes:
python "$TAKENOTES_SKILL_DIR/scripts/strict_mintlify_check.py" \
  --config-dir "$BLOG_ROOT"
For privacy:
rg -n -f privacy-patterns.txt docs/notes
If a validator changes files, inspect the new diff before deciding whether those generated changes belong in the commit.
5

Stage explicit files, not everything

Avoid git add . during agent work unless the task truly owns the entire diff.Prefer:
git add docs/notes/2026/06/2026-06-02-example-note.mdx
git add docs.json
Then check the staged diff:
git diff --cached --stat
git diff --cached --name-only
A clean staging area is the last defense against unrelated commits.
6

Commit with a precise message

Good commit messages make later auditing easier:
git commit -m 'notes: refresh takenotes publishing workflow'
git commit -m 'notes: sanitize legacy private identifiers'
git commit -m 'notes: add guide "Safe Git Collaboration With An AI Agent" (2026-06-02)'
The message should say whether this is a new note, a refresh, a safety cleanup, or a formatting normalization.
7

Deploy the intended snapshot

Deployment tools often read the current directory, including uncommitted files. That can make a preview show changes that are not in Git.If the main worktree has unrelated uncommitted changes, deploy a clean snapshot:
git worktree add /tmp/blog-preview-$COMMIT_SHA $COMMIT_SHA
npx --yes vercel deploy /tmp/blog-preview-$COMMIT_SHA -y
This proves the committed snapshot builds, not just whatever happens to be in the current directory.
8

Verify preview and production separately

Preview and production are different evidence.
curl -I -L --max-time 30 \
  https://blog.example.com/docs/notes/2026/06/2026-06-02-example-note
A Vercel preview READY proves one deployment succeeded. A production HTTP/2 200 on the public domain proves the public site currently serves the page.

​
Destructive Command Policy

Use this table when deciding whether the agent can proceed autonomously:
Command Or ActionRiskPolicy
git status, git diff, git logRead-onlySafe
git add specific-fileStages known workSafe after inspection
git commitRecords staged workSafe if staged diff is checked
git pushPublishes commitsSafe if commit is intended
git resetCan discard or rewrite stateAsk first
git checkout -- fileCan discard changesAsk first
git restoreCan discard changesAsk first
git cleanCan delete untracked filesAsk first
deleting filesCan remove user workAsk first
changing .gitignoreCan hide future changesAsk first
If the agent needs a clean environment, create a clean worktree or temporary copy instead of cleaning the user’s current worktree.

​
Common Failure Modes

Committing unrelated files. This usually happens after git add .. Use explicit paths and inspect git diff --cached --name-only.
Deploying uncommitted changes. Vercel and similar tools may read the working directory. If the worktree is dirty, deploy from a clean worktree pinned to the intended commit.
Using destructive commands to fix confusion. If the agent is confused by local state, the right next step is inspection, not reset or deletion.
Ignoring generated diffs. Validation tools can rewrite files. Treat generated diffs like any other change: inspect, classify, and stage only if they belong to the task.
Reporting success too early. A commit hash, a preview URL, and a production HTTP/2 200 prove different things. Say exactly which one was verified.

​
Final Checklist

  • git status --short --branch was checked before editing.
  • Existing changes were classified as target, related generated, unrelated, or dangerous.
  • No destructive Git or file deletion command was used without explicit approval.
  • The diff only contains files that belong to the task.
  • git diff --check passed.
  • Privacy or secret scans passed when publishing public notes.
  • Staged files were inspected with git diff --cached --name-only.
  • Commit message describes the actual change.
  • Push succeeded.
  • Preview deployment was built from the intended snapshot.
  • Production URL was checked when public publication mattered.
  • Final summary mentioned any remaining unrelated worktree state.

​
What To Remember

Safe Git collaboration with an AI agent is mostly about respecting ownership. The agent can be fast, but it must not assume every file in the worktree belongs to the current task. Inspect first, stage narrowly, avoid destructive cleanup, and verify the exact snapshot that users will see.

​
Metadata

Quick Reference

Typeguide
Statuspublished
Date2026-06-02

Retrieval Tags

codexgitworkflowcollaborationsafety
Related
codex goaltakenotes publishing workflowvercel deployment