How to Keep an Agent's Working Notes Out of the Commit

Git has three ignore mechanisms, and they serve different audiences: .gitignore is committed and shared, .git/info/exclude is local to one clone and never committed, and a global file at ~/.config/git/ignore applies across every repository on the machine 4.

For agent notes you want the first two. .gitignore is the team-wide contract: it says "this repository expects a .agent/ directory and nobody commits it." .git/info/exclude is your personal belt-and-braces, useful when the agent invents a new filename pattern mid-task and you do not want to touch the shared file.

# .gitignore
# Agent working files: never commit
.agent/
.scratch/
*.agent.log

# .git/info/exclude
.agent/
.scratch/

Two details catch people out. First, a pattern like .agent/ matches the directory anywhere in the tree, which is usually what you want; if you only mean the root, anchor it with /.agent/. Second, ignore files apply to untracked files only. If .agent/plan.md was committed before you added the rule, Git will keep showing its modifications in git status forever, because the file is already in the index 4.

There is also a distinction teams miss: being ignored by Git does not make a file invisible to the agent. Many agents scan the filesystem directly rather than reading the Git index, and tools such as Cursor use a separate .cursorignore to control what gets indexed, independent of Git 5. Cursor's own users have reported that agent mode can read files that .gitignore excludes, which is why the maintainers discussed a separate hard-block mechanism 6. The practical consequence: ignore files keep notes out of the commit, but if the note contains a secret, an ignore file is not a security control. Keep secrets out of the notes directory entirely.

Global ignore is the wrong tool here. A rule in ~/.config/git/ignore protects you but not your teammates, and it silently changes behavior in unrelated repositories 4. Reserve it for OS cruft like .DS_Store.

Two commands cover almost every case, and both are cheap enough to run before each commit.

git status --short shows you untracked files with a ?? prefix. If a .agent/ path appears there, the ignore is not working: either the pattern is wrong, or the file is already tracked. git diff --cached --name-only lists exactly what is staged, and it is the authoritative answer to "what is about to go into this commit."

# What is staged right now?
git diff --cached --name-only

# Anything from the notes directory staged?
git diff --cached --name-only | grep -E '^\.(agent|scratch)/' && echo "BLOCKED: notes staged" && exit 1

When you cannot tell why a file is or is not ignored, git check-ignore -v names the file, the line and the pattern responsible 4:

$ git check-ignore -v .agent/plan.md
.gitignore:3:.agent/	.agent/plan.md

That output tells you whether the shared rule, your local exclude, or a global rule is doing the work, which is precisely the information you need when a teammate reports different behavior from yours.

A worked example makes the cost concrete. Suppose an agent writes a 40-line progress note after each of 12 steps, and the note is 2 KB. A 24 KB file inside a pull request is not catastrophic, but it does three things: it adds noise to review, it creates merge conflicts across branches, and it becomes a search result for anyone grepping the repository later. Multiply that by every agent run on the team and the diff stops being readable. The same argument applies to context budget: a bloated lockfile or coverage folder displaces the source the agent should be reading 5. Notes files are the same problem, from the other direction.

Ignore rules do not untrack. If .agent/plan.md is in the index, editing it will show up as a modification no matter what .gitignore says. The fix is one command, then a commit:

# Stop tracking, keep the file on disk
git rm --cached -r .agent/
git commit -m "Stop tracking agent working files"

After that commit, the ignore rule applies and the file stays on your disk but leaves the repository history, except for whatever was committed earlier. If the notes contain anything sensitive, removing them from the working tree is not enough: they remain in history until you rewrite it, which is a decision for the repository owner, not a routine cleanup.

git update-index --skip-worktree and --assume-unchanged are not substitutes. They are index hints for tracked paths, and Git documents --assume-unchanged as a performance optimization for expensive stat calls, not a way to hide personal edits 4. Using them to hide agent notes means a future git reset silently resurrects the file. To audit whether flags are already set in a repository you inherited:

git ls-files -v | grep '^[a-zS]'

