AI agents · Updated 2026-09-27

AI coding agent permissions for Git: read, propose, execute.

Give an AI coding agent explicit Git permissions instead of one broad “Git access” switch. Let it read the repository context it needs. Route consequential writes through a proposal that a human reviews before execution. Reserve direct execution for repositories and operations where you have deliberately accepted the blast radius. These are separate capabilities, and the boundary between them matters more than the agent model.

The three Git permission levels

“The agent can use Git” is too vague to review. It could mean reading git status, filing a proposed rebase, or force-pushing a shared branch. A useful policy names the capability, approval rule and failure boundary.

On a narrow screen, scroll the matrix horizontally.

Permission	What the agent can do	Human gate	Good default	Main risk
Read	Inspect status, refs, history, worktrees, diffs and recovery context without mutating Git.	No approval for each read.	Allow for authorized repositories and the minimum useful data.	Sensitive source, paths or history can enter the agent context.
Propose with approval	Create a structured request for a merge, rebase, reset, discard, patch, plan, worktree, commit, push or branch operation.	A person reviews the operation-specific impact, risk and available recovery context before it runs.	Use for meaningful Git writes, especially shared or destructive operations.	A rushed reviewer can approve a harmful proposal, or repository state can drift.
Direct execute	Run Git mutations without an approval gate, often through a shell or unrestricted tool.	None at execution time.	Limit to disposable or isolated environments with scoped credentials and tested recovery.	The command can alter history, destroy uncommitted work or propagate to a remote.

Why contain-after is weak for Git

Agent safety often starts with containment: grant write access, isolate the process, protect the main branch, keep backups and review the pull request afterward. Those controls still help, but they do not turn every Git mutation into a reversible event.

Git history is part of the artifact. A revert adds a new commit; it does not erase a secret from earlier history. A force-push can reach other clones before anyone notices. A hard reset or discard can remove uncommitted work that no commit contains. Reflogs and backups improve recovery, but their coverage depends on what existed before the mistake and where the mutation propagated.

Pull-request review also happens too late for several local operations. It can review committed code on a branch. It cannot restore an untracked file deleted before the branch existed, and it cannot explain a local rebase or reset that never reached the pull request. The strongest review point is immediately before the Git write, while the proposed operation and current repository state can still be inspected together.

Threats the permission model must cover

Wrong operation: an agent chooses reset when a branch or revert would preserve more evidence.
Wrong scope: a valid discard or commit includes more paths than the task requires.
History damage: a rebase, reset or force push rewrites commits another person already uses.
Credential propagation: a secret enters a commit and reaches a remote, where local undo is insufficient.
State drift: the worktree, HEAD or remote changes between reasoning and execution.
Misleading summaries: friendly copy hides the actual refs, paths, mode or force behavior.
Bypass: the MCP path requires approval while the same host grants an unrestricted terminal.
Incomplete evidence: logs are unsigned, truncated, deleted or treated as stronger proof than they provide.

An approval dialog is useful only when it exposes the operation itself. Review affected refs and paths, reset mode, push behavior, predicted conflicts, available recovery and any state mismatch. A generic “Allow?” prompt merely transfers the agent's ambiguity to the person clicking it.

How FluxGit implements the boundary

FluxGit's current MCP catalog contains 38 contracts: 25 read-only tools and 13 operation-handshake tools. Twelve operation.preview.* tools file proposals for merge, rebase, discard, reset, patch, plan, worktree, commit, push, branch, merged-branch deletion and submodule pointer operations. operation.cancel withdraws the same agent's pending proposal and never mutates Git. The proposal tools are not direct-write endpoints.

Reads do not require one approval per call. The open-source sidecar can perform standard local Git inspection without the desktop app, while FluxGit-powered context such as restore points and the Safety Timeline requires a configured app. A submitted write appears in the desktop approval flow with operation-specific impact, risk and available recovery context. Only an approved proposal runs through the guarded application path.

