The MaeVae guide

1

What you need

Make sure your computer can run MaeVae, and install at least one agent’s command-line tool, before the first start.

MaeVae is the console; the agents are separate programs from their own vendors. MaeVae drives the agent command-line tools you already have and bundles none, and it holds no agent account of its own: each profile uses your own account with the agent’s vendor. So you need three things: 64-bit Windows 11 or 10, Microsoft Edge WebView2, and one agent’s tool that Windows can find.

Check Windows and Microsoft Edge WebView2

MaeVae is made for Windows 11, 64-bit. Windows 10, 64-bit, version 2004 or later, also works. MaeVae’s window is drawn by Microsoft Edge WebView2, the part of Windows that shows web content inside an app, and it is built into Windows 11.

1. Open Windows Settings › System › About.
2. Under Device specifications, System type should read 64-bit operating system.
3. Under Windows specifications, Edition should name Windows 11 or Windows 10. On Windows 10, Version should read 2004 or later (20H2, 21H1, 21H2 and 22H2 are all later).
4. On Windows 11, WebView2 needs nothing more. On Windows 10, open Settings › Apps and look in the list of installed apps for Microsoft Edge WebView2 Runtime; if it is not there, install the Microsoft Edge WebView2 Runtime from Microsoft before you start MaeVae.

At launch, the Microsoft Store version checks for the Runtime as it starts. If it is missing, MaeVae shows one box that says so and gives Microsoft’s WebView2 page, then closes; install the Runtime from there and start MaeVae again.

What you see: each line matches, and on Windows 10 the runtime is in the list of apps. These are Windows’ own pages, so they are not rendered here; the rendering shows what follows once all is right: MaeVae’s first window, its rail still empty.

Install an agent’s tool and check it

Before you start: a terminal, PowerShell or Command Prompt. The npm lines need npm, which comes with Node.js; aider’s line needs Python; Grok’s line is a PowerShell command.

1. Choose an agent and run its install line in the terminal. These are the lines MaeVae itself carries for each agent; the vendor’s own page is the place to check them.

   Claude Code

   npm install -g @anthropic-ai/claude-code

   claude --version

   Codex CLI

   npm install -g @openai/codex

   codex --version

   Gemini CLI

   npm install -g @google/gemini-cli

   gemini --version

   Qwen Code

   npm install -g @qwen-code/qwen-code@latest

   qwen --version

   aider

   python -m pip install aider-install && aider-install

   aider --version

   Grok CLI

   irm https://x.ai/cli/install.ps1 | iex

   grok --version

2. Close the terminal, open a new one, and run the tool’s name with --version, as in the third column. A version number means Windows finds the tool on your PATH.
3. Start MaeVae, or quit it from the tray and start it again if it was running: a tool installed while MaeVae runs may not be seen until MaeVae starts again.

Grok CLI here is xAI’s Grok. Groq, the inference cloud, is not an agent: a Qwen Code or aider profile reaches it through its Endpoint field, and a Codex CLI profile through its Model endpoint box (chapter 12). A profile can also be a plain shell, with no agent at all.

What you see: in New profile, an agent whose tool MaeVae cannot find on your PATH shows “(not installed)” after its name, with the line “Codex CLI isn’t on PATH.” and a Copy install command button, which copies that agent’s install line and opens the vendor’s own page. Once you have installed the tool and started MaeVae again, the mark is gone.

Limit. MaeVae cannot start a pane for an agent whose tool is missing; in the rail, that agent’s heading says “not installed”. Install the tool, check it with --version, then start MaeVae again.

2

Install from the Microsoft Store

Install MaeVae from the Microsoft Store, start it, and leave its updates to the Store.

MaeVae launches on 5 November 2026 on the Microsoft Store first. From launch, the Store installs it and keeps it up to date: there is no setup file to download, and nothing else to install for MaeVae itself apart from the WebView2 Runtime on a Windows 10 computer that lacks it (chapter 1). The agents’ tools are the separate step of chapter 1.

Open MaeVae’s page in the Microsoft Store and install it

1. Use the button below. It opens MaeVae’s listing in the Microsoft Store.
2. On MaeVae’s page, choose the Store’s install button.
3. Wait until the Store says MaeVae is installed. There is nothing to choose during the install and no second program to run.
4. To start MaeVae at once, use the Store’s own button to open it. Later, start it from the Start menu (the next task).

What you see: once the listing is public, MaeVae’s page in the Store; after the install, the Store’s own button to open MaeVae, and MaeVae in the Start menu. The Store is Microsoft’s own app and is not rendered here; the rendering shows what follows when you open MaeVae: its first window, and its icon in the tray at the right end of the taskbar.

Find MaeVae and start it

1. Open the Start menu and choose MaeVae.
2. MaeVae opens on its first window, and its icon appears in the tray at the right end of the taskbar.

What you see: the rail on the left says No profiles yet and offers + Add profile; the stage says Click a profile to open a session. Chapter 3 walks through the window.

Note. MaeVae runs one window at a time: starting it again brings the open window forward instead of opening a second one. If you closed the window, MaeVae is still in the tray, and its sessions are still running.

Let the Store keep it up to date

New versions of MaeVae arrive through the Microsoft Store, the way any Store app’s do; there is nothing to download by hand. Your profiles, settings and logins are not inside the app: MaeVae keeps them in MaeVae’s data folder in your Windows user folder, so an update leaves them as they are.

1. Leave MaeVae’s own updates to the Microsoft Store: nothing inside MaeVae updates the app itself.
2. To see what MaeVae does update, click Quick settings at the foot of the rail. Under Update agents are Update all installed and one button per agent’s tool, with Install before the name of an agent that is missing.

What you see: Quick settings open in the rail, its button now reading Close, and under Update agents the agents’ tools alone. MaeVae’s own new versions come from the Store.

Note. The Update agents buttons in Quick settings update the agents’ own tools, not MaeVae; see chapter 14.

3

Start MaeVae for the first time

Name every part of MaeVae’s window, fold the rail out of the way when you need room, and open New profile.

Get to know the window

MaeVae opens as one window without a Windows title bar of its own: the top of the rail carries the name, and the top bar carries the window’s buttons. Four parts matter at the start; the numbers match the marks on the rendering.

1. The rail, on the left, lists your profiles, grouped under each agent’s name. With none yet it says No profiles yet and offers + Add profile.
2. The stage holds the panes. While it is empty it says Click a profile to open a session, and under it, Each pane is a real terminal pinned to its own account and project.
3. Quick settings, at the foot of the rail, opens a panel in the rail with + Add profile and + Add agent, the app theme, Update agents, the Isolation checks, HUD and sound, the terminal, pets and pane notifications, Usage & cost, Data folder, Backup & restore… and Before uninstalling. While the panel is open, the button reads Close.
4. The top bar counts the open panes and carries the layout buttons, usage, Close all and the window’s own buttons (the top bar, below).

What you see: one window with nothing running yet. The top bar’s empty space moves the window when you drag it, as a title bar would.

Pin, fold or hide the rail

1. Press Ctrl+B, or click the small button at the top of the rail. The rail folds to a strip of lights, one per profile: collapsed.
2. Press Ctrl+B again. The rail slides out of the way and leaves a thin handle at the window’s left edge: auto-hide. Point at the handle and the rail slides back over the panes until you move away.
3. Press Ctrl+B a third time to pin it again. The button’s tooltip always says which mode the rail is in.
4. To make the pinned rail wider or narrower, drag its right edge; double-click the edge to reset it.

