Bilig: Headless Spreadsheet Engine for Node.js Agents

What changed

Bilig has been released as a headless WorkPaper runtime designed for Node.js services, tests, and AI agents. It provides a TypeScript-native environment that allows developers to manage spreadsheet-like data structures, formulas, and calculations programmatically. Key capabilities include setting inputs, recalculating formulas, reading computed outputs, persisting WorkPaper data to JSON, restoring it, and verifying the results, all without requiring a visual spreadsheet application like Excel or a browser-based grid.

The project emphasizes a "workbook-shaped model" where developers can utilize sheets, A1 addresses, formulas, ranges, and named expressions. It offers "verified mutations," providing before/after computed values along with persistence and restore checks to ensure data integrity. Bilig also facilitates "service-owned state," allowing for portable WorkPaper JSON that can be used across different services, queues, tests, and for audit trails. Furthermore, it provides "agent-safe tools" with narrow read/write capabilities, focusing on specific cells, computed readback, and defined writable sheet boundaries. The runtime also maintains "explicit file boundaries," separating concerns like XLSX import, export, risk inspection, and Excel-oracle workflows.

Key Features and APIs

• TypeScript API: Developers can install @bilig/workpaper and use functions like buildA1WorkPaper to create workbook models. The API supports editing cells (editAndReadback), reading back values, and managing the workbook lifecycle.
• Headless Operation: Bilig operates without a graphical user interface, making it suitable for server-side applications and AI agents.
• Formula Recalculation: It can process standard spreadsheet formulas, recalculating outputs based on input changes.
• Persistence: WorkPaper data can be saved to and restored from JSON files, enabling state management.
• Verification: The engine includes verification steps to ensure that data written, recalculated, exported, and restored remains consistent.
• Agent Integration: Bilig supports integration with AI agents through a Model Context Protocol (MCP) server, allowing agents to discover and utilize spreadsheet functionalities as tools.

Command-Line Interface

Bilig also offers CLI commands for evaluation and agent interaction:

• bilig-evaluate: Used to test the engine's functionality, such as editing a cell, recalculating, saving, restoring, and verifying the output. The output includes a verified: true status.
• bilig-agent-start: Initiates an agent MCP server.
• bilig-workpaper-mcp: Runs a local MCP server for a writable WorkPaper.

XLSX and Excel Compatibility

Bilig can import and export .xlsx files, but it clarifies that cached formula values within these files are for diagnostics and not an accuracy oracle. The project provides tools like workbook-compatibility-report and xlsx-cache-doctor for inspecting XLSX files, but these do not guarantee full parity with desktop Excel functionality. Developers needing visual editing, collaboration, macros, or interactive pivots should opt for a spreadsheet application.

Why it matters for builders

Bilig offers AI builders a robust, programmatic way to embed spreadsheet functionality directly into their applications and agent frameworks. This eliminates the need for complex workarounds or external services to handle calculations, data validation, or financial modeling within AI-driven workflows. By providing a headless engine, Bilig ensures that these spreadsheet capabilities can run autonomously in server environments or as part of agent toolkits.

Practical impact

Builders can leverage Bilig to automate tasks that traditionally required manual spreadsheet manipulation. For instance, AI agents can use Bilig to perform real-time pricing calculations, process quote approvals, manage payout logic, or execute formula-backed validation rules. The TypeScript API allows for seamless integration into existing Node.js projects, while the MCP server support enables agents to discover and invoke these spreadsheet functions as tools. Developers can explore examples provided in the repository, such as headless workpaper implementations for pricing and subscription models, or serverless API integrations for quote approvals.

Caveats and source limits

The source material indicates that Bilig is not a full Excel compatibility solution. While it can import and export .xlsx files, it explicitly states that cached formula values within these files are diagnostic and not an accuracy oracle. Developers should be aware that complex Excel features, macros, or specific formula behaviors might not be replicated. The project's focus is on providing a headless runtime for programmatic spreadsheet operations, particularly for AI agents and Node.js services, rather than a direct replacement for the desktop Excel application. Specific performance benchmarks or detailed comparisons against other headless spreadsheet engines are not provided in the source. The latest release mentioned is libraries-v0.163.0.