Everything about Ava Supernova

What is Ava Supernova?

Ava Supernova is an open-source agentic coding assistant. She writes code with you, teaches you anything you want to learn, audits your projects for security issues, and can control your desktop when you need her to. She remembers what you told her last week, respects the conventions of your project, and runs on your machine by default.

Three surfaces, one agent. Use whichever fits your workflow — they share the same brain.

The three surfaces

• VS Code extension — Ava lives next to your editor. Chat panel, unified dashboard, inline diffs.
• Desktop IDE — standalone native app for when you want the whole thing in one window. Built with Tauri.
• Companion — a mobile-friendly web app for when you are away from your desk. Tasks, journal, memory, quick chats.

What makes her different

• Local-first. Your data stays on your machine unless you opt in to cloud sync. No telemetry. Ever.
• Open source. Every line is public — extension, IDE, companion, CLI. Fork it, audit it, verify our claims.
• Free for everyone. 3M tokens every month on the free tier. No credit card, no account required with your own keys.
• Teaching is free forever. Education should not have a price tag.

If you are new to coding, start with Teach mode and ask her to explain something. If you are a seasoned engineer, drop her into Work mode and let the full persona team loose on your codebase. Same agent — different mindset.

Never written code? Start here

If you have never written a line of code, you are exactly who Ava is for. You do not need to learn any jargon to start — you talk to her in plain English, the way you would ask a knowledgeable friend. This page is your whole on-ramp.

What you can do today, with no experience

• Ask her anything, in normal words — "what does this file do?", "why is my page blank?", "what even is a database?" She answers in plain language and remembers the conversation.
• Learn something from scratch — say "teach me Python from zero" and she builds you a proper course with lessons and quizzes. This is always free.
• Get something built — describe what you want ("a button that downloads my notes") and she writes it, showing you every change before it happens.

You don't need to understand everything

Ava has a lot of machinery under the hood — modes, models, specialists, routing. You will see those words around the app and in these docs. Here is the secret: you can ignore almost all of it. Ava picks the right tools and the right helpers for you automatically. The technical pages are there for when you get curious, not because you need them to start.

A gentle first path

1. Install Ava (next page) and open the chat.
2. Type a real question you have. Anything. See how she answers.
3. Try learning mode: type "teach me" and a topic. Follow along.
4. When you want her to actually make or change something, just ask — she will always show you what she is about to do and wait for your "yes".

Install

Pick the surface that matches how you work. You can use more than one — Ava syncs her memory across them when you sign in.

VS Code extension

1. Open the Extensions panel in VS Code (Ctrl+Shift+X / Cmd+Shift+X).
2. Search for "Ava Supernova" and click Install.
3. Press Ctrl+Shift+A (Cmd+Shift+A on macOS) to open the chat panel.
4. Follow the setup wizard — pick a model, set your permission mode, done.

Desktop IDE

1. Download the installer for your platform from the releases page.
2. Run it. The IDE launches with a welcome flow the first time.
3. Sign in for the free platform tokens, or paste your own API key to run fully local.

CLI

1. npm install -g @ava/cli (or pnpm / yarn — your choice).
2. Run ava in any project directory.
3. First run prompts you for a provider and a model. Pick and go.

Your first five minutes

Forget the documentation for a moment. The fastest way to learn Ava is to use her.

