> For the complete documentation index, see [llms.txt](https://docs.fritesai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fritesai.com/reference/logging.md).

# Logging

frites keeps two distinct views of what the council is doing: a **live, per-turn** progress channel in your editor, and a **durable** gateway log on disk. The live channel shows what's happening right now and most editors collapse it once a turn ends. It's the "is it working?" view, not a record. The gateway log is the durable detail view: scroll back to any past turn long after the editor has moved on. This page covers the durable log and the `frites logs` tailer.

## The gateway log

The gateway writes one structured, leveled, turn-scoped record per line to stdout, which the background service captures to `~/.frites/gateway.log` (launchd `StandardOutPath` / systemd `StandardOutput`). Crashes and unformatted stderr land in `~/.frites/gateway.err`. Every turn writes detailed, timestamped, turn-correlated logs: request, the continuation/fan-out decision, each child's start/finish/cost, synthesis, and total spend.

Each text record is formatted as:

```
<iso-timestamp> LEVEL  [turn] message  key=value …
```

The `turn` id is a first-class prefix so per-request lines are easy to scan and grep; remaining fields follow the message as `key=value` pairs.

## `frites logs`

```bash
frites logs [-f|--follow] [-n N|--lines N] [--level debug|info|warn|error]
```

`frites logs` tails `~/.frites/gateway.log` (and appends recent crash lines from `~/.frites/gateway.err`).

| Flag                | Default | Meaning                                                                                     |
| ------------------- | ------- | ------------------------------------------------------------------------------------------- |
| `-f`, `--follow`    | off     | After printing the snapshot, stream new lines live until interrupted (Ctrl-C).              |
| `-n N`, `--lines N` | `60`    | Show the last `N` lines of the main log.                                                    |
| `--level <level>`   | none    | Only show lines at or above this minimum level. An unknown level is rejected with an error. |

Examples:

```bash
frites logs                         # last 60 lines
frites logs -f                      # follow live
frites logs -f --level debug        # include prompt/decision previews
frites logs -n 200 --level warn     # only warnings + errors
```

Without follow, `frites logs` prints the last `N` lines of `gateway.log`, then, if present, a `── gateway stderr (crashes) ──` section with the last 20 lines of `gateway.err`. With `--follow` it also streams new lines from both files as they arrive. If neither log file exists yet, it prints a hint to start the gateway or install the service first.

## Log levels

Levels are ordered `debug` < `info` < `warn` < `error`. The `--level` filter keeps lines at or above the chosen minimum. Lines that aren't level-formatted (raw stderr, crash output) are never hidden by the filter, so you never lose crash output the gateway didn't format.

The gateway's own verbosity is set by the `logLevel` config key (default `info`), overridden by the `FRITES_LOG_LEVEL` environment variable when set. To capture more detail, crank verbosity with `frites config set --global logLevel debug` (or `FRITES_LOG_LEVEL=debug`), then `frites restart` so the service picks it up. The `frites logs --level` flag filters what's *displayed*; `logLevel` controls what's *written*, so a level can only be shown if it was recorded.

## JSON output

Set `FRITES_LOG_JSON=1` to make the gateway emit newline-delimited JSON records (`{ ts, level, msg, …fields }`) instead of the human format. This is useful for ingestion by other tooling.

## Durable detail vs live progress

|          | Live progress channel                      | Gateway log                       |
| -------- | ------------------------------------------ | --------------------------------- |
| Where    | Editor thinking/reasoning channel          | `~/.frites/gateway.log`           |
| Scope    | One turn, right now                        | Every turn, retained              |
| Lifetime | Collapsed by the editor when the turn ends | Durable; scroll back any time     |
| Use      | "Is it working?"                           | After-the-fact detail of any turn |

The live channel is governed by the `streamProgress` and `progressDetail` config keys (see [Configuration](/reference/configuration.md)). Note that not every turn shows the whole council: with `fanOutScope: first-turn` only the substantive request turn fans out, and the host's background/utility calls always run a single agent, so single-agent continuation lines on follow-up turns are expected.

## See also

* [Environment variables](/reference/environment-variables.md): `FRITES_LOG_LEVEL`, `FRITES_LOG_JSON`, and related vars.
* [Configuration](/reference/configuration.md): the `logLevel`, `streamProgress`, and `progressDetail` keys.
* [CLI](/reference/cli.md): the `frites logs` command and service management.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fritesai.com/reference/logging.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.