What you see: the panes take the room the rail gives up. While the rail is hidden, its handle turns amber and shows a dot with the initial of each profile that needs you (chapter 7).

Note. Toggle rail in the command palette does the same as Ctrl+B. While Quick settings or a profile’s editor is open, the rail stays out, since both open inside it.

Read the top bar

From left to right, the top bar holds these parts; some appear only when they can do something.

The count

0 open, 1 open and so on. At launch, after a restart it also counts the waiting places, for example 1 open · 2 waiting (chapter 17).

Show all (N)

At launch, only while one pane fills the window; it brings the others back (chapter 6).

layout

The three layout buttons: columns, rows and grid.

Broadcast to all panes

A box that appears once two or more panes run; a line typed there goes to every pane.

usage

Opens the usage dashboard (chapter 10).

panic

Appears while a pane runs; a second click stops every agent running in MaeVae (chapter 17).

Close all

Closes every pane and stops its agent, after asking.

The window’s buttons

Minimize, maximize and close, which hides the window to the tray while the sessions keep running.

What you see: with two panes running, every part is there; with none, the count reads 0 open and the Broadcast box and panic are gone. Each button’s tooltip says what it does, for example Close to tray, sessions keep running, on the window’s close button.

Start a new profile

1. Click + Add profile in the empty rail. Once you have profiles, the same button sits in Quick settings: click Quick settings at the foot of the rail, then + Add profile.
2. New profile opens over the window, which dims behind it, at Step 1 of 3.
3. To leave without a profile, click its close button, or anywhere on the dimmed window outside the panel.

What you see: New profile in three steps, Agent, Account and Project. Next stays grayed until the profile has a name; chapter 4 fills the steps in.

4

Make your first profile

Fill in New profile’s three steps, give the profile a color, open its pane, and finish the agent’s own first-run steps.

A profile is one identity: one agent, one account and one project folder. MaeVae gives each profile its own isolated configuration folder inside its data folder, so one profile’s login, billing and memory never mix with another’s. New profile asks for the three things in three steps: Agent, Account and Project.

Name the profile and pick its agent

Before you start: New profile is open at Step 1 of 3 (chapter 3).

1. Type a short Name, such as the project or the account the profile is for. The box shows alpha in gray until you type.
2. Pick the Agent: Claude Code, Codex CLI, Gemini CLI, Qwen Code, aider or Grok CLI. A tool MaeVae cannot find shows (not installed) after its name (chapter 1).
3. Click Next. It stays grayed until the profile has a name.

What you see: Step 2 of 3, Account, once you click Next.

Note. The steps make agent profiles. A profile with a plain shell and no agent is made with Advanced (all fields), at the foot of any step: in the full form the Agent list ends with Plain shell. More agents can be added from Quick settings, + Add agent.

Choose the account

1. For Claude Code, choose Fresh isolated account, which gets its own configuration folder and signs in on the first launch, or Use my existing Claude login, which shares the login your everyday Claude Code uses, with its history and memory.
2. For the other agents there is nothing to choose: each gets an isolated configuration folder of its own, and you sign in, or add an API key in the editor, on the first launch. aider has no configuration folder and no login: its API key is the account (chapter 5).
3. Type an Account label if you like, such as the email of the account, so you recognize it. For Claude Code, Codex CLI and Gemini CLI, MaeVae checks it against the real login and warns when the two differ.
4. Click Next.

What you see: Step 3 of 3, Project, once you click Next; Back returns to the step before.

Note. If you choose Use my existing Claude login, MaeVae shows a heads-up: once you turn on MaeVae’s HUD for that profile, MaeVae writes into the login folder your everyday Claude Code uses. Read chapter 18 before you ever uninstall.

Give the profile a color

New profile’s steps have no color; the full editor has one. Use Advanced (all fields), at the foot of any step, to carry what you typed into the full editor now, or set the color once the profile exists:

1. Click the pencil, Edit profile, on the profile’s entry in the rail. Its editor opens in the rail, under the profiles.
2. Under Colour, click a swatch, or the swatch marked + for a color of your own.
3. If you like, Name text colour and Account label colour tint the profile’s name and its account label in the rail and on its pane; each starts on a Default chip that keeps the theme’s color.
4. Click Save changes.

What you see: the profile’s light in the rail, the mark and the name on its pane, and the line under its pane’s header take the new color, so you can tell identities apart at a glance. The same editor holds an icon, a pane theme and more (chapter 16).

Set the project folder

1. On Step 3 of 3, Project, type the folder the agent should work in under Project folder. The gray ~/work/alpha (optional) is only a hint.
2. Leave it empty if you have none yet. An agent pane then starts in a scratch folder of the profile’s own, never in your home folder, because every agent also reads settings from the folder it starts in, and in your home folder those would be its shared ones.
3. Also make a CLI launcher starts ticked. Leave it ticked if you also want to open this profile outside MaeVae, from a launcher or a Windows Terminal tab (chapter 15); untick it if you do not.

What you see: the folder in the box, and the note that the first launch runs the agent’s own one-time setup in the pane.

Note. If a saved folder goes missing later, through a typo or an unplugged drive, the pane starts in the profile’s scratch folder and says so in its first line, and the editor shows a note under Project folder until you set one that exists. A Windows Terminal tab cannot fall back that way, so keep its folder in place.

Choose Trusted or Restricted

1. On the same step, for Claude Code, Codex CLI and Gemini CLI, Capability offers Trusted (full access) and Restricted (boxed to the project folder). Qwen Code, aider, Grok CLI and a plain shell have no Capability: Restricted mode exists for those three agents only.
2. Choose Restricted to keep the agent to its project folder and stop push and deploy commands. A note under the choice says what the box does for this agent, and that it needs a real project folder.
3. Leave Trusted for full access. You can change it later in the profile’s editor (chapter 8).

What you see: the note under Capability; the rendering shows its first sentences, and in the app it goes on to say what the box allows and denies for this agent.

Limit. Restricted mode works by a per-profile folder box and a deny list of command names, not by a sandbox. A deny list is a speed bump: a determined shell can reach the same binaries by another path. Every pane runs as the same Windows user, so the credential stores on the machine, such as git credential helpers, SSH keys and the tokens of hosting tools, are shared across panes. Treat it as a strong guardrail for cooperative agents, not as a security boundary against hostile code.

Create the profile and open its pane

1. Click Create & open.
2. MaeVae makes the profile with its own configuration folder, adds it to the rail under its agent’s name, and opens its pane. The top bar reads 1 open.
3. The agent starts in the pane by itself: Start agent automatically is on for every new profile.

What you see: the pane’s header shows the profile’s name, the agent and a gray Isolation badge. A new profile reads Unchecked until you approve what it has installed (chapter 9). Clicking the profile in the rail later opens its pane again.

Finish the agent’s own first-run steps

The first time a new profile’s pane opens, the agent runs its own one-time setup there. These are the agent’s screens, not MaeVae’s, and their words differ from agent to agent and from version to version. For Claude Code:

1. Pick a text style from the agent’s theme list.
2. Answer the agent’s question whether to trust the files in the project folder.
3. Sign in, which for Claude Code is a login in your browser (chapter 5).

