Config

Cogno reads a plain text config file. Every line is a key = value pair. Dot notation groups related settings. Arrays use bracket syntax.

font.size = 16
color.background = 1a1a2e
shell.default = zsh
keybind = Command+T=new_tab

Only the values you want to override need to appear in your file. Cogno merges your overrides with the built-in defaults, so an empty file is perfectly valid.

Config file location

Build	Path
Release	`~/.cogno/cogno.config`
Development	`~/.cogno-dev/cogno.config`

General

Setting	Type	Default	Description
`enable_watch_config`	boolean	`true`	Reload the config file automatically when it changes on disk

Font

Setting	Type	Default	Description
`font.family`	string	`monospace`	Terminal font family name
`font.size`	int (≥ 1)	`14`	Terminal font size in pixels
`font.weight`	string or number	`normal`	Normal-weight font variant. Accepts `normal`, `bold`, `100`–`900`, or a numeric weight
`font.weight_bold`	string or number	`bold`	Bold-weight font variant
`font.enable_ligatures`	boolean	`false`	Enable font ligatures
`font.custom_glyphs`	boolean	`true`	Render Nerd Font / custom glyphs
`font.draw_bold_text_in_bright_colors`	boolean	`false`	Render bold text using the bright color palette
`font.rescale_overlapping_glyphs`	boolean	`false`	Shrink glyphs that would overflow their cell
`font.app.family`	string	`sans-serif`	Font family for the application UI (tabs, menus)
`font.app.size`	int (≥ 1)	`14`	Font size for the application UI

font.family = "JetBrains Mono"
font.size = 15
font.enable_ligatures = true
font.custom_glyphs = true

Colors

All color values are hex strings without a leading #. 6-digit hex sets an opaque color; 8-digit hex adds an alpha channel in the last two digits (ff = fully opaque, 00 = fully transparent).

Setting	Default	Description
`color.foreground`	`ffffff`	Default text color
`color.background`	`0e1925`	Terminal background color
`color.highlight`	`34bbfe`	Accent / highlight color
`color.black`	`32465c`	ANSI black
`color.red`	`fd1155`	ANSI red
`color.green`	`11d894`	ANSI green
`color.yellow`	`fede55`	ANSI yellow
`color.blue`	`34bbfe`	ANSI blue
`color.magenta`	`e465d9`	ANSI magenta
`color.cyan`	`32d8c1`	ANSI cyan
`color.white`	`eeeeee`	ANSI white
`color.bright_black`	`32465c`	Bright ANSI black
`color.bright_red`	`fd1155`	Bright ANSI red
`color.bright_green`	`11d894`	Bright ANSI green
`color.bright_yellow`	`fede55`	Bright ANSI yellow
`color.bright_blue`	`34bbfe`	Bright ANSI blue
`color.bright_magenta`	`e465d9`	Bright ANSI magenta
`color.bright_cyan`	`32d8c1`	Bright ANSI cyan
`color.bright_white`	`eeeeee`	Bright ANSI white

color.background = 1e1e2e
color.foreground = cdd6f4
color.blue = 89b4fa
color.green = a6e3a1

Cursor

Setting	Type	Default	Description
`cursor.style`	`"bar"` `"underline"` `"block"`	`bar`	Cursor shape when the terminal is focused
`cursor.inactive_style`	`"outline"` `"block"` `"bar"` `"underline"` `"none"`	—	Cursor shape when the terminal is not focused
`cursor.width`	int (0–10)	`4`	Cursor width in pixels (applies to `bar` and `underline` styles)
`cursor.blink`	boolean	`true`	Enable cursor blinking
`cursor.color`	hex	`34bbfecc`	Cursor fill color
`cursor.accent_color`	hex	`34bbfe66`	Secondary cursor color used during selection
`cursor.alt_click_moves_cursor`	boolean	`true`	Move the cursor to the click position when Alt-clicking

Padding

Values are in em units (floating point).

Setting	Type	Default	Description
`padding.left`	number (≥ 0)	`0.5`	Left padding
`padding.right`	number (≥ 0)	`0.5`	Right padding
`padding.top`	number (≥ 0)	`0`	Top padding
`padding.bottom`	number (≥ 0)	`0.5`	Bottom padding
`padding.remove_on_full_screen_app`	boolean	`false`	Remove padding when a full-screen application (e.g. vim) is detected

Background image

Setting	Type	Default	Description
`background_image.path`	string	`""`	Absolute path to an image file. Leave empty to disable
`background_image.opacity`	int (0–100)	`80`	Image opacity (0 = transparent, 100 = opaque)
`background_image.blur`	int (0–10)	`0`	Blur radius applied to the image

background_image.path = /Users/me/wallpaper.png
background_image.opacity = 40
background_image.blur = 3

Setting	Type	Default	Description
`menu.opacity`	int (0–100)	`80`	Opacity of pop-up menus

