# koshi.kdl (/docs/v0.1/configuration/koshi-kdl)



`koshi.kdl` holds the app settings. It sits directly in the
[config directory](/docs/v0.1/configuration#where-the-files-go). `version` is
required; everything else is optional and grouped into blocks. `theme` is the
one top-level setting.

<Callout>
  A bad field is skipped at startup, keeps its default, and is logged — the rest
  of the file still applies. The exception is `update`: a bad value there drops
  the whole file for that launch. `koshi config check` rejects bad fields
  outright.
</Callout>

## theme [#theme]

`theme "midnight"` loads `themes/midnight.kdl`. A missing, invalid, or omitted
theme — or `"default"` — uses the built-in colours. See
[Themes](/docs/v0.1/configuration/themes).

| Key     | Value                                                   | Default     | Since   |
| ------- | ------------------------------------------------------- | ----------- | ------- |
| `theme` | string — the `themes/<name>.kdl` to use, without `.kdl` | `"default"` | ≥ 0.1.0 |

## pane [#pane]

| Key        | Value                                          | Default | Since   |
| ---------- | ---------------------------------------------- | ------- | ------- |
| `min-cols` | integer — smallest width a pane may shrink to  | `2`     | ≥ 0.1.0 |
| `min-rows` | integer — smallest height a pane may shrink to | `1`     | ≥ 0.1.0 |

## scrollback [#scrollback]

| Key               | Value                                                                        | Default             | Since   |
| ----------------- | ---------------------------------------------------------------------------- | ------------------- | ------- |
| `max-lines`       | integer — lines of history kept per pane (negative means `0`: no scrollback) | `10000`             | ≥ 0.1.0 |
| `max-bytes`       | integer — byte ceiling on that history (negative means `0`)                  | `33554432` (32 MiB) | ≥ 0.1.0 |
| `scroll-on-input` | boolean — typing while scrolled up snaps the view back to the newest line    | `#true`             | ≥ 0.1.0 |

`scroll-on-input #false` keeps the view parked while the input still goes
through. Only the primary screen follows; the alternate screen is left to the
full-screen program on it.

## layout [#layout]

| Key                  | Value                                                                                              | Default   | Since   |
| -------------------- | -------------------------------------------------------------------------------------------------- | --------- | ------- |
| `new-pane-direction` | `"left"` \| `"right"` \| `"up"` \| `"down"` — where a new pane opens when the command does not say | `"right"` | ≥ 0.1.0 |

## mouse [#mouse]

| Key             | Value                                     | Default               | Since   |
| --------------- | ----------------------------------------- | --------------------- | ------- |
| `border-resize` | boolean — drag a pane border to resize it | `#true`               | ≥ 0.1.0 |
| `scroll-lines`  | integer — lines per wheel notch           | `3`                   | ≥ 0.1.0 |
| `wheel`         | `"scroll-scrollback"` \| `"ignore"`       | `"scroll-scrollback"` | ≥ 0.1.0 |

## copy [#copy]

| Key                        | Value                                            | Default | Since   |
| -------------------------- | ------------------------------------------------ | ------- | ------- |
| `trim-trailing-whitespace` | boolean — drop trailing blanks from copied lines | `#true` | ≥ 0.1.0 |

## terminal [#terminal]

| Key             | Value                                             | Default                                | Since   |
| --------------- | ------------------------------------------------- | -------------------------------------- | ------- |
| `term`          | string — the `TERM` value child programs see      | `"xterm-256color"`                     | ≥ 0.1.0 |
| `colorterm`     | string — the `COLORTERM` value child programs see | `"truecolor"`                          | ≥ 0.1.0 |
| `default-shell` | string — the shell to launch                      | your `$SHELL` (`%COMSPEC%` on Windows) | ≥ 0.1.0 |

## logging [#logging]

koshi writes `logs/koshi-log-<session-id>.log` below the state directory.
Disabled logging creates no file at all.

| Key       | Value                                                          | Default     | Since   |
| --------- | -------------------------------------------------------------- | ----------- | ------- |
| `enabled` | boolean — write a log file at all                              | `#false`    | ≥ 0.1.0 |
| `level`   | `"info"` \| `"warning"` \| `"error"` — lowest severity written | `"warning"` | ≥ 0.1.0 |
| `format`  | `"pretty"` \| `"json"`                                         | `"pretty"`  | ≥ 0.1.0 |

`info` includes normal lifecycle events, `warning` recoverable problems, and
`error` failures that stop koshi. Each level includes the more severe ones.
Logs store ids and byte counts — never typed or copied text.

## update [#update]

<Callout type="warn">
  A bad value in this block drops the whole `koshi.kdl` for that launch, not just
  the field.
</Callout>

| Key                   | Value                                               | Default  | Since   |
| --------------------- | --------------------------------------------------- | -------- | ------- |
| `auto-check`          | boolean — check GitHub for a newer koshi at startup | `#true`  | ≥ 0.1.0 |
| `check-interval-days` | integer — days between checks                       | `14`     | ≥ 0.1.0 |
| `allow-prerelease`    | boolean — offer pre-release builds too              | `#false` | ≥ 0.1.0 |

## Every setting at its default [#every-setting-at-its-default]

`default-shell` is commented out because its default comes from `$SHELL` or
`%COMSPEC%`.

```kdl title="koshi.kdl"
// koshi.kdl — the complete default configuration.
version 1

theme "default"

pane {
    min-cols 2
    min-rows 1
}

scrollback {
    max-lines 10000
    max-bytes 33554432       // 32 MiB
    scroll-on-input #true
}

layout {
    new-pane-direction "right"
}

mouse {
    border-resize #true
    scroll-lines 3
    wheel "scroll-scrollback"
}

copy {
    trim-trailing-whitespace #true
}

terminal {
    term "xterm-256color"
    colorterm "truecolor"
    // default-shell "/bin/zsh"  // optional override
}

logging {
    enabled #false
    level "warning"
    format "pretty"
}

update {
    auto-check #true
    check-interval-days 14
    allow-prerelease #false
}
```