cryptic

The Cryptics have a fearful reputation, and yet this one – the first specimen I’ve ever seen – seems . . . ‘Imbecilic?’ -- Words of Radiance

Cryptic runs a persistent service that watches directories for incoming markdown files with some basic frontmatter and a body containing the raw HTML content of a website. The content is shipped off to an LLM provider (any OpenAI compatible endpoint), categorized, and summarized, with different summarizations and metadata extraction depending on the category. It uses structured output for reliability, and the entire prompt (other than the system prompt) is defined in the pydantic models. The results are then written out to finalized Markdown in configured output directories.

It's designed to pair with Obsidian Headless Sync and Obsidian Web Clipper. Web Clipper can do LLM processing out of the box, but the output formatting is somewhat limiting; an independent service allows much more flexibility in prompt design and output constraints.

I've included a basic webclipper template for reference in this repository.

Installation

From PyPI:

pip install cryptic-md

From source, clone and run:

poetry install

Set OPENAI_API_KEY, and optionally OPENAI_BASE_URL, in the environment or in a .env file in the project root.

Configuration

Create ~/.config/cryptic/config.yaml:

openai:
  models:
    - gpt-5.4-mini
  default_model: gpt-5.4-mini
  default_reasoning: medium

service:
  vaults:
    personal:
      input_dir: ~/Obsidian/Personal/cryptic-staging
      output_dir: ~/Obsidian/Personal/cryptic-processed
      originals_dir: ~/Obsidian/cryptic-originals
  max_concurrent: 3
  max_tries: 3
  pickup_delay_seconds: 3.0

Override the config path per-invocation with --config /path/to/config.yaml.

Usage

Process a single note in place:

cryptic process note --note path/to/note.md

Run the service against the configured directories:

cryptic service

Drain the input directory once and exit (useful for batch runs):

cryptic service --once

Common flags available on both commands:

• --model NAME — pick a model from openai.models.
• --reasoning {low,medium,high,xhigh} — set reasoning effort.
• --config PATH — use an alternate config file.

Docker

Pre-built images are published to Docker Hub at camillescott/cryptic. The included compose.yaml is the simplest way to run the service:

# Provider API key
export OPENAI_API_KEY=sk-...
# To use a different provider endpoint
export OPENAI_BASE_URL=my.openwebui.local/api
docker compose up -d

It bind-mounts ./vaults → /vaults (your Obsidian tree) and ./config → /config (a directory containing config.yaml). Paths inside config.yaml must be rooted at /vaults, for example /vaults/personal/cryptic-staging.

To build the image locally instead of pulling:

docker build -t cryptic .

inotify works across bind mounts on Linux hosts. On Docker Desktop for macOS or Windows, host filesystem events don't propagate into the container.

Portions of this project's code have been written with agentic coding tools.