1. Open the chat. Whatever surface you are on.
2. Type a question about a file in your project. Try: "Explain what this file does." — or pick a bug and say "Find what is wrong with this function."
3. Ava will read the file (tool call #1). She will ask you to approve the first read. Say yes.
4. Watch her stream an answer. If she wants to make a change, she will show you the diff and wait for you to approve.
5. Switch modes. Type >> to enter Work mode, then ?? to try Teach mode with the same question. Feel the difference.

That is it. You have used 4 of 60 tools and 2 of 6 modes. The rest is progressive — you learn what exists when you need it.

Local vs cloud, in one paragraph

Everything Ava does is local unless you explicitly opt in. Memory, tasks, journal, personality, settings — all stored on your machine in ~/.ava/ and .ava/ (per project). She talks to model providers over HTTPS to run your request, then returns home. She does not phone home. She does not collect telemetry. She does not train on your code.

If you sign in, you get 3M free tokens per month on platform-managed models (Qwen, MiniMax) and optional cloud sync for memory and settings across machines. Sync is per-feature, revocable anytime. Bring your own API key and Ava works fully without an account.

Choosing your routing mode

You do not pick a model — you pick a routing strategy. Ava drives the right model for each subtask under the hood. Three strategies cover every workload, available on every plan.

Maestro — the default

One conductor (Qwen 3.6 Plus) handles every persona, every step. Production-tuned, proven, predictable cost. Pick this if you want Ava to "just work" without thinking about routing. Live on every plan.

Supernova — the polyglot ensemble

A frontier coordinator (DeepSeek V4 Pro, 1.6T parameters / 49B active, 1M context) hands off to specialists per subtask. V4 Flash for high-volume builds, Qwen 3.6 Plus as fallback, Qwen Omni when vision is in play. Best for heavy multi-step work where each step deserves its own specialist.

Aurora — the European stack

Mistral-only routing in three tiers — Mistral Large 3 coordinator + heavy specialists, Mistral Medium 3.5 (the merged flagship released April 2026 — 128B dense, 256K context, vision encoder from scratch, modified-MIT open weights, 77.6% SWE-Bench Verified) for Builder + mid-tier specialists + vision + long-form, Mistral Small 4 at the intent gate. Open weights end to end, never leaves EU infrastructure. Built for GDPR-strict deployments, public-sector, healthcare, anyone with a sovereignty mandate.

Want to drive a specific model yourself?

BYOK (bring your own key) gives you both — the three orchestration modes plus the ability to pick a single model and skip routing entirely. Useful when you have a strong preference, a strict budget, or you are testing a specific model. Paste your provider key in settings, pick the model from the picker, done. Full provider matrix lives in the Reference section.

Plain-English glossary

Every word you might bump into around Ava, explained with no assumed knowledge. You do not need to memorise any of this — flip back whenever a term trips you up.

Routing — how Ava picks models

Here is the short version: you never have to pick which AI model to use. Ava does it for you, choosing the best tool for each part of a job — the way a good manager hands the right task to the right person. The rest of this page explains how that works under the hood. You can ignore almost all of it and just enjoy that it happens.

Ava is a thinking system, not a model menu. You pick one of three orchestration strategies (an "orchestration strategy" is just a named recipe for which AI models get used) — Maestro, Supernova, or Aurora — and Ava routes each subtask to the model best suited for it. ("Routing" means sending each piece of work to the model that handles it best.) Coordinator-tier reasoning where it matters, flash-tier specialists for high-volume work. (The "coordinator" is the lead model that thinks and plans; "specialists" are faster, cheaper models that do the bulk grunt work.) Same persona pipeline runs on all three; what changes is the underlying fleet.

Side-by-side

Maestro

Tier-differentiated Qwen routing, light footprint. Qwen 3.6 Plus owns the coordinator, Builder, planning, security, brainstorm, and long-context work — the slots where its 1M-context hybrid linear-attention pays off. Qwen 3.5 Flash handles chat, image-gen orchestration, and the upstream intent gate, where its $0.07/$0.26 pricing and faster TTFT win on the bulk of low-depth token volume. Qwen 3.5 Omni Plus owns vision input (Qwen 3.6 Plus has no native vision). Qwen 3.5 Plus carries cost-sensitive long-form work. Falls through the priority ladder Qwen 3.6 Plus → 3.5 Plus → 3.5 Flash if the primary coordinator is unavailable.

Supernova

Polyglot ensemble. DeepSeek V4 Pro coordinates and dispatches each subtask to its best-suited specialist: Qwen 3.6 Plus runs every Builder spawn, V4 Flash handles chat plus the mid-tier review/audit personas, Qwen 3.5 Flash absorbs the light-tier classifier work, Qwen 3.5 Omni Plus owns vision input, Qwen 3.5 Omni Flash orchestrates image-gen tool calls, Qwen 3.5 Plus carries the cost-sensitive long-form Content Writer persona. Frontier reasoning where it matters, flash-tier economics on the bulk of token volume.

Aurora

European AI stack — sovereign by design. Mistral-only routing in three tiers: Mistral Large 3 (675B/41B-active sparse MoE) handles the coordinator role plus the heavy specialists that need depth — Researcher, Challenger, CVE Researcher, Ideator, Fact Checker, Security Verifier — and the long-context grunt where its sparse-MoE efficiency wins. Mistral Medium 3.5 — the merged flagship released April 2026, 128B dense, 256K context, vision encoder trained from scratch, modified-MIT open weights, 77.6% SWE-Bench Verified — runs the actual working tier: Builder spawns, mid-tier specialists (Architect, Verifier, Sequencer, Tutor, Reporter), vision input, and long-form writing. Mistral Small 4 expanded from a single role at the intent gate to also handling chat and image-gen orchestration — its $0.15/$0.60 pricing and configurable reasoning earn their keep on the high-volume low-depth routes. Open weights end to end, never leaves EU infrastructure. Aurora deliberately does not silently cross-route to a non-Mistral model when one is unavailable; the router surfaces an error instead — that is what makes it "Aurora" rather than a Mistral-flavoured Maestro.

Why orchestration?

Routing each subtask to the right specialist costs less than running every step on a frontier model — and produces better results, because each model is used for what it is best at. Coordinator tokens get spent on reasoning and planning; build-tier tokens flow to flash-tier models. Cost stays predictable, quality stays high, and you do not need to know which model to pick — Ava picks for each step.

Ava Credits — how billing works

Credits are simply how Ava counts what you use — like minutes on a phone plan. Every plan, including the free one, comes with a pool of credits, and each thing Ava does (answering you, making an image) costs a small number of them. That's the whole idea. The detail below is for when you want to know exactly what costs what.

Ava bills in credits, not raw tokens. (A "token" is the tiny chunk of text — roughly a few letters — that AI models read and write in; most services charge you per token, which is hard to predict.) One credit covers one unit of work — a chat turn, a persona spawn (one helper doing a piece of the task), an image generation. Decoupling from token-level metering means you do not need to know which model is running to know what an action will cost. The same chat turn costs the same whether Maestro routes it to Qwen 3.6 Plus or Supernova routes it to V4 Pro.

Plans

Every plan has access to every feature — model access, Creative Studio, all six modes, the full persona orchestration. Higher tiers buy more credits and a higher rate-limit ceiling, not unlocked features.

• Free — $0/month. 300 credits. 20 requests/minute rate limit. No card required.
• Pro — $19/month. 5,000 credits. 60 requests/minute.
• Ultra — $39/month. 10,000 credits. 120 requests/minute.
• Enterprise — $79/month. 20,000 credits. 200 requests/minute.

What things cost

Per-action cost table — what gets deducted from your credit pool when each action runs. (A "cache hit" is when Ava reuses work it already did instead of redoing it; when that happens you pay less — the charge drops by 70%, or 50% on output-heavy models like DeepSeek V4 Pro.)

• Chat turn — 2 credits. A single back-and-forth in any mode.
• Light call — 1 credit. Intent gate, classification, single-shot read.
• Heavy persona — 3 credits. Architect, Researcher, CVE Researcher, Ideator (depth ≥ 4).
• Light persona — 1 credit. Scout, Verifier, Sequencer, Challenger (depth ≤ 2).
• Orchestration — 10 credits. Full persona pipeline spawn (Conductor + multi-persona task).
• Image generation — 12 credits. Hailuo image-01 via Creative Studio.
• Video generation — 150 credits. Hailuo 02 Pro 1080p 6s clip.
• Voice generation — 10 credits. Speech 2.8 HD synthesis.
• Music generation — 50 credits. MiniMax Music 2.5/2.6.
• Background removal — 2 credits.

Per-model multipliers

This bit is for the curious — you don't need it to use Ava. A multiplier just scales the credit cost up or down depending on how expensive the model behind an action is, so heavier models cost a bit more. ("Net margin" is the slice the project keeps after paying its own bills — we aim low so the value flows back to you.)

Heavier models multiply the action cost so credits track real spend instead of a flat bracket. Calibrated for ~55% net margin.

• 0.6× — Mistral Small 4 (Aurora's specialist seat). Sub-1× because Mistral Small 4 is cheaper than the Qwen 3.6 Plus anchor.
• 1.0× — Qwen 3.5 Flash, Qwen Omni Flash, DeepSeek V4 Flash, MiniMax. Base rate.
• 1.2× — Qwen 3.5 Plus, Qwen 3.5 Omni Plus.
• 1.4× — Mistral Large 3 (Aurora coordinator). About par with the Qwen 3.6 Plus anchor.
• 1.5× — Qwen 3.6 Plus (Maestro coordinator).
• 6.0× — DeepSeek V4 Pro (Supernova coordinator + heavy specialists). Recalibrated from 5.0× to restore margin parity at the published V4 Pro rate.

BYOK and credits

BYOK ("bring your own key" — you supply your own account with an AI provider and a key, which is a private password that lets software use that paid account) is for people who already pay an AI provider directly. If that is not you, you can ignore this section entirely.

Bring-your-own-key requests bypass platform infrastructure entirely — the call goes direct from Ava to the provider, you pay the provider, no credits are consumed. The only exception is when a BYOK session spawns a managed-tier persona for a sub-task; the credit deduction still applies because Ava's orchestration surface is being used.

Where to check your balance

• Extension — Settings → Account, or the credit pill in the chat header.
• IDE — Account dashboard tile shows current balance and burn rate.
• Web — ava-supernova.com/dashboard shows balance, history, and renewal date.

The six modes

A mode is the mindset Ava is in — like a colleague swapping hats. Same person, same memory of you, but a builder thinks differently from a teacher. You pick the mode and it changes how she behaves and which helpers she brings. Switch any time with the mode selector, or type a two-character shortcut.

Which one do you want?

Start from what you are trying to do — the mode follows from that:

• I want something built or changed → Work (>>). You describe it, she builds it, showing you every change first. The full helper team kicks in for bigger jobs.
• I want a plan before anything changes → Plan (::). She thinks it through and hands you a plan to approve or edit. She will not touch your files in this mode.
• I just want to talk or ask → Chat (..). A thinking partner with memory, news, and weather. No file changes, no code — just conversation.
• I want to learn something → Teach (??). A real course built for you: lessons, quizzes, the lot. Free on every plan, forever. Perfect if you are new.
• I want my project checked for security holes → Security (!!). A team works through the standard list of common web vulnerabilities (the "OWASP" categories) and known reported flaws (called "CVEs"), then hands you a report sorted by how serious each issue is. This one is aimed at developers — skip it if that is not you.
• I want ideas → Brainstorm (**). She generates options grounded in your actual situation, pokes holes in the weak ones, and refines the rest into next steps.

Memory — how Ava remembers you

In plain terms: Ava remembers you. Tell her something once — what you like, a decision you made — and she keeps it, so you don't have to repeat yourself in the next chat or next week. That's the headline. The layers below just explain how she keeps that memory tidy over time.

Ava has a persistent memory ("persistent" means it sticks around after you close the app) that survives across conversations, across projects, and across machines if you enable sync (sync copies your memory between your devices). It is not a chat log. It is a structured, searchable understanding of who you are, what you like, and what you have decided.

Five layers

1. Extract — key facts captured from every message in real time.
2. Reflect — deeper analysis runs at the end of meaningful sessions. Patterns, themes, contradictions.
3. Accumulate — corrections and preferences compound over weeks and months.
4. Analyse — the graph engine links related memories and flags contradictions when new information conflicts with old.
5. Consolidate — similar memories merge; stale ones prune. Memory gets sharper over time, not noisier.

Recall

When you ask a question, Ava searches memory by meaning ("semantic search" — it understands what you mean, so it finds the right memory even if you phrase it differently), not just by matching exact words. Mode-specific filters run alongside — Chat mode pulls personal context, Work mode pulls project decisions and code patterns.

Tasks and journal

Ava keeps three kinds of notes for you, and it's easy to mix them up. The quick way to remember: memory is what she knows about you, tasks are what you still need to do, and the journal is a diary of how things went. Here is when to use which.

Three things that sound similar and are not: memory, tasks, and journal. Here is when to use which.

• Memory — persistent facts. Preferences, decisions, patterns. Asked about repeatedly, rarely created manually.
• Tasks — things to do. Action items with due dates and status. You tick them off when done.
• Journal — reflection. Daily log, dual entries (yours and Ava observations about the session). Useful for mood tracking, session reviews, context for tomorrow.

Ava writes to all three when it makes sense. You can write to any of them directly from the dashboard. Nothing is locked to a single place you use Ava — a task you create in one (say the command-line tool) shows up everywhere else (like the desktop app), automatically.

Permissions — three modes, ten categories

Permissions are your safety dial. They decide when Ava asks your okay before doing something on your computer, versus just getting on with it. You can set her to ask about everything, ask about the risky stuff only, or trust her to run — and you can change it any time. If you're not sure, leave it on the default and you'll be fine.

Ava has 60 tools ("tools" are the actions she can take — reading a file, searching the web, and so on). Every tool belongs to a category (file operations, shell, git, web, media, database, system, documents, memory, learning). Every tool call passes through the permission gate (a checkpoint that decides whether to ask you first) before it runs. You control what gets auto-approved, what asks once, and what always asks.

Balanced is the default. Strict for when you are auditing her behaviour (watching closely to check each step). Autonomous for when you want her to just go.

Interjection and hard-stop

You are always in charge. While Ava is busy working, you can either nudge her in a new direction without breaking her stride, or stop her cold. Two buttons, two outcomes — that's all this page is about.

Ava runs until her plan completes or you stop her. You have two ways to step in (the word for this is "intervene") while she is running.

Interject — steer without cancelling

Type a new message while Ava is working. She finishes her current tool call, reads your message, and adjusts her plan. No context is lost. Use this when you want to redirect, add information, or change priorities mid-run.

Hard-stop — cancel and clear

Press Escape (CLI), click Stop (extension, IDE), or type a stop command. The current run cancels, pending tool calls drop, and the conversation is ready for a fresh turn.

Desktop personas

This page is for the curious and for power users. "Desktop automation" (sometimes called "computer use") means Ava can actually click around your screen and use apps for you — open Gmail, fill a form, send a message — like a person at the keyboard. To do that safely, she splits the job across five small helpers, each with one narrow role. You never deal with them directly; this just shows you who does what.

Every step in a desktop trajectory (one run of Ava driving your screen toward a goal) runs a five-persona wave. Each persona has one job and only one job. The separation keeps prompts tight, outputs structured, and reasoning skeptical by design.

Scout

Reports what is visible on screen right now. Never invents elements. Never plans. Returns a ScreenState JSON with element IDs, names, bboxes, confidence, and a grounding source (UIA, Playwright DOM, or OmniParser vision).

Planner

Decides the single next action. One action per step — never batches. Prefers reversible paths. Classifies risk per the safety ontology. Outputs a ProposedAction JSON with kind, target, params, riskClass, reasoning, and an expectedPostState prediction.

Actor

Executes exactly what Planner proposed — after the approval gate has cleared. No improvisation. No retry. Failure is reported faithfully and Verifier handles the next move.

Verifier

Checks whether the action landed. Compares the fresh ScreenState against Planner's prediction. Returns verified, deviated, or rollback_needed. Also runs loop detection — repeating an action that already succeeded is a deviation, not a verification.

Narrator

The only voice the user hears during a trajectory. One past-tense sentence per step ("Opened Gmail.", "Clicked Compose."). Also writes the structured audit log. Says when something went wrong — never hides a problem.

Desktop safety ontology

In short: before Ava clicks anything on your screen, she sorts the action by how risky it is. Reading the screen? Harmless. Sending money or deleting something? She always stops and asks you first — every single time, no exceptions. The five labels below are just the rungs on that risk ladder. This is power-user detail, but the takeaway is simple: the dangerous stuff always needs your yes.

Every proposed action is classified into one of five risk classes. The classification combines three signals — what the on-screen target is, a plain-language description of it ("semantic caption" — Ava's own words for what she's looking at), and the action's settings — and escalates up (treats it as riskier) when they disagree. A false positive (asking when it didn't need to) is just a nag. A false negative (not asking when it should have) is a product-ending incident.

The five classes

• Observational — read UIA tree, screenshot, hover. Always auto-allowed.
• Navigational — scroll, move focus, open a menu. Auto-allowed in Drive mode.
• Mutative-reversible — type into a field, paste, open an app, navigate a URL. Confirms in Ask mode; auto in Drive within the whitelist.
• Mutative-irreversible — send, submit, pay, delete, confirm, publish. Always confirms, regardless of permission level. Approval never caches.
• Privileged — UAC elevation, sudo, registry edits, credential prompts. Forbidden by default. Single-use opt-in required per session.

Never-cached approvals

Every competitor caches approvals (remembers your "yes" and reuses it next time). That is the largest foothold for prompt injection — an attack where a booby-trapped web page sneaks hidden instructions to the AI to make it act against you. If approvals are cached, a compromised page can ride on a "yes" you gave earlier. Ava never caches. Each mutative-irreversible action asks fresh.

Secrets handling

Passwords, API keys, and 2FA codes (the one-time codes a second app or text gives you when you log in) are handled via opaque handles — placeholders that stand in for the real value. Ava sees "{secret}", not the actual password. The real value never enters her memory, her activity log, or what she "reads" — a separate low-level layer types it in at the last moment, at the keypress, so the AI part never touches it.

Desktop grounding hierarchy (Preview)

Before Ava can click a button, she has to actually understand what's on your screen and where things are — that's "grounding" (figuring out what each thing on screen is and its exact spot). She has three ways to do it and picks the most reliable one that works for the app you're in. This is deep power-user detail; the point is just that she prefers solid, accurate methods over guessing from a picture.

Three tiers, evaluated in order. Cheapest reliable source wins.

1. Browser window → Playwright DOM

If the active window is a web browser, Ava reads the page's own structure (the "DOM" — the underlying list of what's on a page) instead of guessing from the picture. Reading the structure is about 10× more reliable than eyeballing pixels — she knows exactly where each button is and when the page has finished loading. This is the main path for anything on the web, not a backup.

