Reference

Configuration & state

verde.json settings, update and transcript preferences, verde.yml stacks, themes, state files, and runtime logs.

verde.json

User config is loaded from $XDG_CONFIG_HOME/verde/verde.json or ~/.config/verde/verde.json on Linux/macOS, and %APPDATA%\Verde\verde.json on Windows. VERDE_CONFIG can point to a custom file. It is read on startup and on app refresh.

json
{
  "theme": {
    "theme": "default",
    "colors": {
      "background": "#101820",
      "panel": "#151b24",
      "accent": "#50c878",
      "text": "#f0f0f5",
      "selection": "#58a6ff"
    }
  },
  "ui": {
    "font_size": 20
  },
  "open": {
    "default": "folder",
    "links": "verde_browser"
  },
  "terminal": {
    "font_size": 18,
    "profiles": [
      { "label": "Local Agent", "command": ["my-agent", "--interactive"] }
    ]
  },
  "transcript": {
    "tool_call_groups": "collapsed"
  },
  "updates": {
    "check_automatically": true
  },
  "notifications": {
    "enabled": true
  },
  "keybinds": {
    "new_thread": "CommandOrControl+T",
    "browser": "Ctrl+B",
    "workspace": {
      "focus_up": "Ctrl+K",
      "focus_down": "Ctrl+J",
      "focus_left": "Ctrl+H",
      "focus_right": "Ctrl+L",
      "previous": "Alt+Up",
      "next": "Alt+Down"
    }
  }
}

Keybinds are loaded on startup and on app refresh. Use a string for one shortcut or a string array for multiple shortcuts. Use null, an empty string, or an empty array to disable a binding. See Keybinds for the full keybinds reference.

Most of these options also appear in Settings:

  • Appearance — theme and UI font size.
  • Transcript — tool-call groups: collapsed, expanded, or remember_last.
  • Terminal — font size, launch profiles, and whether terminal link clicks open in Verde's browser pane or the system browser.
  • Workspace — the default open action for project files and folders.
  • Agent integrations — status-pip hooks for supported provider CLIs.
  • Updates — check now, install an available release, and automatic checks.
  • Notifications — enable or disable desktop notifications.

Settings that write verde.json apply when you choose Save. Provider hook installation/removal runs immediately because it updates the provider's own configuration.

Open actions

open.default controls the workspace header's primary open action. Supported string values are folder, editor, cursor, vscode, and zed. editor uses the configured system editor; the named values target that application directly.

For another editor or workspace tool, use a custom action:

json
{
  "open": {
    "default": {
      "label": "Workbench",
      "action": "my-editor ."
    },
    "links": "system_browser"
  }
}

The custom command runs through the platform shell with the imported project as its working directory. open.links accepts verde_browser or system_browser and controls where links clicked in terminal output open.

Updates

Automatic update checks are enabled by default. Disable them in Settings or with:

json
{
  "updates": {
    "check_automatically": false
  }
}

The Updates card shows the installed version and a wrapped release-note preview. Use Show more to expand the notes in place or Open release page for the complete GitHub release. You can also install the newest release without opening Settings:

bash
verde update

On Linux and macOS, restart Verde after the installer completes. AUR-managed Linux installs open yay or paru in an interactive terminal pane. The Windows updater exits the running app, installs the release, and relaunches it.

Transcript preferences

transcript.tool_call_groups controls how consecutive transcript tool calls open: collapsed, expanded, or remember_last. Failed groups open so their error remains visible. With remember_last, Verde also maintains its internal last-expanded state for the next group. See Chat, models & runs.

verde.yml stack config

Project stack config is loaded from verde.yml or verde.yaml in the workspace root. processes: and agents: entries both run in terminal docks; agent entries may also declare provider (codex, claude, opencode, cursor, amp, or other), revive, notify, mcp, and hooks metadata. New agent metadata defaults to disabled unless explicitly set.

yaml
processes:
  web:
    command: "npm run dev"
    cwd: "."
    restart: on_crash

agents:
  codex:
    provider: codex
    command: "codex"
    cwd: "."
    revive: attach_or_create
    notify: true
    mcp: true
    hooks: true

Use processes: for normal long-running commands such as dev servers. Use agents: for terminal/TUI AI tools that should behave like first-class Verde surfaces. With the Codex example above, Verde creates or reuses a terminal dock for the agent and wires Codex hook events into pane/workspace attention. Plain codex managed commands are launched with features.codex_hooks=true when hooks: true is set, so PermissionRequest can mark the surface waiting and Stop can mark it done.

