Every key Paneflow recognises today, grouped by what it controls. All
keys are optional and resolve to a sensible default when omitted. The
authoritative source is the [JSON Schema](https://github.com/ArthurDEV44/paneflow/raw/main/schemas/paneflow.schema.json)
shipped with each release.

## Core [#core]

The five most-asked-about keys.

### How do I set `default_shell`? [#how-do-i-set-default_shell]

Type: `string` (optional). Default: `$SHELL`.

```json
{ "default_shell": "/bin/zsh" }
```

Paneflow resolves the value through a fallback chain: configured
path (if executable) -> `$SHELL` -> `/bin/sh`. A configured shell
that is missing or non-executable falls through to the next link
and emits a log warning.

### How do I set `theme`? [#how-do-i-set-theme]

Type: `string` (optional). Default: `"One Dark"`.

Built-in themes:

* `"One Dark"` - dark theme, default.
* `"PaneFlow Light"` - light theme.

```json
{ "theme": "PaneFlow Light" }
```

Unknown names fall back to `"One Dark"` and emit a log warning. Themes
hot-reload on file save (500 ms mtime polling) - no restart needed.

### How do I set `window_decorations`? [#how-do-i-set-window_decorations]

Type: `"client" | "server"` (optional). Default: `"client"`.

```json
{ "window_decorations": "client" }
```

`"client"` draws a custom title bar (CSD); `"server"` defers to the OS
compositor (SSD). The default is `"client"` on all platforms; there
is no OS-specific override. **Read once at startup - changes require
a restart.**

### How do I set `shortcuts`? [#how-do-i-set-shortcuts]

Type: `object` mapping `keystroke -> action_name` (optional). Default:
empty object (built-in defaults apply).

```json
{
  "shortcuts": {
    "ctrl+shift+t": "new_tab",
    "ctrl+shift+w": "close_pane"
  }
}
```

Keys are keystroke strings; values are action names. See the full
[keybindings reference](/docs/keybindings) for the action vocabulary.
User entries override the built-in defaults with last-write-wins
semantics.

### How do I set `commands`? [#how-do-i-set-commands]

Type: `array` of command definitions (optional). Default: empty array.

```json
{
  "commands": [
    {
      "name": "Open API",
      "workspace": { "cwd": "~/projects/api" }
    }
  ]
}
```

  The schema accepts `commands` entries, but the runtime currently
  ignores them and logs `"commands are not yet implemented - they will
  be ignored"`. The structural shape is stable; the runtime activation
  ships in a later release.

## Typography [#typography]

The three typography keys landed in an early 0.2.x release; the
project did not pin per-key release tags, so the exact `since` value
is approximate.

### How do I set `font_family`? [#how-do-i-set-font_family]

Type: `string` (optional). Default: platform monospace fallback chain.

```json
{ "font_family": "JetBrains Mono" }
```

Paneflow tries the configured family first, then falls back to the
first installed monospace family it can locate.

### How do I set `font_size`? [#how-do-i-set-font_size]

Type: `number` (optional, pixels). Default: `14`.

```json
{ "font_size": 14 }
```

### How do I set `line_height`? [#how-do-i-set-line_height]

Type: `number` (optional, multiplier in the range `1.0`–`2.5`).
Default: `1.3`.

```json
{ "line_height": 1.3 }
```

Values outside the `1.0`–`2.5` range are rejected with a log warning
and the default is used instead.

## Input [#input]

### How do I set `option_as_meta`? [#how-do-i-set-option_as_meta]

Type: `boolean` (optional, Unix). Default: `true`.

```json
{ "option_as_meta": false }
```

When `true` (the default), the Alt key (Linux) or Option key (macOS)
sends an ESC prefix - the standard Meta-key behavior used by Emacs,
Vim, and most terminal applications. Set to `false` if you want
Option to produce native Unicode characters on macOS (e.g.,
`Option+e` -> `é`).

## AI agent buttons [#ai-agent-buttons]

Toggles for the per-agent quick-launch buttons in the pane title bar.

### How do I set `claude_code_button_visible`? [#how-do-i-set-claude_code_button_visible]

Type: `boolean` (optional). Default: `true`.

```json
{ "claude_code_button_visible": false }
```

### How do I set `claude_code_bypass_permissions`? [#how-do-i-set-claude_code_bypass_permissions]

Type: `boolean` (optional). Default: `false`.

```json
{ "claude_code_bypass_permissions": true }
```

When `true`, the Claude Code launcher invokes the CLI with
`--dangerously-skip-permissions`. Off by default for safety.

### How do I set `codex_button_visible`? [#how-do-i-set-codex_button_visible]

Type: `boolean` (optional). Default: `true`.

```json
{ "codex_button_visible": false }
```

### How do I set `opencode_button_visible`? [#how-do-i-set-opencode_button_visible]

Type: `boolean` (optional). Default: `true`.

```json
{ "opencode_button_visible": false }
```

## Telemetry [#telemetry]

### How do I set `telemetry`? [#how-do-i-set-telemetry]

Type: `object` `{ enabled: boolean | null }` (optional). Default:
`{ "enabled": null }` (prompt on first launch).

```json
{ "telemetry": { "enabled": false } }
```

Set `enabled: false` to disable all PostHog reporting. Set
`enabled: true` to opt in without the first-launch prompt.

## Terminal [#terminal]

### How do I set `terminal.ligatures`? [#how-do-i-set-terminalligatures]

Type: `boolean` inside the `terminal` object (optional). Default:
`false`.

```json
{ "terminal": { "ligatures": true } }
```

Enables programming ligatures for fonts that ship them (Fira Code,
JetBrains Mono, Iosevka, etc.). The font must contain the ligature
glyphs for the feature to take effect.

## A complete example [#a-complete-example]

```json
{
  "$schema": "https://github.com/ArthurDEV44/paneflow/raw/main/schemas/paneflow.schema.json",
  "default_shell": "/bin/zsh",
  "theme": "One Dark",
  "font_family": "JetBrains Mono",
  "font_size": 14,
  "line_height": 1.3,
  "window_decorations": "client",
  "option_as_meta": true,
  "shortcuts": {},
  "terminal": { "ligatures": false },
  "telemetry": { "enabled": null },
  "claude_code_button_visible": true,
  "claude_code_bypass_permissions": false,
  "codex_button_visible": true,
  "opencode_button_visible": true,
  "commands": []
}
```

For the live schema definition see
[`paneflow.schema.json`](https://github.com/ArthurDEV44/paneflow/raw/main/schemas/paneflow.schema.json).