# Quickstart Source: https://verdeai.dev/docs/quickstart Edit: https://github.com/JonathanRiche/verde/blob/master/packages/website/src/content/docs/quickstart.md ## Install Install the latest Verde release from the website. On Linux or macOS: ```bash curl -fsSL https://verdeai.dev/install.sh | sh ``` On Windows x64, open PowerShell and run: ```powershell irm https://verdeai.dev/install.ps1 | iex ``` The installers download the matching release artifact from GitHub and verify it before installation. Linux installs into `~/.local`, macOS installs into `/Applications`, and Windows installs the complete app and runtime package into `%LOCALAPPDATA%\Programs\Verde`, creates a Start Menu shortcut, and launches the app. The Windows install does not require administrator access. For other paths — Arch Linux via the AUR, an npm launcher, a custom prefix, or a source build — see the [install section on the homepage](/#install). On Linux, the embedded browser pane uses the system WPE WebKit runtime. The installer will warn if the required libraries are missing and print the package command for your distribution. You can let it install them by setting `VERDE_INSTALL_BROWSER_DEPS=1` before running it. ## Authenticate a provider Verde does not host a model. It drives the coding-agent CLIs already installed on your machine, so install and authenticate at least one provider before launching the app: | Provider | Setup | | ----------- | ---------------------------------------------------------------------------------- | | Codex | Install the [Codex CLI](https://github.com/openai/codex), then run `codex login`. | | Claude Code | Install [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and Node.js, ensure `node` is on `PATH`, then log in. | | OpenCode | Install [OpenCode](https://github.com/anomalyco/opencode); ensure `opencode` is on `PATH`. | | Cursor | Install the [Cursor CLI](https://cursor.com/docs/cli/installation), ensure `agent` is on `PATH`, run `agent login`. `CURSOR_API_KEY` is also supported for headless environments. | | Amp | Install [Amp](https://ampcode.com); ensure `amp` is on `PATH`. Amp runs as a terminal TUI rather than a chat pane — launch it from the command palette. | See [Provider setup](/docs/providers) for the full per-provider notes. ## Launch ```bash verde ``` The first launch opens an empty workspace. If no GUI provider is ready, the **Connect an AI provider** screen shows which CLIs are missing, need sign-in, or are ready. Finish setup and choose **Check again**, or choose **Not now** to continue without a chat provider. The sidebar on the left lists your projects and threads; the main area is where chat, terminal, and browser panes live as a tiling tree. ## Import a project Right-click the sidebar or click the **+** button to import a project. Verde watches the project directory you import; threads, processes, and agents all operate against that workspace root. A project can optionally declare a stack in `verde.yml` (or `verde.yaml`) at its root — long-running processes and agent CLIs to drive from the terminal dock. See [Configuration & state](/docs/config) for the schema. ## Start a chat thread 1. With a project imported, press `Ctrl+T` (or `Cmd+T` on macOS) to create a new chat thread. 2. Open the searchable model picker. Before the first message you can choose both the provider and model; after that, the provider stays bound to the thread. 3. Open the **Run** pill to choose available reasoning and speed options, plus **Supervised** or **Full access** command permissions. 4. Type a prompt and press `Enter` to send. The transcript grows as the agent streams; consecutive tool calls collapse into a status summary you can expand. 5. Press `Tab` while focused in a chat thread to return focus to the prompt box. See [Chat, models & runs](/docs/chat) for provider readiness, model shortcuts, follow-ups, approvals, and transcript preferences. ## Tile a browser pane Press `Ctrl+B` to toggle the embedded browser pane next to the focused chat. On Linux it uses WPE WebKit, on macOS WKWebView, on Windows WebView2 — never a bundled Chromium. Use it to keep docs, a preview server, or a staging URL in view while the agent works. You can drive the browser pane from the CLI too: ```bash verde live browser open --url http://localhost:3000 verde live browser navigate --url http://localhost:3000/dashboard verde live browser eval --script "document.title" ``` Click the browser inspector to enter **Design Mode**. Select an element, box, or freeform region; describe the change; then route the resulting context to a chat or terminal agent. See [Design Mode](/docs/design-mode) for platform screenshot support and delivery behavior. ## Split a terminal Press `Ctrl+Shift+T` to split a terminal pane next to the focused workspace pane. Right-click inside a terminal to spawn shell tabs or agent launch-profile tabs (Claude, OpenCode, Codex, Cursor, Amp). Per-terminal zoom (`Ctrl+-` / `Ctrl+=`) and the full layout persist across launches. ## Move around - `Ctrl+H / J / K / L` — move focus across panes, vim-style - `Ctrl+Shift+H / J / K / L` — swap the focused pane with its neighbor (rearrange the tiling) - `Alt+Shift+← ↑ ↓ →` — resize the focused pane - `Alt+Z` — zoom the focused pane to fill the workspace; press again to restore - `Alt+1 … Alt+9, Alt+0` — jump between workspaces by sidebar order - `Alt+↑ / Alt+↓` — cycle to the previous / next workspace The full set of defaults and how to remap them is in [Keybinds](/docs/keybinds). ## Open the command palette `Ctrl+Shift+P` opens a Raycast-style launcher that ranks chat threads, open panes, workspaces, and app commands in a single searchable list. Press `Ctrl+Enter` on any result to open it in a fresh pane. Closing a workspace with `Ctrl+Shift+W` removes it from the active sidebar but keeps its layout and threads. Use the command palette's reopen action to bring it back. Slash commands like `/stack` and `/process` run from the composer alongside each provider's own commands. See [Panes & tiling](/docs/panes) for the full pane surface. ## Where to go next - [Provider setup](/docs/providers) — provider-specific notes and troubleshooting. - [Chat, models & runs](/docs/chat) — model selection, run permissions, approvals, and transcript controls. - [Design Mode](/docs/design-mode) — send browser selections to chat and terminal agents. - [Panes & tiling](/docs/panes) — splits, focus, resize, zoom, the terminal dock, and the browser pane. - [Keybinds](/docs/keybinds) — every default and how to remap. - [CLI reference](/docs/cli) — drive Verde from your shell with `verde live` and `verde state`. - [Configuration & state](/docs/config) — `verde.json`, `verde.yml`, themes, Omarchy integration. - [Troubleshooting](/docs/troubleshooting) — provider auth, browser runtime, source-build issues. --- # Provider setup Source: https://verdeai.dev/docs/providers Edit: https://github.com/JonathanRiche/verde/blob/master/packages/website/src/content/docs/providers.md ## How providers work Verde does not host a model and does not relay your prompts through a hosted backend. It spawns and talks to the coding-agent CLIs you already have on your machine, and supports each agent in one or both of two modes: - **GUI chat** — the provider drives Verde's native chat panes over its own protocol: streaming transcript, composer, slash commands, approvals. - **Terminal TUI** — Verde launches the agent's own TUI inside an embedded Ghostty terminal pane, wired into the sidebar's live status pips. | Provider | GUI chat | Terminal TUI | How the GUI integration talks | | ----------- | -------- | ------------ | -------------------------------------------------------------- | | Codex | ✓ | ✓ | Runs the local `codex` CLI; boots `codex app-server` per thread | | Claude Code | ✓ | ✓ | Anthropic's Claude Agent SDK against the local runtime | | OpenCode | ✓ | ✓ | Drives the `opencode` CLI; starts `opencode serve` on demand | | Cursor | ✓ | ✓ | Speaks to the Cursor CLI ACP server (`agent acp`) | | Amp | – | ✓ | TUI-only — launches the `amp` CLI in a terminal pane | All of them run against the project directory you imported into Verde. Tokens, transcripts, and project files stay on your machine. ## Readiness check If none of the GUI providers is available at launch, Verde opens **Connect an AI provider**. Each provider reports **Ready**, **CLI not found**, **Sign-in needed**, or **Could not verify** while Verde checks its executable and local authentication. Install or sign in using the instructions below, then choose **Check again**. **Open setup guide** returns to this page and **Not now** dismisses the screen. Amp is excluded from this check because it is TUI-only. A GUI provider can also become unavailable later—for example, after credentials expire—in which case sending shows an explicit error instead of dropping the prompt. ## Codex Install the [Codex CLI](https://github.com/openai/codex) and authenticate: ```bash codex login ``` Verify `codex` is on `PATH` from a normal shell. Verde starts `codex app-server` when a Codex thread begins; you do not need to start it yourself. Codex threads expose **Default** and **Fast** under the composer's **Run** pill. The setting maps to Codex's `service_tier` / `fast_mode`. The Run menu also shows the reasoning levels supported by the selected model and the thread's access setting. ## Claude Code Install [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and log in on your machine. Verde talks to the local runtime through Anthropic's Claude Agent SDK — there is no Verde-side authentication. Make sure the Claude Code binary and `node` are both reachable from the shell environment Verde was launched from. Packaged Verde installs include the provider bridge; Verde runs it with the Node.js executable found on `PATH`. ## OpenCode Install [OpenCode](https://github.com/anomalyco/opencode) and verify `opencode` is on `PATH`. Verde starts `opencode serve` on demand when an OpenCode thread begins. OpenCode does not have a Codex-style speed tier concept, so the **Speed** row is hidden when OpenCode is selected. ## Cursor Install the [Cursor CLI](https://cursor.com/docs/cli/installation), make sure `agent` is on your `PATH`, and authenticate: ```bash agent login ``` `CURSOR_API_KEY` is also supported for headless environments where interactive login is not possible. Verde talks to the Cursor ACP server (`agent acp`) over its native protocol. Cursor models that advertise fast-mode support show **Default** and **Fast** under the **Run** pill. The row is hidden for Cursor models without that capability. ## Amp Install [Amp](https://ampcode.com) and make sure `amp` is on your `PATH`. Amp is **TUI-only**: it does not appear in the chat composer's provider switcher. Instead, launch it from the command palette (`Ctrl+Shift+P` → **Start New Amp TUI**) and Verde opens the `amp` CLI in a new embedded terminal pane in the current workspace. To wire Amp into the sidebar's live status pips, install Verde's Amp plugin: ```bash verde integrations install amp --global ``` That writes a small lifecycle plugin to `~/.config/amp/plugins/verde-notify.ts` which reports `working` / `done` / `error` to the pane's status pip as the agent runs (only when Amp is running inside a Verde pane). You can also toggle it from the settings modal under **Status pip hooks**, and remove it with `verde integrations remove amp --global`. ## Models and run settings The searchable model picker groups models by provider, marks defaults, and supports `Ctrl+1` through `Ctrl+9` for its visible results. OpenCode, Claude Code, and Cursor model lists are loaded from the installed provider; Codex uses Verde's supported model list. Before a new thread sends its first message, choosing a model can also switch the provider. Once the transcript has started, the provider is locked to keep the provider session consistent. The **Run** pill contains only controls the selected provider/model supports: reasoning, **Default/Fast** speed, and **Supervised/Full access** permissions. See [Chat, models & runs](/docs/chat) for the complete behavior. To run several providers side by side, create additional chat threads (one per provider) and tile them in the same workspace. Each thread keeps its own provider, model, and transcript; the layout is shared. ## Driving provider CLIs from terminal docks You can also launch any provider's TUI directly inside a terminal pane — useful when you want the agent's native UI rather than Verde's chat surface. The command palette (`Ctrl+Shift+P`) has a **Start New … TUI** entry for each of Codex, Claude, OpenCode, Cursor, and Amp, plus **Open Current Thread in TUI** entries that promote a running GUI chat thread into that provider's terminal TUI. Right-clicking inside a terminal offers the same launch profiles as tabs. From the CLI: ```bash verde live agent open --provider codex verde live process restart --name codex ``` The first command opens a managed Codex TUI without requiring a `verde.yml` entry. The second launches or restarts a Codex agent declared in your `verde.yml` `agents:` block. See [Configuration & state](/docs/config) for the stack schema and the [CLI reference](/docs/cli) for the full command surface. ## Troubleshooting provider auth If prompt sending fails, check in this order: 1. **Is the provider installed?** `which codex`, `which opencode`, `which agent`, etc., from the shell Verde was launched in. GUI launches on some platforms inherit a different `PATH` than a terminal — relaunch Verde from a terminal if you suspect this. 2. **Is the provider authenticated?** Re-run the provider's login command (`codex login`, `agent login`, etc.) and confirm credentials are still valid. 3. **Is the project imported?** Verde runs the provider against the imported project directory. A provider CLI in a different working directory will not see the same files. 4. **Check the logs.** Provider helper stderr is written to the runtime log alongside Zig panics. On Linux: ```bash tail -f ~/.local/share/verde/Native/logs/verde.stderr.log ``` For broader install and runtime issues, see [Troubleshooting](/docs/troubleshooting). --- # Chat, models & runs Source: https://verdeai.dev/docs/chat Edit: https://github.com/JonathanRiche/verde/blob/master/packages/website/src/content/docs/chat.md ## Connect a provider Verde checks the four GUI-chat providers—Codex, Claude Code, OpenCode, and Cursor—when the app opens. If none is ready, the **Connect an AI provider** screen reports one of these states for each provider: - **Ready** — the CLI is installed and authenticated. - **CLI not found** — install the provider and make sure its executable is on the `PATH` inherited by Verde. - **Sign-in needed** — run the provider's login flow, then return to Verde. - **Could not verify** — the readiness check failed or timed out. After installing or signing in, choose **Check again**. **Not now** dismisses the screen without changing provider configuration. Amp is not listed because it runs as a terminal TUI rather than a native chat provider. See [Provider setup](/docs/providers) for the exact install and login commands. ## Choose a provider and model Create a chat with `Ctrl+T`, then open the model pill in the composer. The picker has a provider rail, model search, default-model badges, and `Ctrl+1` through `Ctrl+9` shortcuts for the visible results. Before the first message is sent, selecting a model from another provider also switches the thread's provider. Once a thread has messages, its provider is locked so the transcript and provider session stay consistent; create another thread to use a different provider. Verde loads the available models from OpenCode, Claude Code, and Cursor at runtime. Codex models come from Verde's supported model list. A provider that is missing or signed out remains visible with a readiness hint instead of silently accepting a prompt it cannot send. ## Configure a run The **Run** pill groups the settings that affect the next agent run: - **Reasoning** appears only when the selected provider and model expose a reasoning-effort control. - **Speed** appears for Codex and for Cursor models that support fast mode. Choose **Default** or **Fast**. - **Access** is always available. **Supervised** asks before risky commands; **Full access** lets the agent run commands without asking first. Access is saved per thread. Reasoning and speed options can change when you switch models because not every provider exposes equivalent controls. ## Send, steer, and stop Press `Enter` to send the composer. While an agent is working, type another message and press `Tab`: Codex tries to steer the active turn, while Claude Code, OpenCode, and Cursor queue the message as the next turn. The pending message stays pinned above the composer. Double-click that pin to pull it back into an empty composer for editing, then press `Tab` to queue it again. **Stop** aborts the active run. Verde keeps the draft with its thread, so changing panes does not discard unfinished text. The same paths are scriptable with `verde live chat send`, `followup`, `stop`, and `draft`. See [CLI reference](/docs/cli#chat-control). ## Attach images and mention files Paste an image with `Ctrl+V` (`Cmd+V` on macOS) while the chat composer owns focus. Verde stages it above the composer instead of converting it to text. Paste again to attach multiple images, remove individual previews before sending, and click a transcript image to open its full-size preview. Codex, Claude Code, and OpenCode accept local image attachments. Cursor accepts them only when its ACP session advertises image support. Remote Herdr Codex GUI sends do not currently accept local image attachments; Verde reports the limitation instead of silently dropping them. To reference a workspace file, type `@` followed by part of its name or path. Verde searches the imported workspace, shows up to eight matching files, and inserts the selected relative path into the prompt. Use the arrow keys and `Enter`, or click a result. ## History and provider threads Each workspace ends with a **History · N** row in the expanded sidebar. It opens the command palette scoped to that workspace's saved chats, grouped into **Today**, **This week**, and **Older**. Search there to find a thread, press `Enter` to open it in an existing chat pane, or `Ctrl+Enter` to open it in a new pane. Press `Tab` on a result for thread actions. Right-click a workspace—or use `Ctrl+Shift+P`—to import an existing Codex, OpenCode, or Claude Code provider thread. The import dialog lists recent provider sessions and also accepts a provider thread ID. Cursor thread import is not supported yet. Imported and Verde-created provider threads can be refreshed with **Sync thread** when they have a provider thread ID and no request is running. The same thread menu can open a linked thread in its provider TUI, return a TUI thread to chat, or archive the thread. Archiving removes it from the active sidebar without deleting its persisted transcript. ## Approvals and input requests Providers can pause a run for approval. Verde renders the request in the transcript and lets you approve or deny it without leaving the chat pane. Codex MCP yes/no confirmations use this same approval surface. Structured MCP forms are not supported yet; Verde marks the input request unsupported and declines it rather than guessing an answer. **Full access** reduces command approvals, so use it only for workspaces and instructions you trust. ## Tool-call groups Consecutive tool calls collapse into a summary row showing the number of calls and their completed, failed, or running state. Click the row to inspect the individual calls. A group containing a failure opens by default so the error is not hidden. Choose the default under **Settings → Transcript → Tool call groups**: - **Collapsed** — start each group closed unless it failed. - **Expanded** — start each group open. - **Remember last** — reuse the last state you chose. The same preference is available as `transcript.tool_call_groups` in [`verde.json`](/docs/config#verdejson). ## Design feedback from the browser For UI work, Design Mode can select an element or region in the browser and send its DOM context—and, where supported, a screenshot—straight to a chat or terminal agent. See [Design Mode](/docs/design-mode). --- # Design Mode Source: https://verdeai.dev/docs/design-mode Edit: https://github.com/JonathanRiche/verde/blob/master/packages/website/src/content/docs/design-mode.md ## Start Design Mode Open your app in Verde's browser pane, then click the inspector button beside the address bar. Design Mode overlays the page so you can turn a visual target into an agent-ready prompt without describing its location by hand. Use the inspector's dropdown to choose a selection mode: - **Point** — click one DOM element. - **Draw Box** — drag a rectangular region. - **Draw Freeform** — draw around an irregular region. Design Mode works on `app://` content and HTTP(S) pages, including localhost preview servers. It is unavailable on restricted URL schemes such as `file:`, `data:`, and `about:`. ## Describe the change After making a selection, type the requested change in the prompt bubble. Verde adds selection context such as the page URL, element details, and selected geometry. This gives the agent both your instruction and a stable description of what you pointed at. The selection overlay belongs to the page preview; it does not edit the page or source files by itself. The receiving agent still decides what code to inspect and change. ## Choose where to send it When more than one compatible agent pane is open, **Send to** lets you choose a chat thread or terminal TUI. With only one target, Verde selects it automatically. - An idle chat with a clean composer sends immediately. - A working chat can receive the request as a queued follow-up. - If the chat already has an unsent draft, Verde preserves it and places the Design Mode request in the composer instead of overwriting or unexpectedly sending the draft. - A terminal TUI receives the prompt as pasted input but does not submit it. Review or edit the text in the TUI, then press `Enter` yourself. ## Screenshots and platform support All native browser backends support the selection overlay and text context: WPE WebKit on Linux, WKWebView on macOS, and WebView2 on Windows. Selection screenshots currently require the Linux WPE backend's frame-copy support. On macOS and Windows, Design Mode still sends the instruction and DOM selection context without an image. If a screenshot is captured, chat targets receive it as an attachment; terminal targets receive its local file path in the pasted prompt. ## Control Design Mode from the CLI The live CLI can enable the inspector and select its mode: ```bash verde live browser inspector-enable verde live browser inspector-mode --mode point verde live browser inspector-mode --mode draw-box verde live browser inspector-mode --mode draw-freeform verde live browser inspector-disable ``` `inspector-toggle` is also available. Add `--json` for automation, and use the other browser commands to open or navigate the preview first. See [CLI reference](/docs/cli#browser-control). --- # Panes & tiling Source: https://verdeai.dev/docs/panes Edit: https://github.com/JonathanRiche/verde/blob/master/packages/website/src/content/docs/panes.md ## Workspace anatomy Each Verde window is one workspace tied to an imported project. Inside a workspace you get a tiling tree of panes — chat threads, terminals, and a browser pane — that share the main area. The sidebar on the left lists projects and threads; the main area is the tiling surface; the terminal dock is a terminal pane living in the same tree as chat and browser panes. There is no floating-window layer. Everything is tiled, and the layout persists across launches. ## Splitting panes Splits come from two places: keyboard shortcuts for the common cases, and the pane header buttons for everything else. - `Ctrl+Shift+T` — split a terminal pane next to the focused workspace pane. - `Ctrl+T` — start a new chat thread (creates a new chat pane). For chat-vs-chat splits and terminal-vertical splits, use the pane header buttons: `C|` and `C-` split a chat pane vertically or horizontally; `T|` and `T-` do the same for terminals. Right-click terminal content for selection copy, zoom, workspace splits around the focused pane, and **Close pane**. Right-click a terminal tab to rename or close it. If `terminal.profiles` is configured in `verde.json`, the first custom launch profile also appears in the terminal context menu. Use `Ctrl+Alt+T` for a new shell tab. Launch Codex, Claude, OpenCode, Cursor, or Amp TUIs from the command palette; the built-in agent launchers are not entries in the terminal right-click menu. Terminal-internal tabs live inside the focused terminal pane. Workspace split actions create new workspace panes in the tiling tree, not new tabs inside a terminal. ## Moving focus - `Ctrl+H / J / K / L` — focus the pane to the left / down / up / right (vim-style). - `Tab` — while focused inside a chat thread pane, return focus to the prompt box. - `Alt+1 … Alt+9, Alt+0` — jump between workspaces by sidebar order. - `Alt+↑ / Alt+↓` — cycle to the previous / next workspace. ## Resizing - `Alt+Shift+← ↑ ↓ →` — grow the focused pane in that direction. - Drag the divider between two workspace panes to resize the split manually. Resizes are committed to the layout immediately and persist with the workspace. ## Rearranging panes - `Ctrl+Shift+H / J / K / L` — move the focused pane past its neighbor in that direction. - `Ctrl`-drag a pane — pick it up with the mouse and drop it where it should go. Use these when the layout is right but a pane is in the wrong place. Moves are non-destructive — every pane keeps its content and provider. ## Zooming and minimizing - `Alt+Z` — zoom the focused pane to fill the workspace; press again to restore. - Pane header button — minimize the pane into the restore strip; click to bring it back. - Pane header button — close the pane (or `Ctrl+W` / `Alt+X`). ## The sidebar The left rail shows projects, threads under each project, and the active pane in each workspace. Each pane row carries its provider glyph and a live title, so you always know what is working without switching to it. - `Ctrl+S` — toggle the sidebar (visible ↔ icon rail). - `Ctrl+Shift+S` — toggle the sidebar's hidden mode (no rail at all). When collapsed to the icon rail, each workspace avatar carries a row of small **status pips** — one dot per open pane, in layout order. Pips pulse green while an agent is working, yellow while it waits for input, and settle when it's done or errors, so you can watch several agents from a rail a few pixels wide. Context menus (new thread, close, expand) still work from the collapsed rail. Right-click the sidebar for project import, rename, and **Close workspace**, and use the new-thread / pencil button to open a Codex TUI directly. Closing a workspace archives it without deleting its saved panes, threads, or layout. Use the command palette's reopen action—or `verde live workspace reopen`—to restore it. ## The terminal dock Verde's embedded terminals are powered by Ghostty's `libghostty-vt` terminal engine. Each terminal pane is a full terminal with tabs, splits, OSC titles, scrollback with a scrollbar, and per-terminal zoom. - `Ctrl+Alt+T` — new terminal tab inside the focused terminal pane. - `Ctrl+Shift+R` — rename the active terminal tab. - `Ctrl+Shift+PageUp` / `Ctrl+Shift+PageDown` — previous / next terminal tab. - `Ctrl+Alt+↑ ↓ ← →` — move focus between terminal splits inside the focused terminal pane. - `Ctrl+-` / `Ctrl+=` — per-terminal zoom; restored with the terminal layout. Per-terminal zoom is independent of the workspace-level zoom (`Alt+Z`). It persists per terminal surface, not per workspace. Terminal applications can render Kitty graphics-protocol images inline. The image follows terminal scrolling and is cleared when the application erases or replaces it, like other terminal content. ## The browser pane Press `Ctrl+B` to toggle the embedded browser pane next to the focused chat. The backend is the host platform's native webview: WPE WebKit on Linux, WKWebView on macOS, WebView2 on Windows. No bundled Chromium. You can drive the browser pane from the CLI: ```bash verde live browser open --url https://example.com verde live browser navigate --url https://example.com/dashboard verde live browser eval --script "document.title" verde live browser status --json ``` The inspector button enters **Design Mode**, where you can select an element or draw a region and send its context to a chat or terminal agent. See [Design Mode](/docs/design-mode) for selection modes, routing, and screenshot support, and [CLI reference](/docs/cli) for the full browser command surface. ## Persisting layouts Workspace layouts, per-terminal zoom, terminal tab state, and the browser pane's URL all persist across launches in Verde's SQLite state. Closing the app and reopening it restores the same tiling tree for each project. Closing a workspace from the sidebar or with `Ctrl+Shift+W` also preserves that state; reopen the workspace from the command palette when you need it again. You can inspect the persisted layout without launching the app: ```bash verde state panes --project current --json ``` And the live layout while the app is running: ```bash verde live panes --project current --json ``` ## Command palette and slash commands `Ctrl+Shift+P` opens the command palette — a single ranked list of threads, panes, workspaces, and app commands. `Ctrl+Enter` on a thread result opens it in a fresh pane. The palette also carries **Start New … TUI** entries for Codex, Claude, OpenCode, Cursor, and Amp, and **Open Current Thread in TUI** entries that promote a GUI chat thread into that provider's terminal TUI. The sidebar's **History · N** row opens the same palette scoped to one workspace's saved threads. Thread actions include open in a new pane, sync from the provider, open as a TUI or chat, and archive. Workspace actions also import existing Codex, OpenCode, and Claude Code threads. See [Chat, models & runs](/docs/chat#history-and-provider-threads) for the complete workflow and current provider limitations. Typing `/` in the composer opens a slash-command picker. Running a command shows a pending row in the transcript while it executes, then a result card (`/usage` renders a structured card with limit bars and recent daily usage). Workspace commands, available with every provider: - `/stack` — start / stop / restart / status for every process and agent declared in the workspace's `verde.yml`. - `/process` — start / stop / restart / focus a single declared process by name; `/process crashed` refreshes status and reports the number of crashed processes. - `//text` — escape hatch: send a literal prompt that begins with a slash. Provider-native commands surface in the same picker: - **Claude Code** — `/usage`, `/compact [instructions]`, plus skill commands such as `/code-review`, `/debug`, `/loop`, `/batch`, and `/skills`. - **Codex** — `/usage`, `/compact`, `/goal [status|clear|…]`, `/review [changes|base |commit |custom …]`, and `/shell confirm ` (requires typed confirmation). - **OpenCode / Cursor** — no native slash commands yet; `/stack`, `/process`, and `//` still work. --- # Keybinds Source: https://verdeai.dev/docs/keybinds Edit: https://github.com/JonathanRiche/verde/blob/master/packages/website/src/content/docs/keybinds.md ## Default keybinds These are the defaults, read from `packages/desktop/src/keybinds.zig`. Override any of them under `keybinds` in your Verde config — see [Remapping](#remapping) below. ### App | Combo | Action | | -------------------------- | ------------------------------------- | | `Ctrl+Shift+P` / `Cmd+Shift+P` | Command palette | | `Ctrl+T` / `Cmd+T` | New chat thread | | `Ctrl+W` / `Cmd+W`, `Alt+X` | Close the focused pane | | `Ctrl+Shift+W` / `Cmd+Shift+W` | Close the current workspace (reopen from the command palette) | | `Ctrl+R` / `Cmd+R`, `Ctrl+Shift+R`, `F5` | Refresh / reload app | | `Alt+O` | Open the default project | | `Ctrl+Shift+O` | Open in external editor | ### Sidebar & panes | Combo | Action | | -------------------------- | ------------------------------------- | | `Ctrl+S` / `Cmd+S` | Toggle the sidebar (visible ↔ icon) | | `Ctrl+Shift+S` | Toggle the sidebar's hidden mode | | `Ctrl+B` | Toggle the embedded browser pane | | `Tab` | Inside a chat pane, focus the prompt box | | `Alt+1 … Alt+9, Alt+0` | Jump between workspaces by sidebar order | | `Alt+↑` / `Alt+↓` | Cycle to the previous / next workspace | ### Focus (vim-style) | Combo | Action | | -------- | ------------------------------- | | `Ctrl+H` | Focus the pane to the left | | `Ctrl+L` | Focus the pane to the right | | `Ctrl+K` | Focus the pane above | | `Ctrl+J` | Focus the pane below | `Alt+arrow` combos are no longer focus aliases — `Alt+↑` / `Alt+↓` now cycle between workspaces (see the sidebar table above). ### Swap (rearrange the tiling) | Combo | Action | | ------------------ | ------------------------------------- | | `Ctrl+Shift+H` | Swap focused pane with the left one | | `Ctrl+Shift+L` | Swap focused pane with the right one | | `Ctrl+Shift+K` | Swap focused pane with the one above | | `Ctrl+Shift+J` | Swap focused pane with the one below | ### Resize (grow) | Combo | Action | | ------------------ | ---------------------------- | | `Alt+Shift+←` | Grow the focused pane left | | `Alt+Shift+→` | Grow the focused pane right | | `Alt+Shift+↑` | Grow the focused pane up | | `Alt+Shift+↓` | Grow the focused pane down | ### Zoom | Combo | Action | | ------- | --------------------------------------------------- | | `Alt+Z` | Zoom the focused pane to fill the workspace; toggle again to restore | ### Workspace splits | Combo | Action | | ----------------- | ------------------------------------------------- | | `Ctrl+Shift+T` / `Cmd+Shift+T` | Split a terminal pane next to the focus | Vertical / horizontal chat splits, terminal-vertical splits, and minimize have **no default keybind**. Use the pane header buttons: `C|` / `C-` for chat vertical / horizontal, `T|` / `T-` for terminal vertical / horizontal, and the minimize button. You can bind these actions yourself — see the table of binding keys below. ### Terminal (inside a focused terminal pane) | Combo | Action | | ---------------------------------- | ------------------------------- | | `Ctrl+Alt+T` / `Cmd+Alt+T` | New terminal tab | | `Ctrl+Shift+R` / `Cmd+Shift+R` | Rename the active terminal tab | | `Ctrl+Shift+PageUp` | Previous terminal tab | | `Ctrl+Shift+PageDown` | Next terminal tab | | `Ctrl+Alt+↑` / `Cmd+Alt+↑` | Focus the terminal split above | | `Ctrl+Alt+↓` / `Cmd+Alt+↓` | Focus the terminal split below | | `Ctrl+Alt+←` / `Cmd+Alt+←` | Focus the terminal split left | | `Ctrl+Alt+→` / `Cmd+Alt+→` | Focus the terminal split right | | `Ctrl+-` / `Ctrl+=` | Per-terminal zoom out / in | ### Chat transcript scrolling | Combo | Action | | ----------- | ------------------------------- | | `↑` | Scroll up one line | | `↓` | Scroll down one line | | `PageUp` | Scroll up one page | | `PageDown` | Scroll down one page | Transcript scrolling is **direct** — no inertia or velocity decay. When input stops, the view stops. Do not expect a multi-frame glide. ## Remapping Override any binding under `keybinds` in your `verde.json`. On Unix it is under `$XDG_CONFIG_HOME/verde` or `~/.config/verde`; on Windows it is under `%APPDATA%\Verde`. Use a string for one shortcut, or a string array for multiple shortcuts on the same action: ```json { "keybinds": { "new_thread": "CommandOrControl+T", "browser": "Ctrl+B", "workspace": { "close_current": "CommandOrControl+Shift+W", "focus_up": "Ctrl+K", "focus_down": "Ctrl+J", "focus_left": "Ctrl+H", "focus_right": "Ctrl+L", "previous": "Alt+Up", "next": "Alt+Down", "move_left": "Ctrl+Shift+H", "move_right": "Ctrl+Shift+L", "move_up": "Ctrl+Shift+K", "move_down": "Ctrl+Shift+J", "toggle_maximize": "Alt+Z", "close": ["CommandOrControl+W", "Alt+X"], "select": ["Alt+1", "Alt+2", "Alt+3", "Alt+4", "Alt+5", "Alt+6", "Alt+7", "Alt+8", "Alt+9", "Alt+0"] }, "terminal": { "new_tab": "CommandOrControl+Alt+T", "close": "CommandOrControl+Shift+W", "rename_tab": "CommandOrControl+Shift+R", "tab_previous": "CommandOrControl+Shift+PageUp", "tab_next": "CommandOrControl+Shift+PageDown", "focus_up": "CommandOrControl+Alt+Up", "focus_down": "CommandOrControl+Alt+Down", "focus_left": "CommandOrControl+Alt+Left", "focus_right": "CommandOrControl+Alt+Right" } } } ``` ## Disabling a binding Set the binding to `null`, an empty string, or an empty array to disable it: ```json { "keybinds": { "terminal": { "toggle": null, "split_up": null, "split_down": null, "split_left": null, "split_right": null } } } ``` ## Binding keys reference The keybinds config uses the same accelerator grammar as the desktop defaults. The top-level keys group actions by surface; the inner values are one shortcut or an array of shortcuts. | Group | Keys (subset) | | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | top | `refresh`, `open_default`, `open_editor`, `new_thread`, `command_palette`, `toggle_sidebar`, `toggle_sidebar_hidden`, `toggle_browser`, `toggle_terminal` | | chat | `chat_up`, `chat_down`, `chat_page_up`, `chat_page_down` | | `workspace` | `split_chat_vertical`, `split_chat_horizontal`, `split_terminal_vertical`, `split_terminal_horizontal`, `toggle_maximize`, `minimize`, `close`, `close_current`, `focus_left`, `focus_right`, `focus_up`, `focus_down`, `focus_prompt`, `move_*`, `grow_*`, `select`, `previous`, `next` | | `terminal` | `new_tab`, `close`, `rename_tab`, `tab_previous`, `tab_next`, `split_up`, `split_down`, `split_left`, `split_right`, `focus_up`, `focus_down`, `focus_left`, `focus_right` | Keybinds are loaded on startup and on app refresh. See [Configuration & state](/docs/config) for the full `verde.json` schema and where state lives. --- # CLI reference Source: https://verdeai.dev/docs/cli Edit: https://github.com/JonathanRiche/verde/blob/master/packages/website/src/content/docs/cli.md ## Overview `verde` is both the desktop launcher and a CLI for reading persisted state and controlling a running app. CLI-only commands run before SDL startup, so you can use them from scripts without opening a window. ```bash verde # Launch the desktop app verde app # Launch the desktop app explicitly verde --help # Show CLI help verde version [--json] # Print version metadata verde update [--json] # Install the latest Verde release verde capabilities [--json] # Print supported CLI/live features verde open [--json] # Open a URL in this Verde workspace's browser pane verde completion # Print shell completion script verde state # Read persisted state while the app is closed verde notify [options] # Update the current terminal surface verde integrations # Inspect and install optional provider hooks verde theme # Import, validate, export, or reset themes verde session # Manage persistent terminal sessions verde mcp # Run Verde's stdio MCP bridge verde herdr # Open or inspect Herdr-backed remote workspaces verde live # Control or inspect the running app ``` Use `--json` when scripting. Live IPC responses use a stable envelope: ```json { "id": 1, "ok": true, "result": {} } ``` Errors return `ok: false` with an `error.code` and `error.message`. ## Updates ```bash verde update verde update --json ``` `verde update` launches the official installer for the current platform. For an Arch installation owned by the `verde-bin` AUR package, it reports the detected `yay` or `paru` command instead so the package manager remains the owner of the installation. On Linux and macOS, restart Verde after the installer finishes. On Windows, the updater waits for the running app to exit, installs the new release, and starts Verde again. The command requires network access to the release assets. You can also check and install releases from **Settings → Updates**. For an AUR install, Verde opens `yay` or `paru` in an interactive terminal pane so sudo password prompts and package progress remain visible. The card shows the installed version, release notes, **Check now**, **Install update**, and the **Check automatically** preference. ## Theme packages Theme commands run without launching the desktop UI. Imports accept local JSON, ordinary HTTP(S) URLs, and GitHub `blob` links. A successful import installs and activates the theme; it then appears alongside Verde and Omarchy in the Settings theme dropdown. ```bash verde theme import [--dry-run] [--json] verde theme validate [--json] verde theme export [file] [--name ] [--json] verde theme reset [--json] # Hosted example from the Verde theme gallery verde theme validate https://verdeai.dev/themes/kanagawa.json verde theme import https://verdeai.dev/themes/kanagawa.json ``` `validate` and `import --dry-run` do not change `verde.json`. `export` resolves Omarchy-derived colors into a portable package, so the result can be used on Linux, macOS, or Windows. Theme packages only apply allowlisted visual colors and optional UI/terminal font sizes; font-family and command settings are never imported. ## Offline state commands State commands read Verde's persisted SQLite state and do not require the app to be running. ```bash verde state path [--json] verde state workspaces [--json] verde state panes --project [--json] verde state threads --project [--json] verde state transcript --project --thread [--json] ``` - `path` prints the SDL pref path and `state.sqlite` location. - `workspaces` lists imported projects and the selected workspace. `projects` remains an alias for compatibility. - `panes` prints the saved workspace layout and terminal dock state for a project. - `threads` lists saved chat threads for a project. - `transcript` prints one saved chat transcript by thread index or provider thread id. ## Live discovery commands Live commands talk to the running desktop app over current-user local IPC: a Unix socket on Linux/macOS or a named pipe on Windows. Start the app first. ```bash verde live capabilities [--json] verde live status [--json] verde live projects [--json] verde live active [--json] verde live panes [--project ] [--json] verde live threads [--project ] [--json] verde live terminals [--project ] [--json] verde live surfaces [--json] verde live processes [--json] verde live inspect --pane [--project ] [--json] verde live inspect --focused [--json] verde live browser status [--json] verde live workspace select --project [--json] verde live workspace create --path /path/to/project [--json] verde live workspace rename --project --label "New name" [--json] verde live workspace close --project [--json] verde live workspace reopen [--project ] [--json] ``` - `capabilities` prints the live method list without requiring the app to be running. - `status` returns protocol version, app pid, selected project, focused pane, current pane graph, terminal/process summary, and browser runtime state. - `active` returns the current project and focused pane. - `surfaces` lists in-memory terminal surface status and attention metadata. - `workspace close` removes a workspace from the active sidebar without deleting its saved threads or layout. `archive` is an alias for `close`. - `workspace reopen` restores the specified closed workspace, or the most recently closed one when `--project` is omitted. ## Browser control ```bash verde live browser status [--json] verde live browser open --url https://example.com [--project ] [--json] verde live browser navigate --url https://example.com [--json] verde live browser close [--json] verde live browser toggle [--json] verde live browser back [--json] verde live browser forward [--json] verde live browser reload [--json] verde live browser focus [--json] verde live browser blur [--json] verde live browser select-all [--json] verde live browser copy [--json] verde live browser cut [--json] verde live browser paste-text --text "hello" [--json] verde live browser eval --script "document.title" [--json] verde live browser post-json --json-payload '{"type":"ping"}' [--json] verde live browser inspector-enable [--json] verde live browser inspector-disable [--json] verde live browser inspector-toggle [--json] verde live browser inspector-mode --mode point|draw-box|draw-freeform [--json] ``` The browser pane uses the host platform's native webview (WPE WebKit, WKWebView, or WebView2). `browser open` opens a URL in the workspace's browser pane, creating one if needed. `browser eval` runs JavaScript in the loaded page and returns the result as JSON. The inspector commands control [Design Mode](/docs/design-mode) for browser-to-agent visual feedback. `select-all` and `copy` operate on the focused page element or selection; `cut` and `paste-text` target the focused editable element. ## Chat control Chat commands resolve the target workspace pane to a chat thread and drive it through the same composer / send path as the UI. ```bash verde live chat status --pane [--json] verde live chat transcript --pane [--json] verde live chat draft set --pane --text "Reply with exactly: ok" [--json] verde live chat draft append --pane --text " and more" [--json] verde live chat send --pane [--prompt "fix the tests"] [--json] verde live chat followup --pane --prompt "now run the linter" [--json] verde live chat stop --pane [--json] verde live chat approve --pane --decision approve|deny [--call ] [--json] ``` - `status` returns the current draft, send state, and pending approval status. - `transcript` returns persisted messages for the pane's thread. - `draft set` replaces the current draft; `draft append` appends to it. - `send` sends `--prompt`, `--text`, or a trailing prompt argument. If no prompt is supplied, it sends the current draft. - `followup` queues or steers a prompt while a send is active. - `stop` aborts the current send for that chat thread. - `approve` resolves the current pending approval. `--decision` accepts `approve` or `deny`. ## Terminal and process control Terminal commands resolve the target workspace pane to its terminal dock and write through the same active PTY input path as the UI. ```bash verde live terminal write --pane --text $'cargo test\r' [--json] verde live terminal write --focused --text $'printf "ok\\n"\r' [--json] verde live terminal tail --pane [--lines ] [--json] verde live terminal screen --pane [--lines ] [--json] verde live process list [--project ] [--json] verde live process start --name [--project ] [--json] verde live process stop --name [--project ] [--json] verde live process restart --name [--project ] [--json] verde live process inspect --name [--project ] [--json] verde live process logs --name [--project ] [--json] verde live agent open --provider codex [--project ] [--json] verde live stack start [--project ] [--json] verde live stack stop [--project ] [--json] verde live stack restart [--project ] [--json] verde live stack status [--project ] [--json] ``` - `terminal write` sends text to the active terminal tab/pane. Include `\r` when you want to submit a shell command. - `terminal tail` returns recent terminal output; `screen` returns the current visible terminal screen. - `process start`, `stop`, and `restart` control entries loaded from `verde.yml`. - `agent open --provider codex` opens a first-class Codex TUI in the selected workspace without requiring a `verde.yml` entry. - `stack start`, `stop`, and `restart` apply the same action to every configured process and agent in the selected workspace. ## Pane management ```bash verde live pane split --pane --kind chat|terminal --axis horizontal|vertical [--json] verde live pane focus --pane [--json] verde live pane resize --first --second --axis horizontal|vertical --ratio <0..1> [--json] verde live pane move --pane --direction left|right|up|down [--json] verde live pane minimize --pane [--json] verde live pane maximize --pane [--json] verde live pane restore --pane [--json] verde live pane close --pane [--json] verde live palette list [--json] verde live palette run --command pane.split_terminal_down [--json] ``` ## Persistent terminal sessions The session daemon keeps terminal processes addressable independently of a particular visible pane. List and inspect sessions even when the desktop app is not running; persisted metadata remains available if the daemon is offline. ```bash verde session list [--json] verde session inspect --id [--json] verde session new [--workspace ] [--cwd ] [--name ] -- verde session attach --id verde session write --id --text $'cargo test\r' [--json] verde session tail --id [--lines ] [--json] verde session screen --id [--lines ] [--json] verde session kill --id [--json] verde session cleanup [--json] ``` `attach` is interactive. For automation, prefer `write`, `tail`, and `screen` with an explicit session id. ## MCP bridge `verde mcp` starts a JSONL stdio MCP server that exposes Verde's local live controls to compatible agents. It is primarily used by agent integrations; most users do not invoke it directly. The bridge handles MCP initialization, tool discovery, and tool calls, and requires the relevant live Verde target for operations that control the app. ## Provider integrations Provider hooks are optional add-ons that let agent CLIs drive Verde's sidebar status pips. They never overwrite provider config or change provider login/auth behavior. ```bash verde integrations list [--json] verde integrations doctor [--json] verde integrations install [--global] verde integrations remove [--global] verde integrations disable ``` - **Claude / Codex** hooks are project-local (`.claude/settings.local.json` / `.codex/hooks.json`); `--global` installs them in `~/.claude/settings.json` / `~/.codex/hooks.json` instead. - **Amp** uses a global lifecycle plugin at `~/.config/amp/plugins/verde-notify.ts` (install with `--global`). The plugin is a no-op outside Verde panes. - **OpenCode / Cursor** have no stable hook installer yet; `list` and `doctor` report them as unsupported. ## Remote workspaces (Herdr) Herdr opens or attaches Verde workspaces on a remote host over SSH and syncs pane state, with handoff to move a local workspace to a remote (and unlink to bring it back) and reusable connection profiles. `handoff` and `unlink` require the app to be running. ```bash verde herdr status [--json] verde herdr open --herdr-workspace --session [--profile |--remote ] [--remote-cwd ] [--local-dir ] [--json] verde herdr handoff [--workspace ] [--all] [--session ] [--profile |--remote ] [--remote-cwd ] [--dry-run] [--json] verde herdr unlink [--workspace ] [--all] [--json] verde herdr profiles list [--json] verde herdr profiles add --name --ssh-target [--session ] [--remote-cwd ] [--local-dir ] [--json] verde herdr profiles remove [--json] verde herdr profiles test [--json] ``` ## Terminal surface notifications Verde terminal children receive identity variables such as `VERDE=1`, `VERDE_SESSION_ID`, `VERDE_WORKSPACE_ID`, `VERDE_WORKSPACE_PATH`, `VERDE_DOCK_ID`, `VERDE_PANE_ID`, `VERDE_SOCKET`, `VERDE_LIVE_SOCKET`, `VERDE_SESSIONIZER_SOCKET`, and `VERDE_CLI`. Terminal tools can use those variables to update their pane surface: ```bash verde notify --title "Codex needs input" --body "Approve command?" --status waiting verde notify --status working --progress 0.4 --label "Running tests" verde notify --status done --title "Agent finished" verde notify --clear ``` `--status` accepts `idle`, `working`, `waiting`, `done`, or `error`. Combined with `--progress` (0..1), it drives the surface's progress bar. ## Selectors and exit codes - Use `--pane ` for deterministic automation. - Use `--focused` for interactive smoke tests. - Use `--project current` for the selected project, or pass a project index, id, or path. - Chat commands require a chat pane. Terminal commands require a terminal pane. | Exit | Meaning | | ---- | --------------------------------------------------------------------------------- | | `0` | CLI command parsed and, for live commands, received a live response. | | `1` | Command failure before a structured live response. | | `2` | Invalid CLI arguments. | | `3` | Live server is not running or not ready. | | `4` | Offline state target not found. | Live IPC request failures return JSON error codes such as `not_found`, `invalid_request`, `invalid_target`, `rejected`, `unsupported`, or `method_not_found`. Scripts must check the JSON envelope's `ok` field, not only the process exit code. ## Shell completion `verde completion` prints static completion scripts for bash, zsh, fish, and PowerShell. The generated completions cover command names, nested live-control commands, flags, and fixed flag values such as `--kind chat|terminal`, `--axis horizontal|vertical`, and `--decision approve|deny`. ```bash verde completion bash verde completion zsh verde completion fish verde completion powershell ``` Common install patterns: ```bash # bash verde completion bash > ~/.local/share/bash-completion/completions/verde # zsh mkdir -p ~/.zfunc verde completion zsh > ~/.zfunc/_verde # Ensure ~/.zfunc is in fpath before compinit, for example: # fpath=(~/.zfunc $fpath) # fish verde completion fish > ~/.config/fish/completions/verde.fish ``` The first completion slice is intentionally static so tab completion stays fast and never depends on the desktop app being open. Dynamic project, pane, process, and thread completions can be layered on top of this later. --- # Configuration & state Source: https://verdeai.dev/docs/config Edit: https://github.com/JonathanRiche/verde/blob/master/packages/website/src/content/docs/config.md ## 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](/docs/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](/docs/chat). ## 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 ` 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`](https://github.com/JonathanRiche/verde/blob/master/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](/docs/cli) 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`](https://github.com/JonathanRiche/verde/tree/master/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`](https://github.com/JonathanRiche/verde/blob/master/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`](https://github.com/JonathanRiche/verde/tree/master/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](https://github.com/JonathanRiche/verde/blob/master/LICENSE). --- # Troubleshooting Source: https://verdeai.dev/docs/troubleshooting Edit: https://github.com/JonathanRiche/verde/blob/master/packages/website/src/content/docs/troubleshooting.md ## Provider prompt sending fails If sending a prompt produces an error instead of streaming a reply, check in this order: 1. **Is the provider installed?** Run `which codex`, `which opencode`, `which agent`, etc., from the shell Verde was launched in. GUI launches on some platforms inherit a different `PATH` than a terminal — relaunch Verde from a terminal if you suspect this. ```bash which codex which opencode which agent ``` 2. **Is the provider authenticated?** Re-run the provider's login command and confirm credentials are still valid: ```bash codex login agent login ``` Claude Code is authenticated through its own SDK; Verde has no Verde-side login for it. Make sure the Claude Code binary and `node` are both reachable from the shell environment Verde was launched from. 3. **Is the project imported?** Verde runs the provider against the imported project directory. A provider CLI in a different working directory will not see the same files. 4. **Check the logs.** Provider helper stderr is written to the runtime log alongside Zig panics. On Linux: ```bash tail -f ~/.local/share/verde/Native/logs/verde.stderr.log ``` For provider-specific setup, see [Provider setup](/docs/providers). ## Provider readiness does not update After installing a provider CLI or completing its login flow, return to **Connect an AI provider** and choose **Check again**. If its state still says **CLI not found**, launch Verde from the same shell where the provider command works; desktop launchers can inherit a different `PATH`. If it says **Sign-in needed**, run the provider's login command outside Verde and retry. A timed-out or failed probe appears as **Could not verify** and should be checked against the runtime log. Amp never appears on this screen because it is a terminal-only provider. ## Linux browser runtime missing The embedded browser pane on Linux uses the system WPE WebKit runtime — there is no bundled Chromium. If the required libraries are missing, the installer warns and prints the install command for your distribution. The libraries Verde looks for are: - `libWPEWebKit-2.0.so` - `libWPEBackend-fdo-1.0.so` - `libjavascriptcoregtk-6.0.so` - `libEGL.so.1` - `libGLESv2.so.2` Install them by distribution: | Distro | Command | | ------------ | --------------------------------------------------------------------------------------------- | | Arch | `sudo pacman -S wpewebkit wpebackend-fdo` | | Debian 13+ | `sudo apt-get update && sudo apt-get install libwpewebkit-2.0-1 libwpebackend-fdo-1.0-1 libjavascriptcoregtk-6.0-1 libegl1 libgles2` | | Fedora | `sudo dnf install wpewebkit wpebackend-fdo` | | openSUSE | `sudo zypper install libWPEWebKit-2_0-1 libwpebackend-fdo-1_0-1 libjavascriptcoregtk-6_0-1 libEGL1 libGLESv2-2` | You can also let the installer install them by setting `VERDE_INSTALL_BROWSER_DEPS=1` before running it: ```bash curl -fsSL https://verdeai.dev/install.sh | VERDE_INSTALL_BROWSER_DEPS=1 sh ``` ## WebView2 on Windows Windows native-webview builds use Microsoft WebView2. Windows systems that do not include WebView2 need the Microsoft WebView2 Runtime installed separately, and packaged builds must ship or locate `WebView2Loader.dll` next to `verde.exe` or on the DLL search path. The Windows native-webview build also requires the Microsoft WebView2 SDK headers at compile time. ## Design Mode has no screenshot The element and region selector works with WPE WebKit on Linux, WKWebView on macOS, and WebView2 on Windows. Selection screenshots currently require the Linux WPE backend's frame-copy support. On macOS and Windows, Verde sends the instruction and DOM context without an image; this is expected. See [Design Mode](/docs/design-mode) for routing details. ## Update check or install fails Open **Settings → Updates** and choose **Check now** again. Update checks and installers need access to GitHub release metadata and assets. If the in-app flow still fails, run: ```bash verde update --json ``` The JSON error is suitable for scripts and issue reports. Standalone Linux/macOS installs need `curl`; Windows uses PowerShell. A `verde-bin` installation owned by pacman needs either `yay` or `paru`, and the in-app flow opens that helper in a terminal pane. You can always use the install command on the [homepage](/#install) to replace a standalone installation manually. ## Source-build errors Source builds require Zig `0.16.0` and SDL3 development files for your platform. The default browser backend uses the host platform webview instead of bundled Chromium. Linux builds also require WPE WebKit development packages. The supported invocation from the repo root is: ```bash mise run build ``` If you must call the build directly: ```bash zig build --release=safe -Dbrowser-backend=native_webview ``` Common pitfalls: - **Bare `zig build` does not compile.** It defaults to Debug + the WPE `verde-browser-linux` helper, which trips a vendored `packages/ghostty/.../osc.zig` comptime `@sizeOf` assertion and a `crt1.o` linker error. Always pass `--release=safe -Dbrowser-backend=native_webview`, or use `mise run build`. - **Running `zig build` from `packages/desktop`.** That installs to `packages/desktop/zig-out`, not the top-level `zig-out/bin/verde` the app launches from. Always build from the repo root. - **CEF fallback.** CEF is still available as an explicit fallback if you need the legacy Chromium backend: ```bash mise run build-cef # or zig build --release=safe -Dbrowser-backend=cef -Dcef-sdk-path=/path/to/cef ``` For release-style local installs, use the packaged install scripts: ```bash bash ./scripts/release/install-linux-local.sh ./scripts/release/install-macos-local.sh ``` ## Reading the runtime logs Verde writes runtime logs under SDL's platform pref path. 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. If the app crashes, the `last-crash.log` is the single best place to start. Discover the exact pref path on your machine: ```bash verde state path --json ``` ## Inspecting the live app While the app is running, you can inspect a lot without touching the UI: ```bash verde live status --json | jq '.result.browser' verde live panes --project current --json verde live processes --json verde live inspect --focused --json ``` Exit code `3` means the live server is not running or not ready — start the app first. See [CLI reference](/docs/cli) for the full command surface and exit codes. ## Getting help - [GitHub issues](https://github.com/JonathanRiche/verde/issues) for bugs and feature requests. - [CLI reference](/docs/cli) and [Configuration & state](/docs/config) for the full programmatic surface. - [Provider setup](/docs/providers) for provider-specific setup and authentication.