# Macros

Macros are quick prompt buttons on the Command Panel. Each configured slot stores a prompt, an icon URL, and a mode. Firing a macro opens a new Agent, Plan, or Discuss tab and sends that prompt immediately. You can include `/skill_name` mentions in the prompt body the same way you do in chat.

## Where they appear

The Command Panel lives in the editor column: below the editor and above the Terminals dock. It appears when a project is open and the editor split is shown. Without the editor column, the panel is unavailable.

The panel has two heights:

- **Collapsed** (default on first run): a strip of nine slots, the Global | Local | Account scope control, and an expand chevron.
- **Expanded**: the same strip plus a configurator for the selected slot.

## Scopes

Global, Local, and Account are three separate sets. The Command Panel scope selects which set you edit and fire. They do not merge.

| Scope | Availability | Purpose |
|-------|--------------|---------|
| **Global** | Always | Personal macros on this computer under `~/.insula/macros/` |
| **Local** | Project open | Project macros under `<project>/.insula/macros/`; commit with the repository when the team should share them |
| **Account** | Signed in | Personal macros that sync across machines. Cloud backup does not need to be enabled |

If Local is selected without a project, or Account without a sign-in, the panel falls back to Global. Closing the project while Local is selected returns you to Global.

Where these spaces fit among settings, rules, and skills is covered in [Settings spaces](/wiki/02-settings-spaces).

## Configure a slot

There are exactly nine slots. Buttons show an icon only; the prompt source name appears in the Prompt picker.

1. Click a dashed **+** slot (or expand the panel, then click an empty slot). The panel expands and the slot is ready to edit.
2. Set **Prompt**: choose **New prompt** or an existing source in that scope's library.
3. Set **Icon URL** (live preview on the slot) and **Mode** (**Agent**, **Plan**, or **Discuss**).
4. Edit the prompt body. Placeholder text reminds you to use `/` for skills.
5. Use **Run** to fire, or **Clear slot** to unconfigure the slot.

Edits save as you work. Prompt bodies live as files under that scope’s `prompts/` directory. Several slots may share one source; editing the body updates every slot that uses it. **Clear slot** removes the slot configuration; the prompt file stays in the library.

## Run a macro

| Panel state | Action | Result |
|-------------|--------|--------|
| Collapsed, filled slot | Click the slot | Fires immediately |
| Expanded, filled slot | Click the slot | Selects the slot for editing |
| Expanded | **Run**, or send from the prompt editor | Fires the selected macro |

A fire always opens a **new** tab and sends the stored prompt. It does not continue the active chat. An empty prompt is blocked with **Macro has no prompt**. **Plan** and **Discuss** require an open project; without one those modes are unavailable.

## Skills and modes

Include `/skill_name` in a macro prompt to load a skill when the new session starts. Skill authoring and naming are covered in [Skills and rules](/wiki/03-skills-and-rules).

**Mode** chooses which kind of session the fire creates:

- **Agent** for direct work
- **Plan** for durable plan drafting
- **Discuss** for read-only exploration

Mode and tool behavior for those sessions are detailed on [Agents](/wiki/05-agents). Macros do not pick a model; Active Models from Settings apply as usual. See [Models](/wiki/04-models).

## Defaults and project setup

On a fresh install, Global may seed **Discover Code Base**: explore layout, entrypoints, languages, docs, and risks, then summarize and wait for a follow-up. Existing Global macros are left alone on later updates.

For Local macros, add project `.insula` when you want shared configuration: ask the agent to load `skill_bootstrap-insula`, or create the files yourself. Confirm before anything is written. Local macros belong under `<project>/.insula/macros/`.

## Sharing and sync

1. Personal shortcuts on one machine: use **Global**.
2. Team or repository shortcuts: use **Local** under `.insula/macros` and commit them.
3. The same personal macros on another machine: sign in and use **Account**.
4. Global and Local stay on the machine. Account macros sync when you are signed in. If cloud Account macros already exist, they take precedence over the local Account cache on login.
5. **Delete my data** removes cloud Account macros. The local Account cache may remain until you clear those slots yourself.

On a remote connection, Account macros stay with the desktop client. See [Remote servers](/wiki/08-remote-servers).

## Related topics

- [What is Insula](/wiki/01-what-is-insula)
- [Settings spaces](/wiki/02-settings-spaces)
- [Skills and rules](/wiki/03-skills-and-rules)
- [Models](/wiki/04-models)
- [Agents](/wiki/05-agents)
- [Remote servers](/wiki/08-remote-servers)