Configuration System Architecture & JSON Schema

[djdarcy]

Summary

Establish the foundational configuration system architecture for session-logger, including file location, JSON Schema validation, loading hierarchy, and extraction of hardcoded values into configurable settings.

This is a long-running issue that will evolve as new configurable options are added.

Relationship to Other Issues

• Feature: User-configurable logging channels and file routing #1 (Logging Channels): Defines what to configure (channels, routing)
• This issue: Defines how configuration works (schema, location, loading)
• Bidirectional Project-Sesslog Linking #2, Export Auto-Detection and Organization #3, Session Manager - Project Integration #4: Will add sections to the schema as implemented

Config File Location

Path: ~/.claude/plugins/settings/session-logger.json

Rationale:

• Follows Claude Code plugin architecture patterns
• Mirrors ~/.claude/plugins/cache/ structure
• Keeps plugin configs organized together
• Scales well as plugin ecosystem grows
• Clear separation from Claude Code's own settings.json

Directory Structure:

~/.claude/
├── settings.json                           # Claude Code settings
├── plugins/
│   ├── cache/                              # Installed plugins
│   ├── settings/                           # Plugin configurations
│   │   └── session-logger.json             # THIS FILE
│   └── installed_plugins.json
├── session-states/                         # Runtime state (not config)
└── sesslogs/                               # Log output (not config)

JSON Schema

Create config-schema.json for:

• IDE autocompletion via $schema reference
• Validation at config load time
• Self-documenting configuration
• Type checking for all settings

Schema Location: Published to repo for $schema URL reference

Config File Example:

{
  "$schema": "https://raw.githubusercontent.com/DazzleML/claude-session-logger/main/schemas/config-schema.json",
  "version": "1.0",
  
  "channels": { ... },
  "performance": { ... },
  "display": { ... }
}

Configuration Loading Hierarchy

Priority (highest to lowest):

1. Environment Variables     CLAUDE_SESSLOG_*
2. Project Config           {cwd}/.session-logger.json
3. Global Config            ~/.claude/plugins/settings/session-logger.json
4. Built-in Defaults        Hardcoded in code

Merging Strategy: Deep merge, arrays replace (not concatenate)

Settings to Extract from Hardcoded Values

Performance Settings

Setting	Current Location	Default	Type
max_file_size_for_line_detection	find_line_number()	2097152 (2MB)	int
content_preview_length	truncate_preview()	20	int

Display Settings

Setting	Current Location	Default	Type
verbosity	Config class	2	int (0-4)
datetime_mode	Config class	"full"	enum
pwd_enabled	Config class	false	bool
show_line_numbers	implicit	true	bool

Channel Routing (Issue #1)

Setting	Current Location	Default	Type
channels.*	hardcoded routing	per-category	object
tool_routing.*	N/A	{}	object

Future Settings (Issues #2, #3, #4)

Setting	Issue	Purpose
linking.*	#2	Bidirectional project links
exports.*	#3	Export auto-detection
session_manager.*	#4	Session manager paths

Implementation Tasks

• Create ~/.claude/plugins/settings/ directory on first run
• Create schemas/config-schema.json with all settings
• Implement ConfigLoader class with hierarchy support
• Extract hardcoded constants to config
• Add environment variable override support (CLAUDE_SESSLOG_*)
• Validate config against schema on load
• Graceful fallback on invalid config (log warning, use defaults)
• Cache config after first load (avoid re-reading per tool call)
• Document all settings in docs/configuration.md

Environment Variable Pattern

# Override any setting via environment
CLAUDE_SESSLOG_VERBOSITY=4
CLAUDE_SESSLOG_PERFORMANCE_MAX_FILE_SIZE=4194304
CLAUDE_SESSLOG_DISPLAY_DATETIME=none

Error Handling

Scenario	Behavior
Config file missing	Use defaults (zero-config works)
Invalid JSON	Log warning, use defaults
Schema validation fails	Log specific errors, use defaults for invalid fields
Permission denied	Log warning, use defaults

Success Criteria

• Zero-config continues to work (no breaking changes)
• IDE autocompletion works via $schema
• All hardcoded values extractable to config
• Config loads in <10ms
• Clear error messages for invalid config

Analysis

See 2026-02-01__22-42-51__configuration-system-design.md for detailed design analysis.

[djdarcy]

Addendum: Configuration Versioning Strategy

Schema Version Field

Every config file includes a version field:

{
  "$schema": "...",
  "version": "1.0",
  ...
}

Version Semantics

Version Change	When	Example
Patch (1.0.x)	New optional settings added	Add display.show_agent_prefix
Minor (1.x.0)	New sections added, no breaking changes	Add exports section for #3
Major (x.0.0)	Breaking changes, renames, removals	Rename channels to routing

Migration Strategy

def load_config(path):
    config = load_json(path)
    version = config.get("version", "1.0")
    
    # Apply migrations in order
    if version < "1.1":
        config = migrate_1_0_to_1_1(config)
    if version < "2.0":
        config = migrate_1_x_to_2_0(config)
    
    # Update version after migration
    config["version"] = CURRENT_VERSION
    return config

Migration Principles

1. Never delete user data - Deprecated fields are ignored, not removed
2. Migrate silently - Auto-upgrade without user intervention
3. One-way migrations - Don't downgrade, only upgrade
4. Log migrations - Debug log when migration applied

Schema Evolution Tracking

Maintain schemas/ directory with versioned schemas:

schemas/
├── config-schema.json          # Current (symlink to latest)
├── config-schema-1.0.json      # Original
├── config-schema-1.1.json      # Added exports section
└── CHANGELOG.md                # Schema change history

Deprecation Pattern

{
  "version": "2.0",
  "channels": { ... },
  
  // Deprecated - will be removed in 3.0
  // Use "channels.bash" instead of "shell_routing"
  "_deprecated": {
    "shell_routing": "Use channels.bash instead"
  }
}

Backwards Compatibility Window

• Current version: Full support
• Previous major: Read-only support (auto-migrate on load)
• Older versions: Warn and attempt migration