When Not to Use Aura

The fastest way to lose trust is to oversell. Here are the cases where Aura is the wrong tool, in our own words.

We would rather you not install Aura than install it and regret it. This page exists so you can self-select out.

The Concern

Every tool markets itself as universally useful. Engineers have learned to mentally subtract the marketing and ask "where does this actually not fit?" If the vendor cannot answer that question, the tool is either immature or the vendor is dishonest.

Aura has specific cases where it is the wrong tool. We maintain this list publicly because (a) you deserve to know, and (b) we would rather steer people away than have them fight the tool for a quarter and churn.

Cases Where Aura Is Not the Right Tool

1. You are a solo developer on a small repository

If you are the only committer on a repo of a few thousand lines, Aura is overkill. The things Aura is good at — cross-developer coordination, cross-branch impact alerts, agent collision detection, function-level sync between peers — have no audience when the peer count is one.

You would still get marginal benefits from intent tracking and aura prove, but those benefits do not justify learning another tool. A pre-commit hook that runs your tests is probably a better investment of an afternoon.

Recommendation: plain Git, maybe with conventional-commits and a decent pre-commit hook. Revisit Aura if your team grows or you start using AI agents heavily.

2. Your primary language is not well-parsed by tree-sitter

Aura's semantic layer depends on a working tree-sitter grammar. Language support, as of today:

| Language | Support | |---|---| | Rust | full | | TypeScript / JavaScript | full | | Python | full | | Go | full | | Java | full | | C | full | | C# | full | | Ruby | full | | PHP | full | | Swift | partial (macros fall back to text) | | Kotlin | partial | | C++ | partial (heavy template metaprogramming falls back) | | Scala | partial | | Elixir | partial | | Zig | partial | | Fortran | not supported | | Assembly | not supported | | COBOL | not supported | | Ada | not supported | | Hand-rolled DSLs and embedded template languages | not supported |

"Full" means Aura tracks functions, types, and imports with high fidelity. "Partial" means core constructs work but certain advanced features degrade to file-level or text-level handling.

If your codebase is primarily in a "not supported" language, Aura runs but cannot offer its semantic features — you are paying the complexity cost without receiving the benefit. Wait until we ship support, or consider contributing a grammar.

Recommendation: plain Git, until the grammar lands.

3. You operate in a regulated pipeline that mandates a specific VCS

Some government, defense, and heavily-regulated industries operate under rules that mandate specific version control software, certified against a specific control set, with approved hosting. If the rule says "Git, self-hosted, with this configuration," you do not have latitude to add a layer on top without going through a control review.

Even in default (Git-compatible) mode, Aura writes to .aura/ and runs background processes. A strict compliance posture may prohibit that. Your compliance team, not your engineering team, makes this call.

See regulated environments for cases where Aura does add value in compliance contexts. For cases where the mandate is strictly "no additional tooling," respect the mandate.

Recommendation: whatever your compliance office says, even if that is "not this."

GitHub as a platform — pull requests with reviews from @mentioned users, issue cross-linking, organization-level permissions, Dependabot, GitHub Actions, Projects, Codespaces, GitHub Discussions — is a rich product that Aura does not replicate.

If your team's workflow is fundamentally "open a PR, get reviews via GitHub UI, merge via GitHub," Aura does not replace that workflow. It runs alongside it. You gain a semantic layer, better local intent tracking, agent coordination. You do not gain anything GitHub-shaped.

This is not a reason not to use Aura — Aura works fine on top of a GitHub workflow. It is a reason not to expect Aura to be a GitHub alternative. Do not evaluate Aura against features it does not claim.

Recommendation: keep GitHub, keep your PR workflow, add Aura if the semantic and agent-coordination features solve real pain. Do not uninstall GitHub.

5. You are a very large team with hierarchical approval chains

Aura's collaboration model assumes a relatively flat team structure where peers coordinate via live sync, zones, and messages. Teams of ~500 developers on one Mothership work in our internal testing. Teams of 1000+ with strict hierarchical review chains ("this must be signed off by the architecture review board before merging to main") work, but Aura's real-time features add less value when every change already passes through a human gate.

