inspectread-only
Read-only tools
Expose repository status, fleet signals, diff context and recovery surfaces without granting mutation endpoints.
ai agents and git, governed · reviewed 2026-09-28
MCP context without handing over the controls.
FluxGit MCP exposes 25 read-only tools and 13 human-gated operation tools: twelve submit Git proposals and one cancels a pending proposal. The sidecar never executes a Git write itself. It sends an operation and reason to the desktop app, which shows an operation-specific preview, risk and available recovery context. Through FluxGit, the Git operation runs only after the user approves it.
How does FluxGit stop an AI agent from writing to Git directly?
FluxGit MCP exposes no direct mutation tool. Twelve operation tools create proposals and
the desktop app is the only route from a proposal to a Git write; a person approves or rejects there. If the
agent host separately gives the agent a shell, it can still run git outside MCP, so FluxGit states
that boundary and records externally observed pushes without pretending it controls the shell.
Current scope
The propose-approve loop is live and was verified end to end against a real MCP client, but it is beta software: interactive rebase is not yet supported in the handshake, and the result channel is a poll, not a push. What is shipped is tested; what is not is listed on this page.
What can an agent inspect through FluxGit MCP?
The 25 read-only tools include 15 free-shell tools, four hybrid tools with documented
local fallbacks, five safety and restore-point tools that require the app, and operation.status for an
accepted proposal. Every tool declares its tier instead of returning a guessed answer.
boundaryapp-controlled
Write boundary
Risky Git actions stay in the FluxGit desktop cockpit where previews, safety rails and human confirmation can apply.
trustaudit
Audit trail
Beta workflows can review what context agents requested, helping teams debug and set trust boundaries.
Which MCP tools work without the FluxGit app?
The protocol is open and so is the shell: fluxgit-hq/fluxgit-mcp-server on GitHub, Apache-2.0. It speaks MCP and works without the app for standard Git inspection. The tools that need FluxGit return an explicit upgrade hint, not a fake answer.
free shellopen source
Standard Git inspection
repo.brief, repo.scope, conflict.read (an active conflict as structured data: base, ours, theirs and marker regions), repo.status, repo.refs, repo.branchStack, repo.history, repo.reflog, commit.details, worktree.changes, worktree.list, submodule.status, diff.text, fleet.digest and agents.presence. Works locally with git and, for agents.presence, the local agent detector.
hybridgraceful fallback
Capability-negotiated tools
fleet.radar, diff.semantic, diff.semanticFallbacks, repo.conflictPreflight. Each returns documented fallback metadata instead of guessing. With the FluxGit app running, diff.semantic returns the real structural payload: per-file hunks with the changed tokens, plus an honest per-file fallback with the reason and text-diff arguments for files the engine cannot parse. Standalone, it answers with the honest fallback contract instead of pretending.
FluxGit-poweredrequires the app
Safety-grade tools
safety.timeline, safety.eventDetails, flux.latestRestorePoint, flux.restorePoints, flux.restorePointDetails. Return error code 10001 without FluxGit because synthesizing them from local refs would mislead the agent.
Built and live today.
Version control is shifting from a human authoring tool to a human governance layer over change written by machines. These are not plans; they are in the current build.
provenance
See what the machine wrote
Every agent-authored commit is flagged in the history with an AI badge and the detected signature — from commit trailers and author identity, never guessed. Approvals and executions land in an audit log you can sign with Ed25519.
governance
Approve intent, not clicks
Single operations and multi-step plans go through one approval card with risk copy. A plan captures the branch commit before its first step, and the completed card can restore that branch's HEAD and tracked files through the guarded reset flow. Step safety snapshots and Safety Timeline cover uncommitted work separately; this is not a full index, working-tree or untracked-file snapshot. A declarative policy can also reject out-of-policy proposals (wrong branch, forbidden operation, a repository path outside an agent's scope) before a card even opens, with rules per MCP client.
parallel work
Watch every parallel workspace
Linked worktrees — including agent worktrees — show up as badges on commits, as playhead rings on the graph, and as a cockpit strip with compare, reveal and open actions plus divergence against your checkout.
review at volume
Triage by risk, not by time
The Review Inbox in Review mode ranks pending agent proposals by destructiveness — a hard reset outranks a merge no matter which arrived first — with inline reject, and lists machine-authored commits with reveal-in-graph.
Agents that can see each other.
When several agents work on the same machine, each one should know what the others are touching before it proposes a change. FluxGit MCP gives them that context without giving any of them a new way to write.
presenceagents.presence
Who else is in this repository
The other coding agents working in one repository, how FluxGit knows (process, session log, editor or MCP), their branch and the files they are changing. The calling agent is excluded. Names are what each tool declares about itself.
activityfleet.digest
What changed across the fleet
Reflog moves of HEAD and local branches across repositories since a given time, newest first, with history rewrites flagged. Bounded, and limited to the allowed roots.
collisionsotherAgents
Overlap hints on every proposal
A proposal result can list other agents in the same repository and the paths they share with it. The hint is informational: it never blocks a proposal or changes the approval.
policyper agent
Rules per agent and per path
Policy rules can target one MCP client and narrow it to repository paths. Out-of-scope proposals are refused before a card opens. The client name scopes the rule; it is not authentication.
In the desktop app, pending proposals appear on their repository's row in Fleet Radar. FluxGit also detects agents working outside its MCP server from local processes, session logs and editor workspaces, places them on the commit graph where they are working, and flags an agent that is changing files with no proposal waiting.
What is mobile today, and what still comes next.
The private mobile preview can open authorized desktop terminals and show repository state. Approval authority remains on the desktop.
orchestrationshipped
Merge the winning attempt
This one graduated from the roadmap: when several agents try the same task in parallel worktrees, you compare the attempts from the cockpit strip, merge the winner through the guarded flow with a restore point, and the guarded cleanup removes the rest while never touching a worktree with uncommitted work.
mobile companionprivate preview
See repositories and authorized terminals from your phone
FluxGit Mobile has been exercised on Android and iPad with real desktop terminals. A Codex session has been operated from a phone, while approving or rejecting agent proposals remains a desktop action.
Built for your agent's context window.
An agent's scarce resource is context, not speed. repo.brief returns branch, status, recent history and worktree context in one typed response, reducing the separate orientation commands an agent needs. The read tools use bounded, structured answers designed for models, with explicit truncation and fallback metadata where applicable. See the reproducible benchmark, artifacts and counterexamples.
one callrepo.brief
Situational awareness in one call
Branch, ahead/behind, in-progress operation, working-tree summary, stashes, aggregated submodule drift, recent commits and next-step hints in one typed call.
diffdiff.semantic
Review behavior, not lines
With FluxGit running, the agent gets structural change data instead of treating every parseable change as raw text — and the tool says so honestly, per file, when anything falls back to text.
preflightrepo.conflictPreflight
Know the conflict before proposing
Merge-tree based what-if without fetch or mutation. The agent finds out whether a merge conflicts before it asks you to approve one.
multi-repofleet.radar
Watch a fleet without a fetch
One call summarizes which of your repositories need attention, including predicted upstream conflicts from cached refs. No remote is touched.
Tool surface.
Twenty-five read-only tools, twelve proposal tools (branch, commit, push, merge, rebase, discard, reset, patch, worktrees, multi-step plans, merged-branch deletion across repositories and submodule pointers), and operation.cancel, all labelled by tier. Git writes run only in the desktop app after you approve a proposal in FluxGit.
repo contextfree
Read the repo
repo.brief· one-call situational awareness: branch, ahead/behind, in-progress operation, working-tree summary, stashes, submodule drift, recent commits and next-step hintsrepo.scope· monorepo scoping: one subtree's changes, recent commits, churn and CODEOWNERS owners in a single callrepo.status· working tree, current branch, dirty pathsrepo.refs· branches, tags, remotes, stashesrepo.branchStack· current vs upstream/base/relatedrepo.history· paginated commit historyrepo.reflog· movement timeline with recovery hintscommit.details,worktree.changes,worktree.list,submodule.status
difffree + enhanced
Explain changes
diff.text· standardgit diffcompatible patchdiff.semantic· negotiated. Real structural payload (per-file hunks, changed tokens, truncation flags) when the FluxGit app is running; supported=false plus text-diff arguments standalonediff.semanticFallbacks· per-path fallback metadata, enriched with the same per-file reasons when the app is running
multi-repofree + enhanced
Cross-repo signals
fleet.radar· prioritized attention stack across selected repos. Cached refs only without FluxGit; predictive when gateway is wiredfleet.digest· reflog activity across repositories since a given time, history rewrites flaggedagents.presence· other coding agents working in one repository, from local sourcesrepo.conflictPreflight· advisory merge/rebase outcome before running, never mutatingconflict.read· an active conflict as structured data instead of raw markers
safetyFluxGit-powered
Recovery context
safety.timeline· synthesized risk events from restore points + reflogsafety.eventDetails· drill-down into one eventflux.latestRestorePoint,flux.restorePoints,flux.restorePointDetails· audit-grade undo/redo points
write-with-UI-handshake (NEW)Requested by AI
Agent proposes, you approve.
operation.preview.commit· message plus the exact file list that will be staged and committed, shown before anything is writtenoperation.preview.push· remote, branch and upstream intent surfaced; force-with-lease is flagged high risk before you approveoperation.preview.branch· create a branch (optionally checked out) — non-destructive, and the card says so honestlyoperation.preview.merge· agent proposes a merge; FluxGit renders the approval cardoperation.preview.rebase· rewrites-history warning surfaced in the cardoperation.preview.discard· irrecoverable-warning card with path listoperation.preview.reset· mode-aware (hard mode forces strong confirmation)operation.preview.patch· monospace patch preview with applyToIndex toggleoperation.preview.worktree· add a parallel worktree so agent work never disturbs your checkoutoperation.preview.plan· a 1-10 step sequence reviewed and approved as one unit; execution stops at the first failure and reports per-step resultsoperation.preview.branchDelete· delete a merged local branch in one or more repositories; the card inspects each one, needs explicit confirmation and records every tip for restoreoperation.preview.submodulePointer· record a drifted submodule pointer in its parent, or return the submodule to it, with a restore pointoperation.cancel· the agent withdraws its own pending proposal;operation.status(read-only) polls the outcome
The agent dispatches a proposal through the gateway; FluxGit shows a "🤖 Requested by AI agent" card in the desktop cockpit with the agent's plain-language reason. You approve or reject; FluxGit executes through the operation's existing safety path. Where that operation creates a restore point, the completion result exposes it; additive operations instead report their actual branch, commit, push or worktree outcome. The agent can report the real result and recovery boundary without guessing, but never holds write power.
What happens after a person approves a Git operation?
FluxGit executes the accepted proposal through the same guarded operation path used by the desktop app, records the result in the audit stream, and returns the actual branch, commit, push or worktree outcome. When that operation creates a restore point, the completion result includes it. Additive operations report their real outcome without claiming a restore point that was not created.
Semantic diff with explicit fallback.
Agents lie when they describe a patch as "semantic" without a semantic payload behind it. The contract makes that impossible: diff.semantic only returns supported: true when the FluxGit engine produced structural output. With the desktop app running it does exactly that: per-file hunks with the changed tokens, an honest per-file fallbackToText with the reason and ready-to-use text-diff arguments for files the engine cannot parse, and explicit truncation flags on large diffs. Standalone, it returns the arguments the agent should pass to diff.text as a text-diff fallback, and a precise reason.
Agents connected to FluxGit MCP must say "FluxGit reported a text-diff fallback for this file" when supported=false, never "this is a semantic diff". The wording is published as a contract; we treat over-claiming as a bug.
Honest by protocol
No silent fallback. No fake structure inferred from a text patch. If the file fell back, the agent surfaces which path and why. Senior engineers notice this; it's why we wrote it down.
Does FluxGit work with Codex, Claude Code, Cursor, and local models?
FluxGit works with Codex, Claude Code, Cursor, and a local model when the application running the model can launch a local stdio MCP server. MCP compatibility belongs to the host, not to the model weights: Ollama or Llama alone are not an integration claim. The host can call 25 read-only tools; twelve operation.preview.* tools submit Git proposals and operation.cancel withdraws a pending proposal. FluxGit's sidecar does not execute Git writes. The desktop app shows the proposal's reason, impact, risk and available recovery context, and a person approves or rejects it. Claude Code and Cursor have detected setup paths; Codex uses the generic MCP configuration. A local-model workflow uses that same generic configuration only when its host supports MCP. If the host also grants a shell, the agent may run git outside FluxGit, so that separate permission remains outside the MCP approval boundary.
Connect any MCP-compatible agent.
FluxGit MCP is protocol-aligned, not vendor-aligned. Install the published Apache-2.0 crate, then paste the block below into a compatible host that can launch a local stdio MCP server. The server is also listed in the official MCP Registry. The desktop app pre-fills the absolute sidecar path and gateway address from the running process.
cargo install fluxgit-mcp-sidecar --locked{
"mcpServers": {
"fluxgit": {
"command": "<absolute path to fluxgit-mcp-sidecar bundled with FluxGit>",
"env": {
"FLUXGIT_MCP_HANDSHAKE_ADDR": "<auto-filled, e.g. 127.0.0.1:59647>",
"FLUXGIT_MCP_AUDIT_LOG": "<optional path to a JSONL audit file>"
}
}
}
}Works with any MCP-compatible code agent. No client-specific install required.
Shipped 2026-05-28
What happens after you approve an agent's Git proposal?
An operation.preview.* call submits a proposal and normally returns promptly with accepted: true, its previewId, current status and a next action pointing to read-only operation.status. The FluxGit desktop app shows the approval card. After a person approves or rejects it, the client polls operation.status until the proposal reaches a terminal state.
Only completed reports a successful Git outcome. Rejected, failed, expired and cancelled proposals return structured errors. The audit stream records the proposal lifecycle and outcome, including approval, rejection, cancellation, failure or expiry. Restore-point metadata appears only when the approved operation captured one.
The moat
Cloud-hosted MCP servers without an app cannot do this. FluxGit can because the approval UI lives in the desktop cockpit. It's the structural reason FluxGit-powered tools require FluxGit.
Privacy and security posture.
MCP can expose sensitive repository facts to a connected agent, so the boundary must be explicit. FluxGit gives agents no direct Git mutation endpoint: each requested Git mutation is a proposal that a human approves in the app. Semantic diff fallback is labeled, fleet status never fetches aggressively on an agent's behalf, and AI/provider data sharing is a separate user-controlled decision. The audit log hashes arguments rather than storing them verbatim.
Related features.
- Fleet Radar gives agents a read-only attention stack across selected local repos.
- Semantic diff gives structural context when supported and fallback labels when not.
- Safety rails keep write decisions in the guarded desktop workflow.
- Reflog recovery explains the recovery surface agents can inspect without changing Git.
- Agent setup: Claude Code, Cursor and Codex.
- Learn what a Git MCP server is, then follow the generic setup guide.
- From the blog: AI agents and Git, without handing over the keys, Your agent's context window is the new CPU and Submodules are where agents go to die.
Parallel agent work.
Use one Git worktree and branch per coding-agent task to separate checked-out files, then compare attempts before proposing the merge. Worktrees reduce collisions; the FluxGit proposal boundary governs supported Git writes made through its MCP. The GitKraken comparison shows how that boundary differs from a direct-write MCP and worktree-based agent sessions.