@maleus/callimaque

Turn .xlsx, .docx, .pdf, .pptx and .csv files into something an LLM can actually reason about: a structured JSON model of the document, plus an optional Markdown report.

Document parsers usually give you either raw text — losing every structural signal — or a DOM you have to walk yourself. Callimaque sits in between. It extracts what the naive path drops: hidden sheets, data validations and their option lists, cross-sheet formula dependencies, tracked changes, comments, speaker notes, bookmark outlines, form fields, CSV dialect and encoding. Then it infers the parts nobody stores explicitly — where a table actually starts, what a column's type really is, which defined names are broken.

Install

npm install -g @maleus/callimaque

Requires Node.js 24 or later.

Usage

callimaque <command> <file> [--md] [--out <dir>]

| Command | Input | | ------- | ------------------------------------------------------ | | xlsx | Excel / Google Sheets workbooks | | docx | Word documents | | pdf | PDF files | | pptx | PowerPoint decks | | csv | Delimiter-separated text (comma, semicolon, tab, pipe) |

Flags:

• --out <dir> — where to write the outputs. Defaults to the input file's directory.
• --md — also emit a Markdown report next to the JSON dump.

Outputs land in <out>/:

• <basename>.dump.json — the structured model. This is the source of truth.
• <basename>.md (xlsx) or <basename>.analysis.md (everything else) — the Markdown report, only with --md.

Progress and a short per-document summary go to stderr, so stdout stays free.

Exit codes: 0 success, 1 bad input or unknown flag, 2 refused input (a macro-enabled .xlsm, for instance).

Example

callimaque xlsx budget.xlsx --md --out ./callimaque-out
jq '.sheets | map({name, state, formulaCount})' ./callimaque-out/budget.dump.json

What each analyzer extracts

xlsx — per-sheet visibility (visible / hidden / veryHidden), used range, cell and formula counts, merged cells, data validations with their parsed option lists (including the x14 extension form that most libraries skip), conditional formatting, defined names with broken #REF! flagged, a cross-sheet dependency graph, and inferred tabular blocks with per-column type inference.

docx — the body rendered as Markdown (headings, lists, tables, hyperlinks, footnotes), plus comments and tracked changes as first-class sections rather than discarded markup. Embedded images are written out and referenced inline.

pdf — text per page, bookmark outline, annotations, form fields, hyperlinks, page sizes, and a per-page "is this a scan?" heuristic. Embedded images are extracted as PNG.

pptx — slides in presentation order, body text with bullet levels, speaker notes (often where the real narrative lives), resolved hyperlinks, tables, and hidden-slide detection.

csv — delimiter, encoding and line-ending detection, then per-column type inference (string / integer / decimal / boolean / date / enum) with null counts, distinct counts and candidate keys.

Claude Code skills

The package ships five skills under skills/, one per format. They tell an agent when to reach for callimaque, how to read the JSON dump rather than skim the Markdown draft, and what a good analysis report contains.

Copy the ones you want into your repository:

cp -r "$(npm root -g)/@maleus/callimaque/skills/analysis-xlsx" .claude/skills/

Development

pnpm install
pnpm run build      # bundles the CLI to dist/callimaque.js
pnpm test
pnpm run type:check

The test suite runs each analyzer end-to-end against a committed fixture and asserts on the resulting JSON. The fixtures carry synthetic content on purpose — they exist for their structure, not their prose.

License

MIT