docs/reference

Configuration

The complete configuration, generated from code.

The default file is ~/.config/vibeke/config.toml. Set VIBEKE_CONFIG to use another file.

Vibeke reloads the file after a change. If parsing fails, it keeps the previous configuration. Unknown keys produce warnings.

vibeke --default-config prints the template below. Each setting shows its default value. Settings marked for new panes do not change existing panes.

## Vibeke configuration — ~/.config/vibeke/config.toml (override with VIBEKE_CONFIG).
## Each setting shows its default. Remove the comment marker to change it.
## Unknown keys produce warnings. If parsing fails, Vibeke keeps the previous configuration.
## Sizes: "200MiB", "8G". Durations: "30m", "14d". Port ranges: "20000-29999".

## Show the setup guide on the next start.
## onboarding = false

## [config]
## Reload automatically when this file changes.
## watch = true

## [theme]
## Built-ins: catppuccin, catppuccin-latte, terminal, tokyo-night, dracula, nord, gruvbox,
## one-dark, solarized, kanagawa, rose-pine, vesper, plus any themes/*.toml.
## mode        = "auto"                  # auto (follow the host terminal's light/dark) | light | dark
## name        = "catppuccin"
## auto_switch = true
## dark_name   = "catppuccin"
## light_name  = "catppuccin-latte"
## Token overrides: panel_bg, fg, muted, accent, red, yellow, green, blue, border, selection…
## [theme.custom]
## accent = "#f5c2e7"
## Default pane palette overrides: ansi0..ansi15, fg, bg, cursor.
## [theme.pane]
## bg = "reset"

## [terminal]
## default_shell        = ""             # "" -> $SHELL -> /bin/sh
## shell_mode           = "auto"         # auto | login | non_login
## new_cwd              = "follow"       # follow | home | current | <path>
## term                 = "xterm-256color"
## scrollback_lines     = 10000
## archive_scrollback   = true
## archive_styles       = false
## archive_max_per_pane = "200MiB"
## archive_days         = 30
## grapheme_width       = "auto"         # auto | unicode | legacy
## allow_passthrough    = false
## Override incorrect host reports. Example: host_overrides = { kitty_graphics = false }
## host_overrides = {}
## Additional environment variables for each pane.
## [terminal.env]
## EDITOR = "nvim"

## [clipboard]
## osc52_write       = "allow"           # allow | deny
## osc52_read        = "deny"            # deny | ask | allow
## copy_on_select    = true              # a mouse selection is copied on release (false: stays in copy mode for y)
## primary_selection = false
## mouse_select_in_apps = "modifier"     # modifier (shift/alt+drag selects over mouse-reporting apps) | always (every drag selects. Apps receive clicks and wheel events)
## remote_write      = "allow"           # allow | ask_once | deny
## remote_write_max_bytes    = "1MiB"      # larger OSC 52 writes are dropped
## remote_write_min_interval = "5s"        # per-pane gap between clipboard prompts

## [paste]
## translate       = "paths_only"        # paths_only | embedded (upload automatically) | ask (confirm first) | off
## max_auto_bytes  = "50MiB"
## inbox_retention = "2w"

