Aura Docs

Aura Documentation

The semantic version control engine for the AI era. Aura tracks logic at the AST level, coordinates AI agents in real time, and runs entirely on your infrastructure. 120 pages across twelve modules.

12 modules
120 pages
Start reading
Part 1

Introduction

What Aura is, why it exists, and why semantic version control is the next paradigm after Git.

  1. What is Aura?

    A semantic version control engine for the AI era. Tracks logic, not text.

  2. Why Aura Exists

    Git was built for humans. AI writes 80% of new code. Text diffs can't keep up.

  3. The Third Era of Version Control

    CVS → SVN → Git → Aura. Each era solved a paradigm the last couldn't.

  4. Aura vs Git

    Text-diff vs AST-diff. Blob-hashing vs content-addressed logic. Where the two differ.

  5. Who Should Use Aura

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

  6. The Aura Philosophy

    Code is logic, not text. Intent is sacred. Sovereignty is non-negotiable.

  7. Mission and Roadmap

    Where Aura is going: from CLI to standard infrastructure for AI-native engineering.

  8. Core Principles

    Seven principles that guide every design decision in Aura.

  9. How Aura Works (High Level)

    Tour of the engine: AST parser, merge engine, Sentinel, Mothership, MCP server.

  10. Key Design Decisions

    Why Rust, why tree-sitter, why P2P, why open source.

Part 2

Quickstart

Install Aura and ship your first semantic commit in under ten minutes.

  1. Install on macOS

    Homebrew, curl installer, and verifying your install on Apple Silicon and Intel.

  2. Install on Linux

    Debian, Ubuntu, Arch, Fedora, and manual binary installation on Linux.

  3. Install on Windows

    Native Windows install via Scoop, Chocolatey, and WSL2 paths.

  4. Run Aura in Docker

    Official container image, volume mounts, and running Mothership in Docker.

  5. Build from Source

    Cloning the repo, cargo build, and contributing your first patch.

  6. Initialize Your First Repo

    aura init, git-compatibility mode, and understanding the .aura directory.

  7. Your First Commit with Intent

    Why intent logging matters and how to write a good intent message.

  8. Understanding `aura save`

    The command that does everything: snapshot, intent, commit, push.

  9. Connect to Your Team

    Join a Mothership with a single token and start syncing in real time.

  10. Install Troubleshooting

    Common errors, permissions, PATH, hook installation, and how to recover.

Part 3

Core Concepts

The mental model behind Aura: ASTs, semantic identity, intent, and the Sentinel.

  1. Semantic Diff

    Why diffing ASTs is more accurate than diffing text, with concrete examples.

  2. AST Merge Explained

    How Aura merges two branches by walking the abstract syntax tree.

  3. Function-Level Identity

    Every function has a content hash that survives renames and moves.

  4. Intent Tracking

    How Aura captures the 'why' behind every change and prevents intent poisoning.

  5. Shadow Branches

    Aura's parallel semantic branches that mirror git branches without polluting them.

  6. Content-Addressed Logic

    Logic nodes are addressed by their semantic content, not by file + line.

  7. Rename-Proof Identity

    Why renaming a function does not break its history or references in Aura.

  8. Snapshots vs Commits

    The difference between an Aura snapshot and a git commit, and when to use each.

  9. The Session Model

    How Aura groups work into sessions for coherent history and rewind.

  10. The Pre-Commit Hook

    What Aura's hook actually does, in strict and non-strict mode.

Part 4

CLI Reference

Every Aura command, with flags, examples, and common patterns.

  1. aura save

    The all-in-one command: snapshot, intent log, commit, and push in one shot.

  2. aura merge

    Semantic merge. Flags, conflict handling, and differences from git merge.

  3. aura pull

    Pull function-level changes from teammates with AST-level conflict resolution.

  4. aura push

    Push your changes to the Mothership or a git remote with intent metadata.

  5. aura rewind

    Surgically revert a single function to a previous state without touching anything else.

  6. aura trace

    See every change to a function across the entire history, across renames.

  7. aura prove

    Mathematically verify that a behavioral goal is implemented correctly.

  8. aura diff

    Semantic diff: added, removed, and modified logic nodes with context.

  9. aura status

    Tracked logic nodes, active session, team sync status, and pending pulls.

  10. aura doctor

    Diagnose a broken repo: stuck sessions, orphaned snapshots, missing hooks.

Part 5

Semantic Merge Engine

