Your First Aura Repository

Run aura init, understand what gets created, and decide whether to run alongside Git or entirely standalone.

Aura tracks your code at the AST level. That tracking lives in a per-repository directory called .aura/, initialized by aura init. The command is fast, non-destructive, and reversible. On an existing Git repository it layers in alongside .git/ without touching any of Git's state. On a fresh directory it can either bootstrap a Git repository at the same time or run fully standalone.

This page walks you through both modes, explains what .aura/ contains, and covers the one-time integrations — hooks, .gitignore entries, editor hints — you should set up on day one.

The short version

For an existing Git repository:

cd path/to/your/repo
aura init

For a new project, bootstrap both Git and Aura:

mkdir my-project && cd my-project
aura init

For a standalone, no-Git-at-all repository:

mkdir my-project && cd my-project
aura init --no-git

Verify:

aura status

That is the whole happy path. The rest of this page explains what actually happened.

What aura init does

Running aura init produces a small, well-defined set of changes. They are easy to inspect and easy to undo.

  1. Creates .aura/ at the root of the repository. This directory holds all Aura state for this project.
  2. Parses every source file Aura knows how to parse (Rust, Python, TypeScript, JavaScript, Go, and more) to build an initial index of logic nodes — functions, methods, classes.
  3. Writes a baseline snapshot so future diffs have a reference point.
  4. Installs a pre-commit hook at .git/hooks/pre-commit if Git is present. The hook defers to aura for semantic validation.
  5. Adds .aura/cache/ and .aura/sessions/ to .gitignore (but leaves .aura/intent_log.jsonl and .aura/config.toml tracked, because those are part of your repo's shared state).
  6. Initializes the local session so aura status, aura log-intent, and the MCP tools have a working context.

No files outside of .aura/, .git/hooks/, and (optionally) .gitignore are modified. If the repository does not have a .gitignore, aura init creates one.

Command-line flags worth knowing

  • aura init --no-git — do not look for or create a Git repository. Aura runs fully standalone; all hooks and intents are enforced by Aura alone. See the standalone section below.
  • aura init --no-hooks — skip hook installation. Useful on developer machines where hooks are managed by a separate dotfiles system. You can install them later with aura hooks install.
  • aura init --languages rust,python — restrict the initial parse to specific languages. Useful in enormous polyglot repos where the full parse would be slow on the first run. Aura will still detect and parse other languages it encounters later; this flag only limits the initial baseline.
  • aura init --force — re-initialize an existing .aura/ directory. This discards local session state (intents, snapshots not yet pushed to Mothership) and rebuilds the baseline. Almost never what you want; use aura doctor --repair instead.

Anatomy of .aura/

After aura init succeeds, your .aura/ directory looks approximately like this:

.aura/
├── config.toml              # Project-level config. Committed.
├── intent_log.jsonl         # Append-only log of intents. Committed.
├── snapshots/               # Content-addressed AST snapshots. Partially committed.
│   ├── objects/
│   └── index.db
├── sessions/                # Per-developer session state. Gitignored.
│   └── <session-id>/
├── cache/                   # Parse caches. Gitignored.
│   └── parse/
├── team/                    # Mothership sync ledger, if connected. Gitignored.
│   ├── zones.json
│   └── sync.log
└── handover/                # Compressed context payloads for AI agents. Gitignored.

A few specifics worth understanding:

config.toml — the committed configuration. It declares strict mode, which branches are protected, which languages to parse, and any repo-wide policy (for example, "never allow a commit that deletes a public function without an explicit breaking: tag in the intent"). Commit this file; it is how teammates inherit your policy.

intent_log.jsonl — one JSON object per line, each recording a logged intent. The pre-commit hook reads this log to verify your stated intent matches your actual diff. Commit this file; it is the audit trail.

snapshots/ — content-addressed blobs of AST state. The index database (index.db) is gitignored because it can be rebuilt; the objects/ directory is partially committed so that CI can verify historical diffs. The default .gitignore rule Aura writes gets this split right; do not second-guess it without reading the snapshot model docs.

sessions/ — ephemeral per-developer state. Never committed. Holds the current session's working set, any in-flight snapshots, and the MCP agent's memory for this session.

cache/ — parse caches. Also ephemeral. Deleting this directory is always safe; Aura rebuilds it on next invocation.

team/ — populated only when you join a Mothership. Never committed; each developer's sync state is local.

handover/ — compressed semantic payloads used for AI agent handoff via aura handover. Ephemeral and local.

Running alongside Git

This is the default and most common mode. Aura detects .git/ and layers in. Your existing Git workflow is unchanged: git add, git commit, git push, and git pull all work exactly as they did before. Aura operates on top.

The visible changes:

  1. The pre-commit hook now runs aura to validate your staged changes against your logged intent. If you have not logged an intent, it prompts you to do so. If the intent and diff do not match, the commit is flagged as possible intent poisoning and the hook exits non-zero.
  2. .aura/intent_log.jsonl and .aura/config.toml become part of your repo's shared state, just like .github/ workflows or eslintrc.
  3. Your commit messages remain free-form text. The intent is recorded separately in the intent log and referenced from the commit.

You can always bypass the hook with git commit --no-verify, but doing so is logged in the intent log so the audit trail is intact. Strict mode — configured in config.toml — makes --no-verify a hard error instead of a logged event.

Existing repositories

Aura is designed to be introduced gradually into a large existing Git repository. The first aura init in a ten-year-old monorepo is slower (the initial parse may take minutes), but once the baseline is written, day-to-day use is fast. You do not need to rewrite history, add intents retroactively, or change your branching model. The moment aura init finishes, every new commit carries semantic tracking; everything before stays as it was.

For very large repositories (>1M lines), consider:

aura init --languages rust,go       # limit initial parse
aura config set parse.lazy true      # parse files on touch, not upfront

The lazy setting defers first-time parsing of a file until something in that file changes. Most files in a monorepo are cold; this setting is the difference between a two-minute and a twenty-minute initial baseline.

Running standalone with --no-git

Aura can run fully independently of Git. aura init --no-git creates a repository where Aura is the sole version-control authority. Use this mode for:

  • Greenfield prototypes where you have not decided on a Git remote yet.
  • Isolated research code that will never be pushed anywhere.
  • Pure AI-agent workflows where an agent is the primary committer and Git's text-level model adds nothing.
  • Experimentation with Aura itself.

In standalone mode:

  • aura init --no-git creates only .aura/. No .git/.
  • aura save replaces git commit. See your first aura save.
  • aura rewind replaces git checkout and git revert for semantic units (functions, classes).
  • Hooks are enforced by Aura's own CLI wrappers, not by .git/hooks/.

You can always add Git later:

git init
aura hooks install

Aura detects the new .git/ directory and registers its pre-commit hook on the next invocation. The existing intent log and snapshots remain intact.

Compatibility with existing Git conventions

A few explicit guarantees:

  • .gitignore is respected. Aura never parses files that Git ignores.
  • Submodules are not entered. Aura treats a submodule boundary the same way Git does: the submodule is tracked as a pointer, not recursed into.
  • LFS files are not parsed. If a file is managed by Git LFS and is a binary, Aura skips it. If it is text, Aura parses it normally.
  • Worktrees work. Each git worktree gets its own .aura/sessions/ namespace; Aura correctly isolates per-worktree state.
  • Hooks managed by other tools (pre-commit.com, husky, lefthook) are preserved. Aura detects an existing hook manager and installs its check as a delegated step rather than overwriting.

Verifying the install

aura status

Expect output similar to:

Repository: /path/to/your/repo
Branch:     main
Session:    active (id a3f09c21)
Logic nodes tracked: 142
Open intents: 0
Pending impacts: 0
Team sync: disconnected
Strict mode: off

If Logic nodes tracked is 0, Aura did not find any source files it knew how to parse. Confirm your language is supported with aura languages list, and that your files are not gitignored.

Undoing aura init

Aura init is fully reversible. To remove Aura from a repository:

aura uninstall-repo

This removes .aura/ and un-installs the pre-commit hook, leaving Git untouched. The command prompts before deleting so you do not lose an intent log accidentally.

For a full manual removal, delete .aura/ and remove the hook:

rm -rf .aura
rm .git/hooks/pre-commit  # only if Aura installed it

Next steps

You have a working repository. Now:

Up next

Your First Commit with Intent

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