What you see: once the setup is done, opening the pane starts the agent straight away. If a fresh pane seems to wait with a theme list or a trust question, it is this setup: complete it and the agent starts.

5

Sign in inside the pane

Sign each profile in to its own account, inside its own pane, check which account it uses, or give it an API key instead.

You sign in inside the pane, in the agent’s own login, the same way you would in a terminal of your own. MaeVae never asks for your password and never sees it. The login the agent saves stays in that profile’s own configuration folder, apart from every other profile’s.

Follow the agent’s own sign-in

1. Click the profile in the rail to open its pane; the agent starts in it.
2. Follow the agent’s own sign-in in the pane. Each agent signs in its own way:

   Claude Code

   Signs in through your browser during its first-run setup.

   Codex CLI

   Run it in its pane and sign in, or set an API key in the profile’s editor.

   Gemini CLI

   Set a Gemini API key from Google AI Studio in the profile’s editor. Google’s own sign-in in the pane works only with a Workspace Code Assist license.

   Qwen Code

   Works with an API key, an Endpoint and a Model, and needs all three to use the endpoint (chapter 12). For Alibaba’s own sign-in, run /auth in its pane instead.

   aider

   Has no login: its API key, set in the profile, is the account.

   Grok CLI

   Run grok in its pane and sign in, or set an xAI API key.

3. When the agent says you are signed in, the profile keeps that login in its own configuration folder; the next time the pane opens, the agent starts signed in.

What you see: a small green dot after the profile’s name in the rail marks a profile that is signed in. The rail reads those dots each time it refreshes its list, for example when a pane opens or exits, so a new sign-in shows its dot at the next refresh, not at once.

Check which account a profile is signed in as

1. Click the pencil, Edit profile, on the profile’s rail entry.
2. Read the Account line in the editor: signed in as, then the account, or not signed in.
3. If the account differs from the profile’s Account label, the editor offers Use “…” as the label, with the account in the quotes; click it to make the label match, then Save changes.

What you see: MaeVae reads which account the profile’s folder is signed in to and shows it; the password stays inside the agent’s own login, where you typed it.

Limit. Two features you turn on yourself keep a copy of the login token: the account switcher (chapter 11) and a backup with Include account logins ticked (chapter 13). The HUD’s quota reader also reads the token, in memory, to ask the vendor’s usage service for the figures (chapter 10).

Use an API key instead of a login

1. Open the profile’s editor with the pencil, Edit profile.
2. Set Authentication to API key. Claude Code, Codex CLI, Gemini CLI, Qwen Code and Grok CLI offer both; aider has only a key.
3. Paste the key into the API key box. While it is empty the box says paste key; once a key is stored it says so, and a new key typed there replaces it.
4. Click Save changes.

What you see: MaeVae keeps the key in the Windows Credential Manager, never in a file, and gives it to this profile’s pane only. A second small dot after the profile’s name in the rail marks a stored key; Remove saved key, under the box, takes it away again.

Note. A launcher or Windows Terminal tab of a profile in API-key mode carries no key and falls back to whatever login its folder holds, so use the pane, which injects the key. aider’s launcher is the exception: it reads the saved key each time it runs (chapter 15). A backup copies keys only when you tick Include API keys (chapter 13).

6

Work side by side

Run several agents at once: open more profiles, arrange their panes, at launch let one fill the window, move between them from the keyboard, send one line to all of them, write in a compose box, and review what an agent changed.

Open a second profile beside the first

1. Make a second profile as in chapter 4, or click one already in the rail.
2. Its pane opens beside the first. Each pane is a real terminal with its own agent, account and project folder.
3. The top bar now reads 2 open, the Broadcast to all panes box appears, and, at launch, each pane’s header gains the fill button.

What you see: two panes, each with its own agent at work, and the profile’s light on in the rail for each.

Note. A profile can run in more than one pane: click it again while its pane is open and a second pane of it opens. The two share the profile’s HUD figures and its attention light, which MaeVae keeps per profile. At launch, a new pane always shows every pane, even if one filled the window.

Switch the layout: columns, rows or grid

1. In the top bar, after the word layout, click one of the three buttons: columns, rows or grid. Each button’s tooltip names its layout, for example Side-by-side columns.
2. In the grid, the panes fill the space whatever their number; with three, the last one spans the row.
3. The Layout actions of the command palette do the same.

What you see: the same panes, still running, in the new arrangement. At launch, choosing a layout also shows every pane again if one filled the window.

Note. At launch, the arrangement is remembered: which panes are open, their order and sizes, the layout and the pane that fills the window are saved as you change them, and come back after MaeVae starts again (chapter 17).

Drag a gutter or a divider

1. Point at the line between two columns or two rows, the gutter, or at a divider of the grid.
2. Drag it. The panes refit as you drag, and neither pane of the pair can be squeezed below a small share of their room.
3. To change the order of the panes, drag a pane by the grip at the left of its header, or use the two arrow buttons in its header, which move it one place earlier or later.

What you see: the panes at their new sizes, and each terminal refitted to its pane. At launch, the sizes are saved with the rest of the arrangement once you let go.

Note. The rail has an edge of its own: while it is pinned, drag its right edge to make it wider or narrower, and double-click the edge to reset it.

Let one pane fill the window, then bring the others back

At launch: this task is part of the Microsoft Store version of MaeVae.

1. With two or more panes open, click the fill button in a pane’s header, press Alt+0, or choose Maximise pane in the command palette.
2. That pane fills the window. The others are hidden, not closed: their agents keep running.
3. To bring them back, click Show all (3) in the top bar (the number is the count of panes), press Alt+0 again, choose Show all panes in the palette, or click the same header button, which now shows the grid’s sign.

What you see: while one pane fills the window, its header button shows the grid’s sign and the top bar shows Show all with the number of panes.

Note. While panes are hidden, Show all also carries a count of the hidden panes that need you, so an approval behind the full pane is not missed. Opening a new pane, or choosing a layout, shows every pane again too.

Move between panes from the keyboard

Alt+1 to Alt+9

Move the keyboard to pane 1 to 9. At launch, while one pane fills the window, Alt and a number makes that pane fill it instead.

Alt+0

At launch: the pane that has the keyboard (the first, if none has it) fills the window; pressed again, every pane shows.

Ctrl+K

Opens or closes the command palette.

Ctrl+B

Pins, folds or hides the rail.

Ctrl and the mouse wheel

Makes a pane’s text smaller or larger; the two text-size buttons in its header do the same.

Ctrl+Shift+F

Searches the pane’s scrollback.

Ctrl+V

Pastes, once per press (on by default); Ctrl+Shift+V, a right-click and Shift+Insert paste too, and selecting text copies it.

1. Press Alt+2: the keyboard moves to pane 2, which shows a thin ring in its profile’s color.
2. At launch, press Alt+0: pane 2 fills the window. Press Alt+3: pane 3 fills it instead.
3. At launch, press Alt+0 again: every pane shows, and the keyboard stays in pane 3.

What you see: the pane with the keyboard carries a thin ring in its profile’s color.

Note. Only the number keys of the top row count: Alt with the number pad still types a Windows Alt code. While the keyboard is in a text box, such as an editor field or the Broadcast box, Alt and a number stay with the box. At launch, on a waiting place after a restart the keyboard lands on the place itself, so Enter starts nothing.

Run an action from the command palette

