# Agents

Agents in Insula are chat tabs: **Agent**, **Discuss**, and **Plan**. Each tab keeps its own conversation. With a project open, the agent works in that workspace. At home, only the companion **Agent** is available.

## Home and project scope

Without a project open, Insula is in home mode. You get **Agent** chat as a companion: manage remembered projects, open a folder, and handle account sign-in. There is no file tree, terminal, or Insight. Each time you land in home, a new chat session starts. Past home sessions stay available from the session picker (**New chat**, then list, open, or delete).

Open a folder (or pick a known project) and chats become scoped to that project. **Plan** and **Discuss** unlock. Close the project and you return to home.

Use the tab strip above the composer to switch conversations. **+** opens **New agent tab**. Double-click a tab to rename it, drag to reorder, and close tabs you no longer need. Plan and Discuss stay disabled until a project is open.

## Agent

**Agent** is the standard implementer. It uses the **Chat** model. See [Models](/wiki/04-models).

At home it can:

- Answer questions and help you get oriented
- List and forget remembered projects (forgets Insula's stored data for that project, such as chats and indexes; your folder on disk stays)
- Start account login

With a project open it can:

- Read and edit project files
- Run terminal commands (approval-gated; see below)
- Search the project by meaning through Insight
- Load skills (type `/` for autocomplete)
- Run deeper read-only research that returns a short briefing so the main chat stays lean

Rules and skills shape how Agent behaves. See [Skills and rules](/wiki/03-skills-and-rules). Insight setup and day-to-day use are on [Insight DB](/wiki/07-insight-db).

## Discuss

**Discuss** is available only with a project open. It is read-only exploration and explanation: it can read files, use Insight, load skills, and run research. It does not edit files or run terminal commands. For changes, switch to **Agent** or **Plan**.

## Plan

**Plan** is available only with a project open. It authors a durable markdown plan you watch take shape in the editor, then you choose when to execute it.

1. Describe the work in a **Plan** tab.
2. The plan opens live as a preview in the editor.
3. Use **Show plan** in the composer when a plan path exists.
4. Review the plan, then choose **Build** on the preview. The button moves through **Building...** to **Built**. Progress streams into the Plan conversation.
5. A finished build stays **Built** so it is not run again by accident.

Plans live in machine project data, outside the repository. Drafting uses the **Chat** model. Execution uses **Build** (or Chat if Build is unset). See [Models](/wiki/04-models).

When a decision blocks planning, Plan pauses with an **Input needed** card: **Yes** / **No**, multiple choice, or free-text **Answer**. One question is pending at a time. Clearing the conversation or closing the project clears a pending question.

## Terminal commands and approvals

When Agent or a Build wants to run a shell command, Insula shows a **Command approval** card:

- **Allow** runs that command once
- **Always allow** runs it and adds a prefix (the command's first word) to the allowlist
- **Deny** blocks the command

Open **Settings** from the top bar, then **Agent**, to edit **Terminal Allowlist**. Entries are **prefix** or **regex**. With an empty allowlist, every command asks for approval.

**Agent Terminals** on the composer lists commands the agent started. Use **Kill** or **Kill all** to stop them. That list is separate from terminals you open yourself in the editor or dash.

## Compaction

Long conversations grow prompt size. Use **Compact** on the composer to summarize older turns. You may see a compacted marker in the transcript. Token pressure shows against the compaction cap.

Under **Settings → Agent → Context Compaction**, set **Compaction cap (tokens)** (default `200000`). The cap is global for agent contexts and is the threshold at which compaction is suggested.

## 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)
- [Macros](/wiki/06-macros) (a macro opens a new Agent, Plan, or Discuss tab and sends its prompt)
- [Insight DB](/wiki/07-insight-db)