Your First aura save

One command for snapshot, intent, commit, and push. When to reach for it, and when to keep using raw Git.

aura save is the unified Aura workflow command. It bundles the four discrete steps that ought to happen on every commit — pre-edit snapshot, intent log, Git commit, and (optionally) Mothership push — into a single invocation. It is the command most developers end up running by reflex once they have worked with Aura for a few days. This page covers what it actually does under the hood, when it is the right tool, and the handful of situations where plain git commit is still the better choice.

The short version

Inside an Aura-initialized repository, with changes staged:

git add src/auth.rs src/config.rs
aura save "Switched password hashing from bcrypt to argon2id"

That single command:

  1. Snapshots every modified file to .aura/snapshots/ (so aura rewind can recover any of them).
  2. Logs the supplied string as your intent in .aura/intent_log.jsonl.
  3. Validates the intent against the AST-level diff. Aborts if they disagree.
  4. Runs git commit with the same message.
  5. If a Mothership is connected, pushes the changed functions via Live Sync so teammates see them immediately.

If any step fails — intent mismatch, hook rejection, Git error — the whole save is aborted and the repository is left in the state it was in before you invoked the command. No half-committed states.

What each step does, in detail

1. Snapshot

The first thing aura save does is take a snapshot of every file that is currently modified (staged or unstaged) in the working tree. The snapshot is content-addressed and written to .aura/snapshots/objects/. It is durable: even if the subsequent commit fails, the snapshot remains, and you can recover the file or any function inside it with aura rewind.

This is the "safety net" step. It exists because the single most valuable recovery operation in day-to-day work is "undo that one function I just ruined." The snapshot makes that operation semantic — aura rewind auth::hash_password — rather than a full-file revert.

2. Log intent

The intent string you pass to aura save is recorded in .aura/intent_log.jsonl with the same fields aura log-intent would write. The log entry is timestamped, branch-tagged, and cryptographically tied to the staged diff's hash.

If you pass no string, aura save opens $EDITOR with a templated message. The template includes the staged diff's semantic summary at the top, so you can write an intent that actually describes the change.

3. Validate

Aura parses the staged diff into its AST-level representation, compares it against the stated intent, and decides whether they describe the same change. Agreement is a judgment, not a hash match: the comparison is done by a rule-based engine plus, optionally, an LLM-backed review step for cases that are harder to judge mechanically.

If agreement holds, validation passes silently. If it does not, aura save prints the semantic diff with the mismatched nodes highlighted and exits non-zero without committing. You can then either amend the intent or unstage files and re-run.

4. Commit

If validation passes, aura save shells out to git commit with:

git commit -m "<your intent string>"

It runs through the normal pre-commit hook, which re-validates (this is a cheap idempotent check) and records the commit SHA back into the intent log entry.

If you want a different commit message from your intent string — for example, a Conventional Commits-formatted message that differs from the longer intent — use:

aura save --intent "Switched password hashing from bcrypt to argon2id; added ConfigError" \
          --message "feat(auth): migrate to argon2id"

5. Push to Mothership

If this repository is connected to a Mothership, the final step is a push of the changed function bodies (not full files, not full commits) to the Mothership. This is the Live Sync path. It happens automatically after a successful local commit.

Teammates running the same repo receive the function-level change within seconds. If someone else is editing the same function, Aura's live-sync layer surfaces a collision notification on their side; see connecting to a team.

If no Mothership is connected, this step is a no-op.

Flags worth knowing

  • --no-push — skip the Mothership push step. Useful if you are committing partially-working code you do not want teammates to pick up yet.
  • --no-snapshot — skip the snapshot step. Rarely what you want; saves a few milliseconds at the cost of rewind safety.
  • --amend — amend the last commit. Works like git commit --amend but correctly updates the intent log so the hook does not complain on the next commit.
  • --wip — marks this save as work-in-progress. The hook relaxes its intent/diff agreement rules, and the Mothership push is suppressed by default. Use when you are stubbing something out.
  • --force — bypass hook rejection. Recorded in the intent log as a forced save so the audit trail is intact. Blocked in strict mode.

