Aura vs Git

Git tracks bytes. Aura tracks logic. Everything else follows from that one difference.

Aura is not a replacement for Git in the sense of "use one or the other." You can run both in the same repository, and in most adoption paths you will. Aura is a replacement for Git in the sense that it answers the questions Git cannot answer: what changed semantically, whose function is this, did the intent match the code, can three agents merge this cleanly. This page compares the two systems directly — where they overlap, where they diverge, and where each is the right tool.

The one-line difference

Git's primitive is the byte-addressed blob. Aura's primitive is the content-addressed logic node.

Everything else — diff behavior, merge behavior, rename tracking, identity stability, agent coordination, intent validation — is downstream of that one choice.

Side-by-side

| Dimension | Git | Aura | |-----------|-----|------| | Primitive | Byte-addressed blob | AST-normalized logic node | | Identity | Hash of file bytes | Hash of normalized syntax tree | | Diff | Line-level (Myers) | Node-level, cross-language | | Merge | Three-way text merge | Three-way graph merge | | Rename detection | Heuristic, post-hoc | Intrinsic (identity is content) | | Cross-file moves | Lost history | Preserved automatically | | Reformat noise | Appears in diff | Ignored (normalized AST) | | Commit metadata | Free-text message | Validated intent field | | Intent verification | None | Pre-commit hook compares intent vs AST changes | | Collaboration model | Push/pull commits | Push/pull commits + Live Sync function-level + Sentinel agent coordination | | Sovereignty | Distributed but forge-centralized | Self-hosted Mothership, P2P | | Agent coordination | None | Sentinel protocol, zone claims, cross-agent messages | | AI integration | Tool-by-tool | Native MCP server with 29+ tools | | Language scope | Language-agnostic (text) | Language-agnostic (tree-sitter) | | License | GPLv2 | Apache 2.0 | | First released | 2005 | 2024 |

The categories where the two systems look similar — distributed, language-agnostic, open source — are real similarities. The categories where they diverge are the ones that matter when AI is in the loop.

Worked scenario 1: a function is renamed

Under Git

Alice renames calculate_tax to compute_tax in billing.py. Her diff shows:

- def calculate_tax(amount, region):
+ def compute_tax(amount, region):
      rate = lookup_rate(region)
      return amount * rate

Git sees this as one line deleted and one line added. Rename detection is a heuristic that kicks in when the similarity between two text blobs crosses a threshold. For a one-line change to a function signature, the heuristic usually succeeds — but only at the file level. If Alice also moves the function to tax.py, Git's cross-file rename detection may or may not catch it depending on settings.

Bob, working in parallel, adds a new caller to calculate_tax in checkout.py. At merge time, Git merges Alice's rename cleanly (text-level), but Bob's new call site still references calculate_tax, which no longer exists. The code compiles red. Git didn't notice.

Under Aura

Alice renames the function. Aura computes the AST hash of calculate_tax before and after. The logic is identical, so the aura_id is unchanged. Aura records a rename event against that stable identity.

Bob, working in parallel, adds a new caller. Aura tracks the call edge to the aura_id of the function, not to its textual name. At merge time, Aura sees that one branch renamed a node Bob depends on. It has three options:

  1. Resolve automatically (same logic, call edge follows the node).
  2. Surface a cross-branch impact alert via aura_live_impacts before Bob commits.
  3. Ask the human if there is any ambiguity.

The merge succeeds. The code compiles.

Worked scenario 2: three agents refactor in parallel

Under Git

Agents A, B, and C are told, respectively, "add logging to auth functions," "extract repeated validation into a helper," and "standardize error types across the module." All three touch auth.py, all three reformat what they touch, all three rename or restructure similar call sites.

At merge time, Git sees three textual diffs overlapping in many of the same lines. The three-way merge produces conflict markers across dozens of hunks. A human — or another agent — now has to reconcile textual fragments that each represent a semantically coherent change. The conflict rate in this scenario, measured by AgenticFlict, is around 27%.

Under Aura

The three agents work in parallel. Sentinel sees collision risk on the same functions and surfaces it: aura_sentinel_agents lists the other active agents, and each agent can claim zones via aura_zone_claim. Assume they proceed anyway.

At merge time, Aura operates on the logic graph. Agent A added log statements inside four functions. Agent B extracted a helper and rewired four call sites. Agent C changed the error type of three raise statements. Most of these edits touch different logic nodes, and the merge is clean. Where two agents touched the same node, Aura produces a node-level conflict — not a hunk-level one — and surfaces a structured description: "Agent A and Agent B both modified the body of validate_credentials. A added a log call; B replaced a raise. Resolve."

