# 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: ```bash cd path/to/your/repo aura init ``` For a new project, bootstrap both Git and Aura: ```bash mkdir my-project && cd my-project aura init ``` For a standalone, no-Git-at-all repository: ```bash mkdir my-project && cd my-project aura init --no-git ``` Verify: ```bash 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. │ └── / ├── 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](/snapshot-model). **`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](/mothership-overview). 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: ```bash 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](/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: ```bash 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 ```bash 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: ```bash 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: ```bash rm -rf .aura rm .git/hooks/pre-commit # only if Aura installed it ``` ## Next steps You have a working repository. Now: - [Write your first intent-logged commit](/first-commit-with-intent) — the most important habit. - [Use `aura save` as your unified workflow](/your-first-aura-save) for snapshot + intent + commit in one step. - [Connect to a Mothership](/connecting-to-team) if you are collaborating. - [Wire Claude Code in](/claude-md-integration) via the CLAUDE.md protocol so your AI agent respects the guardrails you just installed.