# What is Insula ## Overview Insula is a personal, chat-first agentic desktop editor from Insula Labs. Conversation is the default surface: you talk with a coding companion that can explore a project, answer questions, draft plans, and carry out work with the models you configure. When a project folder is open, the same window can grow into a full workspace. Alongside chat you can browse files, edit code, run terminals, search the project by meaning through Insight, and open a simple in-app browser. Settings and account live in their own windows so the primary surface stays focused on the work. ## Who it is for Insula is for people who want a local coding companion inside a real project workspace. You keep control of which models run, what the agent may do, and when larger changes proceed. Typical use is to open a folder, discuss the codebase, plan a change, then implement it with clear review points along the way. ## Home and projects Without a project open, Insula is in home mode. You get Agent chat as a companion: manage known projects, open a folder, and handle account sign-in. There is no file tree, terminal, or code search in this state. Each time you land in home, a new chat session starts; past home sessions stay available from a session picker. Open a folder (or pick a known project) and the window becomes a project workspace. Plan and Discuss modes unlock. The agent can work with project files, terminals, and Insight. Close the project and you return to home mode. ## Workspace Insula stays chat-first even with a project open. By default you still see the conversation; a slim dash on the right opens project tools. Expand the layout to show files, editor, and chat together. The editor hosts file tabs, terminals, Insight, and the browser. Panel order and open work are remembered per project when you collapse back to chat-only. Settings open from the top bar in a separate window. Account opens from the dash the same way. ## Modes and plans With a project open you choose among three modes. Each mode keeps its own conversation. - **Agent** is always available. At home it is the companion. With a project open it is the direct implementer: it can read and change files, run approved terminal commands, use Insight, and load skills. - **Discuss** is read-only exploration and explanation. It helps you understand the project without edits or command execution. - **Plan** drafts durable markdown plans you can watch take shape in the editor. When a plan is ready, you choose **Build**. A builder then carries out the plan while you follow progress in the plan conversation. If the planner needs a decision, it can ask you before continuing. Agent and Discuss detail, tool behavior, and related settings belong on the Agents page. Plan authoring and Build stay short here; deeper agent mechanics live later. ## Insight Insight is a per-project local semantic index of your project files. Agents and the Insight view can find code and other content by meaning. It needs an embeddings model assigned in Settings. Indexing respects ignore rules so bulk or private paths can stay out of the index. Changing the embeddings model means the project should be re-indexed. Insight is local to the machine and project data store. Full ignore semantics, search behavior, and day-to-day index operations are covered on the Insight page. ## Models You assign models by role: - **Chat** powers ordinary Agent and Discuss turns, and plan drafting. - **Build** powers the plan builder. If Build is unset, Chat is used for builds. - **Embeddings** powers Insight. Without it, semantic search is unavailable. - **Image understanding** describes images so they can contribute context (for example while indexing). It does not generate images. Provider setup, costs, and recommended pairings are on the Models page. ## Rules, skills, and macros Three related ideas shape how the agent behaves and how you start work: - **Rules** are standing instructions the agent receives (project conventions, tone, constraints). - **Skills** are on-demand playbooks the agent can load when a task matches a named procedure. - **Macros** are quick prompt buttons on the Command Panel. They fire a stored prompt into a new agent tab. Rules, skills, and macros can live on this computer, in the open project, or (for some macros) on your signed-in account. How spaces combine and how you author each kind is covered on the Settings spaces, Skills and rules, and Macros pages. ## Staying in control You stay in the loop on consequential steps: - Terminal commands the agent wants to run require approval unless you have already allowed a matching pattern. - Plans are documents you can read as they are written. Build starts when you choose it, and a finished build is marked so it is not run again by accident. - In Plan mode, the agent can pause with a direct question when a choice blocks progress. Approvals, allowlists, and agent settings are detailed on the Agents page and in Settings. ## Account and remote An **Insula account** is optional. Sign-in unlocks account-scoped macros and optional cloud backup of providers and app preferences. Project files, Insight indexes, and plans stay on the machine. **Open Remote** lets you use another machine over the network as the workspace host while the desktop app acts as the client. Provisioning, reconnect behavior, and what loads from the remote side are on the Remote servers page. ## Next topics - [Settings and spaces](/wiki/02-settings-spaces) - [Skills and rules](/wiki/03-skills-and-rules) - [Models](/wiki/04-models) - [Agents](/wiki/05-agents) - [Macros](/wiki/06-macros) - [Insight](/wiki/07-insight-db) - [Remote servers](/wiki/08-remote-servers)