Logging

The runtime writes structured JSON logs to <runtime-root>/logs/.

Log files roll daily and are retained for a limited window; the log directory is created with owner-only permissions.

Levels

Log levels are trace, debug, info, warning, error, and critical.

The file sink records everything from trace upward.

Terminal output

run --level <LEVEL> sets the minimum terminal verbosity (default debug); --verbose is an alias for debug output. Terminal output is human-readable and written to standard error. Tool inputs and outputs are pretty-printed as JSON at debug level.

Reading logs

logs prints the most recently modified structured log file using the same human-readable format as run.

Use --agent <SLUG> to include only events whose structured AgentSlug property exactly matches the requested slug.

Use --follow to start at the end of the active file and continue printing complete events as they are written.

Following continues across daily and size-based log rotation.

Agent-filtered output excludes events that do not carry an AgentSlug property.

cireilclaw logs --agent mikiru --follow

Interpreting logs

Start with cireilclaw dry-run to separate configuration failures from runtime or provider failures.

When reproducing a problem, increase terminal detail with run --level debug or run --level trace.

Gateway liveness is reported at warning and error level, so it appears even at the default level. The Microsoft.Extensions.Http and System.Net.Http.HttpClient categories are limited to warnings, and the Discord gateway library's own informational lifecycle messages are not shown; the runtime's own gateway entries are the ones to follow.

Do not include tokens, OAuth credentials, or private message content when sharing diagnostics.