The conflict surface area is smaller, more meaningful, and resolvable without reading through line-level diff markers.

Worked scenario 3: intent drift

Under Git

An agent is asked to "add a 5-minute cache to get_user_profile." It adds the cache. It also, while editing, notices that check_permission is called in three places with the same argument and "helpfully" extracts it to a module-level constant. The commit message says "add profile cache." The diff shows both changes.

The human reviewer reads the commit title, skims the diff, sees "+Cache()" and "+PROFILE_PERMISSION =," approves. The extracted constant has subtly changed evaluation order in one edge case. A bug lands in production six weeks later.

Under Aura

The agent calls aura_log_intent("Add 5-minute cache to get_user_profile for read performance.") and commits. The pre-commit hook runs. Aura computes the AST diff: one function body modified in get_user_profile (the cache addition), and one constant added at module scope plus three call-site modifications in check_permission.

The hook flags the commit: the stated intent describes a cache in one function, but the actual changes include restructuring in an unrelated function. The commit is blocked. The agent (or the human) must either narrow the commit, or log the broader intent, or revert the unrelated change.

The bug does not land.

Worked scenario 4: a file is moved

Under Git

You move utils/retry.py to retry/backoff.py. Git sees a delete and a create. Rename detection will usually connect them if the content is identical. If you also made any edits in the same commit, similarity drops, and Git may record two unrelated events. History is effectively broken — git log --follow gives inconsistent results depending on the similarity threshold and commit granularity.

Under Aura

Every function inside the file has a stable aura_id based on its AST. Moving the file — and optionally editing contents — changes no identities. The graph records a location change; history is intact; aura log on any function traces back through the move as a single continuous timeline.

Where Git is still the right tool

This page is not trying to argue Aura wins every dimension. Git still has clear advantages:

  • Maturity. Twenty years of tooling. Every CI system, every editor plugin, every deployment pipeline speaks Git.
  • Ecosystem. GitHub, GitLab, Bitbucket, the entire review culture.
  • Universality. Every developer on Earth knows some Git.
  • Binary files. Aura's logic model is irrelevant for PNGs, PDFs, and Parquet files. Git handles them fine; Aura defers to Git for them.
  • Text-only repos. A documentation repo or a dotfiles repo has no meaningful AST. Aura would be overhead.

The right answer for most teams in the transition period is both. Use Git for the text-and-binary side. Use Aura for the logic side. They coexist in the same working tree — .git/ and .aura/ side by side — and Aura does not disturb Git's object store.

Adoption path

Teams typically adopt Aura in four stages:

  1. Observe. Install Aura in an existing Git repo. Run aura status and aura diff. Watch the semantic diff against your normal Git workflow. No behavior changes yet.
  2. Validate intent. Enable aura log intent and the pre-commit hook on a single repo. Start catching intent drift without changing anything else.
  3. Coordinate agents. Turn on Sentinel when you start running multiple AI agents in parallel. Zone claims and collision detection begin paying back immediately.
  4. Go sovereign. Stand up a Mothership when the team is ready for real-time Live Sync and self-hosted coordination. At this point Aura is load-bearing; Git is now a serialization target.

There is no forced migration. You can stop at any stage and still get value.

Compatibility guarantees

Aura guarantees that:

  • Aura never modifies your .git/ directory.
  • Aura never rewrites commits Git has authored.
  • Aura's on-disk state is isolated in .aura/.
  • Any Git operation you run on the repo continues to work unchanged.
  • Aura can be disabled by removing .aura/ — your Git history is pristine.

This is a deliberate design choice. An era transition is easier when the new system does not demand the old system's removal. See Design Decisions for the rationale.

What Aura does not try to do

Aura does not try to replace:

  • Your code hosting forge (it complements one or replaces it with Mothership if you want).
  • Your code review tool (though it exposes structured data review tools can consume).
  • Your CI system (Aura hooks fit into existing pipelines).
  • Your editor or IDE (Aura is an engine; editor integration is separate).
  • Your language toolchain (tree-sitter does the parsing; nothing else changes).

It replaces the primitive — the unit of version control — and leaves the rest of your stack intact.

The bottom line

If your codebase is written and edited entirely by humans, at a human pace, and you have no agents in the loop, Git is fine. It will be fine for another decade. You do not need Aura.

If your codebase has three AI agents running in it today, or you expect it to by the end of this quarter, or your compliance regime requires intent auditing and sovereign hosting, Git is no longer fine. The substrate is wrong for the workload. Aura is what the substrate becomes next.

Next

Up next

Who Should Use Aura

Teams with AI agents, high merge-conflict churn, or sovereignty requirements.