Scrollbar

Setting	Type	Default	Description
`scrollbar.width`	int (≥ 0)	`6`	Scrollbar width in pixels. `0` hides the scrollbar
`scrollbar.sensitivity`	int (≥ 0)	`1`	Scroll speed multiplier
`scrollbar.scroll_on_user_input`	boolean	`true`	Jump to the bottom when keyboard input is detected while scrolled up
`scrollbar.smooth_scroll_duration`	int (≥ 0)	`0`	Smooth scroll animation duration in milliseconds. `0` disables smooth scrolling
`scrollbar.fast_scroll_sensitivity`	int (≥ 0)	`2`	Scroll speed multiplier when Alt/Option is held
`scrollbar.scrollback_lines`	int (≥ 100)	`100000`	Number of lines kept in the scrollback buffer
`scrollbar.overview_ruler_border_color`	hex	`0e192500`	Color of the overview ruler border (fully transparent by default)
`scrollbar.slider_color`	hex	`32465c66`	Scrollbar slider color
`scrollbar.slider_hover_color`	hex	`32465c`	Scrollbar slider color on hover
`scrollbar.slider_active_color`	hex	`32465c`	Scrollbar slider color while dragging

Selection

Setting	Type	Default	Description
`selection.clear_on_copy`	boolean	`false`	Deselect text after copying
`selection.background_color`	hex	`34bbfecc`	Selection highlight color when terminal is focused
`selection.inactive_background_color`	hex	`34bbfe66`	Selection highlight color when terminal is not focused
`selection.right_click_selects_word`	boolean	`false`	Right-click selects the word under the cursor

Clipboard

Setting	Type	Default	Description
`clipboard.read`	`"allow"` `"deny"`	`allow`	Whether applications can read from the clipboard via OSC 52
`clipboard.write`	`"allow"` `"deny"`	`allow`	Whether applications can write to the clipboard via OSC 52
`clipboard.trim_trailing_spaces`	boolean	`true`	Remove trailing whitespace when copying text
`clipboard.image_paste_ttl_seconds`	int (> 0)	`60`	How long a pasted image URL remains valid

Shell

Cogno supports multiple named shell profiles. Set shell.default to the name of the profile to open when no profile is specified. At most 9 profiles may be defined.

Setting	Type	Default	Description
`shell.default`	string	—	Name of the default shell profile (required)
`shell.order`	array of strings	—	Order in which profiles appear in the UI

Each profile lives under shell.profiles.<name>:

Setting	Type	Default	Description
`shell_type`	`"Bash"` `"ZSH"` `"PowerShell"`	—	Shell type (required)
`path`	string	—	Path to the shell executable. Uses the system default when omitted
`args`	array of strings	—	Extra arguments passed to the shell on launch
`env`	key-value map	—	Environment variables added to the shell’s environment
`working_dir`	string	—	Starting directory. Uses `$HOME` when omitted
`inject_cogno_cli`	boolean	`true`	Make the `cogno` CLI available inside this shell
`enable_shell_integration`	boolean	`true`	Enable shell integration (prompt hooks, command tracking)
`load_user_rc`	boolean	`true`	Source the user’s shell config (`.bashrc`, `.zshrc`, etc.)
`use_conpty`	boolean	—	Use ConPTY on Windows. Has no effect on other platforms

shell.default = zsh
shell.order = [zsh, bash]

shell.profiles.zsh.shell_type = ZSH
shell.profiles.zsh.inject_cogno_cli = true
shell.profiles.zsh.enable_shell_integration = true

shell.profiles.bash.shell_type = Bash
shell.profiles.bash.path = /usr/local/bin/bash
shell.profiles.bash.working_dir = /Users/me/projects

Prompt

Cogno can render a custom prompt built from named segments. Each segment is a colored block that shows a dynamic value (field) or static text. Segments are assembled into profiles that control display order.

Profile settings

Setting	Type	Description
`prompt.active`	string	Name of the active prompt profile
`prompt.profile.<name>.order`	array of strings	Segment names to display, in order
`prompt.profile.<name>.default_separator`	string	Default separator inserted between segments

Segment settings

Every segment is defined under prompt.segment.<name>. A segment must have either field or text, not both.

Setting	Type	Description
`field`	string	Dynamic data field: `directory`, `user`, `machine`, `duration`
`text`	string	Static text content
`foreground`	hex or named color	Text color
`background`	hex or named color	Background color
`bold`	boolean	Bold text
`italic`	boolean	Italic text
`underline`	boolean	Underline text
`size`	int (≥ 1)	Font size override for this segment
`padding_left`	int	Inner left padding in pixels
`padding_right`	int	Inner right padding in pixels
`margin_left`	int	Outer left margin in pixels
`margin_right`	int	Outer right margin in pixels
`radius_left`	int (≥ 0)	Left corner radius
`radius_right`	int (≥ 0)	Right corner radius
`when`	string	Condition expression: `returnCode==0` or `returnCode!=0`
`format`	`"string"` `"number"` `"json"` `"upper"` `"lower"` `"timespan"`	How to format the field value
`fallback`	string	Value to show when the field has no data