When to use aura save vs. raw Git

aura save is the right command for almost every commit in an Aura-tracked repository. Reach for raw Git when:

  • You are committing to a repo that has not been aura init-ed. aura save requires .aura/ to exist.
  • You are performing a rebase, cherry-pick, or other history-rewriting operation. Use the native Git commands. Aura tracks semantic identity across rebases correctly; no special wrapper needed.
  • You are resolving a merge conflict interactively. Resolve with git, then aura save --message "merge: ..." "Merged branch foo, resolving conflict in parser::tokenize by keeping the new behavior." for the final commit.
  • You are operating on the repo from a script that does not have an intent context. A script committing generated files (say, a regenerated lockfile) has no meaningful intent to log. Use raw git commit with --no-verify and document the script's role in .aura/config.toml under [policy.allow_unverified].

For everything else, aura save is shorter, safer, and produces a better audit trail.

From the agent's side

Claude Code and other MCP-aware agents do not call aura save. They call the individual MCP tools — aura_snapshot, aura_log_intent — and then issue the commit themselves. This is deliberate: at the tool-call granularity, the agent has richer context about why it is snapshotting or logging, and Aura's MCP server can give more targeted warnings (team zones, sync conflicts) at each step.

aura save is the shape humans reach for; the equivalent agent-side flow is the MCP tool chain. Both produce the same audit record. See the CLAUDE.md protocol for the full agent workflow.

Interaction with strict mode

In strict mode, aura save is effectively required — raw git commit without a prior aura log-intent is blocked by the hook. Teams that enable strict mode typically also alias git commit to a warning-emitting wrapper that points developers at aura save.

A minimal shell alias:

alias commit='aura save'

That covers the common case. When you do need raw Git behavior, type git commit with no alias.

Recovering from a bad save

Because aura save snapshots before it commits, everything is recoverable. The most common recovery scenarios:

"I committed, but realized I included the wrong file."

git reset HEAD~1
# files are back in the working tree, unstaged
aura rewind <file-or-function>  # if you need to discard a change

"I committed and now a function behaves worse than before."

aura rewind auth::hash_password

Aura restores just that function from its last-known-good snapshot and leaves the rest of the commit intact. You then aura save the rewind as a new commit.

"My intent was wrong; the diff was right."

git commit --amend --no-edit
aura log-intent --amend "Correct intent goes here."

The amended intent supersedes the bad one in the log.

"The whole commit was a mistake."

git reset --hard HEAD~1

The snapshots remain in .aura/snapshots/. Nothing is lost from Aura's perspective; Git has lost the commit as normal, and you can re-try.

What aura save is not

A few common misunderstandings worth flattening:

  • It is not a replacement for Git. It is a wrapper that calls git commit after doing the Aura-specific preamble. If Git breaks, so will aura save.
  • It does not push to your Git remote. The "push" step is a Mothership function-level push, not git push. If you want both, run git push after.
  • It is not required. You can use aura log-intent + git commit forever if you prefer separate steps. aura save is convenience, not policy. (Unless you enable strict mode, in which case the policy is enforced by the hook, not by the command name.)
  • It is not available in --no-git repositories. Standalone Aura repositories use aura commit instead, which is the same workflow minus the Git step.

Typical session

A realistic five-minute slice of using aura save:

# Morning — pull teammate changes first
aura live-sync-pull

# Work...
vim src/parse.rs
vim tests/parse.rs

# Check what you're about to commit
git status
git diff --cached

# Commit
git add src/parse.rs tests/parse.rs
aura save "Taught parse_expr to handle trailing commas in tuples; added regression test"

# Push Git branch to remote
git push

That is the whole loop. Once aura save is muscle memory, the friction of the intent discipline drops to zero — you write the message as you would have written a commit message anyway, and the hook validation happens in the background.

Next steps

Up next

Connect to Your Team

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