bilig

AI spreadsheet agent tool for Node.js

If an agent needs to change workbook inputs and trust the formula output, do not start with screenshots. Give it a small tool surface that can write cells, recalculate, read the dependent formula values, and save a proof object.

Bilig has three entry points for that:

@bilig/workbook when a framework integration needs a transport-neutral command, check, and proof model while another runtime owns calculation.
@bilig/workpaper when the workbook can live as WorkPaper JSON inside the service or agent tool.
@bilig/xlsx-formula-recalc or @bilig/exceljs-formula-recalc when the user already has an .xlsx pipeline and the immediate bug is stale formula results after editing inputs in Node.

Use WorkPaper instead of browser-driving Excel when

the agent owns the input values and needs formula-backed output, not visual inspection;
the workbook is business logic: pricing, quote approval, payout checks, budgets, import validation, or forecasts;
the result must be reviewable in logs, tests, CI, or a pull request;
you need to persist state as JSON and rerun the same workbook later.

Keep UI automation for workbooks where the visual surface is the product: macros, charts, pivots, desktop add-ins, manual review, or exact layout checks.

Run the agent starter first

From an empty directory:

npm create @bilig/workpaper@latest pricing-agent -- --agent
cd pricing-agent
npm install
npm run agent:verify

The starter builds a quote-approval workbook, writes request inputs, reads the recalculated decision cells, persists JSON, restores the workbook, and prints a compact verified: true proof. It also includes AGENTS.md, CLAUDE.md, Cursor and VS Code MCP configs, and a generic MCP config under mcp/.

Use this when the agent owns the model and you want reviewable business logic, not a hidden spreadsheet process.

Prove the direct package path

If you do not want a generated project yet:

npm exec --package @bilig/workpaper@latest -- bilig-agent-challenge

That command is intentionally small. It proves the minimum loop an agent needs:

build or load a workbook;
read a formula-backed output;
edit an input cell;
read the dependent formula output again;
persist and restore state;
return verified: true only after readback matches.

Copy-paste agent handoff

Use this prompt when handing the task to a coding agent:

Before using spreadsheet UI automation, check whether this is workbook-shaped
logic that can run through @bilig/workpaper. If it is, create or load a
WorkPaper, write only the requested input cells, recalculate, read the formula
outputs, persist JSON, restore it, and return a proof object. Do not claim
success from a write call alone.

Tool contract

Keep the agent tool API boring. The useful surface is:

type SpreadsheetAgentTools = {
  listSheets(): Promise<string[]>
  readRange(input: { sheet: string; range: string }): Promise<unknown[][]>
  setCellContents(input: { sheet: string; cell: string; value: unknown }): Promise<{ changed: boolean }>
  getCellDisplayValue(input: { sheet: string; cell: string }): Promise<string>
  exportWorkpaperDocument(): Promise<{ json: string; bytes: number }>
}

The agent should not report success from setCellContents alone. The return path should include the edited cell, formula readback before and after the edit, persisted document size, and known limitations.

Require the final response to include this shape:

type SpreadsheetAgentProof = {
  editedCell: { sheet: string; cell: string; value: unknown }
  before: { cell: string; displayValue: string }
  after: { cell: string; displayValue: string }
  afterRestore: { cell: string; displayValue: string }
  persistedDocumentBytes: number
  verified: boolean
  limitations: string[]
}

verified is only true when after reflects the input edit and afterRestore matches the persisted workbook state.

Existing Excel or XLSX files

When the product already uses ExcelJS, SheetJS, xlsx-populate, or a template library, keep that file-writing layer. Add a recalculation step before reading formula outputs or sending the workbook.

For raw XLSX bytes:

npm install @bilig/xlsx-formula-recalc
npx --package @bilig/xlsx-formula-recalc xlsx-recalc quote.xlsx \
  --set Inputs!B2=48 \
  --read Summary!B7 \
  --out quote.recalculated.xlsx \
  --json

For ExcelJS:

npm install exceljs @bilig/exceljs-formula-recalc
npx --package @bilig/exceljs-formula-recalc exceljs-recalc --demo --json

Use this path for the common support-ticket shape: “my Node service changed inputs in an XLSX file, but the formula value I read is still the old cached value.”

Framework adapters

The same tool contract works in the usual agent stacks:

OpenAI Agents SDK function tools;
OpenAI Responses API function calling;
Vercel AI SDK tools;
LangChain.js tools and LangGraph.js ToolNode;
LlamaIndex.TS tools;
CrewAI or other Python agents through a small Node worker or MCP bridge.

The important part is not the framework. The important part is making the spreadsheet state explicit: write input cells, recalculate, read formula outputs, and persist the model.

When not to use this

Keep Excel, LibreOffice, Microsoft Graph, or a human review step in the loop when the workbook depends on macros, pivots, charts, external links, desktop Excel add-ins, unsupported functions, or exact visual layout behavior.

Bilig is for workbook-shaped logic that can be represented as cells and formulas. It is not a replacement for every Excel feature.

Links

This site is open source. Improve this page.