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. Working Directory: Next, it looks for a lectic.yaml file in the current working directory. This is useful for project-level configuration that you might commit to a git repository.

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

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): Merged recursively. If a key exists in multiple sources, the value from the source with higher precedence wins.
  • 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-3-opus-20240229

And a project-specific file, project.yaml:

# ./project.yaml
interlocutor:
    name: haiku
    model: claude-3-haiku-20240307
    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-3-haiku 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.