Named colors for foreground and background: black, red, green, yellow, blue, magenta, cyan, white, brightBlack, brightRed, brightGreen, brightYellow, brightBlue, brightMagenta, brightCyan, brightWhite.

prompt.active = default
prompt.profile.default.order = [dir, error, ok]

prompt.segment.dir.field = directory
prompt.segment.dir.foreground = black
prompt.segment.dir.background = blue
prompt.segment.dir.padding_left = 5
prompt.segment.dir.padding_right = 5
prompt.segment.dir.radius_right = 5

prompt.segment.error.text = !
prompt.segment.error.margin_left = 5
prompt.segment.error.radius_left = 5
prompt.segment.error.radius_right = 5
prompt.segment.error.when = returnCode!=0

prompt.segment.ok.text = ✓
prompt.segment.ok.margin_left = 5
prompt.segment.ok.radius_left = 5
prompt.segment.ok.radius_right = 5
prompt.segment.ok.when = returnCode==0

Keybindings

Each keybinding is one line:

keybind = [scope:][performable:]combo[>combo...]=action[:arg...]

Multiple keybind = lines are additive — later lines do not remove earlier ones.

Scopes:

always — fires even when a UI element (e.g. search box) has keyboard focus

Modifiers:

performable — only fires if the action is currently available

Combo format: modifier keys joined with +, then the key name. Command+T, Control+Shift+W, Option+Right.

Chord sequences: two combos separated by >. Example: Control+X>Control+S=save.

Available actions

Category	Action
Clipboard	`copy`, `cut`, `paste`
Buffer	`clear_buffer`, `clear_line`, `clear_line_to_end`, `clear_line_to_start`
Cursor movement	`go_to_start_of_line`, `go_to_end_of_line`, `go_to_next_word`, `go_to_previous_word`
Word editing	`delete_previous_word`, `delete_next_word`
Text selection	`select_all`, `select_text_left`, `select_text_right`, `select_word_left`, `select_word_right`, `select_text_to_start_of_line`, `select_text_to_end_of_line`
Tabs	`new_tab`, `close_tab`, `close_terminal`, `close_other_tabs`, `close_all_tabs`, `select_next_tab`, `select_previous_tab`, `select_tab_1` … `select_tab_9`
Panes	`split_right`, `split_left`, `split_down`, `split_up`, `maximize_pane`, `minimize_pane`, `select_next_pane`, `select_previous_pane`
Shell profiles	`open_shell_1` … `open_shell_9`
Window	`new_window`, `close_window`, `quit`
Workspaces	`open_workspace`, `select_workspace_default`, `select_workspace_1` … `select_workspace_9`
Autocomplete	`trigger_autocomplete`, `cycle_completion_mode`
Features	`open_ai_chat`, `open_command_palette`, `open_terminal_search`, `open_notification`, `open_config`

# Override the default split shortcut
keybind = Command+Shift+D=split_down

# Fire copy even inside the search box
keybind = always:performable:Command+C=copy

# Chord: Ctrl+X then Ctrl+C
keybind = Control+X>Control+C=copy

Terminal

Setting	Type	Default	Description
`terminal.webgl`	boolean	`true`	Use the WebGL renderer for better GPU-accelerated performance
`terminal.inactive_overlay_opacity`	int (0–100)	`30`	Dimming percentage applied to inactive terminal panes
`terminal.allow_transparency`	boolean	`true`	Allow transparent terminal backgrounds
`terminal.tab_stop_width`	number	`8`	Width of a tab character in columns
`terminal.minimum_contrast_ratio`	number	`4`	Minimum contrast ratio between text and background colors
`terminal.screen_reader_mode`	boolean	`false`	Enable accessibility / screen reader mode
`terminal.word_separator`	string	`"()[]{}'\"\\,;:/&<>*+=$^!~\` “`	Characters treated as word boundaries for double-click selection and word movement
`terminal.progress_bar.enabled`	boolean	`true`	Show a progress bar in the terminal tab header (uses OSC 9;4 escape sequences)

Autocomplete

Setting	Type	Default	Description
`autocomplete.provider.timeout_ms`	int (≥ 1)	`160`	Maximum time in milliseconds allowed for a single dynamic autocomplete provider to respond

Search

