---
title: Configuration & Customization
description: "Configure Verdent through the Settings panel"
---

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

### What You'll 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

**Keyboard Shortcut:**
- **macOS:** `Cmd+,`
- **Windows:** `Ctrl+,`

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

Settings changes apply immediately without requiring restart.

---

## 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

| 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

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

### Automation

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

### 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

| 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

Configure which models appear in the model selector.

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

### 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

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

Rules are Markdown files that guide Verdent's behavior.

### 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

```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

Define security rules to block potentially dangerous commands.

### 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

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

### 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

### 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

**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

```
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

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

---

## 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

```
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

Configure Model Context Protocol servers for external tool integration.

**Access:** Settings → MCP

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

### 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

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

---

## Terminal Settings

**Access:** Settings → Terminal

### Font Settings

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

### 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

**Access:** Settings → Editor

### 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

| 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

| 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

**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

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

| 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)

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

---

## Keyboard 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

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

<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

<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>