2. Native app with UIA → Windows UI Automation

For ordinary desktop apps on Windows, Ava reads a built-in accessibility map ("UIA", the same data screen-readers use to describe a window) — it lists each control, its name, and where it sits. If that map returns at least five usable, named items, she trusts it and uses it.

3. UIA empty or junk → OmniParser vision

When that map is missing or useless (some apps, games, and remote screens don't provide one), Ava falls back to actually looking at a screenshot. A vision tool (OmniParser) spots the clickable regions and labels what each one is, turning the picture back into a list she can act on — combined with whatever little the accessibility map did give.

Desktop kill switches (Preview)

A "kill switch" is exactly what it sounds like — an emergency way to stop Ava instantly when she's controlling your screen. The reassuring part: there are three of them, each built separately, so if one fails another still works. You don't have to learn all three. Just know that when something looks wrong, you can always stop it, and the strongest stop (the panic kill below) doesn't rely on Ava cooperating.

After reading every public autonomy incident (real cases where AI agents ignored stop commands, deleted email archives, wiped drives), we built three kill switches in three different layers. None of them depend on the AI model itself — if Ava is stuck or unresponsive, you can still stop her.

Pause — space or the Pause button

Freezes on the next step boundary. Resumable. Use this when you want to intervene without losing the trajectory.

Stop — Escape or the Stop button

Clean abort. Narrator summarises what was done so far. Not resumable. Audit log commits.

Panic kill — triple-Escape or Ctrl+Shift+K

The hardest stop there is. A small, separate watchdog program force-quits the part of Ava that is driving your screen. It does not wait for the AI to respond, does not need the app window to be working, and does not care what state things are in — it just kills it. This is the one for when something is genuinely wrong.

All three work from the companion app too. Either driver can end it.

Tool reference

This is the full lookup of every tool Ava has — a "tool" just being a specific action she can take, like reading a file or running a search. You do not need to read this page. Ava picks the right tool herself every time. It is here for when you are curious about exactly what she can do.

The full built-in toolbox. Every tool here is registered in the core runtime (the engine underneath all three surfaces) and available to Ava when the mode and permission mode allow it. Filter by category or risk.

No need to memorise any of this — the table below is just a reference card.

Risk levels

• Safe — reads things without changing anything. file_read, glob (find files by name pattern), grep (search inside files for text), git_status (Git is the system that tracks changes to your project).
• Write — changes files, saves a checkpoint of your work (a "commit"), or produces something new. file_edit, git_commit, generate_image.
• Dangerous — runs commands on your computer (the "shell"), controls the desktop, goes out to the internet, or queries databases. bash, browser, desktop_*.

Models

A "model" is the AI brain doing the thinking — Qwen, DeepSeek, Mistral and others. This page lists every model Ava can use. The short version: you do not have to choose one. Ava picks the right model for each step herself. Read on only if you want to understand or override that.

Every model Ava can route to, plus the three orchestration strategies — the rules that decide which model handles each part of a job. Pick a routing mode and let Ava dispatch, or pick a single model and skip routing entirely.

Routing modes

Three orchestrated strategies. The same persona pipeline (the small team of specialist helpers Ava runs behind the scenes) runs on all three; what changes is the underlying fleet of models. Pick a mode in the model selector and Ava handles the rest. Each card below shows the constituent specialists the conductor routes to.

You do not need to memorise the cards below — they are here so you can see what each strategy is made of.

Platform-managed models

Available on every plan, including the free tier. Tokens (the units of text AI is measured in — roughly three-quarters of a word each) count against your plan allowance. The keys (the private passwords that unlock each paid model) are rotated and monitored by the platform — nothing for you to configure.

Bring your own key

An "API key" is a private password that lets software use a paid service on your own account. "BYOK" just means "bring your own key" — using yours instead of ours. Paste your API key in settings. BYOK requests go direct from Ava to the provider (the company that runs the model) — they do not pass through our infrastructure and do not consume platform tokens. You pay the provider; we do not see the traffic.

Persona orchestration

A "persona" is a helper role Ava plays behind the scenes for harder jobs — an explorer, a planner, a fact-checker. You never talk to them directly and you do not need to understand this page to use Ava. It is here for when you are curious how she breaks a big job into a small expert team.

24 specialists across 5 mode teams. The Conductor (the helper that coordinates the rest) decides which team runs, in what order, and with what context. Chat mode has no personas — it is Ava herself.

How orchestration runs

1. You send a message in Plan, Teach, Security, or Brainstorm mode (or a complex Work request).
2. The Conductor reads the request, picks the mode team, and builds an execution plan — some personas run sequentially, some in parallel waves.
3. Each persona has its own system prompt, a restricted tool allowlist, and a shared context pool of what previous personas found.
4. The final persona produces a summary, a plan, or a report, depending on mode.
5. Ava presents the result to you. You approve, tweak, or redirect.

The full roster below is reference only — no need to memorise who does what. Ava assembles the right team for you.

CLI commands

This page is for the CLI — the version of Ava you type to in a terminal window, rather than clicking buttons. If you use the extension or the desktop app, you can skip it entirely. It is here for people who prefer the keyboard.

The CLI is a REPL — a prompt that waits for you to type, runs what you typed, then waits again. These slash commands (instructions that start with "/") work from the prompt.

• /help — list commands and current mode.
• /mode <name> — switch mode (work, plan, chat, teach, security, brainstorm).
• /model <id> — switch model without leaving the session.
• /clear — clear the current conversation. Memory is untouched.
• /history — list past conversations in this project.
• /memory — open the memory browser.
• /tasks — list and manage tasks.
• /journal — open today journal entry.
• /settings — open the settings menu.
• /exit — quit the REPL.

Launch flags

Flags are extra options you add when you start Ava, each beginning with "--", to set how she opens.

• --mode <name> — start in a specific mode.
• --model <id> — start with a specific model.
• --permission <mode> — strict / balanced / autonomous.
• --project <path> — set the project root explicitly.

Configuration

This page shows where Ava keeps her settings and files on your computer. You almost never need to touch any of it by hand — the app manages it for you. It is here for when you want to see, back up, or share those files yourself.

Ava reads configuration (her saved settings) from two scopes. Global settings — the ones that apply everywhere — live in a folder called ~/.ava/ (the "~" is shorthand for your home folder). Per-project settings live in a .ava/ folder inside the project itself.

Global — ~/.ava/

• settings.json — model preferences, permission mode, personality, language.
• memory/ — your global memories (preferences, decisions that apply everywhere).
• tasks.json — cross-project task list.
• journal/ — daily journal entries, date-organised.

Project — .ava/

• instructions.md — project-specific instructions Ava always loads. Durable context ("we use pnpm, not npm", "API keys live in 1Password").
• context.md — optional freeform project notes.
• memory/ — memories scoped to this project.
• datasets/config.json — opt-in dataset capture configuration.

Keyboard shortcuts

Keyboard shortcuts are optional speed-ups — every one of them is also a button you can click. Look here only if you want to drive Ava faster from the keyboard.

Shortcuts by surface (each of the three places Ava runs: the VS Code extension, the desktop app, and the terminal). Customise them in each surface settings. No need to memorise the list below.

Project context

This explains how Ava reads up on your project before she starts — the files she looks at to understand what you are working on. You do not need to set any of this up; she does it on her own. Read it if you want to know where to put a note so she always sees it.

Ava loads several layers of context (background information she holds in mind) when you open a project. Understanding the layers helps you put information in the right place.

Loaded automatically

• .ava/instructions.md — treated as durable, high-priority guidance. Always in context.
• .ava/context.md — freeform notes. Loaded, lower priority.
• README.md — scanned on first run for project summary.
• package.json / pyproject.toml / Cargo.toml — the small files that list a project setup; read to detect the language, framework, and test command.
• .gitignore — the list of files to leave out of version control; respected by all file tools (glob, grep, project_index).

Loaded on demand

"On demand" means Ava only fetches these when a task actually needs them, rather than up front.

• Project index — a structured map of your files and the named pieces inside them (functions, classes — "symbols") and how they connect ("imports"). Built lazily, meaning only when Ava needs it.
• Git history — the record of past changes; pulled when git_status, git_diff, or git_create_pr are called (git is the tool that tracks every change to a project; "PR" is a pull request, a proposed batch of changes).
• Memory — entries are matched by meaning ("semantically") and injected one turn at a time, not all at once.

Desktop budget caps

When Ava controls your desktop on your behalf — clicking, typing, opening apps — each run is called a "trajectory". This page explains the safety limits that stop any one run from going on too long or costing too much. The takeaway: she always stops and checks in before overrunning. The numbers are here if you want the detail.

Every trajectory runs under three simultaneous caps (hard limits). The first one hit wins. The trajectory never silently continues past a breach — the Narrator (the helper that talks you through what is happening) pauses and asks what to do.

Three hard caps (default)

• Step count — 30 steps
• Token budget — 500,000 tokens
• Wall-clock — 5 minutes

Task cost bands

• Simple (search docs, open a page) — 5–10 steps, ~70–135K tokens, ~$0.04–0.08
• Medium (log in, check logs, download output) — 15–25 steps, ~205–340K tokens, ~$0.12–0.21
• Complex (triage three GitHub issues) — 25–30 steps, ~340–410K tokens, ~$0.21–0.25

Free tier includes 3M tokens monthly — roughly 15 medium tasks or 21 complex ones if you only use desktop automation. Mixed use (chat + code + a few automations) is comfortable.

Desktop session whitelist

A "whitelist" is simply the list of apps and websites you have said Ava is allowed to touch while she controls your desktop. This page explains how you grant that permission and why it resets each time. The short version: she can only act where you let her, and she asks before going anywhere new.

At the start of a desktop session Ava asks where she is allowed to act. Plain English works: "Gmail, Cursor, the Azure portal." She reads that and confirms the match back to you ("Gmail web, Cursor the app, portal.azure.com").

How it enforces

Looking-only actions — taking a screenshot, reading the list of buttons and fields on screen (the "UIA tree", Windows own map of what is in a window) — are allowed everywhere, because you need to see what is on screen to decide whether to add an app to the whitelist. Anything that changes something is blocked outside the list; Ava pauses and asks whether to add it.

Session-scoped, deliberately

The whitelist does NOT persist across sessions. There is no "remember this app" option. Every new trajectory starts with a fresh scope. Inconvenient by design — forgetting to reauthorise is a feature, not a bug.

Mid-trajectory additions

During a trajectory you can add apps from the header: "+ Allow app" opens a small input. Tap Add and the new app is live for the rest of the session.

Knowledge packs

In plain terms: hand Ava a folder of your own documents, and she can read from them to answer your questions. A "knowledge pack" is just that bundle of files — your reference material she is allowed to draw on.

Drop a directory of reference material (specs, RFCs, meeting notes, API docs) into a knowledge pack. Ava can pull the relevant pieces into context when a conversation touches the topic.

Packs are indexed locally. Retrieval is semantic — Ava finds the right document by meaning, not filename. ("Semantic" means she matches on what a document is about, so you do not need to remember the exact words or the file name.) Packs can be shared with a team or kept private.

Creative Studio

Want to make an image, a short video, a song, or a spoken voiceover? Just describe it and Ava makes it for you — no design or audio software needed.

Image, video, music, and voice generation — built into the same workflow as your code. Generate an icon, a product mockup, a demo video, a voiceover for a tutorial. Powered by MiniMax.

What you can make

• Images — prompt to PNG/JPG. Background removal one call away.
• Video — short AI videos from a text prompt (MiniMax Hailuo).
• Music — instrumental or vocal tracks with lyrics.
• Voice — text-to-speech with selectable voices.

Creative Studio costs deduct from the same token allowance as coding — one pool, one number. BYOK your own MiniMax key and it is free to your plan.

Office Suite

Need a report, an email, or a document written up? Ava can draft it and hand you a real Word, Excel, or PDF file you can open and edit like any other.

Reports, emails, and documents — drafted, formatted, and exported to native formats (.docx is Word, .xlsx is Excel, .pdf is a PDF).

• report_generate — a structured .docx pulling from tasks, journal, memory, and project state.
• email_draft — tone-controlled email to a .docx file.
• document_manage — create, read, edit, export across Word, Excel, PDF, CSV, Markdown.

Useful when Ava is writing on your behalf — status reports, kickoff decks, client updates. The .docx lands in your project where you can polish it.

Daily briefing

In plain terms: a short "here is where you left off" note each morning, so you can pick up without rereading everything.

Morning summary: yesterday journal, open tasks, project state, and any reminders Ava has set. Optional — turn it on in settings.

The briefing uses memory to surface relevant context ("last time you worked on the auth flow, you noted you wanted to revisit the refresh token strategy"). Not a news feed — a focused catch-up.

Workflows

In plain terms: teach Ava a routine you do over and over, give it a name, and she can run the whole thing again on demand. A "workflow" is just that saved routine — a set of steps Ava repeats for you.

Save a sequence of steps you find yourself repeating — review PR → run tests → write release notes → draft the email. A workflow is a reusable plan Ava can replay with different inputs.

Workflows are stored per project in a folder named .ava/workflows/ inside your project. Share them with your team by committing the directory (saving it into your shared project so teammates get it too).

Events and notifications

In plain terms: while Ava works you get a tidy step-by-step list of what she is doing, and a ping when a long job finishes so you can step away.

While Ava is running you see structured updates, not a wall of text. Each tool call, each persona handoff, each streamed delta is a discrete event in the UI — expandable for detail, collapsible for overview.

Background runs emit OS-level notifications when they complete. You can walk away from a long build and Ava will tell you when it is done.

Personality Designer

In plain terms: dial in how Ava talks to you — chatty or brief, formal or casual, more jokes or fewer — so she sounds the way you like.

Shape how Ava talks to you. Tone, energy, verbosity (how much she says), formality, humour. Sliders and presets — terse engineer, warm mentor, dry colleague, or your own blend.

Personality affects phrasing, not competence. She still runs the same tools and follows the same permission rules. Her name is locked to Ava — that is non-negotiable.

Desktop Automation

In plain terms: Ava can take over your mouse and keyboard to do tasks for you — open an app, click buttons, fill in a form — while you watch and approve anything important.

A new mode for Ava, prefix @@. She observes the desktop, decides what to do, and drives UI automation (controlling the apps on your screen for you) to get it done. Runs on your actual machine with your actual credentials — not a cloud browser. Available on every tier once shipped.

Why another one

Every other desktop-automation product is something you start when you're at your desk. Ava is the one that's still there when your error tracker fires at 2am — IDE keeps running, your phone pairs over a secure channel, you approve irreversibles with a tap.

She also remembers how to navigate your apps across sessions. Every other agent relearns them every time. The memory differentiator compounds with use.

How it works

Each step runs a five-persona wave: Scout observes, Planner picks the next action, Actor executes, Verifier checks, Narrator tells you what happened. The sidecar chooses the cheapest reliable grounding — UIA for native apps, Playwright for browsers, OmniParser vision when nothing else has a useful tree.

See the concepts pages for safety ontology, grounding hierarchy, kill switches, and the session whitelist model.

Common errors

Most errors have a short, specific cause. Here are the common ones and how to fix them. Do not worry if the wording sounds technical — each one below tells you what you are actually seeing and exactly what to do.

Model not responding

What you see: Ava goes quiet and does not reply.

Check the status indicator in the chat header. If it says "connecting", your provider (the AI service Ava is talking to) is reachable but slow — give it thirty seconds. If it says "unavailable", Ava auto-fell-back to the next model in the chain (she automatically switched to a backup model). If nothing at all, verify your API key in Settings and test the connection. (An API key is the private password that lets Ava use a paid AI service.)

Tool call failed

What you see: one of Ava's steps (a "tool call" — her reading a file, running a command, and so on) shows a red error instead of finishing.

Click the failed tool call to see the error. Common causes: she tried to touch a file outside your project folder, which is blocked on purpose for your safety (this guard is called "path traversal" protection — it stops her wandering outside the folder you are working in); a command that needs to run in a different folder; or a file that got moved since Ava last looked at it. Tell her what went wrong — she will retry with corrections.

Memory not recalling

What you see: Ava cannot find something you are sure she should remember.

Memory works by meaning, not exact words (this is what "semantic" means). So "What did I decide about auth?" works better than "find my auth decision". If the memory is definitely there but not surfacing, open the memory browser and search — if it is not there, it was never saved in the first place.

Sign-in loops

What you see: you sign in, but Ava keeps asking you to sign in again — a loop that never lets you through.

The fix is to clear the saved sign-in details and start fresh: in the extension run "Ava: Sign Out" from the command palette, in the IDE use Settings → Account → Sign Out, in the CLI delete the file at ~/.ava/auth.json (a small sign-in file in a folder named .ava in your home directory). Then sign in again.

Token exhausted

What you see: a message that you are out of free usage for the month. ("Tokens" are how AI usage is measured — "exhausted" just means you have used up this month's free allowance.)

Free-tier monthly budget resets on the 1st of each month. Until then, switch to a BYOK provider (use your own API key) to keep working. Your account remains active — only the free platform-managed requests are paused.

Where logs live

A "log" is just a diary your computer keeps of what happened — useful when something breaks and you (or support) need to see the details.

When you need the raw picture — what tool was called, what information it got, what the AI service returned — the logs are plain text files in a folder on your computer at ~/.ava/logs/ (a folder named .ava in your home directory, with a logs folder inside it).

• ~/.ava/logs/session-<date>.log — per-session transcripts including tool calls, streamed responses, and errors.
• ~/.ava/logs/extension.log — VS Code extension host log. Activation failures, panel errors.
• ~/.ava/logs/ide.log — desktop IDE log. Sidecar process messages, Rust panics.
• ~/.ava/logs/cli.log — CLI REPL log.

In the extension, "Ava: Show Logs" in the command palette opens the relevant log in an editor tab. In the IDE, Settings → Diagnostics has a "Open Logs" button. The CLI can tail its own log with ava logs --follow.

Filing a support request

In plain terms: if something is wrong and the fixes above did not help, send us a message about it. The easiest way is to just ask Ava to do it for you.

If a problem is not covered by common errors, file a support ticket (send the support team a request for help). You can do it inside Ava (no form to fill out) or on the web.

From inside Ava

Ask her to file it. "Ava, can you file a support ticket about this?" She calls support_request, attaches the relevant session context (with credentials redacted), and sends it. Fastest path.

From the web

Visit ava-supernova.com/support. Pick a category (bug, feature, account, security, general) and describe what happened. Response within one working day.

What to include

• What you were trying to do.
• What actually happened.
• Which surface (extension, IDE, CLI, companion) and which version.
• Any error message or log excerpt. Redact credentials first.

Reporting security issues

In plain terms: if you have spotted a way Ava could be broken into or misused (a "vulnerability" — a security weakness), please tell us privately first so we can fix it before anyone can take advantage. This page is how.

Found a vulnerability? Thank you. We take every report seriously and work with you on the fix before any public disclosure (before the problem is announced publicly).

How to report

1. Email security@ava-supernova.com with a description, reproduction steps, and your preferred disclosure window.
2. Or file a support ticket with category "security" — same triage queue.
3. We acknowledge within 24 hours.

Our commitments

• Coordinated disclosure — we agree a timeline with you before anything is public. Default is 90 days.
• Credit — you are credited in the fix notes unless you prefer anonymity.
• No legal retaliation — good-faith research is welcome. We will not send lawyers after you.