---
title: "Settings Reference"
description: "Every tab in the Cerevisor Settings popup, every field, every toggle, what it does and what the default is."
slug: reference/settings
section: reference
subsection: settings
canonical_url: https://cerevisor.com/docs/reference/settings
last_verified: 2026-05-18
last_verified_version: "1.2.0"
updated_at: 2026-05-18T15:08:18.053416+00:00
---

Open the Settings popup from the gear icon in the title bar. It has **14 tabs**, listed below in the order they appear in the sidebar.

This page is the master reference for every tab. Each tab section covers its purpose, the fields it contains, the default values, and notes on what each setting actually changes when you flip it.

| Tab | What it covers |
|---|---|
| [Workflow](#workflow) | Workflow name/description, preamble, native mode, wow directive, situational-awareness directive, custom suffix. |
| [Permissions](#permissions) | Granular per-category permission flags (filesystem, execution, web, search, meta). Trust profile. |
| [Input](#input) | What input the workflow accepts when run — none, user message, file, folder, or webhook. |
| [Agents](#agents) | Role palette ordering, custom agent templates. |
| [Chat Builder](#chat-builder) | The AI Chat Builder's provider/model + system-prompt config. |
| [Integrations](#integrations) | Claude Code CLI integration, "Launch in Claude Code" path. |
| [Skills](#skills) | Semantic skill retrieval mode, skill embedding refresh. |
| [Automation](#automation) | Scheduled runs, Loop & Enhance config. |
| [Learning Experience](#learning-experience) | Welcome intro, sample folders, contextual guidance cards. Toggle the whole layer on/off. |
| [MCP Servers](#mcp-servers) | Add/remove/configure MCP servers. |
| [Web Search](#web-search) | Default web-search provider (Tavily, Perplexity, Linkup), per-provider API keys, test connection. |
| [Vault](#vault) | Secrets the workflow can reference (API keys, tokens) without exposing them in `.cerevisor` files. |
| [Subscription](#subscription) | License state, trial countdown, manage subscription, upgrade. |
| [Updates](#updates) | Current version, check for updates, last-checked time, update channel. |

---

## Workflow

The home tab. Settings that affect the active workflow's identity and execution behavior.

| Field | Type | Default | What it does |
|---|---|---|---|
| **Name** | Text input | Inherits from file | The workflow's display name. Editable here or in the title bar. |
| **Description** | Textarea | empty | A short description visible on the Home Screen card and in workflow exports. |
| **Preamble** | Textarea | empty | Free-form text prepended to the generated prompt. Use it for "always start by reading this README" or any workflow-wide context. |
| **Execution mode** | Select | `sequential` | `sequential` runs columns in order. `parallel-columns` runs all columns simultaneously (rarely useful). |
| **Include permissions in prompt** | Toggle | on | If on, the generated prompt enumerates the allowed permissions upfront. |
| **Include deliverables in prompt** | Toggle | on | If on, the generated prompt summarizes every agent's output definition at the bottom. |
| **Native mode (Structured Orchestration)** | Toggle | on | Enriches the generated prompt with subagent types, tool scoping, model hints. |
| **Wow directive, enabled** | Toggle | on | Whether the global "wow" quality directive is appended to every prompt and injected into every agent's system message. |
| **Wow directive, text** | Textarea | A starter "make this excellent" directive | The directive itself. Editable; resets to default with a "Reset" link. |
| **Situational Awareness directive, enabled** | Toggle | on | Whether the situational-awareness hygiene directive is injected into every workflow. Pushes agents to surface uncertainty, attribute beliefs to their source, and name unknowns explicitly. Independent of the Wow directive (see [SA configure-and-run](../../guides/situational-awareness/configure-and-run.md) for why both exist). |
| **Situational Awareness directive, text** | Textarea | The default SA instruction | The directive itself. Editable; resets to default with a "Reset" link. |
| **Custom suffix** | Textarea | empty | Text appended to the generated prompt after everything else. |
| **Auto-connection exclusions** | Multi-select | empty | Agent roles excluded from smart auto-connect. Useful if you want, e.g., reviewers to never be wired automatically. |

---

## Permissions

Granular control over what agents can do without prompting you.

The top of the tab shows your current **Trust Profile** with a button to change it (re-opens the Trust Profile Setup modal).

Below that, permissions are organized into five categories. Each category has three radio options: **Allow** (no prompt), **Ask** (prompt on each use), **Deny** (block entirely).

### Filesystem

| Permission | Default (Standard profile) |
|---|---|
| Read files | Allow |
| Write files (in workspace) | Ask |
| Write files (outside workspace) | Ask |
| Edit files | Ask |
| Delete files | Ask |
| Create directories | Ask |

### Execution

| Permission | Default |
|---|---|
| Bash (read-only commands) | Ask |
| Bash (write/execute commands) | Ask |
| Spawn subagent | Allow |
| Long-running processes | Ask |

### Web

| Permission | Default |
|---|---|
| Web fetch | Allow |
| Web fetch (external sites) | Allow |
| HTTP POST requests | Ask |

### Search

| Permission | Default |
|---|---|
| Web search | Allow |
| Skill search (find_skills) | Allow |

### Meta

| Permission | Default |
|---|---|
| Read workflow metadata | Allow |
| Ask user (`ask_user` tool) | Allow |
| Write to memory | Ask |

Each category also has a free-form notes field where you can write per-workflow exceptions ("never let agents write to ~/work/sensitive/").

---

## Input

Defines what triggers and feeds the workflow.

| Input type | What it does |
|---|---|
| **None** | The workflow runs with no input — agents start from their instructions only. |
| **User Message** | A textarea you type into at run time. The message is injected into the entry agent's context. |
| **File** | A file picker at run time. The file's contents are read into the entry agent. |
| **Folder** | A folder picker at run time. The folder is set as the project context for the run; agents can read any file inside. |
| **Webhook** | The workflow can be triggered via a unique URL. Cerevisor shows the URL plus an enable/disable toggle. |

For all types except None, you also pick the **Entry agent**: the agent that receives the input. Defaults to the first agent in the first column.

Type-specific fields:

- **User Message:** Optional default text shown in the run-time input box.
- **File:** Optional accepted extensions (`.md, .pdf, .txt`).
- **Folder:** Optional max depth for scanning.
- **Webhook:** Display-only URL + regenerate-secret button + enable/disable toggle.

---

## Agents

Manage the agent palette and your saved Custom Agent templates.

### Role visibility & order

A drag-reorderable list of all 17 built-in roles plus your Custom Agent templates. Each row has:

- A grab handle for reordering (drag).
- The role's name, abbreviation badge, and tagline.
- A visibility toggle. Hidden roles don't appear in the palette or context menus.

Reordering affects the 0–9 placement shortcuts: 1 = first visible role, 2 = second, etc.

### Custom Agent Templates

A list of agent templates you've saved. Each row shows the template name, base role, and number of skills. Actions:

- **Edit**: opens the template editor (same UI as the Agent Config popup, but saves to the template store).
- **Delete**: removes the template (with confirm).
- **Use in workflow**: drops an agent built from the template into the active workflow's rightmost column.

Click **+ New Custom Agent** at the bottom to create a new template.

---

## Chat Builder

Configure the floating AI Chat Builder that you open with Ctrl/Cmd+L.

| Field | Type | What it does |
|---|---|---|
| **Provider** | Chip picker | Which provider the chat builder uses. Defaults to the workflow's default provider but can be overridden so e.g. you can build with a fast Haiku while running with Sonnet. |
| **Model** | Dropdown | Specific model within the chosen provider. |
| **Trust mode** | Select: Full trust / Ask me / Restricted | How freely the chat builder can apply edits. Full trust = applies all edits immediately; Restricted = previews every edit for approval. |
| **Response mode** | Select: Apply edits / Discuss only | Whether the chat builder edits the workflow or just talks about it. |
| **System prompt override** | Textarea | Replaces the default chat-builder system prompt. Power-user setting. |

Codex CLI and Cursor Agent providers are not selectable here: the chat builder needs a chat API, which neither of those provides.

---

## Integrations

Configuration for the optional "Launch in Claude Code" CLI integration.

| Field | What it does |
|---|---|
| **Claude integration enabled** | Toggle. When on, Cerevisor detects the `claude` CLI and the "Launch in Claude Code" share menu becomes available. |
| **Claude CLI path** | Auto-detected, but editable if you have a custom install. |
| **Default model for CLI runs** | Dropdown of Claude models. Used when you launch the generated prompt in Claude Code. |

If the toggle is off, the Share menu's "Launch in Claude Code" entry is hidden.

---

## Skills

| Field | What it does |
|---|---|
| **Semantic skill retrieval** | Select: `auto` / `on` / `off`. Controls whether Cerevisor uses on-device embeddings (Xenova all-MiniLM-L6-v2) to rank skill relevance. `auto` = use when available, silently degrade to keyword-only if not. `on` = require it (errors if it fails to load). `off` = keyword-only. |
| **Re-embed all skills** | Button. Triggers a full re-embed pass over every skill. Run after upgrading the embedder or after large skill edits. |
| **Skill folders** | Read-only display of the folders Cerevisor scans: `~/.claude/skills/` and `~/.cerevisor/skills/`. |
| **Force rescan** | Button. Re-scans the skill folders immediately. |

---

## Automation

Manage scheduled workflow runs and Loop & Enhance.

### Scheduled runs

A list of existing schedules. Each row shows:

- The workflow name.
- The cron expression (with a human-readable preview, e.g. "Every Monday at 9:00 AM").
- The next fire time.
- Enable/disable toggle.
- Edit + Delete buttons.

Click **+ New schedule** to open the Schedule Config popup.

### Loop & Enhance

Settings for the round-loop workflow-improvement system.

| Field | Default | What it does |
|---|---|---|
| **Enabled for this workflow** | Off | Whether to use Loop & Enhance on the next run. |
| **Max rounds** | 3 | Hard cap on how many detect-fix-rerun cycles will execute. |
| **Budget cap (USD)** | $5.00 | Total cost across all rounds, including planner LLM calls. |
| **Convergence mode** | strict | `strict` = stop only when no failures detected. `loose` = stop when failure count drops below the previous round. |
| **Pause between rounds** | Off | If on, the run pauses after each round and waits for you to approve continuation. |
| **Planner provider** | Inherits chat builder's | Which provider runs the per-round planner LLM. |
| **Planner model** | Inherits | Specific model. |
| **Stuck detection** | On | If two consecutive rounds produce the same failure fingerprint, abort. |

---

## Learning Experience

Toggles for the layer of onboarding scaffolding, contextual guidance, and progressive disclosure.

| Field | Default | What it does |
|---|---|---|
| **Enabled** | On | Master switch. When off, the entire LX layer goes dark — no welcome modal, no contextual guidance cards, no sample folder seeding. |
| **Welcome intro seen** | On after first launch | Marks the welcome intro as seen. Flip off to make it reappear on next launch. |
| **Welcome slides** | (default copy) | Edit the welcome intro slides in your own voice. Each slide has a title and body. |
| **Template samples** | (default per template) | The sample files seeded when you pick a template on the Home Screen. Editable per template. |
| **Contextual guidance cards** | (defaults) | The "first agent placed" / "first wave complete" / etc. hint cards. Edit copy or disable individually. |

---

## MCP Servers

Manage Model Context Protocol servers.

### Server list

Each registered server shows:

- Name, transport type (currently always `stdio`).
- Status (connected / disconnected / error).
- Tool count (e.g. "12 tools").
- Enable/disable toggle.
- Edit / Remove buttons.
- "View tools" expander that lists every tool the server exposes with its description.

### Add a server

Click **+ Add MCP server**. The form fields:

| Field | Required | What it does |
|---|---|---|
| **Name** | Yes | Display name in the UI. |
| **Command** | Yes | The executable to spawn (e.g. `npx`). |
| **Args** | No | Command arguments, one per line. |
| **Working directory** | No | Defaults to the workflow's project folder if set. |
| **Environment variables** | No | Key/value pairs passed to the spawned process. |
| **Enable on connect** | Toggle | If on, Cerevisor starts the server immediately and tries to list its tools. |

### Per-server permission policy

Each server has its own permission policy (Allow / Ask / Deny) for its tools, settable on the server row. This is in addition to the global `mcp` category in Permissions.

Trial / Free tier users see a license gate on this tab, MCP is a Trial+/Paid feature.

---

## Web Search

Configure the `web_search` tool's backend.

| Field | What it does |
|---|---|
| **Default search provider** | Select: None / Tavily / Perplexity / Linkup. Workflow-wide default. |
| **Tavily API key** | Text input (masked). Stored in OS keychain. |
| **Perplexity API key** | Text input (masked). |
| **Linkup API key** | Text input (masked). |
| **Test** | Per-provider button. Sends a trivial `ping` query without saving the key first, so you can validate before commit. |

Per-agent override is set in the Agent Config popup → Search provider field.

---

## Vault

Securely store secrets the workflow needs without putting them in the `.cerevisor` file.

### Secret list

Each row shows:

- Secret name (e.g. `OPENAI_API_KEY`).
- Last-modified date.
- Edit / Delete buttons.
- A masked value display with a "Reveal" toggle.

### Add a secret

Click **+ Add Secret**. Opens the Add Vault Secret modal:

| Field | What it does |
|---|---|
| **Name** | The key. Agents reference secrets by name (e.g. `{{vault.OPENAI_API_KEY}}` in instructions). |
| **Value** | The secret value. Stored in the OS keychain. |
| **Description** | Optional human-readable note. |

Vault references in agent instructions are resolved at run time, never written to logs or audit trails.

---

## Subscription

License management.

The top of the tab shows your current tier, **Trial** (with countdown), **Free**, **Paid**, or **Grace** (transient network error state).

For trial users:

- Days remaining in trial.
- What's enabled at trial.
- Big "Upgrade to Paid" CTA.

For free users:

- What's gated (workflows ≥ N, worlds ≥ N, MCP, Loop & Enhance, scheduler, cloud, per-agent provider, web-search, chat-builder, workshop edit).
- Upgrade CTA.

For paid users:

- License key (masked, with copy button).
- License email.
- Active instance count.
- Activated-on date.
- Deactivate this device button (frees the seat).
- Re-validate button (forces a fresh license check).

For grace users (license-server unreachable):

- Days remaining in grace before downgrade to Free.
- Last successful check time.
- Re-validate button.

---

## Updates

Auto-update controls.

| Field | What it does |
|---|---|
| **Current version** | The version you're running. |
| **Last checked** | Timestamp of the last update check. |
| **Status** | One of: Up to date / Update available / Downloading / Ready to install. |
| **Auto-check on launch** | Toggle (default on). Whether to check for updates on every launch. |
| **Check now** | Button. Forces an immediate check. |
| **Restart and install** | Button. Visible only when an update has been downloaded. |
| **Release notes** | Visible when an update is available. Renders the release's markdown notes. |

Updates always download regardless of your license tier, paid customers cannot be stranded on a broken build by a license-server outage.