Skip to main content

​
Configuration System Specification

Version: 1.0.0 Status: ACTIVE Effective: v0.18.0+ Last Updated: 2025-12-19

​
RFC 2119 Conformance

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals.

​
Preamble

This specification defines the configuration system for cleo, including global and project-level configuration, priority resolution, environment variable integration, and the config command interface.
Authority: This specification is AUTHORITATIVE for configuration system behavior. Implementation status is tracked separately in CONFIG-SYSTEM-IMPLEMENTATION-REPORT.md.

​
Executive Summary

The cleo configuration system provides:
  • Global Configuration: User preferences at ~/.cleo/config.json
  • Project Configuration: Project-specific settings at .cleo/config.json
  • Priority Resolution: Deterministic override hierarchy
  • Environment Variables: Runtime overrides via CLEO_* variables
  • Config Command: LLM-agent-friendly interface for reading/modifying settings

​
Part 1: Configuration Hierarchy

​
1.1 Priority Resolution Order

Configuration values MUST be resolved in this priority order (highest to lowest):
PrioritySourceDescription
1 (Highest)CLI FlagsCommand-line arguments
2Environment VariablesCLEO_* variables
3Project Config.cleo/config.json
4Global Config~/.cleo/config.json
5 (Lowest)DefaultsSchema-defined defaults

​
1.2 Resolution Behavior

  • The system MUST check each source in priority order
  • The system MUST return the first non-null value found
  • The system MUST fall back to schema defaults if no value is found
  • The system MUST NOT merge partial objects across sources

​
Part 2: Global Configuration

​
2.1 Location

  • Global config MUST be stored at ~/.cleo/config.json
  • Global config MUST be created during installation if not present
  • Global config MUST use the template at templates/global-config.template.json

​
2.2 Scope

Global config SHOULD contain only user preferences that apply across all projects:
SectionPurpose
outputOutput formatting preferences
displayUI display preferences
cliCLI behavior (aliases, debug)
defaultsDefault values for new tasks
Global config MUST NOT contain project-specific settings such as:
  • Archive thresholds
  • Validation rules
  • Session configuration
  • Backup settings

​
2.3 Schema

Global config MUST validate against schemas/global-config.schema.json.

​
Part 3: Project Configuration

​
3.1 Location

  • Project config MUST be stored at .cleo/config.json
  • Project config MUST be created during ct init if not present
  • Project config MUST use the template at templates/config.template.json

​
3.2 Scope

Project config MAY contain all configuration sections:
SectionPurpose
outputOutput formatting
archiveAuto-archive behavior
loggingAudit log settings
sessionSession management
validationData validation rules
defaultsDefault task values
displayDisplay preferences
cliCLI settings
backupBackup configuration
hierarchyHierarchy constraints (sibling limits, depth)

​
3.3 Schema

Project config MUST validate against schemas/config.schema.json.

​
Part 4: Environment Variables

​
4.1 Naming Convention

Environment variables MUST follow this pattern: 
CLEO_{SECTION}_{KEY}
Where:
  • SECTION is the config section in SCREAMING_SNAKE_CASE
  • KEY is the config key in SCREAMING_SNAKE_CASE

​
4.2 Mapping

Environment VariableConfig Path
CLEO_FORMAToutput.defaultFormat (special case)
CLEO_OUTPUT_DEFAULT_FORMAToutput.defaultFormat
CLEO_OUTPUT_SHOW_COLORoutput.showColor
CLEO_OUTPUT_SHOW_UNICODEoutput.showUnicode
CLEO_OUTPUT_DATE_FORMAToutput.dateFormat
CLEO_ARCHIVE_ENABLEDarchive.enabled
CLEO_ARCHIVE_DAYS_UNTIL_ARCHIVEarchive.daysUntilArchive
CLEO_LOGGING_ENABLEDlogging.enabled
CLEO_VALIDATION_STRICT_MODEvalidation.strictMode

​
4.3 Type Conversion

  • Boolean values: "true", "1", "yes" → true; "false", "0", "no" → false
  • Numeric values: MUST be valid integers or floats
  • String values: MUST be used as-is

​
Part 5: Config Command

​
5.1 Subcommands

The config command MUST support these subcommands:
SubcommandPurpose
show [PATH]Display configuration value(s)
get PATHGet single value (JSON output for scripting)
set PATH VALUEUpdate a configuration value
listList all configuration keys with values
reset [SECTION]Reset to defaults
editInteractive menu editor
validateValidate configuration against schema

​
5.2 Flags

FlagPurpose
--globalTarget global config instead of project
--format json|textOutput format
--dry-runPreview changes without applying
--quietSuppress output (for scripting)

​
5.3 JSON Output Format

JSON output MUST follow the standard envelope format: 
{
  "$schema": "https://cleo.dev/schemas/v1/output.schema.json",
  "_meta": {
    "command": "config",
    "subcommand": "set",
    "timestamp": "2025-12-19T00:00:00Z"
  },
  "success": true,
  "scope": "project|global",
  "path": "output.defaultFormat",
  "value": "json",
  "previous": "text"
}