1. Press Ctrl+K. The palette opens near the top of the window, with the cursor in its box, which says Search commands.
2. Type a few letters. The list keeps the actions whose name or key hint contains them.
3. Move with the arrow keys and press Enter to run the highlighted action, or click it. Esc closes the palette.

What you see: the actions of the palette, in this order: Open, for each profile, with its agent as the hint; Jump to pane, for each pane, with its Alt key; at launch, Maximise pane, or Show all panes while one fills the window; the three layouts; Usage & cost dashboard; Toggle rail; Close all panes; and Theme, for each theme.

Send one line to every pane

1. With two or more panes running, click the Broadcast to all panes box in the top bar.
2. Type a line and press Enter. The line goes to every open pane at once, as if typed there and followed by Enter, and the box empties.

What you see: the line at each pane’s prompt and each agent’s own answer, in its own words.

Limit. The line reaches every pane, the panes of Restricted profiles included, so read it before you press Enter. At launch, a waiting place after a restart receives nothing: it has no session.

Write a prompt in the compose box

1. Open Quick settings and, under Compose box, click Customize compose box….
2. Tick Show a compose box on panes. Under Corrections, Autocorrect common typos when you send and Dictionary (spelling suggestions as you type) work offline; Your own dictionary takes words of your own.
3. Click Save.
4. Type a prompt in the box at the bottom of a pane and press Enter to send it to the pane; Shift+Enter starts a new line.

What you see: the prompt in the pane, corrected when Autocorrect is ticked, as if you had typed it there. The box never touches what you type straight into the terminal.

Redraw a pane that shows leftover characters

1. If a resize leaves stray characters on a pane, click its Redraw button, the circular arrow in the pane’s header.
2. MaeVae nudges the program in the pane to repaint its terminal.

What you see: the pane repainted, with only the agent’s current screen in it.

Note. A Gemini pane that draws on the normal screen also gets Gemini’s own clear-screen key, which Gemini ignores until something has been typed in the pane, so a faint copy may stay above. MaeVae turns on Gemini’s alternate screen for every new Gemini profile, and there the nudge alone repaints cleanly; for an older profile, Draw on the alternate screen is in its editor and takes effect when the pane next opens.

Review what an agent changed, then keep it or drop it

Before you start: the profile has a project folder that is a git repository. review stands in the header of every profile with a project folder; for a folder that is not a repository, the panel says so. Some renderings in this guide leave review out of a pane’s header where their task does not need it.

1. Read the branch chip after the agent’s label in the pane’s header: the branch of the project folder, a dot while there are uncommitted changes, and how many commits it is ahead of or behind its upstream.
2. Click review in the pane’s header. The review panel opens over the pane; its head reads Review changes, with the branch and the number of changed files.
3. Read the changed files, each with its git status, then the summary of the lines changed and the changes themselves.
4. To keep the changes, type a message in the Commit message box and click Commit all, or press Enter in the box. The button stays grayed until there is a message.
5. To drop them instead, click Discard, then click it again while it reads “sure? reverts tracked”.
6. Close the panel with the close mark at its top right; the pane is back as it was.

What you see: after Commit all, git’s own summary of the new commit under the changes, and the panel then reads “No uncommitted changes in the project folder.” After Discard, it reads “Reverted tracked files to the last commit (new untracked files kept).”

Limit. Commit all stages every change in the project folder, yours as well as the agent’s, and commits it with the repository’s own settings and hooks, so read the list first. Discard puts only the tracked files back to the last commit: a new file the agent wrote stays, and in a repository with no commit yet there is nothing to go back to.

7

When an agent needs you

Turn the attention queue on for each profile, know every place it tells you, answer from the pane, and do the one-time step Codex and Gemini need first.

When an agent asks for an approval, or finishes a turn, MaeVae lights its pane, badges the tray icon, and can raise a Windows notification and a chime. All of it rides on attention events the agent sends through hooks MaeVae sets up for that profile, so the first task turns them on.

Turn the glow on and watch a pane light up

Before you start: the profile’s editor is at hand (the pencil on its rail entry). An agent reads its hooks when it starts, so a pane opened before this step needs to be opened again.

1. Claude Code: click hud on the profile’s rail entry. It turns on the HUD and the attention hooks together, written into that profile’s own settings beside anything you added there. The editor’s Attention hooks button turns the attention part off and on by itself.
2. Codex CLI, Gemini CLI, Qwen Code and Grok CLI: click Enable attention glow in the profile’s editor. The button then reads Attention glow: on, and MaeVae has written its hooks into that profile’s own settings, beside any hooks of yours.
3. aider: nothing to do. The glow is on from the start, and only ever green, because aider never asks for an approval through MaeVae.
4. Close the profile’s pane and open it again, so the agent reads its new hooks.

What you see: a waiting pane lights amber and its header says waiting; a pane whose turn has finished lights green and says done, or waiting for you when Claude Code sits at its prompt. The profile’s light in the rail takes the same color. Click the pane to clear the mark.

Note. For a Claude profile that shares your everyday login folder, hud asks for a second click first, because it changes your everyday Claude Code too. Codex and Gemini each need one more step inside the agent before their glow works: see Codex’s and Gemini’s tasks below.

Find a waiting agent from the tray

1. Look at MaeVae’s icon in the tray. While any pane waits for you it carries an amber dot, and so does MaeVae’s button on the taskbar; the icon’s tooltip says how many wait.
2. Double-click the tray icon, or open its menu and choose Show MaeVae, to bring the window forward.
3. Find the amber pane. If the rail is hidden, its handle has turned amber and shows a dot with the initial of each profile that needs you.

What you see: the dot on the tray icon and on the taskbar button stays until nothing waits any more.

Get a Windows notification

While MaeVae’s window is not the one you are working in, an agent that needs your approval or has finished a turn also raises a Windows notification. Its title names the profile, for example “Research needs approval” or “Research finished”; its text is the agent’s own message or, when the agent sent none, “Waiting for your go-ahead.” or “Turn complete.” While the window is in front of you, the glow is enough, so none is sent.

1. Nothing to turn on: the notification follows the attention events of the first task.
2. If none arrives, open Windows Settings › System › Notifications: Notifications must be on and Do not disturb off, and MaeVae must be on in the list of apps once it has appeared there.

What you see: the notification in the corner of the screen, where Windows puts it; MaeVae sends one per event, not one per minute.

Limit. Windows decides whether a notification is shown. The notification editor of the last task asks Windows the same question and says so under its check boxes when Windows will not deliver one.

Turn on a chime

1. Open the profile’s editor with the pencil, Edit profile.
2. Tick Notification chime. A list of chimes appears: open it and point at a chime to hear it, or press Preview.
3. Click Save changes.

What you see: from now on the chime sounds once for each event, an approval needed or a turn finished, whether or not you are looking at that pane. It plays through Windows audio, so it sounds even while MaeVae is hidden in the tray, though Windows may then hold it back for up to about a minute.

Note. Mute all notification chimes, in Quick settings under HUD and sound, silences every profile at once. The editor offers the chime only for the agents that send attention events, and it needs them on, as in the first task. If Preview is audible but the chimes are not, Windows is sending MaeVae’s sound to another output: open the Volume mixer and set MaeVae’s output device to your speakers or to Default.

Limit. A profile you started in a Windows Terminal tab does not chime: MaeVae only hears its own panes.

Approve or deny from the pane’s header