How Aura merges every file type with the right granularity.

  1. How AST Merge Works

    Step-by-step walkthrough of the three-way AST merge algorithm.

  2. JSON Deep-Merge

    How Aura merges JSON by key path instead of line, and how to configure it.

  3. YAML Merge

    Preserving comments and anchors while doing deep structural merges.

  4. Environment File Merge

    Per-key merge for .env files with secret detection and masking.

  5. Conflict Resolution

    When Aura flags a true conflict, how to resolve it, and how to configure defaults.

  6. Interactive Conflict Picker

    The terminal UI for picking yours, theirs, or a merged version interactively.

  7. Merge Strategies

    Prefer-ours, prefer-theirs, semantic-union, and custom strategy configuration.

  8. Cross-Language AST Support

    Rust, TypeScript, Python, Go, Java, and how languages are added to Aura.

  9. Tree-Sitter Integration

    How Aura uses tree-sitter grammars for language support and parse accuracy.

  10. Limitations and Edge Cases

    When Aura falls back to text merge and why that's still safe.

Part 6

Mothership Mode

Self-hosted P2P team hub. Code stays on your network.

  1. Mothership Overview

    What the Mothership is, why it exists, and why it runs locally.

  2. Starting a Mothership

    aura mothership start, choosing an interface, and verifying connectivity.

  3. Join Tokens and Security

    How join tokens work, expiration, rotation, and revocation.

  4. TLS and JWT

    Automatic TLS cert generation, JWT auth, and how peers verify each other.

  5. P2P Architecture

    Why Aura is peer-to-peer, not client-server, and what that means for your data.

  6. Team Topology

    Star, mesh, and hub-and-spoke patterns for different team sizes.

  7. Offline Mode

    Keep working when the Mothership is unreachable and reconcile on reconnect.

  8. The Persistent Daemon

    How the Mothership survives reboots and auto-reconnects on network changes.

  9. Scaling the Mothership

    Teams of 5, 50, and 500 — configuration patterns and hardware guidance.

  10. Mothership Troubleshooting

    Port conflicts, firewall issues, TLS failures, and common fixes.

Part 7

AI Agent Coordination

The Sentinel: how Aura coordinates Claude, Cursor, Gemini, and Copilot on the same codebase.

  1. Sentinel Overview

    The agent coordination layer. What it watches and when it intervenes.

  2. Agent Collision Detection

    How Aura detects when two agents are editing the same function.

  3. Zone Claims

    Agents stake out territory. How claims work, expire, and conflict.

  4. The Agent Inbox

    Agents message each other. The protocol, use cases, and replies.

  5. Knowledge Sharing

    Agents share discoveries across sessions via the team knowledge base.

  6. Claude Code Integration

    MCP server, CLAUDE.md protocol, and hooks for Claude Code.

  7. Cursor Integration

    .cursorrules, MCP, and making Cursor aware of Aura's semantic state.

  8. Gemini CLI Integration

    GEMINI.md, intent logging from Gemini, and shared context.

  9. Copilot Integration

    How Aura works with GitHub Copilot and Copilot Workspace.

  10. Multi-Agent Workflows

    Patterns for running 3+ agents concurrently without stepping on each other.

Part 8

Live Sync & Real-Time

Function-level real-time sync. Google Docs, but for code.

  1. Live Sync Overview

    What real-time function sync is and when to use it.

  2. Function-Level Sync

    Why Aura syncs at the function level, not the character or line level.

  3. Cross-Branch Impact Alerts

    Getting notified when a function you depend on changes on another branch.

  4. Sync Conflicts

    How live-sync conflicts are surfaced and resolved.

  5. WAL Architecture

    The write-ahead-log that makes live sync durable and crash-safe.

  6. Bandwidth and Performance

    How much data Aura pushes, compression, and tuning for slow networks.

  7. Selective Sync

    Only sync specific directories, files, or functions. Patterns and config.

  8. Presence and Cursors

    See who is editing what, in real time.

  9. Sync Troubleshooting

    Stuck syncs, stale state, and how to force-reconcile.

  10. Live Sync and Privacy

    What gets synced, what stays local, and how to audit the traffic.

Part 9

Integrations & Ecosystem

