Configuration & Customization

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

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

Models Settings

Configure which models appear in the model selector.

For provider API keys, see Bring Your Own Key (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

# 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

Commit AGENTS.md to version control to share project-specific standards with your team.

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:

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

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

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

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.

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.

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.

Configuration & Customization

Execution Modes

Extensibility & Integration

On this page