Logging

llmist uses structured logging for debugging and monitoring.

Log Levels

Level	Priority	Use Case
silly	0	Most verbose, internal state dumps
trace	1	Detailed execution flow
debug	2	Debugging information
info	3	General operational info
warn	4	Warnings (default)
error	5	Errors that may need attention
fatal	6	Critical failures

Environment Variables

# Set log level
export LLMIST_LOG_LEVEL="debug"

Variable Reference

Variable	Description	Default
LLMIST_LOG_LEVEL	Minimum log level	warn

Session-Based Logging

Each CLI session automatically creates its own log directory at ~/.llmist/logs/<session-name>/ with a memorable name like sunny-falcon. Numbers are only appended when there’s a name collision (e.g., sunny-falcon-2). Session logs are stored in session.log.jsonl within that directory.

CLI Logging

Use command-line flags:

    # Set log level
    npx @llmist/cli agent "task" --log-level debug

    # Enable trace for maximum verbosity
    npx @llmist/cli agent "task" --log-level trace

Or configure in ~/.llmist/cli.toml:

[agent]
log-level = "debug"

Programmatic Configuration

Using .withLogger()

import { LLMist, createLogger } from 'llmist';

const logger = createLogger({
  minLevel: 'debug',
});

await LLMist.createAgent()
  .withLogger(logger)
  .askAndCollect('Your prompt');

Custom Logger

import { createLogger } from 'llmist';

const logger = createLogger({
  minLevel: 'debug',
  name: 'my-app',
});

// Log directly
logger.debug('Custom message', { data: 'value' });
logger.info('Agent started');
logger.error('Something failed', { error });

Silent Mode

Suppress all logging:

const logger = createLogger({
  minLevel: 'fatal', // Only fatal errors
});

Log Output Format

Console output:

[2024-01-15 10:23:45] DEBUG (llmist): LLM call started
  model: "anthropic:claude-sonnet-4-5"
  messageCount: 3
[2024-01-15 10:23:46] DEBUG (llmist): LLM call complete
  tokens: { input: 150, output: 80 }
  duration: 1234

File output (structured JSON):

{"level":"debug","time":"2024-01-15T10:23:45.123Z","msg":"LLM call started","model":"anthropic:claude-sonnet-4-5"}

Debugging with Logs

Capture LLM Interactions

    LLMIST_LOG_LEVEL=trace npx @llmist/cli agent "task" 2>&1 | tee debug.log

Debug Gadget Execution

const logger = createLogger({ minLevel: 'trace' });

await LLMist.createAgent()
  .withLogger(logger)
  .withGadgets(MyGadget)
  .askAndCollect('Test');

Trace output shows:

• Gadget parameters received
• Execution timing
• Return values

Production Logging

const isProd = process.env.NODE_ENV === 'production';

const logger = createLogger({
  minLevel: isProd ? 'warn' : 'debug',
});

Integration with External Loggers

Wrap external loggers:

import pino from 'pino';

const pinoLogger = pino({ level: 'debug' });

// Create adapter
const logger = {
  debug: (msg, data) => pinoLogger.debug(data, msg),
  info: (msg, data) => pinoLogger.info(data, msg),
  warn: (msg, data) => pinoLogger.warn(data, msg),
  error: (msg, data) => pinoLogger.error(data, msg),
};

await LLMist.createAgent()
  .withLogger(logger)
  .askAndCollect('Task');

See Also

• Debugging Guide - Troubleshooting techniques
• CLI Configuration - CLI logging settings
• Hooks Guide - Custom monitoring with hooks