# Configuration & Customization (/docs/verdent/configuration/settings)

> Configure Verdent through the Settings panel



Verdent provides comprehensive configuration through a dedicated Settings panel organized into multiple categories.

### What You'll Learn [#what-youll-learn]

* Navigate the settings categories
* Configure models, thinking levels, and automation
* Create rules, subagents, and custom commands
* Customize editor, terminal, and diff settings

***

## Accessing Settings [#accessing-settings]

**Keyboard Shortcut:**

* **macOS:** `Cmd+,`
* **Windows:** `Ctrl+,`

**Alternative:** Click the Settings icon in the interface.

Settings changes apply immediately without requiring restart.

***

## Settings Categories [#settings-categories]

The settings panel is organized into **11 categories**:

| Category        | Purpose                                     |
| --------------- | ------------------------------------------- |
| **General**     | Theme, updates, proxy, shell environment    |
| **Chat**        | Default models, thinking levels, automation |
| **Models**      | Enable/disable models, set reasoning levels |
| **User Rules**  | User Rules, Project Rules                   |
| **Permissions** | Deny rules for command safety               |
| **Subagent**    | Create and manage custom subagents          |
| **Command**     | Custom slash commands                       |
| **MCP**         | Model Context Protocol servers              |
| **Terminal**    | Font, cursor, shell settings                |
| **Editor**      | Font, tabs, auto-save, visual preferences   |
| **Diff**        | Diff viewer configuration                   |

***

## General Settings [#general-settings]

| Setting         | Options                                       |
| --------------- | --------------------------------------------- |
| **Theme**       | Light, Dark, System                           |
| **Language**    | Interface language preference                 |
| **Updates**     | Auto Update, Check on Startup, Manually Check |
| **HTTP Proxy**  | Proxy URL for HTTP                            |
| **HTTPS Proxy** | Proxy URL for HTTPS                           |

### Update Mode [#update-mode]

Control how Verdent handles updates:

| Option      | Description                                  |
| ----------- | -------------------------------------------- |
| **Auto**    | Automatically downloads and installs updates |
| **Startup** | Checks for updates on app launch             |
| **Manual**  | Only updates when you explicitly request     |

***

## Chat Settings [#chat-settings]

### Automation [#automation]

| Setting                       | Description                                                          |
| ----------------------------- | -------------------------------------------------------------------- |
| **Auto Generate Code Review** | Automatically generate code review analysis after assistant messages |

### Model Selection [#model-selection]

| Setting                 | Description                                |
| ----------------------- | ------------------------------------------ |
| **Default Agent Model** | Choose the default AI model for Agent mode |
| **Default Plan Model**  | Choose the default AI model for Plan mode  |

### Notifications [#notifications]

| Setting                 | Description                                    |
| ----------------------- | ---------------------------------------------- |
| **System Notification** | Show system notification when task is finished |
| **In-app Notification** | Show in-app notification when task is finished |

<Tip>
  For System Notifications to work, ensure notification permissions are enabled at the OS level. Check your system settings to allow Verdent to send notifications.
</Tip>

***

## Models Settings [#models-settings]

Configure which models appear in the model selector.

For provider API keys, see [Bring Your Own Key (BYOK)](/docs/verdent/configuration/byok).

### Preset Models [#preset-models]

Presets combine an Agent model and a Plan model for different use cases.

| Preset          | Description                                          | Agent Model | Plan Model |
| --------------- | ---------------------------------------------------- | ----------- | ---------- |
| **Performance** | Maximum context, frontier models (1–2× credit usage) | Opus 4.5    | Opus 4.5   |
| **Balance**     | Optimal blend of performance and cost                | Sonnet 4.5  | Sonnet 4.5 |

### Creating Custom Models [#creating-custom-models]

Create new models with custom model combinations:

| Field           | Description                         |
| --------------- | ----------------------------------- |
| **Name**        | Model name (up to 20 characters)    |
| **Agent Model** | Model used for Agent Mode execution |
| **Plan Model**  | Model used for Plan Mode analysis   |

***

## User Rules Settings [#user-rules-settings]

Rules are Markdown files that guide Verdent's behavior.

### Rule Types [#rule-types]

| Rule Type         | Location                | Scope                 |
| ----------------- | ----------------------- | --------------------- |
| **User Rules**    | `~/.verdent/VERDENT.md` | All projects (global) |
| **Project Rules** | `<project>/AGENTS.md`   | Current project       |

**Access:** Settings → User Rules

**Precedence:** AGENTS.md (highest) → User Rules → defaults

**Auto-save:** Changes auto-save after 500ms

### Example User Rules [#example-user-rules]

```markdown
# User Rules

## Code Style
- Always use TypeScript
- Prefer functional components in React
- Use async/await over promises

## Documentation
- Include JSDoc comments for exported functions
- Add usage examples in documentation
```

<Tip>
  Commit AGENTS.md to version control to share project-specific standards with your team.
</Tip>

***

## Permissions Settings [#permissions-settings]

Define security rules to block potentially dangerous commands.

### Purpose [#purpose]