## [keys]
## prefix             = "ctrl+b"
## prefix_timeout_ms  = 1500
## resize_repeat_ms   = 500              # repeat direct resize keys without another prefix; 0 disables
## prefix_passthrough = true
## prefix_menu        = true             # after the prefix, show every prefix key in groups (prefix+? shows it at once)
## prefix_menu_ms     = 400              # wait this long for a second key first; 0 shows the menu immediately
## altgr_mode         = "auto"           # auto | text | chord
## shift_enter_legacy = "lf"             # lf | cr: shift+enter for apps without kitty keys (lf = newline in agent TUIs)
## Action bindings. "prefix+x" needs the prefix. A chord without it is a direct binding.
## "" unbinds. Ranges: "prefix+1..9".
## help                     = "prefix+?"
## settings                 = "prefix+s"
## detach                   = "prefix+q"
## reload_config            = "prefix+shift+r"
## open_notification_target = "prefix+o"
## cancel_transfer          = "prefix+shift+c"
## review_clipboard         = "prefix+y"
## workspace_picker         = "prefix+w"
## goto                     = "prefix+g"
## new_workspace            = "prefix+shift+n"
## new_worktree             = "prefix+shift+g"
## open_worktree            = ""
## remove_worktree          = ""
## rename_workspace         = "prefix+shift+w"
## close_workspace          = "prefix+shift+d"
## previous_workspace       = ""
## next_workspace           = ""
## previous_agent           = ""
## next_agent               = ""
## focus_agent              = ""
## switch_workspace         = ""
## new_tab                  = "prefix+c"
## rename_tab               = "prefix+shift+t"
## previous_tab             = "prefix+p"
## next_tab                 = "prefix+n"
## switch_tab               = "prefix+1..9"
## close_tab                = "prefix+shift+x"
## rename_pane              = "prefix+shift+p"
## remote_image_paste       = "ctrl+v"
## split_vertical           = "prefix+v"
## split_horizontal         = "prefix+minus"
## close_pane               = "prefix+x"
## zoom                     = "prefix+z"
## resize_mode              = "prefix+r"
## break_pane               = "prefix+!"
## move_pane                = "prefix+m"
## toggle_split             = "prefix+alt+t"
## swap_pane_previous       = "prefix+{"
## swap_pane_next           = "prefix+}"
## cycle_layout             = "prefix+space"
## resize_pane_left         = "prefix+ctrl+left"
## resize_pane_right        = "prefix+ctrl+right"
## resize_pane_up           = "prefix+ctrl+up"
## resize_pane_down         = "prefix+ctrl+down"

## toggle_sidebar           = "prefix+b"
## focus_pane_left          = "prefix+h"
## focus_pane_down          = "prefix+j"
## focus_pane_up            = "prefix+k"
## focus_pane_right         = "prefix+l"
## cycle_pane_next          = "prefix+tab"
## cycle_pane_previous      = "prefix+shift+tab"
## last_pane                = ""
## edit_scrollback          = "prefix+e"
## enter_copy_mode          = "prefix+["
## paste_buffer             = "prefix+]"
## command_palette          = "prefix+:"
## search_scrollback        = "prefix+/"
## next_attention           = "prefix+a"
## next_attention_focus     = "prefix+shift+a"
## inbox                    = "prefix+i"
## mark_unread              = "prefix+u"
## pin_pane                 = "prefix+alt+p"
## float_new                = "prefix+f"
## toggle_floats            = "prefix+shift+f"
## sync_input               = "prefix+shift+s"
## new_task                 = "prefix+shift+k"
## preview_list             = "prefix+shift+o" # previews on every machine: pane, window, proxy, mirror
## last_workspace           = "prefix+shift+l" # toggle to the previously focused workspace
## url_hints                = "prefix+shift+u" # label URLs/IDs in the focused pane: open or copy
## sync_input_pane          = "prefix+alt+s"   # add/remove the focused pane from the tab's sync set
## fleet                    = "prefix+shift+m" # fleet grid: every agent on every machine
## batch_approvals          = ""               # batch view of equivalent approvals (also `A` on a card)
## collisions               = ""               # agents editing the same files in a shared checkout: pause, tell, fresh task, ignore
## setup                    = ""               # onboarding: terminal check, integrations, notifications, theme
## trust_repo               = ""               # review and trust this repo's .vibeke/ (repo-local config)
## agent_list               = "prefix+alt+a"   # every agent on every machine, by attention; enter jumps
## mention_picker           = "prefix+@"       # name panes and insert @name into the focused pane
## elevation_requests       = "prefix+shift+e" # review a pane's `vibeke auth elevate` request (y/n)
## tab_renumber             = ""               # renumber this workspace's tabs 1..n in order
## task_recreate            = ""               # recreate the checkout of a task marked missing
## task_forget              = ""               # forget a task marked missing (nothing is deleted)
## connections              = "prefix+alt+d"   # Connections: devices, people, hosts, handoffs (opens the last tab used)
## handoffs                 = "prefix+shift+h" # Connections → Handoffs: incoming handoffs and the ones being sent
## handoff_send             = "prefix+alt+h"   # hand off the focused pane to another host
## hosts                    = ""               # Connections → Hosts: peers, invitations, paste an invitation
## share_pane               = "prefix+alt+v"   # share the focused pane or its workspace with someone (view or approve)
## cloud_send               = ""               # send the focused pane's agent to a cloud sandbox
## cloud_bring_back         = ""               # bring the focused cloud pane back to this host or a paired host
## sandboxes                = ""               # cloud sandboxes: sign-in, state, suspend, bring back, destroy, clean up
## open_images              = "prefix+alt+i"   # view new images: the gallery of images agents and you attached

