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

# Continue a conversation
lectic -i chat.lec

# Pipe in a question
echo "Summarize this: $(cat notes.md)" | lectic -f template.lec

# Use it in scripts
git diff --staged | lectic -f commit-msg.lec -S >> commits.log

Bring your own editor. Lectic has LSP support, so you get completions, diagnostics, and folding in Neovim, VS Code, or anything else that speaks LSP.

Bring your own language. Tools, hooks, and macros are just executables. Write them in Bash, Python, Rust — whatever you want.

Composable primitives. A small set of building blocks (:cmd, :ask, :reset, macros, hooks, tool definitions) combine to handle a wide range of workflows.

Plain text all the way down. Conversations are markdown files. No databases, no proprietary formats, no lock-in.

nix profile install github:gleachkr/lectic

# Download from GitHub Releases, then:
chmod +x lectic-*.AppImage
mv lectic-*.AppImage ~/.local/bin/lectic

Download the macOS binary from GitHub Releases and add it to your PATH.

1. Set an API key:

export ANTHROPIC_API_KEY="your-key"
# Or: GEMINI_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY

2. Create a file called chat.lec:

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

What's the weather like on Mars?

3. Run Lectic:

lectic -i chat.lec

Lectic appends the response to the file. Add another message and run again to continue the conversation.

What do you make of this diff?

:cmd[git diff HEAD~1]

interlocutor:
  name: Assistant
  prompt: You are a helpful assistant.
  tools:
    - exec: rg --json
      name: search
      usage: Search the codebase. Pass search patterns as arguments.
    - sqlite: ./analytics.db
      name: query
      readonly: true

interlocutors:
  - name: Writer
    prompt: You are a creative writer.
  - name: Editor
    prompt: You are a critical editor. Be harsh but constructive.

:ask[Writer] Write a short poem about the sea.

:::Writer
The waves roll in, the waves roll out...
:::

:aside[Editor] What do you think of this?

:::Editor
The opening line is clichéd. Consider a more striking image.
:::

hooks:
  - on: assistant_message
    do: |
      #!/bin/bash
      if [[ "$TOOL_USE_DONE" == "1" ]]; then
        notify-send "Lectic" "Done"
      fi

Drop a script called lectic-review in ~/.config/lectic/ or on your PATH:

#!/bin/bash
git diff --staged | lectic -f ~/.config/lectic/review-prompt.lec -S

Then run lectic review.

Lectic includes an LSP server (lectic lsp) that provides completions, diagnostics, hover information, go-to-definition, and folding.

• Neovim: Full plugin at extra/lectic.nvim
• VS Code: Extension at extra/lectic.vscode
• Other editors: Any editor that can run an external command on the buffer works. The LSP makes it better.

Full documentation is at gleachkr.github.io/Lectic.

• Getting Started
• Configuration
• Tools
• Cookbook — recipes for common workflows

MIT