Permission rules prevent accidental execution of destructive commands. Each rule is a pattern that, when matched, blocks the command.

**Storage:** `~/.verdent/permission.json`

### Syntax [#syntax]

* One rule per line
* Supports `*` wildcards for pattern matching
* Exact match by default
* Case-sensitive

### Example Deny Patterns [#example-deny-patterns]

| Pattern            | Purpose                       |
| ------------------ | ----------------------------- |
| `rm -rf /`         | Block recursive root deletion |
| `sudo *`           | Block sudo commands           |
| `git push --force` | Block force push              |
| `DROP TABLE`       | Block dangerous SQL           |
| `npm publish`      | Block publishing              |
| `curl * \| *sh*`   | Block piping scripts to shell |
| `:(){ :\|:& };:`   | Block fork bombs              |

***

## Subagent Settings [#subagent-settings]

### Built-in Subagent [#built-in-subagent]

**@verifier** - Quick code verification and validation checks.

```
@verifier Check this function for potential issues
@verifier Validate my authentication implementation
```

### Creating Custom Subagents [#creating-custom-subagents]

**Access:** Settings → Subagent → Add Subagent

| Field           | Description                                  |
| --------------- | -------------------------------------------- |
| **Name**        | Identifier for @-mention invocation          |
| **Description** | Brief explanation of purpose                 |
| **Prompt**      | System instructions defining behavior        |
| **Model**       | Sonnet 4.5, GPT-5, GPT-5-Codex, or Haiku 4.5 |

### Example Custom Subagent [#example-custom-subagent]

```
Name: security-reviewer
Description: Security-focused code review specialist
Prompt: You are a security-focused code reviewer. When analyzing code:
- Prioritize security vulnerabilities (SQL injection, XSS, auth flaws)
- Reference OWASP Top 10
- Provide specific remediation with code examples
Model: Sonnet 4.5
```

### Management Actions [#management-actions]

* **Add:** Create new custom subagent
* **Edit:** Modify existing configuration
* **Enable/Disable:** Toggle availability
* **Duplicate:** Copy as template
* **Delete:** Remove permanently

***

## Command Settings [#command-settings]

Create custom slash commands for repetitive tasks.

**Access:** Settings → Command

| Field           | Description                     |
| --------------- | ------------------------------- |
| **Name**        | Command name (invoked with `/`) |
| **Description** | What the command does           |
| **Content**     | The prompt or action to execute |

### Example Commands [#example-commands]

```
Name: fix-lint
Description: Fix all linting errors in current file
Type: prompt
Content: Review and fix all linting errors in this file. Explain each fix.
```

**Usage:** Type `/fix-lint` in the Input Box.

***

## MCP Settings [#mcp-settings]

Configure Model Context Protocol servers for external tool integration.

**Access:** Settings → MCP

**Storage:** `~/.verdent/mcp.json`

### Adding MCP Servers [#adding-mcp-servers]

MCP servers are configured via JSON. Click **Add Server** and paste the configuration JSON from the MCP server's documentation.

**Example Configuration:**

```json
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": [
        "-y",
        "@upstash/context7-mcp"
      ]
    }
  }
}
```

<Tip>
  Use NPX or UVX configurations when available for easier setup. Popular MCP servers are available via Quick Add.
</Tip>

### Server Status [#server-status]

| Status      | Description                |
| ----------- | -------------------------- |
| **Success** | Connected, tools available |
| **Failed**  | Connection error           |
| **Loading** | Initializing               |

***

## Terminal Settings [#terminal-settings]

**Access:** Settings → Terminal

### Font Settings [#font-settings]

| Setting            | Range/Options      |
| ------------------ | ------------------ |
| **Font Size**      | 8-32px             |
| **Font Family**    | System fonts       |
| **Line Height**    | Numeric multiplier |
| **Letter Spacing** | Numeric            |

### Cursor Settings [#cursor-settings]

| Setting          | Options                 |
| ---------------- | ----------------------- |
| **Cursor Style** | Block, Underline, Bar   |
| **Cursor Blink** | On/Off                  |
| **Cursor Width** | 1-10px (bar style only) |

**Shortcuts:**