## [keys.copy_mode]
## mode = "vi"                           # vi | emacs
## editor_include_ansi = false           # edit_scrollback's editor file keeps colours (in-memory rows)
## per-key overrides (key = "action", "" unbinds), e.g. y = "copy", "ctrl+e" = "edit_scrollback".
## Actions: exit cancel left right up down half_page_up half_page_down page_up page_down
## line_start line_end top bottom view_top view_middle view_bottom word_next word_prev word_end
## select_char select_line select_block search_forward search_backward search_next search_prev
## copy edit_scrollback prompt_prev prompt_next select_output

## Mode-local keymaps: [keys.navigate], [keys.resize], [keys.card].

## Custom commands (type = shell | pane | popup | float. Other fields: cwd, env, title, when):
## [[keys.command]]
## key     = "prefix+alt+g"
## type    = "popup"
## command = "lazygit"
## width   = "80%"
## height  = "80%"

## [ui]
## interaction_overlay           = "unfocused"   # off | unfocused | always
## max_fps                       = 120
## background_animation_fps      = 4
## animate                       = true
## focus_follows_mouse           = false
## focus_follows_mouse_delay_ms  = 120
## confirm_close                 = "running"     # running | always | never
## marked_unread_clears_on_focus = false
## title_sync                    = true          # set the outer terminal title (OSC 2)
## title_format                  = "{workspace} · {pane}"   # also {tab}, {machine}, {session}

## [ui.sidebar]
## attention_section = true
## position          = "left"            # left | right
## width             = 28
## min_width         = 18
## max_width         = 48
## auto_width        = true
## collapsed         = false
## show_shell_panes  = false
## nest_tasks        = true
## preview_thumbnails = false             # tiny latest-screenshot thumbnail per preview row (kitty graphics or iTerm2)
## show_state_source = "inferred-only"   # inferred-only | always | never

## [ui.sidebar.isolation_glyphs]
## host      = ""
## sandbox   = "sb"
## container = "ct"
## vm        = "vm"

## [ui.images]
## sidebar = true      # show the Images section in the sidebar
## recent  = 5         # images listed there (1-20)
## popup   = true      # show a card when an agent attaches an image to the focused pane

## Token rules: match by harness, state or regex, then rename, recolor, or hide.
## [[ui.sidebar.token]]
## match = { harness = "codex" }
## label = "cx"

## [ui.tabs]
## position     = "top"                  # top | bottom | hidden
## show_numbers = true

## [ui.status_bar]
## enabled  = false
## position = "bottom"                   # top | bottom
## left     = ["machine", "task", "branch"]
## center   = ["attention"]
## right    = ["agents_summary", "clock"]

## [ui.sync_input]
## include_agents = false

## [ui.interactions]
## batch           = true
## deadline_window = "60s"               # "deadline approaching" in the inbox when this little time is left

## [ui.inbox]
## also_working = true                   # footer listing busy agents without an open question

## [ui.fleet]
## tile_view = "terminal"                # terminal | timeline

## [notifications]
## channel               = "native"      # native | osc | both | none
## sound                 = "default"     # default | none | <path>
## suppress_when_focused = true
## coalesce_ms           = 3000
## quiet_hours           = ""            # "22:00-07:00"
## channels              = []            # toast | native | osc | sound | bell. [] uses `channel`

## [notifications.on]
## needs_approval      = true
## needs_answer        = true
## done                = true
## error               = true
## bell                = false
## osc                 = true
## remote_disconnected = true
## deadline            = true            # an inbox item's native deadline is approaching
## review              = true            # a tracked task is ready for review, or its check failed

## [agents]
## auto_detect       = true
## shims             = true
## resume_on_restart = "ask"             # ask | always | never
## name_from_task    = true

## [agents.approvals.claude]
## persist_always      = false           # "allow always" edits Claude's settings (off: session-scoped rule)
## persist_destination = "localSettings" # localSettings | projectSettings | userSettings

## [agents.harness.claude]
## enabled     = true
## integration = "hooks"                 # hooks | stream-json | screen
## extra_args  = []

## [agents.harness.pi]
## integration = "extension"             # extension | rpc | screen

## [agents.harness.codex]
## shim            = true
## headless_shared = false
## Added after `codex` when Vibeke isolates a headless app-server run: Codex's own
## sandbox cannot nest inside Vibeke's (the PTY path passes `--sandbox danger-full-access`).
## isolated_args   = ["-c", 'sandbox_mode="danger-full-access"']