1. When a pane lights amber and its header says waiting, read the agent’s question in the pane.
2. Click approve to send Enter, which picks the option the agent has highlighted, or deny to send Esc.
3. The light clears and the agent carries on with your answer.

What you see: the agent’s next lines in the pane, and the profile’s light in the rail back to its own color.

Note. The buttons appear only on the pane whose agent asked. Codex’s hooks cannot say which pane that is, so with two Codex panes of one profile open, an approval may belong to the other one; the buttons’ tooltip says so. An agent started outside MaeVae, in a Windows Terminal tab or from a launcher, can be mirrored on its profile’s pane, marked · outside, but without approve and deny: answer it in that terminal.

Trust MaeVae’s hooks in Codex, once

Before you start: Enable attention glow is on for the Codex profile, and its pane has been opened again since.

1. In the Codex profile’s pane, type /hooks.
2. Codex shows its hooks. Trust MaeVae’s two, PermissionRequest and Stop.
3. Ask the agent for something that needs an approval: the pane now lights amber.

What you see: from then on the Codex pane lights and chimes. Codex asks again whenever the hooks’ text changes, after a MaeVae update for instance.

Limit. Until this step is done the pane never glows or chimes for that profile, and Codex shows Hook failed under its reply if a hook cannot run.

Let Gemini load the hooks

Before you start: Enable attention glow is on for the Gemini profile, and its pane has been opened again since.

1. In the Gemini profile’s pane, trust the project folder Gemini opened in, when Gemini offers it. Gemini loads hooks only in a folder it trusts.
2. Type /hooks panel to see MaeVae’s two hooks listed, and on.

What you see: the two hooks, on. MaeVae’s hooks need no trust of their own in Gemini: the folder’s trust is the one step.

Limit. Until Gemini trusts the folder, the pane never glows or chimes for that profile.

Choose how a pane signals

1. Open Quick settings and click Customize pane notifications…, or, for one profile, Customize for this profile… in its editor.
2. Under Behaviour, pick a Style: Pulsing border ring, Steady glow border, Flash then settle, Corner dot, Full-pane tint, Blink, or Off (left rail only). Intensity and Speed set its strength and pace.
3. Under States & colours, tick the states that signal: Needs approval, Waiting / finished and Working (off at first). Give each a color, and tick OS toast for a Windows notification whenever a pane enters that state.
4. Click Save.

What you see: the panel previews the style as you change it, and any open pane of the profile shows it live. Off (left rail only) keeps only the rail’s light.

Note. An OS toast ticked here fires when a pane enters that state, apart from the notification of the third task, and never while this panel is open. Also mirror this profile’s Windows Terminal / launcher sessions on its pane, on at first, lets a pane show what its profile’s agent does in a Windows Terminal tab, marked · outside.

10

The HUD and the usage dashboard

Read the figures each agent reports, in its pane and in the usage dashboard, turn the HUD on for a Claude profile, get a warning before a limit, and find out why a figure is missing.

Each pane can show what its agent reports about itself: the model, the cost, the tokens, the quota and the context, as far as that agent writes them down.

Read the figures in a pane

Before you start: for a Claude profile, the HUD is on (see Turn the HUD on for a Claude profile). Codex CLI, Gemini CLI, Qwen Code, Grok CLI and aider panes fill it out of the box, from files the agent writes itself as it works.

1. Read the pane’s header. After the agent’s label it shows the model in a frame, the cost (for example $1.86), the tokens (Σ 184.0k), the 5-hour and weekly quota (5h 31%, wk 46%) and the context gauge with its percent. A figure the agent does not report is simply left out of the header.
2. For a strip under every pane, open Quick settings, go to HUD & sound and tick Chrome HUD. Tick Place it above the terminal (else below) if you want it on top.
3. Read the strip: the state word (working, waiting, done or idle), the profile’s name and the agent, then Model:, Ctx Used: and Up: (how long the pane has been open). That is the strip as it comes; Customize chrome strip… adds Cost:, Total:, Weekly:, Context: with its gauge, and more.
4. Watch the context gauge: it turns amber above 65 percent and red above 85.

What you see: the header and the strip show the same figures. The strip names each one (Model:, Cost:, Total:), and a figure the agent does not report is grayed out, with a dash in its place; the renderings in this guide write n/a instead. The strips rendered here are customized to show Cost:, Total:, Weekly: and Context:; as it comes, the strip shows Model:, Ctx Used: and Up:.

Note. The quota figures of a Claude profile are read with that profile’s own sign-in from Claude’s usage endpoint, which is not an official one. They are kept for about a minute and simply stay away if the call fails.

Open the usage dashboard

1. Click usage in the top bar. Usage & cost in Quick settings and Usage & cost dashboard in the command palette (Ctrl+K) open the same panel.
2. Read one row per profile: Profile (with “live” while a pane is open), Model, Cost, Σ tok, In / Out / Cached, Ctx, Weekly, 5h, ±lines, Updated and Rotation.
3. Read the last row: the total cost and tokens, and how many profiles are live.
4. Close it with ✕ or Esc.

What you see: the current or most recent session of each profile. Weekly and 5h carry a countdown to their reset; a cell turns amber near the limit and red at it. Every figure is measured from the agents’ own files on disk. It is not a bill.

Note. Claude accounts that share a Rotation group (a field in the profile editor) form a pool. When one reaches its limit, its row offers Rotate → to the account in the group with the most room left.

Turn the HUD on for a Claude profile

1. Rest the pointer on the profile’s entry in the rail. Its small buttons appear at the right: the grip, ✎, hud and ✕.
2. Click hud. MaeVae registers itself as that profile’s status line and attention hooks, merged into the profile’s own settings, without overwriting anything you added there.
3. Open the profile’s pane, or close it and open it again. Claude’s own status line at the foot of the terminal now shows the model, the cost, the session time, the lines changed, the tokens, the 5-hour and weekly quota with their reset countdowns, and a context gauge. The pane’s header mirrors it.
4. To turn it off, click hud again.

What you see: the hud button stays lit while the HUD is on. The same click turns on the profile’s attention hooks (the rail light, the approvals and the chime); the editor’s Attention hooks button turns those off on their own, and the HUD keeps working.

Note. A profile that uses the same login folder as your everyday claude asks for two clicks (the button reads “sure?” first), because turning the HUD on there also changes plain claude.

Get a warning before a limit

At launch: this task is part of the Microsoft Store version of MaeVae.

1. Open Quick settings and find Quota warnings.
2. Set Warn at to a percent; it starts at 85. MaeVae warns once when any quota window a profile reports, the session one or the weekly one, reaches it.
3. Tick Tell me when a spent quota renews for a notice when a window that reached 100 percent can be used again. It is off at first.
4. For one profile, click ✎ on its rail entry and set Quota warning at %. At 0 the profile follows the line in Quick settings.
5. With a percent of its own, the profile also offers Hard stop: tick it to block new agents of that profile once its weekly quota reaches that percent. Its own Tell me when a spent quota renews follows Quick settings, or is set on or off.
6. In the profile’s editor, click Save changes. The two Quick settings take effect as you change them.

What you see: one warning for each quota window as it reaches the line. A profile’s own line is also its weekly limit: at that percent the usage dashboard shows its weekly figure in red. The figures are measured quota use, not billed dollars.

Limit. A warning needs a quota figure, so it works only for an agent that reports one (see What each agent reports, below).

Find out why a figure is missing

