Everything about Ava Supernova

What is Ava?

Ava is an AI that actually does things — not just talks. She'll build you an app, write you a document, teach you something from scratch, design you a logo, or take care of the admin you keep putting off. And she remembers you: what you're working on, how you like things, what you asked for last week.

There's one Ava, and she works wherever you do — in your code editor, as a desktop app, on your phone, or in a terminal. Same memory, same personality, everywhere.

What makes her different

• Yours by default. Your work stays on your own machine. No tracking, no telemetry — ever.
• Open for anyone to see. Every line of Ava is public. Nothing to take on trust.
• Free to start. 300 credits every month, no card, no catch — or plug in your own AI keys and pay us nothing at all.
• Teaching built in. Ask Ava to teach you any subject and she builds you a real course — lessons, examples, and quizzes.

Never written code? The next page is written just for you. Already technical? Skip ahead — she'll keep up.

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.
• 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 thing with Ava

The fastest way to get Ava is to ask her for something real and watch her do it. No setup to read, nothing to learn first — just tell her what you want, in plain words.

Try this now

1. Open the chat.
2. Type something you actually want. Try "explain what this project does", or "add a button that clears the form".
3. Ava shows you what she's about to do — and waits.
4. Happy with it? Say yes. Watch her do it.

That's the whole rhythm: you ask, she shows you the plan, you approve, she does it. She never changes anything without showing you first — so you can't break anything by trying.

A few things worth asking for

• A question — "why is my page blank?", "what does this file do?"
• Something built — "make me a simple to-do list page".
• To learn something — "teach me Python from scratch". She builds you a real course, step by step.
• A document — "write me a one-page project proposal". She'll hand you a Word file or PDF.

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 300 free credits a month on platform-managed models (Qwen, DeepSeek, Mistral) 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.

Do I need to choose an AI?

Here's a relief: you don't pick the AI. Ava chooses the right one for each step automatically, so you get good results without having to think about it.

The one thing you can choose is a routing style — and the default suits almost everyone. You only need the others for a specific reason.

The three styles

• Maestro — the default. Steady, reliable, predictable. Not sure? This is the one.
• Supernova — for heavy, multi-step work, where it pays to put a different specialist on each part of the job.
• Aurora — for when your data must stay in the EU (public sector, healthcare, strict privacy). Runs entirely on European, open-weight AI.

Switch any time from the model picker at the top of the chat. Nothing's locked in.

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.

You pick one of three styles — Maestro, Supernova, or Aurora — and Ava sends each piece of work to the model that handles it best. Maestro is the default, it is live on every plan, and it is a good choice for almost everyone.

Why bother routing?

Putting the right model on each step costs less than running everything on one big expensive model — and gives better results, because each model does what it is best at. You get steady cost and high quality without ever needing to know which model is which.

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.7 Plus or Supernova routes it to V4 Pro.

Plans

Every plan has access to every feature — model access, Creative Studio, all seven 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. Creative Studio.
• Video generation — 150 credits (720p), 300 at 1080p. Creative Studio, via Wan.
• Voice generation — 10 credits. Creative Studio, via Qwen3-TTS.
• 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.)

Each model carries a multiplier that scales an action's cost to track what that model actually costs to run — lighter models cost less than the flat bracket, heavier ones more. Calibrated for ~40% net margin (rebalanced down from 55% so more of the value flows back to you).

