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. Log events are human-readable: trace, debug, and info go to standard output, while warning, error, and critical go to standard error. Tool inputs and outputs from non-remote sessions are pretty-printed as JSON at debug level; remote turns omit those payload logs. Startup/shutdown status messages and the agent table use standard output, except error status messages use standard error.

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 --session <ID> to include only events whose structured SessionId property exactly matches the requested id; it combines with --agent so both filters must match.

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, and session-filtered output excludes events that do not carry a SessionId property.

cireilclaw logs --agent mikiru --session 'discord:1234567890|9876543210' --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.