Lectic Configuration

Lectic offers a flexible configuration system that lets you set global defaults, create per-project settings, and make conversation-specific overrides. This is managed through a hierarchy of YAML files.

Configuration Hierarchy

Configuration settings are merged from multiple sources. Each source in the list below overrides the one before it, with the .lec file’s own header always having the final say.

  1. System Config Directory: Lectic first looks for a configuration file at lectic/lectic.yaml within your system’s standard config location (e.g., ~/.config/lectic/lectic.yaml on Linux). This is the ideal place for your global, user-level defaults.

  2. Workspace Config: Next, Lectic looks for lectic.yaml by walking up from the active document directory (or from the current working directory when no file is active) until it finds one.

  3. Lectic File Header: The YAML frontmatter within your .lec file is the final and highest-precedence source of configuration.

Imports (Modular Configuration)

You can split configuration across multiple files with top-level imports. Each import can be either a string path or an object with path and optional optional: true.

imports:
  - ./.lectic/plugins/sales/module.yaml
  - path: ./.lectic/plugins/finance
    optional: true

Important details:

  • Relative import paths are resolved from the file that declares them.
  • If an import path is a directory, Lectic loads <dir>/lectic.yaml.
  • Imports are recursive, so imported files can have their own imports.
  • Import cycles are detected and reported as errors.

This is useful for plugin bundles, shared team defaults, and separating large configs into smaller modules.

Overriding Default Directories

You can change the default locations for Lectic’s data directories by setting the following environment variables:

  • $LECTIC_CONFIG: Overrides the base configuration directory path.
  • $LECTIC_DATA: Overrides the data directory path.
  • $LECTIC_CACHE: Overrides the cache directory path.
  • $LECTIC_STATE: Overrides the state directory path.

These variables, along with $LECTIC_TEMP (a temporary directory) and $LECTIC_FILE (the path to the active .lec file), are automatically passed into the environment of any subprocesses Lectic spawns, such as exec tools. This ensures your custom scripts have access to the same context as the main process.

Merging Logic

When combining settings from multiple configuration files, Lectic follows specific rules:

  • Objects (Mappings): If the higher precedence source has a name attribute, and the name doesn’t match the name attribute of the lower precedence source, then the higher precedence source replaces the lower precedence source. Otherwise, the objects are combined and matching keys merged recursively.
  • Arrays (Lists): Merged based on the name attribute of their elements. If two objects in an array share the same name, they are merged. Otherwise, the elements are simply combined. This is especially useful for managing lists of tools and interlocutors. When duplicate named items appear within a single file, later entries override earlier ones. The LSP warns on duplicate names in the document header to help catch mistakes.
  • Other Values: For simple values (strings, numbers) or if the types don’t match, the value from the highest-precedence source is used without any merging.

Additionally, the LSP validates header fields. It reports errors for missing or mistyped interlocutor properties and warns when you add unknown properties to an interlocutor mapping, which helps catch typos in keys like model or max_tokens.

Example

Imagine you have a global config in ~/.config/lectic/lectic.yaml:

# ~/.config/lectic/lectic.yaml
interlocutors:
    - name: opus
      provider: anthropic
      model: claude-opus-4-6

And a project-specific file, project.yaml:

# ./project.yaml
interlocutor:
    name: sonnet
    model: claude-sonnet-4-6
    tools:
        - exec: bash
        - agent: opus

If you place this project config at ./lectic.yaml in your working directory, Lectic will merge it with your system defaults and the document header using the precedence above. The haiku interlocutor will be configured with the claude-haiku-4 model, and it will have access to a bash tool and an agent tool that can call opus. You can switch to opus within the conversation if needed, using an :ask[] directive.