• 4.25× — Mistral Medium 3.5 (Aurora's lead coordinator), at its $1.50/$7.50 frontier-flagship rate.
• 1.25× — Mistral Large 3 (Aurora's heavy reserve).
• 1.15× — Mistral Small 4 (Aurora's high-volume workhorse), at its real $0.15/$0.60 rate.
• 0.9× — DeepSeek V4 Pro (Supernova coordinator), at its corrected $0.435/$0.87 rate (was over-charged against a 4×-inflated price).
• 0.7× — Qwen 3.7 Plus (Maestro coordinator).
• 0.6× — Qwen 3.5 Plus, Qwen 3.5 Omni Plus.
• 0.5× — DeepSeek V4 Flash.
• 0.4× — Qwen 3.5 Omni Flash.
• 0.3× — Qwen 3.5 Flash.
• 1.0× — any model without a listed multiplier. Base 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.

Modes — Ava's states of mind

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 → Code (>>). 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. Available on every plan. 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.
• I want to write a document → Write (<<). Reports, proposals, letters, articles — she drafts in Markdown and exports a branded Word doc or PDF, refining section by section. No code, just writing.

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, Code 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.

• 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 — your safety dial

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.

Steering and stopping Ava

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 Code 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, write, 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

The token figures above are the per-trajectory technical caps, not your monthly allowance — that's counted in credits, and the free tier's 300 a month comfortably covers a mix of chat, code, and a few automations.

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

In plain terms: describe the icon, image, video, or voiceover you want, and Ava designs it with you — no design software, no prompt-wrangling.

Creative Studio is a guided design workspace. It opens in three panes — the design types down the left, your canvas in the middle, and the controls for the piece you are working on down the right. There is no "generate" button to hunt for: you talk to the Design Architect (Ava, in her designer role) at the bottom of the screen, she runs the tools for you, and you refine with a few clear controls.

What you can make today

• Icons — the flagship. Start from a real line-icon shape (1,990 built in), choose a material and your brand colour, and Ava restyles it and cuts it to a clean transparent PNG.
• Images — free-form, from a description. Square, landscape, or portrait (1:1, 16:9, 9:16).
• Video — short AI clips from a prompt. 5 or 10 seconds, up to 1080p, in landscape, portrait, or square.
• Voiceovers — text to natural speech, with a waveform preview. Ten voices across ten languages.
• Brand Kit — your palette, kept to hand so every asset stays on-brand.

More design types — app icons, logos, badges, avatars, banners, hero and social images, illustrations, patterns, and a full game-dev set — are being brought over, and show as "soon" in the left rail.

What powers it

Icons and images are generated with Qwen-Image, video with Wan, and voiceovers with Qwen3-TTS. Anything you make lands in your Library, filed under the type you made it in.

Creative Studio is not a paid add-on — it is available on every plan, Free included. Generations draw from your normal credit pool, the same one number as the rest of Ava.

Health & Nutrition

In plain terms: tell Ava your goal and what you have to work with, and she builds you a real workout and meal plan — then helps you follow it, day by day.

Health & Nutrition is a focused room in the dashboard. Ava asks a few things about you — your goal, your equipment, any limits — then draws on a real library of exercises and recipes to build a plan that fits. Plans can be fitness, meal, or both together.

How it works

1. Ava asks about your goal and setup through simple controls — goal cards, equipment chips, a number box — not a wall of questions.
2. She builds a multi-week plan from the catalogue, one you can actually do with what you have.
3. You follow it day by day; Ava can fill in or adjust any single day as things change.

Everything is saved to your local plan library, on your own machine. The recipe and exercise catalogues are real, curated content — not made up on the fly.

Learning

In plain terms: ask Ava to teach you something and she builds you a proper course — lessons, worked examples, and quizzes — then walks you through it at your own pace.

Learning is a focused room in the dashboard. Ava plans a curriculum for what you want to learn, teaches it lesson by lesson, checks your understanding with quizzes, and tracks what you have covered so you can pick up where you left off.

How it works

1. Tell Ava a topic — "teach me Python from scratch", or "help me understand databases".
2. She builds a structured course: modules, lessons, and checkpoints.
3. You learn one lesson at a time; she explains, gives examples, and quizzes you to make it stick.
4. Your progress is saved, so the next session starts where you stopped.

Underneath, this is Teach mode — a small team of specialists (a curriculum architect, a content writer, a fact checker, a quiz master, and a tutor) that Ava coordinates for you.

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.

Library

In plain terms: one shelf for the things you keep — the papers you are reading, the assets you have made, and the documents you have written — so nothing gets lost.

The Library is a browsable dashboard with three tabs:

• Papers — scientific papers you have saved, fetched from arXiv, OpenAlex, and Crossref, with the full text to read inline.
• Assets — everything you have made in Creative Studio, sorted by the same design types you made them in (Open Canvas, Web / App, Game Dev). Filter by group, then by type; each type shows how many you have.
• Documents — the Word, Excel, PDF, and other files Ava has written with you, filterable by where they live (local or synced) and what they are.

A storage bar across the top shows how much space your local files use, and an "Open save folder" button drops you straight into the folder on disk. It is local-first — the Library reads what is on your own machine.

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.