Start or restart a configured Codex agent with:

bash
verde live agent open --provider codex
verde live process restart --name codex

Use verde live agent open --provider codex for the default Codex TUI flow; it creates a managed terminal surface, applies Codex hook setup, and does not need a verde.yml entry. Use verde live process restart --name codex when you want to launch or restart the named agent declared in verde.yml. The same default Codex TUI action is available from the workspace sidebar by right-clicking the workspace new-thread/pencil button and choosing Open Codex TUI.

A Codex TUI opened manually in any Verde terminal still gets Verde identity environment variables and can update the surface through verde notify, BEL, OSC 777, or MCP, but it is not automatically a managed verde.yml agent unless it is launched through the configured process entry.

Themes

Verde ships a warm-green native theme out of the box. Choose Verde, Omarchy, or an installed theme from Settings → Appearance → Theme. The website's theme gallery provides portable packages that import and activate in one command:

bash
verde theme import https://verdeai.dev/themes/kanagawa.json

Imported themes remain in the same Settings dropdown after switching away. You can also import a local JSON file or a GitHub file-page URL. Use verde theme validate <file-or-url> to check a package without installing it, and verde theme export [file] --name "My theme" to create a portable package from the currently resolved colors.

To override individual theme tokens manually, edit verde.json under theme.colors:

json
{
  "theme": {
    "colors": {
      "background": "#101820",
      "panel": "#151b24",
      "accent": "#50c878",
      "text": "#f0f0f5",
      "selection": "#58a6ff"
    }
  }
}

Omit theme.theme to keep Omarchy auto-detection (see below), or set it to "default" to start from Verde's built-in colors.

Omarchy color auto-detection

On Omarchy systems, UI colors are loaded from an Omarchy-compatible colors.toml. Verde honors the first found of:

  1. VERDE_OMARCHY_COLORS=/path/to/colors.toml
  2. $XDG_CONFIG_HOME/omarchy/current/theme/colors.toml
  3. Named Omarchy themes such as $XDG_CONFIG_HOME/omarchy/themes/verde/colors.toml or ~/.config/omarchy/themes/verde/colors.toml

Missing values fall back to Verde defaults. See examples/omarchy/verde/colors.toml for the shape.

State files

App state is saved through SDL's pref path in state.sqlite. Discover the exact path on your machine with:

bash
verde state path --json

You can read projects, panes, threads, and transcripts offline:

bash
verde state workspaces --json
verde state panes --project current --json
verde state threads --project current --json
verde state transcript --project current --thread 0 --json

See CLI reference for the full state command surface.

Logs

Verde writes runtime logs under SDL's platform pref path. Discover the exact directory on your machine with verde state path --json. On Linux, the usual paths are:

  • ~/.local/share/verde/Native/logs/verde.stderr.log
  • ~/.local/share/verde/Native/logs/last-crash.log

Those files capture Zig panic output, provider helper stderr, and the last panic marker written before the app aborted. Tail the stderr log to diagnose provider crashes, prompt-send failures, or rendering issues.

Third-party components

Main third-party components used by the desktop app:

  • @anthropic-ai/claude-agent-sdk for Claude Code provider integration.
  • fff.nvim / fff-c / fff-search for fast file indexing and search, vendored in vendor/fff. License: MIT.
  • Ghostty / libghostty-vt for terminal emulation and VT parsing. License: MIT.
  • zsdl from zig-gamedev for Zig bindings to SDL3. License: MIT.
  • SDL3 from libsdl-org for windowing, input, display integration, and rendering support.
  • zqlite by Karl Seguin for SQLite access. License: MIT-style.
  • zig_dif and zig_markdown for chat markdown and code rendering.
  • stb_image by Sean Barrett and contributors for image decoding, vendored in vendor/stb_image.h. License: public domain or MIT.
  • Codicon, Nerd Fonts, Noto Sans, JetBrains Mono Nerd Font, and Cal Sans font assets for the native UI. See notices in packages/desktop/src/assets/fonts.

If you redistribute Verde, keep the relevant upstream notices and license texts with the distributed app and any vendored source. Verde is licensed under the MIT License — see LICENSE.

Edit this page on GitHub →