At that scale, Git + your existing review process is probably adequate, and the marginal benefit of Aura's coordination features is smaller than the coordination cost of introducing a new tool across a large organization.

Exception: if the large team is heavily AI-agent-assisted, Aura's Sentinel and zone layers become valuable because the coordination problem shifts from humans to agents. But for a purely human team at that scale, the marginal value is less obvious.

Recommendation: pilot on a single team before rolling out. If the pilot team does not see clear wins, do not expand.

6. Your codebase is primarily configuration, data, or generated content

If your repo is mostly JSON, YAML, Terraform, Markdown, SQL migrations, or generated code, Aura's function-level semantic features do not apply. Aura has a JSON merge layer and an env merge layer that handle some of these, but if your repo does not contain code with functions, the core value of Aura is not present.

Recommendation: plain Git is probably fine. Aura's text merge fallback works, but you are paying for a semantic layer you are not using.

7. You need cross-platform clients that do not include Linux-like environments

Aura's CLI is built for macOS, Linux, and Windows (via WSL or native build). We do not currently ship iOS or Android clients, and we do not have a browser-native Aura runtime. If your developer experience depends on mobile or purely-web editing, Aura is not where you are today.

Recommendation: GitHub.dev, Gitpod, or Codespaces for those cases.

8. You do not trust the operational overhead of running a Mothership

Mothership Mode is P2P and self-hosted. Running it well means someone on your team is responsible for: a small server or VPS, TLS certificates, backups of the Mothership's event log, and occasional protocol upgrades when Aura releases a new version.

This is not hard — it is roughly the operational burden of a small Postgres instance — but it is nonzero. Teams without any on-call capability for internal services will find it burdensome. We offer a hosted Mothership (Aura Cloud) for teams that want to skip this, but Cloud is a commercial product and introduces its own trust and data-residency considerations.

Recommendation: plain Git with a hosted Git service (GitHub, GitLab) if you have zero operational capacity. Aura + self-hosted Mothership if you can spare the effort. Aura Cloud if you want hosted and are comfortable with it.

9. You want deterministic, minimal tooling and philosophically resist additional layers

Some engineers prefer simple stacks. Git is old, boring, and universal. Adding another tool, even a good one, violates their operating principle. We respect that. If your team's stated philosophy is to minimize tools, Aura is an addition you might not want.

Aura is not mandatory and never will be. Nothing is lost by not adopting it. The world of plain Git is still a world where good work happens.

Recommendation: plain Git, continue the quiet life.

10. You are evaluating Aura to "solve" a process problem

If your team has messy commits, unclear code review, missing documentation, or weak testing — those are process problems. A tool does not fix process problems. Aura can surface them (intent logs will make unclear commits visible, aura prove will surface gaps between stated goals and shipped code), but it does not fix the underlying culture.

If you install Aura expecting it to fix discipline, you will be disappointed. Fix the process first. Then Aura becomes a force multiplier on good process.

Recommendation: fix the process. Revisit Aura after.

Cases Where Aura Is the Right Tool

For balance, a short list of where Aura does fit:

Teams of 3–500 developers using AI agents for nontrivial portions of their work.
Codebases in well-supported languages where function-level reasoning is valuable.
Projects where stated intent regularly diverges from what actually shipped (semantic drift).
Teams running self-hosted infrastructure and wanting coordination without adding SaaS dependencies.
Regulated environments that benefit from structured intent logs as an audit trail (in addition to, not instead of, existing controls).

If none of those describe you, the honest answer is that Aura may not be for you today. Check back in a release or two; the list will change.

What Aura Does Not Solve

This entire page is a list of things Aura does not solve. The meta-point: no single tool solves everyone's problem. We would rather tell you where we do not fit than pretend to fit everywhere.

The Honest Tradeoff

The cost of the opt-out list above is that Aura's addressable audience is smaller than the marketing version of our pitch would suggest. We are fine with that. A tool that fits 100 teams well is more valuable than a tool that fits 10,000 teams awkwardly. We would rather shrink the funnel and retain users who find real value.