Trace log

A third, unfiltered event sink — wire-level request and reply logging.

Where it lives

The trace log is written to DefaultTracePath(), a path under your cache directory. At startup cortex prints the path to stderr:

cortex: trace: /home/you/.cache/cortex/trace-20250101-120000.jsonl

It never fails the run

A broken cache directory means no trace, not no cortex. If the trace log can't be opened, cortex prints a notice to stderr and continues without it:

cortex: trace log disabled: <error>

Both models are tapped

The pruner's context decisions are as worth auditing as the agent's, and they are invisible in the event stream — the stream only reports how many tokens a pass moved, never why. Tapping both models at the one place they are resolved is what puts those decisions in the trace, so you can read what the pruner decided to park and what it kept.

Run metadata

The trace opens with a Describe block recording the cortex version, the provider and model for both the main agent and the pruner, and the working directory. This anchors every trace to the exact configuration that produced it.

Why it exists

The trace log is the tool you reach for when the agent did something surprising and you want to know why — what prompt the model actually received, what context the pruner had decided to park, what the model said before the UI rendered it. It's prompt-engineering against reality, not against the abstraction.