External Prompts and Instructions

Many Lectic fields can load their text from outside the document. You can point a field at a file on disk, or run a command (or script) and use its output. This lets you keep prompts, usage text, and notes in one place, or compute them on demand.

What supports external sources:

  • interlocutor.prompt
  • macros[].expansion
  • tools[].usage (for tools that accept a usage string)
  • tools[].details (for tools that provide extra details)
  • tools[].init_sql (for sqlite tool initialization SQL)
  • interlocutor.output_schema

Each of these accepts either a plain string, or a string beginning with one of the prefixes below.

For interlocutor.output_schema, loaded content is parsed as YAML (so JSON files are valid too) and then validated as a JSON Schema.

file:PATH

Loads the contents of PATH and uses that as the field value. Environment variables in the path are expanded before reading.

Examples

interlocutor:
  name: Assistant
  prompt: file:./prompts/assistant.md
macros:
  - name: summarize
    expansion: file:$HOME/.config/lectic/prompts/summarize.txt

local:PATH and file:local:PATH

Use local: when a path should be resolved relative to the config source file that contains the value.

Supported forms:

  • local:./...
  • local:../...
  • file:local:./...
  • file:local:../...

Not supported:

  • local:file:...
  • local:exec:...
  • local:/abs/path
  • local:foo/bar (must start with ./ or ../)

local: rewrites to an absolute filesystem path string. file:local: rewrites to file:/absolute/path.

Example:

tools:
  - exec: bash
    env:
      PLUGIN_ROOT: local:./
      PROMPT_FILE: local:./prompts/review.md

interlocutor:
  prompt: file:$PROMPT_FILE
  # or directly:
  # prompt: file:local:./prompts/review.md

exec:COMMAND or exec:SCRIPT

Runs the command and uses its stdout as the field value. There are two forms:

  • Single line: executed directly, not through a shell. Shell features like globbing and command substitution do not work. If you need them, invoke a shell explicitly (for example, bash -lc '...').
  • Multi‑line: treated as a script. The first line must be a shebang (for example, #!/usr/bin/env bash). The script is written to a temporary file and executed with the interpreter from the shebang.

Environment variables in a single‑line command are expanded before running. For multi‑line scripts, variables are available via the process environment at runtime.

Examples

Single line

interlocutor:
  name: Assistant
  prompt: exec:echo "You are a helpful assistant."

Multi‑line script

interlocutor:
  name: Assistant
  prompt: |
    exec:#!/usr/bin/env bash
    cat <<'PREFACE'
    You are a helpful assistant.
    You will incorporate recent memory below.
    PREFACE
    echo
    echo "Recent memory:"
    sqlite3 "$LECTIC_DATA/memory.sqlite3" \
      "SELECT printf('- %s (%s)', text, ts) FROM memory \
       ORDER BY ts DESC LIMIT 5;"

Working directory and environment

  • file: and exec: resolve relative paths and run commands in the current working directory of the lectic process (the directory from which you invoked the command). If you used -f, note that the working directory does not automatically switch to the .lec file’s directory for these expansions. Use absolute paths or cd if you need a different base.
  • local: is the exception: it is resolved relative to the config source file where it appears, then rewritten to an absolute path.
  • Standard Lectic environment variables are provided, including LECTIC_CONFIG, LECTIC_DATA, LECTIC_CACHE, LECTIC_STATE, LECTIC_TEMP, and LECTIC_FILE (when using -f). Your shell environment is also passed through.
  • Macro expansions can inject additional variables into exec: via directive attributes. See the Macros guide for details.

Behavior and errors

  • The value is recomputed on each run. This makes it easy to incorporate recent state (for example, “memory” from a local database) into a prompt.
  • If a file cannot be read or a command fails, Lectic reports an error and aborts the run. Fix the source and try again.

See also

  • External Content for attaching files to user messages.
  • Macros for passing variables into exec: expansions within macros.
  • Configuration Keys for the full list of fields that accept file: and exec: sources.