Treat the output as a cleanup list. Uppercase S marks skip-worktree paths, and lowercase markers can reveal assume-unchanged entries 4.

Manual verification works until someone commits under time pressure. A pre-commit hook makes the rule mechanical. Keep the pattern in one place so the hook and the .gitignore cannot drift apart.

#!/bin/sh
# .githooks/pre-commit
PATTERN='^\.(agent|scratch)/'

staged=$(git diff --cached --name-only --diff-filter=ACMR)
if echo "$staged" | grep -qE "$PATTERN"; then
  echo "Refusing to commit agent working files:"
  echo "$staged" | grep -E "$PATTERN"
  echo "Move them to .agent/ (ignored) or unstage with: git restore --staged <path>"
  exit 1
fi

Enable it with git config core.hooksPath .githooks. The --diff-filter=ACMR flag limits the check to added, copied, modified and renamed paths, so deletions of stale notes do not trip the hook and block the very commit that removes them.

The hook should fail closed, and the error message should say what to do. Compare with the general advice on agent verification: give the agent a check it can run, such as tests, a build or a diff to compare, because without verification it stops when the work merely looks done 7. The same logic applies to the human side of the loop. The hook is the check that runs whether or not anyone remembered.

Put the pattern in a single file that both the hook and the ignore rule read, or at minimum keep a comment in .gitignore pointing to the hook, so a reader changing one knows the other exists.

Two agents in one working tree will collide over the same note paths. The solution is per-agent subdirectories keyed by a stable identifier, with one shared ignore rule covering all of them.

.agent/
├── fe-4821/
│   ├── plan.md
│   └── progress.log
└── api-9107/
    ├── plan.md
    └── progress.log

Keep the parent ignore rule as .agent/ so new subdirectories are covered automatically. Give each agent its own slug from the task or ticket identifier, and tell it in its instructions to write only under .agent/<its-slug>/. That prevents two agents overwriting each other's plan and makes cleanup trivial: delete the slug directory when the task closes.

For genuinely long autonomous runs, a sibling worktree is the cleaner boundary. Each agent gets its own checkout of the same repository, so the main tree stays clean and only finished, human-reviewed commits ever land there. The tradeoff is that the worktree has its own .gitignore-covered paths and its own index, so the pre-commit hook has to be installed in each one. If you use core.hooksPath, that configuration is per-clone, and a linked worktree shares the hooks directory of its parent, which is convenient but means a single hook applies everywhere.

Whichever model you choose, the instruction to the agent should be explicit about identity and location, in the same spirit as Anthropic's advice to be clear and direct and to give reasons for constraints rather than bare prohibitions 8. "Write your plan to .agent/fe-4821/plan.md; this file is ignored by Git so it will never reach a pull request, which is why it is the safe place for half-finished reasoning" is more likely to be followed than "do not commit notes."

If your team runs several agents across different model providers and wants a single place to drive them, that is the kind of setup Quanta Inference is built for: one OpenAI-compatible API key for text, image, video, audio and embedding models, with prepaid pricing in US dollars, so switching the model behind an agent does not mean rewriting the client. See https://quantaintelligence.ai/inference.

Before you hand a repository to an agent:

• Create .agent/ and add .agent/ and .scratch/ to .gitignore, plus .git/info/exclude for your own clone 4.
• Confirm nothing under those paths is tracked: git ls-files | grep -E '^\.(agent|scratch)/' should return nothing, and if it does not, run git rm --cached -r.
• Install the pre-commit hook and set core.hooksPath.
• Put the note location in the agent's persistent instructions, with the reason it exists 3.
• Decide whether note content may include secrets, and if not, say so, because Git ignore does not stop an agent from reading the file 5.
• Reserve one subdirectory per agent when more than one shares the tree.

The underlying principle matches the broader move from prompt engineering to context engineering: what the model sees and what the repository records are separate questions, and both need deliberate curation 1. Keeping working notes is good practice; keeping them out of the commit is what makes it safe practice.