That boundary is deliberately narrow. FluxGit cannot revoke capabilities granted by another program. If Codex, Claude Code, Cursor or another host gives the agent a shell, the agent may run git push, git reset or any other permitted command outside FluxGit. Configure the host's terminal rules and credentials separately. A safe MCP route does not make an unrestricted shell safe.

Recovery and audit have limits

A restore point is evidence and a recovery handle, not a universal undo button. FluxGit can capture restore points for covered risky operations, and the approval view reports the recovery context available for the specific proposal. Some operations do not create a restore point. Remote propagation, deleted untracked data, expired reflogs and exposed credentials can also make complete restoration impossible.

FluxGit records operation outcomes in a chained audit log. Per-entry Ed25519 signing is optional: it is enabled only when a valid signing key is configured. Without one, new entries remain chained but unsigned. A chain can reveal edits, removals or reordering inside retained history; it cannot prove that the whole local history and its checkpoint were never replaced unless you also maintain an independently trusted external anchor.

FluxGit is a public beta. Treat preview, audit and recovery information as decision support, keep normal repository protections, and verify critical operations against the underlying Git state.

A copyable Git permission policy

Use this review template for an agent host, MCP configuration or team policy. It is documentation rather than a FluxGit configuration file; map each rule to the controls your host actually provides.

git_agent_permissions:
  repositories:
    allow: [/path/to/approved-repository]
  read:
    allow: [status, refs, history, diff, worktrees, recovery-context]
    per_call_approval: false
  propose_with_approval:
    allow: [merge, rebase, discard, reset, patch, plan, worktree, commit, push, branch]
    require_operation_preview: true
    require_current_state_check: true
    show: [paths, refs, risk, conflicts, remote_effect, available_recovery]
  direct_execute:
    allow: []
  shell:
    git_mutation: deny
  credentials:
    scope: minimum-required
    force_push: deny
  audit:
    record_outcome: true
    signing: optional-but-explicit
  recovery:
    verify_before_approval: true
    never_describe_as_universal_undo: true

For an isolated scratch repository, a team may intentionally allow direct execution. Record that decision with the repository scope, credentials, prohibited remotes, cleanup plan and expiry date. Permission should follow the environment and operation, rather than the agent's brand name.

Sources and verification

Product counts and limits were checked on 2026-09-27 against the public FluxGit MCP server repository. Git behavior is grounded in the official documentation for git reset, git revert and git reflog. The policy template above is guidance, not an MCP or FluxGit configuration format.

Questions about Git permissions for agents

Should an AI coding agent have direct Git write access?

Use direct Git execution only when the repository, credentials and failure impact make autonomous mutation acceptable. For shared branches, releases, force pushes, resets, rebases and destructive working-tree changes, require a human to review an operation-specific proposal before it runs.

Do read-only Git tools need human approval?

Usually no. Status, refs, history, diffs and recovery context can be exposed as read-only capabilities without asking a person to approve every call. Repository contents can still be sensitive, so scope the repositories and data the agent may inspect.

Can FluxGit stop an agent from running Git in a separate shell?

No. FluxGit controls operations submitted through its MCP proposal path. If the agent host separately grants a shell, the agent can run Git outside that path. Shell permissions must be restricted in the host as a separate control.

Does every approved FluxGit operation create a restore point?

No. FluxGit shows the recovery context available for the specific operation, and covered risky operations can capture restore points. Restore points are not universal, and some changes cannot be restored completely after they propagate outside the local repository.

Is the FluxGit audit log always cryptographically signed?

No. Audit entries are chained, but Ed25519 signing is opt-in. When no signing key is configured, new entries remain chained and unsigned. A local audit chain also cannot prove that the entire retained history was not replaced without an independently trusted external anchor.

Approve before it runs

The original argument for this page still holds: containment helps after a failure, but Git deserves a stronger boundary before consequential writes. Let the agent inspect enough context to be useful. Let it formulate a precise proposal. Give the person responsible for the repository the last decision before execution.

This model does not make the agent infallible or the repository invulnerable. It makes authority legible. You can see which operations are passive, which are pending human judgment and which bypass the gate entirely. That is a permission system a developer can actually review.