How to Give a CLI Agent Access to Your Repo

How much of your repository should an AI agent actually be allowed to see and touch? It's the question you hit the moment you go from "watching an agent edit one file" to "letting it work across a real project," and most guides skip right past it. They tell you to

cd

Here's a composite case, drawn from patterns that recur, to show where it goes wrong and how to set it up properly.

The Problem a Platform Team Faced

A platform team at a fintech — call them the infra crew — wanted an agent to help maintain a large services monorepo. They did what the quick-starts said: pointed the agent at the repo root, gave it write access, and asked it to update a shared logging library used by twelve services.

[object Object], services-monorepo
claude --permission-mode acceptEdits   ,[object Object],
> update the logging library to redact PII ,[object Object], all callers

What this does: Starts the agent with edit access across the entire monorepo and a task that spans a dozen services. It sounds efficient. It's also the moment the blast radius went from "one library" to "everything."

Two things went wrong. The agent read

.env

The Wrong Approach

The wrong model is "the agent needs to see everything to help with anything." It's the same instinct that makes people

/add

[object Object],
git ,[object Object], git@github.com:co/services-monorepo.git
,[object Object], services-monorepo && claude --permission-mode bypassPermissions

What this does: Clones the whole monorepo and runs the agent with no permission gates over all of it. Every secret, every unrelated service, every generated artifact is now in scope. This is the pattern to avoid.

⚠️ Common mistake: Assuming your repo has no secrets in it. Most mature repos have something committed that shouldn't be — an old

.env

The Correct Approach to CLI Agent Repo Access

Three moves turn the infra crew's setup from dangerous to safe.

First, exclude secrets from the agent's view explicitly. Don't rely on the agent's discretion — put sensitive paths on an ignore list the tool respects, the same way

.gitignore

[object Object],
.,[object Object],
.,[object Object],.*
**/secrets/**
**/*.pem
config/credentials.yml

What this does: Tells the agent to treat these paths as invisible. Even if you point it at the repo root, it won't read your credentials into context. This is the single most important step, and almost every tutorial omits it.

Second, start read-only and earn write access. Open in plan or ask mode, let the agent propose the change across the twelve services, and read the plan before a single file changes.

cursor-agent --mode plan
> show me every ,[object Object], of the logging library you,[object Object]

What this does: Runs the agent read-only. It maps the change and lists affected callers without editing anything, so you see the true blast radius before granting write access. If twelve services is too much to review at once, you find out now, for free.

Third, scope write access to a worktree, not the live checkout. Cursor's CLI can run a session in its own Git worktree — a separate working directory on the same repo — so the agent's edits land in an isolated branch you review before merging.

[object Object],
git worktree add ../agent-logging -b agent/logging-pii
cursor-agent  ,[object Object],

What this does: Gives the agent a dedicated working directory on a throwaway branch. Its changes never touch your main checkout, and you review a clean, contained branch before it goes near

main

⚡ Pro tip: Add a

CLAUDE.md

/proto

/migrations

The Monorepo Special Case

Everything above gets harder in a monorepo, and monorepos are exactly where teams are most tempted to point an agent at the root and hope. The problem is scale: a monorepo might hold fifty services, and giving an agent access to all of them to work on one is the broadest possible grant for the narrowest possible task.

The fix is to scope the agent to a subtree, not the whole tree. Most tools let you launch from a subdirectory, and Git's sparse-checkout lets you materialize only the paths you're working on, so the agent literally cannot read services it has no business touching.

[object Object],
git sparse-checkout ,[object Object], services/billing libs/shared
,[object Object], services/billing
claude   ,[object Object],

What this does: Narrows the working tree to one service and its direct dependency, so the agent's entire view is the code relevant to the task. The other forty-nine services aren't excluded by a rule the agent might route around — they physically aren't on disk.

The dependency question is the subtle part. A change to a shared library in a monorepo can ripple into every consumer, so "scope to the subtree" has to include the callers you might break. That's where the read-only-first habit earns its keep twice over: you ask the agent to map every consumer of the shared code before you scope the write, so you know the true blast radius isn't hiding in a service you sparse-checked out of view.

⚡ Pro tip: In a monorepo, run the agent's read-only mapping pass against the full tree, then do the write pass against the narrow sparse checkout. You want maximum visibility when discovering what a change affects, and minimum surface when actually editing. Splitting those two phases across two different scopes is the move most people miss.

⚡ Pro tip: Keep a per-directory project file in large monorepos, not just one at the root. A

CLAUDE.md

services/billing

Results and What Changed

The infra crew's second attempt looked completely different. Secrets were on the ignore list, so the agent never saw a credential. It ran read-only first, listed all twelve callers, and the team decided to split the work into three reviewable batches of four services instead of one twelve-service sweep. Each batch ran in its own worktree branch. The reviewer could actually read each diff.

The change that mattered most wasn't a tool feature — it was sequencing. Read-only first surfaced the real scope before any risk was taken. That one habit converted a scary "update everything" task into three boring, reviewable ones.

git diff main..agent/logging-pii --,[object Object],   ,[object Object],
git merge --squash agent/logging-pii       ,[object Object],

What this does: Shows exactly what the agent changed on its isolated branch, then merges it as a single squashed commit after review. The agent did the work; the human owned the merge.

⚡ Pro tip: Grant access in the order read, then propose, then write — never all three at once. Most repo-access disasters happen because write access came before anyone understood the scope. Reverse the order and the scary surprises turn into cheap read-only discoveries.

How to Apply This to Your Situation

A solo developer on a personal project: you can be looser, but still add an ignore list for any

.env

git diff

A security engineer at a regulated company: run the agent against a local model on the sensitive repos so code never leaves your network, keep a strict ignore list, and require every agent change to land through a worktree branch and PR review.

An open-source maintainer accepting agent-assisted contributions: require contributors to run agents in isolated worktrees and submit squashed, reviewable diffs — never a forty-commit stream from an agent that had full repo access.

A machine-learning engineer working in shared notebook repos: notebooks are a special hazard because they often have outputs — sometimes including printed credentials or sample data — committed inline. Add

*.ipynb

Next Steps

Safe cli agent repo access is a sequence, not a switch: exclude the secrets, start read-only, propose the change, then grant scoped write access in an isolated worktree. The infra crew didn't need a different tool — they needed to stop handing the agent everything at once.

The ignore lists, the off-limits directory rules, the read-then-write sequence — these are identical across every repo you'll ever set up. Save them in PromptABCD so your next project starts with the guardrails already written instead of learning them the way the infra crew did.