* New Terminal: `` Ctrl+Shift+` ``
* Toggle Terminal: `Cmd+J` / `Ctrl+J`

***

## Editor Settings [#editor-settings]

**Access:** Settings → Editor

### Font & Display [#font--display]

| Setting          | Range/Options |
| ---------------- | ------------- |
| **Font Size**    | 8-32px        |
| **Tab Size**     | 1-8 spaces    |
| **Word Wrap**    | On/Off        |
| **Line Numbers** | On/Off        |
| **Minimap**      | On/Off        |

### Editing Behavior [#editing-behavior]

| Setting             | Description                |
| ------------------- | -------------------------- |
| **Auto Save**       | Automatically save changes |
| **Auto Save Delay** | 100-5000ms                 |
| **Format on Paste** | Format code when pasting   |
| **Format on Type**  | Format code while typing   |

### Visual Enhancements [#visual-enhancements]

| Setting                       | Options                                  |
| ----------------------------- | ---------------------------------------- |
| **Render Whitespace**         | None, Boundary, Selection, Trailing, All |
| **Line Highlight**            | None, Gutter, Line, All                  |
| **Cursor Style**              | Line, Block, Underline                   |
| **Cursor Blinking**           | Blink, Smooth, Phase, Expand, Solid      |
| **Bracket Pair Colorization** | On/Off                                   |
| **Sticky Scroll**             | On/Off                                   |
| **Folding**                   | On/Off                                   |

***

## Diff Settings [#diff-settings]

**Access:** Settings → Diff

| Setting                       | Description                                 |
| ----------------------------- | ------------------------------------------- |
| **View Mode**                 | Choose diff display layout (Unified View)   |
| **Font Size**                 | Set the font size for diffs                 |
| **Render Whitespace**         | Render whitespace characters (Selection)    |
| **Show Line Numbers**         | Display line numbers in diff editors        |
| **Show Minimap**              | Display the code minimap                    |
| **Word Wrap**                 | Wrap long lines in diff editors             |
| **Ignore Trim Whitespace**    | Ignore leading/trailing whitespace in diffs |
| **Hide Unchanged Regions**    | Collapse unchanged code regions             |
| **Smooth Scrolling**          | Enable smooth scrolling animations          |
| **Mouse Wheel Zoom**          | Allow zooming with mouse wheel + Ctrl       |
| **Sticky Scroll**             | Keep headers visible when scrolling         |
| **Bracket Pair Colorization** | Colorize matching bracket pairs in diffs    |

***

## Open in External Tools [#open-in-external-tools]

Quickly open your current workspace in external editors, file managers, or terminals. Verdent automatically detects available tools on your system.

**Shortcut:** `Cmd+E` (macOS) / `Ctrl+E` (Windows/Linux)

### Supported Editors [#supported-editors]

| Editor        | Command           |
| ------------- | ----------------- |
| VS Code       | `code .`          |
| Cursor        | `cursor .`        |
| Windsurf      | `windsurf .`      |
| IntelliJ IDEA | `idea .`          |
| WebStorm      | `webstorm .`      |
| Goland        | `goland .`        |
| Sublime Text  | `subl .`          |
| Zed           | `zed .`           |
| Vim/Neovim    | Opens in terminal |
| Emacs         | `emacs .`         |

### System Tools (macOS) [#system-tools-macos]

| Tool     | Description                     |
| -------- | ------------------------------- |
| Finder   | Open workspace folder in Finder |
| Terminal | Open workspace in Terminal.app  |

***

## Keyboard Shortcuts [#keyboard-shortcuts]

### Essential Shortcuts [#essential-shortcuts]

| Action                  | macOS         | Windows/Linux  |
| ----------------------- | ------------- | -------------- |
| **Open Settings**       | `Cmd+,`       | `Ctrl+,`       |
| **New Task**            | `Cmd+N`       | `Ctrl+N`       |
| **New Workspace**       | `Cmd+Shift+N` | `Ctrl+Shift+N` |
| **Switch Chat Mode**    | `Cmd+.`       | `Ctrl+.`       |
| **Switch Model**        | `Cmd+/`       | `Ctrl+/`       |
| **Toggle Detail Panel** | `Cmd+L`       | `Ctrl+L`       |
| **Toggle Sidebar**      | `Cmd+B`       | `Ctrl+B`       |
| **Toggle Terminal**     | `Cmd+J`       | `Ctrl+J`       |
| **Open in IDE**         | `Cmd+E`       | `Ctrl+E`       |

***

## Data Storage [#data-storage]

Verdent stores configuration in these locations:

| Data                  | Location                     |
| --------------------- | ---------------------------- |
| **Configuration**     | `~/.verdent/config.json`     |
| **Permissions**       | `~/.verdent/permission.json` |
| **MCP Configuration** | `~/.verdent/mcp.json`        |
| **Custom Commands**   | Stored in Verdent directory  |
| **Worktrees**         | `{project}/.worktrees/`      |

***

## FAQs [#faqs]

<Accordion title="When do settings changes take effect?">
  Most settings apply immediately:

  * Theme, models, thinking levels: Instant
  * Rules: Apply to new conversations after save
  * Subagents: Available immediately after creation

  **Exception:** Some terminal and MCP settings may require session restart.
</Accordion>

<Accordion title="What's the difference between Base and Worktree workspaces?">
  **Base** is your main project directory. **Worktree** creates an isolated git worktree with its own branch, allowing parallel development without conflicts.
</Accordion>

<Accordion title="Can workspaces share changes?">
  Yes. Since worktrees use the same git repository, you can merge changes between branches, cherry-pick commits, or rebase as needed.
</Accordion>

***

## See Also [#see-also]

<CardGroup cols="2">
  <Card title="Execution Modes" icon="toggle-on" href="/docs/verdent/execution-modes/overview">
    Agent Mode and Plan Mode details
  </Card>

  <Card title="Extensibility & Integration" icon="plug" href="/docs/verdent/advanced-features/integrations">
    Permissions, rules, and MCP integration
  </Card>
</CardGroup>