Codewalkers/docs/logging.md

Structured Logging

Codewalk District uses pino for structured JSON logging on the backend.

Architecture

• pino writes structured JSON to stderr so CLI user output on stdout stays clean
• console.log remains for CLI command handlers (user-facing output on stdout)
• The src/logging/ module (ProcessLogWriter/LogManager) is a separate concern — it captures per-agent process stdout/stderr to files

Environment Variables

Variable	Description	Default
CW_LOG_LEVEL	Log level override (fatal, error, warn, info, debug, trace, silent)	info (production), debug (development)
CW_LOG_PRETTY	Set to 1 for human-readable colorized output via pino-pretty	unset (JSON output)

Log Levels

Level	Usage
fatal	Process will exit (uncaught exceptions, DB migration failure)
error	Operation failed (agent crash, parse failure, clone failure)
warn	Degraded (account exhausted, no accounts available, stale PID, reconcile marking crashed)
info	State transitions (agent spawned/stopped/resumed, dispatch decision, server started, account selected/switched)
debug	Implementation details (command being built, session ID extraction, worktree paths, schema selection)

Adding Logging to a New Module

import { createModuleLogger } from '../logger/index.js';

const log = createModuleLogger('my-module');

// Use structured data as first arg, message as second
log.info({ taskId, agentId }, 'task dispatched');
log.error({ err: error }, 'operation failed');
log.debug({ path, count }, 'processing items');

Module Names

Module	Used in
agent-manager	src/agent/manager.ts
dispatch	src/dispatch/manager.ts
http	src/server/index.ts
server	src/cli/index.ts (startup)
git	src/git/manager.ts, src/git/clone.ts, src/git/project-clones.ts
db	src/db/ensure-schema.ts

Testing

Logs are silenced in tests via CW_LOG_LEVEL=silent in vitest.config.ts.

Quick Start

# Pretty logs during development
CW_LOG_LEVEL=debug CW_LOG_PRETTY=1 cw --server

# JSON logs for production/piping
cw --server 2>server.log