​
5.4 Path Notation

Configuration paths MUST use dot notation:
  • output.defaultFormat
  • archive.daysUntilArchive
  • cli.aliases.ls

​
Part 6: Interactive Editor

​
6.1 Menu Structure

The interactive editor (config edit) SHOULD provide:
  • Main menu with numbered section choices
  • Sub-menus for each configuration section
  • Field-level editing with type validation
  • Save/discard workflow

​
6.2 Input Validation

The editor MUST:
  • Validate input types (boolean, number, string, enum)
  • Validate against schema constraints
  • Preview changes before saving
  • Confirm before applying changes

​
Part 7: Library Integration

​
7.1 Core Library

The library lib/config.sh MUST provide:
FunctionPurpose
get_config_value PATHGet value with priority resolution
set_config_value PATH VALUEUpdate config with validation
get_effective_configMerge global + project configs
resolve_env_override PATHCheck environment override
validate_config FILEValidate against schema

​
7.2 Script Integration

All scripts that read configuration SHOULD:
  • Source lib/config.sh
  • Use get_config_value() instead of direct file reads
  • Respect the priority hierarchy

​
Part 8: Error Handling

​
8.1 Error Codes

CodeConstantMeaning
0EXIT_SUCCESSOperation completed
1EXIT_GENERAL_ERRORUnspecified error
3EXIT_VALIDATION_ERRORSchema validation failed
4EXIT_NOT_FOUNDConfig path not found

​
8.2 Error Messages

Error messages MUST include:
  • The config path that failed
  • The reason for failure
  • Suggested remediation (when applicable)

​
Part 9: Backward Compatibility

​
9.1 Migration

  • Existing projects without config MUST use defaults
  • Missing config files MUST be auto-created on first write
  • Schema upgrades MUST preserve existing values

​
9.2 Deprecated Settings

Deprecated settings:
  • MUST still be read for backward compatibility
  • SHOULD emit deprecation warnings
  • MUST be migrated to new equivalents when possible
DocumentRelationship
LLM-AGENT-FIRST-SPEC.mdDefines JSON output requirements
CONFIG-SYSTEM-IMPLEMENTATION-REPORT.mdTracks implementation status
schemas/config.schema.jsonProject config schema
schemas/global-config.schema.jsonGlobal config schema

​
Appendix A: Configuration Sections Reference

​
A.1 Output Section

KeyTypeDefaultDescription
defaultFormatenum"text"Default output format
showColorbooleantrueEnable colored output
showUnicodebooleantrueEnable Unicode characters
showProgressBarsbooleantrueEnable progress bars
dateFormatenum"iso8601"Date formatting style

​
A.2 Archive Section

KeyTypeDefaultDescription
enabledbooleantrueEnable auto-archiving
daysUntilArchiveinteger7Days before archiving
maxCompletedTasksinteger100Max completed tasks before archive
preserveRecentCountinteger10Keep N recent completed

​
A.3 Logging Section

KeyTypeDefaultDescription
enabledbooleantrueEnable audit logging
maxEntriesinteger1000Max log entries
rotateOnArchivebooleantrueRotate log during archive

​
A.4 Validation Section

KeyTypeDefaultDescription
strictModebooleanfalseEnforce strict validation
warnOnIssuesbooleantrueShow validation warnings
autoFixbooleanfalseAuto-fix validation issues

​
A.5 Hierarchy Section

Configuration for Epic → Task → Subtask hierarchy constraints.
KeyTypeDefaultDescription
maxSiblingsinteger0Maximum children per parent (0 = unlimited, recommended for LLM agents)
maxDepthinteger3Maximum hierarchy depth (epic=0, task=1, subtask=2)
countDoneInLimitbooleanfalseInclude done tasks in sibling count
maxActiveSiblingsinteger8Maximum active/pending children for context management
Design Rationale (LLM-Agent-First): The sibling limits are designed for LLM agents as primary users, not human cognitive limits:
SettingPurposeRationale
maxSiblings: 0No limit (default)LLM agents don’t need cognitive limits; organize freely
countDoneInLimit: falseDone tasks excludedCompleted work is historical; doesn’t consume context
maxActiveSiblings: 8Context managementAligns with TodoWrite sync limit (Part 3.1 of TODOWRITE-SYNC-SPEC)
Set non-zeroOptional limitUse for organization if desired, not required
Key Insight: The original 7-sibling limit was based on Miller’s 7±2 law for human short-term memory. LLM agents:
  • Have 200K+ token context windows, not 4-5 item working memory
  • Don’t experience cognitive fatigue
  • Process lists in parallel without degradation
  • Benefit from hierarchy for organization, not cognitive load management
Active vs Done Task Distinction:
  • Active siblings (pending/active/blocked): Limited by maxActiveSiblings for context focus
  • Done siblings: Unlimited by default (countDoneInLimit: false) since they’re historical record

​
Appendix B: Version History

VersionDateChanges
1.0.02025-12-19Initial specification
1.1.02025-12-20Added hierarchy section (A.5) with LLM-agent-first rationale
End of Specification