## Policy rules (the first matching rule applies. See the policy documentation):
## [[policy.rule]]
## match  = { tool = "Bash", command_regex = '^(pnpm|npm) (test|run lint)( |$)' }
## effect = "allow"

## [tasks]
## root                = "~/.vibeke/worktrees"   # or "sibling" -> ../<repo>-<slug>
## vcs                 = "auto"                  # auto | git
## checkout            = "auto"                  # auto | worktree | clone | none
## branch_template     = "{user}/{slug}"
## fetch_before_create = true
## default_agent       = "claude"
## port_pool           = "20000-29999"
## port_block          = 10
## setup_script        = ".vibeke/setup.sh"
## copy_files          = [".env", ".env.local"]

## [tasks.cleanup]
## on_finish     = "keep"                # keep | archive | remove
## stale_after   = "2w"
## auto_gc       = false
## protect_dirty = true

## [tasks.best_of_n]
## suffix = ""

## Per-repo overrides of the repo's .vibeke/task.toml, keyed by origin URL or repo path.
## The same tables as task.toml; commands set here run without the repo-trust prompt.
## [tasks.repos."github.com/acme/app"]
## files = { clone = ["node_modules"] }
## deps  = { strategy = "auto" }
## setup = { run = ["pnpm db:migrate"], timeout = "10m" }
## env   = { DATABASE_URL = "postgres://localhost:5432/app_{slug_underscored}" }

## [remote]
## input_when_offline = "drop"           # drop | ask
## predictive_echo    = "auto"           # auto | always | never

## Saved machines:
## [[remote.machine]]
## label        = "devbox"
## address      = "me@devbox.tailnet"
## transport    = "ssh"
## keybindings  = "local"              # local | server
## auto_connect = true
## auto_upgrade = false
## bootstrap    = "push"               # push | remote-download

## [pane]
## size_policy = "latest"                # latest | smallest | pinned

## [render]
## max_unacked = 2

## [graphics]                            # images programs place in panes (kitty graphics), new panes
## max_image_bytes    = "32MiB"          # bigger images are refused
## max_total_per_pane = "256MiB"         # per pane screen; the oldest images are evicted

## [compat]
## herdr_env    = true
## herdr_socket = false
## herdr_socket_path = ""                # "" = $RUNTIME/herdr-compat/herdr.sock; e.g. "~/.config/herdr/herdr.sock" once Herdr is gone (a live socket is never replaced)

## [compat.herdr]                        # Herdr-compatible socket (M5, partial): $RUNTIME/herdr-compat/herdr.sock
## enabled = false
## allow_server_stop = false             # serve `server.stop` / `herdr server stop` (never from a plugin or pane)

## Event log retention (02 §2.3). Read by the running server; changes apply at the next hourly
## sweep (or `vibeke api call storage.prune`). Durations are `7d`/`36h` or a bare number of days.
## [events]
## sync_retention    = "7d"          # catch-up/live-UI events (the `sync` tier)
## history_retention = "90d"         # interactions, policy, task status, agent history (`history`)
## blob_retention    = "30d"         # unreferenced uploads and tool-output payloads in the blob store
## max_rows          = 2000000       # hard cap on event rows; oldest `sync` rows go first; 0 = no cap

## Review evidence (15 §6.3, §6.4). Read by the running server.
## [review.pr]                       # `vibeke api call task.pr.observe`: an explicit lookup through your `gh` login
## provider     = "gh"               # gh | off
## max_age_secs = 900                # an observation older than this is unknown (0 = never stale)
## [review.interval]                 # binds an observed agent command to the subject only when it provably ran on a stable checkout
## enabled       = true
## watcher       = "os"              # os | none (none binds nothing)
## settle_ms     = 400               # late file events still count this long after a command ends
## arm_delay_ms  = 500               # a freshly started watcher counts as armed after this delay
## harnesses     = ["claude"]        # only harnesses whose pre-tool hook runs before the tool

