head lesson
CLI · MCP · API
Choosing tools for AI, from recorded trials.
A catalog for finding tools you can use from the CLI, MCP and APIs, by use case and by comparison axes. Where we have tried a tool’s steps ourselves, there is a record with the version and the date we tried.
Each record is an observation on one machine with one version. Values we could not confirm stay unknown. Listed information is not a guarantee of actual behavior or safety.
How it works
Your AI reads the records, then you choose
- 01
Search by task
Your AI uses headlesson_search to find candidates by the task you want to do, a product name or a comparison axis.
- 02
Read the record
With headlesson_get, it reads the steps, cautions and sources, along with the version and date of the trial.
- 03
Check it yourself
A record is an observation on one of our machines. Before you use a tool, check it in your own environment too.
Features
Read the differences before you choose
Guides to choosing between tools, written from the results and cautions of recorded trials.
- Getting text out of a PDF: which recorded tool for which PDFFor assistants asked to pull text or values out of PDF files, this feature separates tools that are easy to confuse (text extraction, OCR, PDF structure and document conversion) and gives one check-first sequence built from headlesson's records.Read the feature
- JSON, YAML, CSV and SQLite files: which recorded command-line tool for which fileFor assistants asked to read, filter, edit or aggregate data and config files, this feature separates four recorded tools by the kind of file they fit (jq, yq, DuckDB, sqlite3) and lists the pitfalls headlesson observed in their lesson tests, separately from cautions taken from documentation.Read the feature
- Reading a web page or driving a browser: which recorded MCP server for which pageFor assistants asked to read a web page or act in a browser, this feature separates a fetch server from two browser servers and lists what headlesson observed in their lesson tests, separately from cautions taken from their documentation.Read the feature
- Sharing a local service on the internet: three recorded tunnel clients and what was not testedFor assistants asked to put a local demo or service on a public URL, this feature sets out the three recorded tunnel clients side by side and separates what headlesson ran from cautions taken from their documentation.Read the feature
- jq, gojq or jaq: three runs of the same JSON filters, and where they differedFor assistants asked to filter JSON on the command line, this feature compares the three recorded implementations of the jq language on the same authored input.Read the feature
- Drawing a diagram from text: Graphviz, D2 and Mermaid CLI, and why only two passedFor assistants asked to turn a text description into a diagram image, this feature sets out the three recorded command-line renderers and what headlesson saw when each drew the same small graph (nodes a, b, c; edges a→b, b→c, a→c) on macOS on 2026-10-14.Read the feature
- Searching code from the command line: ripgrep, ugrep or git grep, and which files each one seesFor assistants asked to find text in a code tree, this feature compares the three recorded search tools on the same six authored files.Read the feature
- Resizing and cropping an image from the command line: ImageMagick, libvips or sipsFor assistants asked to resize, crop or convert an image, this feature compares the three recorded command-line tools on one small synthetic picture: a 16×12 PNG with four coloured quarters.Read the feature
With version and date
Tools with trial records
Tools for which we publish records of actually trying the steps, with the version and date.
- Poppler utilitiesPDF library whose command-line utilities (pdftotext, pdfinfo and others) extract text and metadata from PDF files.Tested: all steps passed (2026-10-11 · 26.04.0)Read the record
- Tesseract OCROpen-source OCR engine with a command-line program that turns images of text into plain text, TSV, hOCR or searchable PDF.Tested: all steps passed (2026-10-11 · 5.5.1)Read the record
- DoclingLocal document converter with structured JSON and Markdown output.Tested: all steps passed (2026-10-11 · 2.137.0)Read the record
- MarkerLocal document converter with Markdown, JSON and optional hybrid LLM processing.Tested: all steps passed (2026-10-14 · 2.0.0)Read the record
- DuckDBAnalytical SQL database with a CLI that queries CSV, Parquet and JSON files directly.Tested: all steps passed (2026-10-11 · 1.5.6)Read the record
- THTHCLI to research, post, schedule and review your own social accounts.Tested: stopped partway (2026-10-11 · 3.15.0)Read the record
Use it over MCP
MCP tools
- headlesson_search: searches and compares by use case, product name or axis.
- headlesson_get: gets the description, entry points, steps, cautions and sources for an ID.
- headlesson_whats_new: shows changes since a given date and the related features.
- headlesson_feedback: sends feedback about the catalog to the operator.
From a shell, npx headlesson reads the same records.
Contact from an LLM: headlesson_feedback over MCP. The official public contact for people is Threads @head.lesson.
MCP endpoint
https://mcp.headlesson.com/mcpYou can select and copy it. The connection guide explains how to set it up.
Read the connection guideheadless on!
Read the records. Then try it with your AI.