1. Find the grayed figure. In the strip and the usage dashboard the app shows a dash in its place (the renderings in this guide write n/a); in the header it is left out.
2. Rest the pointer on it. Its tooltip gives one of three reasons:
   • “This agent reports no figure for this chip”: the vendor’s gap, not a fault.
   • “No fresh telemetry from this pane yet”: the agent wrote nothing in the last three minutes. This is a pane before its first prompt, or one idle since.
   • “No data source for this vendor yet”: a plain shell or a local-model pane, which MaeVae reads nothing for.
3. If the whole strip is gray, send the agent a prompt: the figures fill in after it, unless the pane is a plain shell or a local-model pane.

Claude Code reports every figure; Codex, Gemini CLI, Qwen Code, Grok and aider each leave out some of the cost, the quota and the context gauge. What each agent reports, side by side, on MaeVae and the AI vendors.

11

A second account of one agent

Add a second account to a Claude profile, switch between its accounts, and know where the switcher works and where it does not.

One Claude profile can hold more than one saved login, so the same project folder can run under another account without a second profile.

Add a second account to a Claude profile

Before you start: a Claude Code profile that signs in with its login (Authentication: Sign in, in the pane). The switcher is opt-in, and it keeps a copy of each saved login token in MaeVae’s data folder.

1. Click ✎ on the profile’s rail entry. Its Account box says “signed in as” and names the current account.
2. Click Save this login, so the current account is kept.
3. Click Add another account. It asks for a second click (“Click again”); click it. MaeVae saves the current login, closes the profile’s panes, signs the profile out, and opens a fresh pane.
4. Sign in inside that pane as the other account, in the agent’s own login.
5. Back in the editor, click Save this login again. Both accounts are listed now, the one in use marked “· active”.

What you see: both saved accounts in the Account box. When the signed-in account no longer matches the profile’s Account label, the editor offers Use “…” as the label.

Switch between saved accounts

1. Click ✎ on the profile’s rail entry.
2. Click Switch beside the account you want. With a pane open it asks “Restart pane?”; click it again.
3. MaeVae saves the current login first, closes the profile’s panes, puts the saved login back and reopens the pane, with no new sign-in.

What you see: the chosen account reads “· active”, and the Account box says it is signed in. Only the login changes: the project folder, the quota warning (chapter 10) and the restrictions stay as they were.

Note. With no pane open, Switch acts on the first click. If the agent does not start by itself in the reopened pane, start it there to run as the new account.

Know where the switcher works, and where it does not

1. Open the profile’s editor and look at its Account box. Where the switcher is not offered, a note in its place says why.
2. For a Claude profile in API-key mode with a key saved, the panes use that key and never read a swapped login, so the switcher is not offered. Set Authentication back to Sign in, or remove the saved key, to use saved accounts.
3. For a Codex CLI, Gemini CLI, Qwen Code or Grok CLI profile, the note says saved accounts are a Claude Code feature. Sign out still clears the profile’s stored login, so its next launch signs in fresh. An aider profile has no login at all: you change its account by replacing its key.

Refused while a pane is open: Sign out, a change of the profile’s configuration folder, a switch between Trusted and Restricted, a change to a Restricted profile’s project folder, a change to a Codex profile’s local endpoint, Remove MaeVae integration and Delete. Close the profile’s panes first: a running agent refreshes its token and would write the old login straight back.

Removing a saved account (its ✕, then “sure?”) deletes that stored login token for good. The live pane and the profile’s current login are not touched.

Limit. MaeVae guards only the panes it opened itself. An agent started from a Windows Terminal tab or a launcher, or a pane still starting, is not counted. When MaeVae sees recent activity from such a session, it warns you and asks you to confirm once more; it cannot stop that session, so close it yourself first.

Let an idle pane switch accounts at the rate limit

Before you start: two or more Claude Code profiles, each signed in to its own account and with its HUD switched on, with the same Rotation group in their editors.

1. In Quick settings, tick Auto-rotate at rate limit. It is off until you tick it. Switch at 5h usage then sets the five-hour use, from 50 to 100 percent and 100 to start with, at which an account counts as at its limit; the weekly window counts at the profile’s own quota warning, or else at 100 percent.

What you see: when a profile in the group reaches its limit while its one pane is idle or finished, MaeVae opens the profile in the group with the most room left if it is not open yet, closes the spent profile’s pane and says which profile it switched to. A pane that is working or waiting for your approval is never switched, and neither is a profile open in more than one pane.

12

Other models

Point a profile at another model server, list the models it offers, save a key, set up Groq, OpenRouter or a server of your own, and tell Grok from Groq.

Codex CLI, aider, Qwen Code and Grok CLI can talk to another model server through a profile’s endpoint: a cloud provider such as Groq or OpenRouter, or a server on your own computer.

Point a profile at another model server

Before you start: a Qwen Code, aider or Grok CLI profile, which have the Endpoint field, or a Codex CLI profile, which has its own Model endpoint box (see Use a model server on your own computer). Grok CLI has an Endpoint but no Model field and no List models.

1. Click ✎ on the profile’s rail entry.
2. Under Endpoint (local model, cloud provider or custom), pick a preset: Agent default (its own cloud), Ollama, LM Studio, llama.cpp, vLLM, LiteLLM proxy, Groq (cloud), OpenRouter (cloud) or Custom… The box under it takes the preset’s address, or any OpenAI-compatible address you type.
3. Or, at launch, in the Microsoft Store version: paste a key or a server’s address into the box at the top of the Endpoint section, Paste a key or a URL (Codex’s Model endpoint box has one too). MaeVae fills the fields below from it at once (typed text fills them on Enter), says in a gray line under the box what it did, and may list the server’s models as List models would. The box then empties, so a key never stays on screen.
4. Fill Model with an id the server offers (the next task lists them for you; Grok CLI has no Model field). Qwen Code uses an endpoint only when the key, the endpoint and the model are all set; with the Model blank it shows its own /auth picker instead, and the editor warns you in amber.
5. Click Save changes. The next pane of this profile uses that endpoint and model; the model is also given to its launcher and tab.

What you see: under the address, the preset’s own note (for Ollama: pull the model first). The pane uses the endpoint the next time it opens.

Note. A model picked with /model inside a Qwen pane is stored by Qwen and would win over the Model field, so each time a pane opens MaeVae sets it back to the profile’s Model when the two differ, and says so in a pane line.

List the models a server offers

1. With an endpoint set, click List models under the Model field (or under a Codex profile’s model box). Nothing is asked of the server until you click, or, at launch, until you paste an address into the Endpoint section’s Paste a key or a URL box.
2. MaeVae’s core sends one request to that endpoint, with the profile’s saved key or the key typed in the box, and to nowhere else.
3. Type in search ids to narrow the list; the count beside it says how many match.
4. Pick one with a click, or with the arrow keys and Enter. It fills the Model field (aider’s as openai/ and the id). Enter in the list never saves the profile, and the field stays yours to edit.

If it fails: an amber note under the button says what went wrong: the endpoint refused the key (401 or 403), wants a key (set API-key mode and save one first), has no /models (404: check the address; most servers want it to end in /v1), or cannot be reached.

Save an API key for a profile

Before you start: an agent that takes a key. Claude Code, Codex CLI, Gemini CLI, Qwen Code and Grok CLI offer a choice of sign-in or key; for aider the key is the account.