## Shared-checkout collision tracker (05 §10). Advisory: it warns, and never blocks, reverts or
## reassigns changes. Read by the running server. A watcher and a status poll run only for a
## checkout that two or more live runs share (or that holds a claim).
## [collision]
## enabled        = true
## window         = "30m"            # rolling window per checkout in which touches count
## read_window    = "10m"            # a read makes another run's later edit of that file `medium`
## fs_attribution = "auto"           # auto | off | aggressive (+ open-file sampling on Linux, best effort)
## enforce_claims = false            # cooperating adapters (Claude) deny *reported* edit tools inside a foreign claim
## dir_depth      = 2                # same directory/module = the first N directory components (0 = rule off)
## poll_interval  = "5s"             # `git status --porcelain` while an agent in the checkout is working
## settle         = "150ms"          # wait before attributing a file-system event (the adapter's report lands first)
## watcher        = "os"             # os | none
## notify         = true             # a notification for high and medium (once per path set per window)
## ignore         = []               # extra repo-relative globs never tracked (.git and node_modules always are)
## max_touches    = 5000             # touches remembered per checkout

## [update]
## channel        = "stable"             # stable | preview
## version_check  = true
## manifest_check = true

## [sharing]
## github = []   # GitHub logins for share, review and continue links on this machine; empty: your account's sharing list

## Named layouts for `vibeke layout apply <name>` / `workspace create --layout <name>` (07 §2.14):
## [layouts.dev]
## cwd = "~/code/app"
## [[layouts.dev.tab]]
## title = "edit"
## pane = { split = "right", children = [{ run = "nvim ." }, { run = "npm run dev" }] }

## Secrets and privacy (09 §9.1-9.2; read by the server, shown here with their defaults):
## [security]
## encrypt_state           = false     # seal scrollback segments and session blobs with a key kept in the OS keychain
## keychain                = "os"      # "os" (macOS Keychain or Secret Service via secret-tool) | "file:<path>" (0600 file; tests, headless hosts)
## redact_scrollback_index = true      # the search index and search.query results hold redacted text; segments stay as shown
## [security.redact]
## patterns = []                       # extra regular expressions redacted in logs, events, bundles, index and assistant payloads
## AI assistance (spec 14). Off by default: nothing is sent anywhere until you enable it, choose a
## connection and a profile, and grant consent per workspace (`vibeke assist consent`). User config
## only: a repository's own config cannot redirect assistant traffic. Requests run on the machine
## where the server runs, which also owns the credentials; `localhost` endpoints mean that machine.
## [assistant]
## enabled                     = false
## default_profile             = "interactive"
## max_concurrent_requests     = 2           # a change applies immediately
## max_queued_requests         = 16
## daily_request_limit         = 100         # provider attempts per UTC day on this machine
## daily_token_limit           = 200000
## daily_cost_limit_usd        = 1.0         # optional; needs known pricing for the model
## requests_per_minute         = 6
## request_timeout_seconds     = 60
## result_retention_hours      = 24
## preview_ttl_seconds         = 600
## auto_send                   = []          # operations that skip the preview; the workspace consent must list them too
## result_cache                = false       # reuse a stored result for identical context under the same grants
## keychain_backend            = ""          # deprecated override of [security] keychain for assistant credentials: "" (inherit) | off | os | "file:<path>" | fake (tests)
## remote_sources              = false       # accept source data a client collected from other machines
## remote_stale_seconds        = 300
## background_enabled          = false       # opt-in: background features (each also needs its own switch below)
## background_summaries        = false
## stall_notices               = false
## background_interval_seconds = 300
## stall_repeat_threshold      = 3
#
## [assistant.connections.primary]
## adapter    = "anthropic"                  # anthropic | openai_compatible | ollama | gemini
## # endpoint defaults to the adapter's standard endpoint. OpenRouter: adapter = "openai_compatible",
## # endpoint = "https://openrouter.ai/api". Plain http:// is allowed for loopback endpoints only.
## credential = { env = "VIBEKE_ASSISTANT_API_KEY" }   # or { file = "~/.config/vibeke/assistant.key" } (mode 0600) or { keychain = "vibeke/assistant/primary" }
#
## [assistant.profiles.interactive]
## connection        = "primary"
## model             = "<selected-model-id>"  # a placeholder, not a recommendation: `vibeke assist models --connection primary`
## max_input_tokens  = 12000
## max_input_bytes   = 65536
## max_output_tokens = 1024
## # capabilities = { streaming = "supported", json_schema = "supported" }   # declare what the model supports; unknown otherwise
## # Optional `background` and `review` profiles serve those features. Without one the default profile
## # is used only if it meets the feature's requirements.

## Sections owned by other components and documented with them:
## [isolation], [preview], [security], [plugins]