Bilig is a TypeScript-native headless WorkPaper runtime, aimed at Node.js services, tests, and AI agents. Its core idea is: keep the workbook model, but run rules in Node without having to drive Excel or a browser spreadsheet.
-
Purpose and positioning Bilig is used to let a service or tool have a workbook model: set inputs, recalculate formulas, read calculation outputs, persist WorkPaper JSON, restore that JSON, and verify results. It explicitly states that it is not a visual spreadsheet application, nor does it claim full Excel compatibility. If an .xlsx file is a contract that must be followed, start with the compatibility report.
-
Main capabilities According to the materials, Bilig's lifecycle is defined as: input → formula recalculation → typed readback → JSON persistence → restore verification. The public TypeScript API includes set(), setMany(), readMany(), display(), and saveJson(). When multiple inputs need to be submitted as a single edit and verified, use editManyAndReadback(). The complete public API is documented in packages/workpaper/README.md. Through MCP, the server exposes the following tools: list_sheets, read_range, read_cell, set_cell_contents, set_cell_contents_and_readback, get_cell_display_value, export_workpaper_document, and validate_formula. It also publishes MCP resources and prompts, letting supported hosts discover the workflow before editing cells. Bilig can import and export workbook files, but formula cached values in .xlsx are only diagnostic information, not a basis for accuracy. The compatibility report can identify risks such as unsupported functions, external links, macros, pivot tables, volatile formulas, etc., but it does not certify Excel compatibility.
-
How to use
-
Verify the published package before installation: the materials mention that the evaluator will edit Inputs!B2, recalculate Summary!B2, save WorkPaper, restore it, and compare the restored value. verified: true means that writing, formula readback, JSON export, and restore readback all pass.
-
Use from TypeScript: use set(), setMany(), readMany(), display(), saveJson() for regular operations; use editManyAndReadback() when multiple inputs need to be submitted as a single edit and verified.
-
Use through MCP: for locally writable WorkPaper, use the local stdio path; suitable for private or persistent project state. Hosted endpoint https://bilig.proompteng.ai/mcp is request-scoped, used only for stateless connector discovery and smoke testing; do not send private workbook data to it.
-
Agent integration: the repository includes AGENTS.md and SKILL.md, and agents can discover the same proof contract from node_modules. It also provides files such as CLAUDE.md, .claude/skills/bilig-workpaper/SKILL.md, .claude/commands/bilig-workpaper-proof.md, .cursor/rules/bilig-workpaper.mdc, .devin/rules/bilig-workpaper.md, .windsurf/rules/bilig-workpaper.md, .clinerules/bilig-workpaper.md, .continue/rules/bilig-workpaper.md, .zed/settings.json, opencode.jsonc, and .opencode/agents/bilig-workpaper.md. It can be used through the agent rule chooser or a host handoff prompt.
-
Integration recipes: first run the evaluator, then use the recipe for the corresponding host, including OpenAI Agents SDK (direct tools, MCPServerStdio, MCPServerStreamableHttp), OpenAI Responses API (function-call read-back with explicit before-and-after evidence), Vercel AI SDK (generateText() and streamText() tool loops), Open WebUI (local or hosted MCP discovery), and n8n (@bilig/n8n-nodes-workpaper community node).
-
Examples: examples/headless-workpaper (pricing, invoicing, budgeting, fulfillment, subscription, persistence, and agent examples), examples/serverless-workpaper-api (quote approval via Hono, Next.js, and persistence adapters), examples/xlsx-recalculation-node (import, recalculate, exportexport, re-import, and verify an XLSX workbook), examples/recalc-bridge-workflows (bridges for existing SheetJS, xlsx-populate, and ExcelJS workflows).
-
Runtime environment: the public WorkPaper package requires Node.js >=24. Local monorepo development uses Node.js 24+, Bun, and pnpm@10.32.1. Published versions include npm registry signatures and provenance attestations.
IV. Applicable scenarios The material recommends using Bilig for pricing, quote approval, spend, forecasting, validation rules, formula-driven workflows, and tests where a service or tool should own the model. When you need visual editing, collaboration, macros, interactive pivot tables or charts, or desktop-level fidelity, you should choose a spreadsheet application or a hosted spreadsheet API.
V. Limitations Bilig is a headless workbook runtime, not a visual spreadsheet application, and does not claim full Excel compatibility. Formula cached values inside .xlsx are only diagnostic information, not a basis for accuracy. The workbook compatibility and xlsx-cache evaluator use bundled demo workbooks to smoke-test published packages and do not inspect your files; no evaluator should be regarded as proof of desktop Excel consistency. When correctness matters, compare against a workbook recalculated by Excel.
VI. Support and security Adoption and design questions can be raised in Discussions; versioned changes are in GitHub Releases; reproducible bugs are reported through Issues, and simplified workbooks can use the formula bug clinic and fixture form; actionable evidence for reports is in SUPPORT.md; private vulnerability reports are in SECURITY.md. Never attach private workbook data, credentials, or tokens in a public issue.
(Note: The material mentions "commands" and "how to run the evaluator" in several places, but does not provide complete installation commands or code content that can be copied directly, so the relevant descriptions are retained as in the original and no specific commands have been invented.)
