Introduction to Lectic

Lectic is a unixy LLM toolbox. It treats conversations as plain text files, which means you can version control them, grep them, pipe them, email them, and edit them in whatever editor you like.

Core Principles

Plain text all the way down

Every conversation is a markdown file (.lec). Because your conversations are files, you can do anything with them that you can do with files:

  • Version control: Track changes with git, branch experiments, diff conversations.
  • Search: grep across your conversation history.
  • Process: Pipe conversations through other tools. Combine lectic with sed, pandoc, or anything else.
  • Back up: Copy files. Sync with rsync. Store wherever you want.

Bring your own editor

Lectic includes an LSP server that provides completions, diagnostics, hover information, go-to-definition, and folding for .lec files. You can use lectic with Neovim, VS Code, or any editor that speaks LSP.

For editors without LSP support, the basic workflow still works: edit a file, run lectic -i file.lec, and the response is appended.

Bring your own language

Tools, hooks, and macros are executables. Write them in whatever language you prefer. If it can read environment variables and write to stdout, it works with Lectic.

This means you’re not locked into a plugin ecosystem or a specific scripting language. Your existing scripts and tools integrate directly.

Composable primitives

Lectic provides a small set of building blocks:

  • :cmd: Run a command and include its output.
  • :ask / :aside: Switch between interlocutors.
  • :reset: Clear conversation context.
  • Macros: Reusable text expansions.
  • Hooks: Run code on events (message sent, tool called, etc.).
  • Tools: Give the LLM capabilities (shell, database, MCP servers).

You can put these together to build all sorts of AI applications: coding assistants, reseach and analysis workflows, orchestrated multi-agent swarms, or simple one-shot command line text processing tools. Take a look at the Cookbook for some detailed recipes.

Quick Example

A minimal conversation:

---
interlocutor:
  name: Assistant
  prompt: You are a helpful assistant.
---

What's 2 + 2?

:::Assistant

4

:::

A more interesting one:

---
interlocutor:
  name: Assistant
  prompt: You are a code reviewer.
  tools:
    - exec: cat
      name: read_file
    - exec: rg --json
      name: search
---
Review the error handling in src/main.ts. Are there any uncaught
exceptions?

The assistant can read files and search the codebase to answer.

Next Steps

All of the documentation concatinated into a single markdown file can be found here