1. Click ✎ on the profile’s rail entry.
2. Set Authentication to API key. (An aider profile has no choice to make: it shows the API key box straight away.)
3. Paste the key into API key.
4. Click Save changes.

What you see: the key box shows that a key is saved, and Remove saved key appears under it. The key is stored in the Windows Credential Manager, never in a file, and handed to this profile’s panes only.

Note. A launcher or Windows Terminal tab of a profile in API-key mode carries no key; it falls back to whatever login the profile’s folder holds. Use the pane for such a profile, since the pane brings the saved key. aider is the exception: its launcher reads the key when it starts (see Give aider a launcher).

Use a Groq account

Before you start: a Groq account and a key from Groq’s console, and a Qwen Code, aider or Codex CLI profile. Groq (groq.com) is an inference cloud; it is not xAI’s Grok.

1. Set Authentication to API key and paste your Groq key.
2. Pick the endpoint preset Groq (cloud). The editor reminds you to use API-key mode with your own key and names the page where Groq issues it.
3. Fill Model: the editor offers the preset’s example id as a one-click “use” link, or click List models and pick one.
4. Click Save changes.

What you see: the next pane of this profile talks to Groq with your API key and the model you set.

Use OpenRouter

Before you start: an OpenRouter key, and a Qwen Code, aider or Codex CLI profile. One OpenRouter key reaches models from many vendors.

1. Save your OpenRouter key in the profile (API-key mode, or the API key box of an aider profile).
2. Pick the endpoint preset OpenRouter (cloud).
3. Click List models, search the ids, and pick one, for example qwen/qwen3-coder. For aider the field takes it as openai/qwen/qwen3-coder, since aider names an OpenAI-compatible route openai/ and the id; Qwen Code takes the id as listed.
4. Click Save changes.

What you see: the model id in aider’s form. The figures of an aider pane come from aider’s own chat history, and aider prints a cost only for a model whose rates it knows.

Use a model server on your own computer

Before you start: the server runs and has a model ready: for Ollama, pull the model first; for LM Studio, load a model in its local server tab.

1. For Qwen Code or aider, pick the server’s preset under Endpoint: Ollama, LM Studio, llama.cpp, vLLM or LiteLLM proxy. The address is filled for you. Local servers take a throwaway key, and the editor offers a one-click “use API-key mode with” the placeholder that server expects.
2. For Codex CLI, find Model endpoint (Codex) and tick Route this profile to a local, cloud or custom model server. Pick a preset (or type a base address) and fill the model the server offers.
3. Click List models to check the server answers, then Save changes.

What MaeVae writes for Codex: Codex does not read an endpoint from the environment, so MaeVae writes a model provider block into this profile’s own Codex configuration, never the shared one. Ticking the box switches the profile’s model to the endpoint; unticking it returns Codex to its default. A keyless local server such as Ollama or LM Studio needs no key; for a server that does, set the profile to API-key mode and save the key.

Limit. A change to a Codex profile’s local endpoint is refused while the profile has a pane open. Qwen Code shows no context gauge for a model set through the Model field, since Qwen does not know that model’s window.

Run Grok, xAI’s agent

1. Click + Add profile and pick Grok CLI as the Agent.
2. Click Next. Step 2 says the agent gets its own isolated folder and that you sign in on first launch, or add an API key in the editor.
3. Finish the steps, and in the new pane run grok and sign in, or set an xAI API key in the profile’s editor.

What you see: the new profile under a Grok CLI heading in the rail. Each Grok profile has its own home folder, which holds its login and its MCP tokens, so Sign out clears that one profile only.

Note. Grok here is xAI’s Grok, not Groq. For a Groq account, use the Groq preset on a Qwen Code, aider or Codex CLI profile (see Use a Groq account).

Note. Every Grok pane, launcher and tab runs with Grok’s Claude, Cursor and Codex compatibility switched off, so your Claude skills, commands and permission rules stay out of it. Grok still finds the plugins installed for Claude and has no setting to stop that; grok inspect in the pane lists what it picked up.

13

Backups

Make a backup, choose what goes in, restore one, and move MaeVae to another computer.

A backup is a zip, or a plain folder, of MaeVae’s own data: your profiles, settings and layouts, and, only if you tick them, your logins, your usage history and your API keys.

Make a backup

1. Open Quick settings and click Backup & restore…. The MaeVae Backup panel opens on its Back up tab.
2. In Backup folder, keep or type a folder outside MaeVae’s data folder, such as a USB drive or a synced folder. MaeVae refuses a folder inside its own data folder.
3. Under What to include, tick what you want (see the next task). Save as a single .zip is ticked out of the box; untick it for a plain folder you can browse.
4. Click Back up now. A progress line names the phase while it runs.

What you see: when it ends, the panel says where the backup was saved, and a short message counts the files and their size. A file that vanishes during the run is skipped and listed, rather than stopping the backup.

Limit. There is no cancel once a backup starts, so a large backup of the logins’ folders runs to its end.

Choose what the backup includes

1. Leave the boxes as they are for the essentials. Always included: your profiles and their settings, your agent definitions, the app settings, the global HUD layouts and each profile’s own status line, the layout of your panes, and the Windows Terminal tab icons you picked.
2. Tick Include account logins to carry the sign-ins with you: the profiles’ own configuration folders and the account switcher’s saved logins, every saved account and not only the active one.
3. Tick Include usage history for the HUD’s history, which rebuilds itself anyway.
4. Tick Include API keys to take the keys out of the Windows Credential Manager and into the backup.

What you see: a warning under each box that adds a secret. With logins or keys inside, the backup holds real credentials: keep it somewhere safe, and consider encrypting it yourself. Without the keys box, the panel lists the profiles whose API keys a file backup cannot capture.

Never included: live process state, half-written temporary files, and the agents’ own shared login folders, which are yours and not MaeVae’s.

Restore a backup

1. Open Quick settings, click Backup & restore…, and choose the Restore tab.
2. Point Backup folder at the folder that holds your backups. The list shows each one with its kind, its size, and whether it holds logins or API keys.
3. Pick one, then set Restore options: Restore account logins (ticked out of the box), Restore API keys (only onto profiles that exist here), and Overwrite existing files (left off, it keeps what is already here).
4. Click Restore selected.

What happens: each restored profile is pointed at this computer’s MaeVae data folder, even when the backup came from another Windows user. Sign-in files are replaced only as a set, the token and the account identity together. Launchers and Windows Terminal tabs that already exist are refreshed; no new ones are made. With Overwrite on, your current profile list and settings are copied aside first.

Move MaeVae to another computer

1. On the old computer, make a backup with Include account logins ticked (and Include API keys if your profiles use keys), into a folder you can carry or that syncs.
2. On the new computer, install MaeVae from the Microsoft Store (see Install from the Microsoft Store) and install the agent tools you use (see What you need).
3. Open Quick settings, click Backup & restore…, choose Restore, point it at the backup and click Restore selected.
4. If you use launchers or Windows Terminal tabs, re-create them from each profile’s editor: a restore refreshes only those that already exist on this computer.

What you see: the profiles in the rail, each pointed at the new computer’s data folder. Sign in again only where you left the logins out.

Limit. API keys are restored only for profiles that exist on this computer, and a backup without Include API keys holds none: enter those keys again in each profile’s editor.

14

Update an agent from inside MaeVae

Update an agent’s command-line tool from Quick settings, install a missing one, and read what the update came to.

