Guide

Keyboard shortcuts

Anywhere

In context

Mouse and menus

• Click a file in the tree to preview it; the next preview replaces it. Double-click the file, or its tab, to keep it open.
• Double-click a terminal's tab to rename it. The same works in the status bar's Terminals list.
• Double-click a project's name to rename it. A single click folds the project away.
• Middle-click a tab to close it.
• Drag the edges between panels to resize them.
• Space cards, scripts and git changes show their buttons when you hover them.

Right-click menus

Projects and spaces

A project is a folder you open in Aira. Its spaces are the folders you work in: the project root (its primary space), a nested package, or a git worktree.

• Project settings: an icon (a symbol, one emoji, or a PNG or SVG from inside the project), one of 24 colours or the default accent, and the agent tracking files Aira has added to its repos.
• Space settings: a name and a folder, inside the project or outside it.
• Add a nested space by right-clicking a folder in the file tree.
• Star a space to keep it in the Spaces tab with starred spaces from other projects.
• Remove project and Remove space only take them out of Aira. Files on disk are not touched.

Scripts

Scripts belong to a project and run in its scripts window, one tab each. The script dialog has a working directory, the scripts Aira detected in package.json and the Makefile, a runner, what to run, a name, and a preview of the final command. Only run runs it once without saving; Save & run does both.

Runners

• Pin a script to add it to the Start set. Start runs the pinned scripts, or every script if none are pinned, and becomes Stop all scripts while any run.
• A failed script (one that exits with an error, not one you stopped) gets a red dot, counts toward “failed” in the window's summary, and shows “Exited with code n”.
• Scripts still running when you quit come back as a banner with Run again.

Agents

Pick an agent from the + in the tab bar. Aira runs the CLI you have installed, signed in as you; agents that aren't installed are marked in the menu. Custom command… opens the script dialog for anything else (it runs, but isn't tracked as an agent).

• Statuses: Working, Needs input, Done, Idle, Exited and Not running.
• A hook file is only added after you choose Enable when Aira asks. It's listed in .git/info/exclude, so it's never committed, and it does nothing unless the agent was started from Aira. If a file with that name already exists, Aira leaves it alone and falls back to terminal activity. Remove the files from the project's settings.
• Codex asks you once to trust its hook.
• With notifications on, macOS tells you when an agent finishes, needs input or exits, as long as you aren't looking at it.

Git

The Git view shows one changes tree for all of the project's repositories, nested repos and worktrees included.

• Click a changed file to see its diff against HEAD.
• A commit always goes to one repository. Checking files in another repo moves the selection there and says so.
• Amend last commit, Commit (⌘⏎) and Commit and Push. Each repository has Pull and Push, and Fetch all repositories fetches them all.
• Generate writes the message from the checked files, with the provider from Settings.
• Switch / create branch: pick a branch or type a new name. Deleting a branch asks first, and asks again before forcing it.
• Each repository lists its Worktrees; + adds one. Removing a worktree asks first.
• Rollback checked files to HEAD asks first, because it can't be undone.

AI commit messages

Choose a provider under AI (commit messages) in Settings. Nothing is sent until you press Generate. API keys are kept in the macOS Keychain, one entry per provider, and never in Aira's config or logs. Providers marked below ask once, before the first diff is sent (“Send diff”). How each provider was reviewed.

Agent CLIs run with your own login and subscription; Aira never reads their credentials. The model field is optional for them.

Status bar and ports

From left to right: the project, its branch with commits ahead (↑) and behind (↓), memory for the app and its terminals, Ports, and the running terminals.

• Ports lists the ports your processes listen on, grouped by project, and notes when one blocks a script. Search with any port number.
• Freeing a port that belongs to one of your scripts stops the script. Any other process asks first, showing its name, process ID and command.
• The terminals list shows each running terminal's memory. Double-click one to rename it.

Settings

Open with ⌘,.

What Aira asks first

Anything that stops a running process, deletes something or sends your code somewhere asks before it happens.