Configuration

lazyshell config init writes a fully commented config file at the right place, and lazyshell config show prints the configuration actually in effect — after every layer has had its say — together with the sources it came from. That second command is the answer to "why is my setting not taking".

lazyshell config edit opens that file in your editor — $VISUAL, else $EDITOR, else the first of nano, vim, vi that is installed — creating it from the commented template first if it does not exist yet. When the editor exits, the saved file is re-read and anything wrong with it (an unknown key, an out-of-range value, an unparseable keybinding) is reported straight away rather than at the next start.

Where the file lives

lazyshell reads its YAML config file from the first match:

1. $LAZYSHELL_CONFIG, if set
2. $XDG_CONFIG_HOME/lazyshell/config.yml
3. ~/.config/lazyshell/config.yml

A missing file is not an error — lazyshell just runs with its built-in defaults. A partial file only needs to mention the fields it wants to override; everything else keeps its default.

Precedence

built-in defaults  <  ~/.config/lazyshell/config.yml  <  project lazyshell.yml
                   <  environment variables  <  command-line flags

Option reference

Key specs

Key specs use gocui.Parse syntax: a bare character (n), or Ctrl+N, Alt+Space, Tab, Esc.

The remappable action ids are:

new_session, new_named_session, new_session_in_dir, kill_session, delete_session, rename_session, duplicate_session, restart_session, zoom, next_tab, prev_tab, filter_sessions, export_session, toggle_broadcast, jump_next_blocked, jump_prev_prompt, jump_next_prompt, copy_last_output, arm_watch, set_group, filter_group, broadcast_group, kill_group, restart_group, toggle_debug, select_next, select_prev, cycle_focus, help, quit.

An id outside that list is reported rather than ignored.

Colours

Colours accept any of:

• an ANSI terminal colour name — black, red, green, yellow, blue, magenta, cyan, white, and each one prefixed with bright (brightblue, …). These follow your terminal's own palette;
• a W3C/CSS colour name (navy, teal, chartreuse, …) or #rrggbb, for a specific colour rather than a palette slot;
• default, for the terminal's own default colour.

Full example

This is what lazyshell config init writes — every option at its default value, so you can delete whatever you do not change.

# ~/.config/lazyshell/config.yml

language: fr
shell: ""
term: xterm-256color
scrollback_size: 10000

sessions_panel_width: 40
sessions_panel_height: 10
agents_panel_height: 6
portrait_max_width: 84
portrait_min_height: 45

refresh_interval_ms: 30
kill_timeout_ms: 2000

prefix_key: Ctrl+O

keybindings:
  new_session: "n"
  new_named_session: "N"
  new_session_in_dir: "M"
  kill_session: "x"
  delete_session: "D"
  rename_session: "r"
  duplicate_session: "c"
  restart_session: "R"
  zoom: "z"
  next_tab: "]"
  prev_tab: "["
  filter_sessions: "/"
  export_session: "w"
  toggle_broadcast: "b"
  jump_next_blocked: "B"
  jump_prev_prompt: "{"
  jump_next_prompt: "}"
  copy_last_output: "Y"
  arm_watch: "v"
  set_group: "g"
  filter_group: "G"
  broadcast_group: "A"
  kill_group: "X"
  restart_group: "W"
  toggle_debug: F12
  select_next: "j"
  select_prev: "k"
  cycle_focus: Tab
  help: "?"
  quit: "q"

markers:
  bell: "!"
  alt_screen: "#"
  activity: "●"
  broadcast: "+"
  agent_idle: "●"
  agent_working: "●"
  agent_blocked: "●"
  agent_done: "●"
  agent_idle_color: "green"
  agent_working_color: "yellow"
  agent_blocked_color: "red"
  agent_done_color: "blue"
  command_failed: "✗"
  restart: "↻"

scroll:
  page_lines: 0
  half_page_divisor: 2

theme:
  active_border_color: green
  inactive_border_color: default
  selected_bg_color: blue
  locked_border_color: red
  tab_active_color: green

clipboard:
  fallback_command: ""

notify:
  fallback_command: ""

window_title:
  enabled: true

mouse:
  enabled: true
  wheel_lines: 3
  forward_to_app: true

perf:
  refresh_interval_ms: 5000

env_tab:
  mask_secrets: true

control:
  enabled: false

agent_stats_command: ""

restore_layout: ask