# Logging and crash reports (/docs/v0.4/using/logging)



Logging is off by default. When enabled, koshi writes one file per session:

```text
logs/koshi-log-<uuid>.log
```

The name carries the session's **bare** UUID, without the `session-` prefix the
id prints with. The `logs/` directory lives below koshi's platform state
directory. Disabled logging creates no file.

Every koshi process reads this block for its own log file — the session server
and each attached terminal alike.

## Configure [#configure]

```kdl title="koshi.kdl"
version 1

logging {
    enabled #true
    level "warning"
    format "pretty"
}
```

| Setting   | Values                             | Default     |
| --------- | ---------------------------------- | ----------- |
| `enabled` | `#true` / `#false`                 | `#false`    |
| `level`   | `"info"` / `"warning"` / `"error"` | `"warning"` |
| `format`  | `"pretty"` / `"json"`              | `"pretty"`  |

`info` includes normal lifecycle events. `warning` adds recoverable problems.
`error` keeps only failures that stop koshi. Each level includes more severe
events.

`pretty` is human-readable. `json` writes one JSON object per line for tools to
parse.

## Crash reports [#crash-reports]

A crash report is separate from the log file. No setting turns it on or off.

If koshi panics while you have a session open, it restores your terminal first
and then writes a report to the data directory:

```text
crash-<seconds-since-1970>.txt
```

| Platform | Data directory                        |
| -------- | ------------------------------------- |
| Linux    | `~/.local/share/koshi`                |
| macOS    | `~/Library/Application Support/koshi` |
| Windows  | `%APPDATA%\koshi\data`                |

A panic at 2026-08-08 12:00:00 UTC writes `crash-1786190400.txt`. Attach that
file to a bug report.

The file holds the koshi version, the operating system and processor, the time,
the panic message, the source line that panicked, and the stack. koshi reads
only those from the panic.

## Privacy [#privacy]

Logs include ids, lifecycle events, errors, and byte counts. Crash reports
include the panic and the stack. Neither stores pane content, scrollback, typed
input, or copied text.

Remove old logs and crash reports with the platform cleanup steps on the
[Uninstall](/docs/v0.4/uninstall) page.