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]