MaeVae runs each agent’s own updater for you, one at a time, and says what came of it.

Update one agent

1. Open Quick settings. Under Update agents there is one button per agent: its name when it is installed, “Install” and its name when it is missing.
2. Click the agent’s button, for example Gemini CLI. While it runs the button says it is updating, and a Stop button appears.
3. Watch the notice at the bottom right: “Working” and “Updating Gemini CLI…” until the run ends, then the result.
4. Update all installed runs every installed agent’s updater in turn.

What you see: the notice’s tag and one headline per agent. The real headline also names the version before and after; the rendering leaves the numbers out.

Note. Only one update runs at a time, and each gets five minutes before MaeVae stops it and ends its process. Stop ends a run at once, and a stopped run never marks a healthy agent as broken.

See what a button runs, or install a missing agent

1. In Quick settings, under Update agents, rest the pointer on an agent’s button: its tooltip shows the exact command, beginning “Run:”.
2. For a missing agent, click Install and its name: it runs that agent’s install command. Missing: lists the agents that are not on your PATH. At launch, in the Microsoft Store version, Grok CLI is the exception: its Install shows its command with Copy, for you to run in PowerShell yourself.
3. If the agent still does not show as installed, restart MaeVae: a program installed into a new folder is seen only after a restart.

What each button runs: the agent’s own updater. Claude Code runs claude update; Codex CLI, Gemini CLI and Qwen Code run npm install -g with their own package; aider runs uv tool upgrade aider-chat; Grok CLI runs grok update. A version check runs around each update, and every run starts in a working folder of its own.

aider: before it runs anything, MaeVae checks that uv is on its PATH and owns the aider it would update. If not (aider installed with pip or pipx, for example), the notice says which as a Warning and nothing runs.

Grok CLI: its own update check is switched off inside MaeVae’s panes (it would install into the profile’s folder), so this button is the way to update Grok. A grok update typed in a pane still works too.

Read what an update came to

1. Read the notice’s tag: Done (it went through), Warning (it went through with something to read, or nothing ran and the headline says why) or Error (it failed, was stopped or timed out, or the agent no longer reports its version).
2. Click Details to read the command’s own output.
3. A Done notice goes away by itself after a few seconds. A Warning or an Error stays until you click Dismiss, or until the next notice takes its place.

What you see: one headline per agent, the tag beside it in words, so the color is never the only sign. The headline in the rendering is shortened; the app’s own continues with a pointer to the details.

Note. Gemini CLI and Qwen Code each ship one small native module built by an install script, and their update commands allow exactly that one script, so the updates keep working if npm starts blocking unreviewed scripts. A first Install keeps npm’s default, so it may show npm’s notice about them as a Warning.

If an agent no longer starts after an update, reinstall it with its own install command (see An agent broken by its own update).

15

Windows Terminal tabs and launchers

Write a launcher and a Windows Terminal tab for a profile, make one along with a new profile, keep old ones current, and set up aider’s.

A profile can also start outside the MaeVae window, from a launcher file or a Windows Terminal tab, with the same isolated account.

Write a launcher and a Windows Terminal tab

Before you start: a profile that runs an agent (a plain shell has no launcher).

1. Click ✎ on the profile’s rail entry.
2. Click Create / update CLI launcher (pinned WT tab). MaeVae saves the profile and writes a .cmd launcher beside the profile’s own folder. When Windows Terminal is installed, it also adds a Windows Terminal profile, so the tab shows this profile’s name and stays pinned to it.
3. To give the tab its own icon, set Project icon in the editor (Browse… picks an image, which MaeVae copies in when you save), then click Save changes.
4. Open Windows Terminal and pick the profile’s name from its drop-down, or run the .cmd from any terminal. The same isolated agent starts in that console.

What you see: no note under the button once the launcher is current. Both the launcher and the tab use the profile’s launch command (for example claude --continue).

Note. The launcher opens its tab by the tab’s own id, so two profiles with the same name under different agents never collide. MaeVae edits only its own entry in Windows Terminal’s settings and keeps the rest of that file, your comments included. An older tab of the same name that MaeVae made is taken over and rewritten in place rather than duplicated.

Make a launcher when you create a profile

1. Click + Add profile and go through the steps to step 3, Project (see Make your first profile).
2. Leave Also make a CLI launcher ticked, as it starts.
3. Click Create & open. The launcher and its tab are written along with the new profile.

What you see: the new profile’s pane opens as usual. The launcher sits beside the profile’s folder, and its tab is in Windows Terminal’s drop-down under the profile’s name.

Know what a launcher clears, and update an old one

1. Open Quick settings. If any launcher or tab differs from what MaeVae would write now, a Launchers part appears and names them.
2. Read the line: it says how many launchers are out of date and whether any lacks the environment scrub.
3. Click Update all. MaeVae rewrites each out-of-date launcher and its tab from the saved profile.

What a launcher clears: both the launcher and the tab clear the other agents’ credential variables (ANTHROPIC_API_KEY, OPENAI_API_KEY and their like) before they pin the profile’s own folder, so a token or key set for your whole Windows account cannot quietly override the profile’s account. The tab does it with a real step for each variable at the start of its command line.

What Update all keeps: keys you added to a tab yourself, such as a color scheme or a font, and a variable of your own in the tab’s environment block. Only the variables MaeVae manages there are reset. A launcher that is already current is never touched, and MaeVae only reads them to compare; it never rewrites one on its own. A notice at start-up and a note in the profile’s editor also say when one is out of date.

Left over from deleted profiles: Removed profiles’ launchers… in Quick settings lists launchers and tabs whose profile is gone, and removes them safely. It never touches a login folder.

Limit. A launcher or tab of a profile in API-key mode carries no key; it falls back to whatever login the profile’s folder holds. Use the pane for such a profile. aider is the exception (next task).

Give aider a launcher

Before you start: an aider profile with its API key saved (see Save an API key for a profile).

1. Click ✎ on the aider profile’s rail entry.
2. Click Create / update CLI launcher (pinned WT tab) in its Account box.
3. Start aider from the launcher or the tab. When it finishes a turn there, MaeVae hears it: the profile’s rail light turns green, and if the profile has a pane open whose own agent is quiet, that pane shows “done · outside”.

Why aider is different: aider has no login and no configuration folder; its API key is the account. So its launcher and tab hold nothing but a call to MaeVae’s launch helper. At run time the helper reads the profile’s saved key from the Windows Credential Manager, clears every agent credential variable as a pane does, applies the profile’s endpoint, model and attention settings, enters the project folder, and starts aider in that console. The key is never written into the launcher or the tab.

Limit. Such a launcher goes out of date only when MaeVae itself moves; re-create it then. The “outside” mark has no approve or deny buttons, since MaeVae sends keys only to its own pane’s agent: answer in the terminal where aider runs.

16

Make it yours

Pick a theme, give a profile its own pane theme, icon, chime and pet, and choose the status line.

Themes, pane themes, icons, chimes, pets and the status line change how MaeVae looks and sounds, for the whole app or for one profile.

Pick a theme for the app

1. Click Quick settings at the foot of the rail.
2. Open App theme. Rest the pointer on a theme to preview it on the whole window; click to keep it. Some of the built-in themes are light.
3. For a theme of your own, click Custom themes…, which opens the custom-theme editor.
4. Animation, under App theme, sets an ambient animation for the window, previewed the same way.