MCP, IDEs, CI/CD, and every other system Aura plugs into.

  1. MCP Server

    Aura's Model Context Protocol server exposes 29+ tools to AI agents.

  2. CLAUDE.md Protocol

    The canonical way to teach Claude about your Aura-aware repo.

  3. GitHub Integration

    PR reviews, checks, and pushing Aura intent into GitHub.

  4. GitLab Integration

    Self-hosted GitLab and GitLab.com integration patterns.

  5. IDE Integrations

    VS Code, JetBrains, Vim, Emacs, and Zed extensions.

  6. CI/CD Integration

    Running aura prove and aura pr-review in CI pipelines.

  7. Slack & Discord Webhooks

    Push Mothership events and intent logs to chat.

  8. Linear & Jira

    Tie intents to tickets. Automatic status updates.

  9. Aura HTTP API

    The REST API for integrating Aura with anything.

  10. Writing Custom Plugins

    How to extend Aura with your own commands and hooks.

Part 10

Enterprise & Self-Hosting

Deploy Aura at scale with compliance, audit, and air-gapped options.

  1. Enterprise Overview

    Features, SLAs, and what Aura offers beyond the open-source CLI.

  2. Self-Hosted Deployment

    Running the Mothership on your own infrastructure at scale.

  3. Air-Gapped Install

    Installing Aura on networks with no internet access.

  4. Compliance and Audit

    SOC 2, ISO 27001, and HIPAA-ready audit trails out of the box.

  5. RBAC and Permissions

    Role-based access control, team roles, and zone-level permissions.

  6. EU Data Sovereignty

    GDPR, Swiss hosting, and keeping code inside your legal jurisdiction.

  7. Migrating from Git

    Moving a 10-year git repo to Aura without losing history.

  8. Backup and Recovery

    Protecting the Mothership and restoring from catastrophic loss.

  9. Performance Tuning

    Cache sizing, thread pools, and profiling a busy Mothership.

  10. Enterprise Support

    How to reach Naridon, SLA tiers, and professional services.

Part 11

Engineering Reality & Tradeoffs

Where Aura is honest about what's solved, what's research, and what Git still does better.

  1. Aura Is Not a Git Killer

    Why we chose Git-compatibility over replacement. How Aura sits on top of Git and what that buys you.

  2. Code Is Not Figma

    Why real-time character-level editing breaks code. How function-level sync sidesteps the correctness problem.

  3. The Silent Conflict Problem

    Real-time systems risk silent merge bugs. How Aura flags, defers, or halts on ambiguity instead of guessing.

  4. CRDT vs AST Merge vs Git Hybrid

    The three architectural choices for real-time code. Why Aura picked AST-aware merge over CRDTs.

  5. Offline, Reproducibility, and Deterministic Builds

    What Git gives you that real-time systems often break. How Aura keeps reproducibility intact.

  6. When NOT to Use Aura

    Honest list: regulated prod pipelines, huge monorepos, specific language gaps, and team sizes where Git-alone still wins.

  7. Execution-Aware Validation

    What `aura prove` actually checks vs what it can't. The gap between AST correctness and runtime correctness.

  8. Scale Limits & Open Research

    Tested team sizes, unsolved problems, and what Aura explicitly punts on today.

  9. Regulated Environments

    SOC 2, HIPAA, FDA, EU AI Act — what Aura helps with and what still needs human process.

  10. Migration Reality Check

    A 10-year Git repo takes time to move. Realistic timelines, traps, and partial-adoption paths.

Part 12

Privacy, Security & Sovereignty

The full threat model, cryptographic design, and how Aura keeps your code on your terms.

  1. The Aura Threat Model

    Adversaries, assumptions, and boundaries. What Aura defends against and what it doesn't.

  2. Cryptographic Design

    TLS, JWT, content-addressed hashing, and signed intent logs. The primitives underneath.

  3. Data Residency and Jurisdiction

    Code never leaves the machines you control. How Aura enforces geographic boundaries.

  4. Secret Detection and Masking

    How .env, API keys, and tokens are detected, masked in diffs, and excluded from sync.

  5. AI Agent Permissions

    Scoped capabilities per agent. Revocation. Audit trail of every agent action.

  6. The Immutable Audit Trail

    Every intent, every change, every agent action. Exportable for compliance.

  7. Supply Chain Integrity

    Reproducible builds, signed releases, SBOM, and verifying what you run.

  8. End-to-End Encryption

    Peer-to-peer encryption. Mothership never sees plaintext in federated mode.

  9. Incident Response Playbook

    Compromised peer. Leaked join token. Agent gone rogue. Step-by-step recovery.

  10. Responsible Disclosure

    How to report vulnerabilities to Naridon. PGP keys. Bounty program status.