Setting	Type	Default	Description
`search.mode`	`"off"` `"hidden"` `"visible"`	`visible`	Initial visibility of the search panel
`search.match.background_color`	hex	`2f8fda55`	Background color of non-active search matches
`search.match.border_color`	hex	`2f8fda`	Border color of non-active search matches
`search.match.overview_ruler_color`	hex	`2f8fda`	Match indicator color in the overview ruler
`search.active_match.background_color`	hex	`f5e66399`	Background color of the currently selected match
`search.active_match.border_color`	hex	`f5e663`	Border color of the currently selected match
`search.active_match.overview_ruler_color`	hex	`f5e663`	Active match indicator color in the overview ruler

Workspace

Setting	Type	Default	Description
`workspace.mode`	`"off"` `"hidden"` `"visible"`	`visible`	Initial visibility of the workspace panel

Notifications

Cogno has two separate setting groups for notifications: notification.* controls behavior, notifications.* controls delivery channels.

Behavior (`notification.*`)

Setting	Type	Default	Description
`notification.mode`	`"off"` `"hidden"` `"visible"`	`visible`	Initial visibility of the notification panel
`notification.highlight_terminal_on_activity`	boolean	`true`	Highlight the terminal tab when a notification fires
`notification.long_running_commands.enabled`	boolean	`false`	Show a notification when a long-running command finishes
`notification.long_running_commands.minimum_duration_seconds`	int (≥ 0)	`10`	Only notify for commands that ran at least this many seconds
`notification.exceptions.handled.enabled`	boolean	`false`	Show a notification for handled application exceptions
`notification.exceptions.unhandled.enabled`	boolean	`false`	Show a notification for unhandled renderer exceptions
`notification.overview.max_items`	int (≥ 0)	`30`	Maximum number of notifications shown in the overview

Delivery channels (`notifications.*`)

Setting	Type	Default	Description
`notifications.app.available`	boolean	`true`	Whether in-app notifications are available on this system
`notifications.app.enabled`	boolean	`true`	Show in-app notifications
`notifications.app.duration_seconds`	int (≥ 0)	`5`	Seconds before an in-app notification auto-dismisses
`notifications.os.available`	boolean	`true`	Whether OS-level notifications are available on this system
`notifications.os.enabled`	boolean	`false`	Send OS notifications (requires system permission)

Command palette

Setting	Type	Default	Description
`command_palette.mode`	`"off"` `"hidden"` `"visible"`	`visible`	Initial visibility of the command palette

AI

Cogno can connect to local or remote AI models for in-terminal assistance.

Feature mode

Setting	Type	Default	Description
`ai.mode`	`"off"` `"hidden"` `"visible"` `"auto"`	`auto`	`auto` enables AI automatically when at least one usable provider is configured
`ai.active_provider`	string	—	ID of the provider to use. Defaults to the first usable provider found

A provider is usable when: enabled is not false, type is set, base_url is non-empty, and model is non-empty.

Providers

Define one or more providers under ai.providers.<name> where <name> is any identifier you choose.

Setting	Type	Required	Description
`type`	`"openai_compatible"` `"ollama_native"`	Yes	Protocol used to talk to the provider
`base_url`	string	Yes	Base URL of the API endpoint
`model`	string	Yes	Model name or ID to use
`api_key`	string	No	API key (for OpenAI-compatible endpoints that require authentication)
`headers`	key-value map	No	Additional HTTP headers sent with every request
`enabled`	boolean	No	Set to `false` to disable the provider without removing it
`auto_detected`	boolean	—	Set automatically by Cogno. Do not set this manually

Auto-detection

On startup, Cogno probes two local endpoints:

Provider	Default URL	Type
Ollama	`http://localhost:11434`	`ollama_native`
LM Studio	`http://localhost:1234`	`openai_compatible`

When a provider is detected, Cogno adds it with auto_detected = true and sets it as the active provider if none is configured. To prevent a provider from being auto-detected, add it manually with enabled = false.

Request context

Setting	Type	Default	Description
`ai.request.include_process_tree`	boolean	`false`	Include the current process tree in the context sent to the AI
`ai.request.max_commands`	int (≥ 0)	`8`	Maximum number of recent commands sent as context
`ai.request.max_output_chars`	int (≥ 0)	`4000`	Maximum terminal output characters sent as context

Examples

# Ollama running locally
ai.mode = auto
ai.providers.ollama.type = ollama_native
ai.providers.ollama.base_url = http://localhost:11434
ai.providers.ollama.model = llama3.2
ai.active_provider = ollama

# LM Studio
ai.providers.lmstudio.type = openai_compatible
ai.providers.lmstudio.base_url = http://localhost:1234
ai.providers.lmstudio.model = meta-llama-3-8b-instruct
ai.active_provider = lmstudio

# OpenAI
ai.providers.openai.type = openai_compatible
ai.providers.openai.base_url = https://api.openai.com
ai.providers.openai.model = gpt-4o
ai.providers.openai.api_key = sk-...
ai.active_provider = openai

# Disable auto-detection of LM Studio
ai.providers.lmstudio.enabled = false