Managing Context: External Content

Lectic aims to make it easy to pull external information into the conversation, providing the LLM with the context it needs to answer questions, analyze data, or perform tasks.

This is done in two primary ways: by referencing files and URIs using standard Markdown links, and by executing shell commands with the :cmd directive.

Content References via Markdown Links

You can include local or remote content using the standard Markdown link syntax, [Title](URI). Lectic will fetch the content from the URI and include it in the context for the LLM.

Please summarize this local document: [Notes](./notes.md)

Analyze the data in this S3 bucket: [Dataset](s3://my_bucket/dataset.csv)

What does this README say?
[Repo](github+repo://gleachkr/Lectic/contents/README.md)

Supported Content Types

  • Text: Plain text files are included directly.
  • Images: PNG, JPEG, GIF, and WebP images are supported.
  • PDFs: Content from PDF files can be extracted (requires a provider that supports PDF ingestion, such as Anthropic, Gemini, or OpenAI).
  • Audio: Gemini and OpenAI support audio inputs. For OpenAI, use provider: openai/chat with an audio‑capable model; supported formats include MP3, MPEG, and WAV. Gemini supports a broader set of audio types.
  • Video: Gemini supports video understanding. See supported formats in Google’s docs: https://ai.google.dev/gemini-api/docs/video-understanding#supported-formats

URI Schemes

Lectic supports several URI schemes for referencing content:

  • Local Files: Simple relative paths like ./src/main.rs or absolute file:///path/to/file.txt URIs.
  • Remote Content: http:// and https:// for web pages and other online resources.
  • Amazon S3: s3:// for referencing objects in S3 buckets. This requires AWS credentials to be configured in your environment.
  • MCP Resources: You can reference resources provided by an MCP server using a custom scheme, like github+repo://....

A few convenience rules apply:

  • For local file references using file://, use absolute paths. A portable way to build these is with $PWD (e.g., file://$PWD/papers/some.pdf).
  • Environment variables in URIs use the $VAR form; ${VAR} is not supported. Expansion happens before any globbing.

You can use glob patterns to include multiple files at once. This is useful for providing the entire source code of a project as context.

[All source code](./src/**/*.ts)
[All images in this directory](./images/*.jpg)

Lectic uses Bun’s Glob API for matching.

Advanced URI Features

Using full file:// URIs for local content enables additional capabilities.

Environment Variable Expansion

Lectic supports environment variable expansion in URIs. This helps in creating portable .lec files that don’t rely on hardcoded absolute paths.

[My dataset](file://$DATA_ROOT/my_project/data.csv)
[Log file](file://$PWD/logs/latest.log)

PDF Page Selection

When referencing a PDF, you can point to a specific page or a range of pages by adding a fragment to the URI. Page numbering starts at 1.

  • Single Page: [See page 5](file.pdf#page=5)
  • Page Range: [See Chapter 2](book.pdf#pages=20-35)

If both page and pages are supplied, pages takes precedence. If a page or range is malformed or out of bounds, Lectic will surface an error that is visible to the LLM.

Command Output via :cmd Directive

Use :cmd[...] to execute a shell command and capture its stdout and stderr. Lectic runs the command with the Bun shell. The result is returns as an inline attachment that appears at the very top of the next assistant block.

How it works - When you run lectic, any :cmd[...] found in the last user message is executed, and ther result is forwared to the LLM. - The result is also inserted as an inline attachment chunk at the beginning of the generated assistant block. It looks like an XML block beginning with <inline-attachment ...>. It includes the command and its content (stdout, or an error wrapper that includes stdout and stderr). - During provider serialization, this attachment is treated as if it were a user message that immediately precedes the assistant’s round. This keeps provider caches stable and avoids recomputing earlier commands. - Older :cmd[...] directives are not re-executed. Their cached attachments remain part of the transcript and are reused across runs.

Use cases - System information: What can you tell me about my system? :cmd[uname -a] - Project state: Write a commit message: :cmd[git diff --staged] - Data analysis: Compute the average: :cmd[cat data.csv | awk '...']

Notes - Output is wrapped in XML. On success, stdout is included. On failure, an <error> wrapper includes both stdout and stderr. - Commands are executed directly (with Bun’s $), in the current working directory. Standard Lectic environment variables like LECTIC_FILE are available.