PSU3D0/agent-spreadsheet

agent-spreadsheet is the tool interaction service for agent-based spreadsheet usage.
It gives agents a safe, inspectable, token-efficient way to read, analyze, mutate, verify, and operationalize Excel workbooks without falling back to brittle UI automation.
If you want an agent to work with spreadsheets like a real system instead of a screenshot puppet, this is the stack.
## What this project is
agent-spreadsheet ships a unified spreadsheet interaction layer across three surfaces:
| Surface | Binary / Package | Mode | Best for |
| CLI | agent-spreadsheet / asp | Stateless files + resident sessions | One-shot pipelines or retained multi-turn workbook editing |
| MCP server | agent-spreadsheet-mcp | Stateful | Multi-turn agent sessions, workbook caching, fork/recalc workflows |
| TypeScript SDK | agent-spreadsheet-sdk | Library | App integrations — drives the server's canonical /v1 route, or runs fully in-process via the embedded WASM engine (no server required) |
The WASM build (agent-spreadsheet-wasm) is the SDK's local runtime, not a separate product surface: JS and TypeScript code targets one object model and the execution substrate (server vs embedded engine) is a configuration choice.
In 0.16 these surfaces share the resident Rust document/evaluator runtime and 32-operation registry. Explicit native sessions automatically start a private journal-backed host. SDK/WASM and genuine just-bash sessions retain their history in memory; XLSX export saves a document snapshot, not a restartable session journal. Warm edit/recalculate/read loops avoid XLSX serialization and repeated evaluator ingestion. See runtime guarantees and limits and the SDK/just-bash examples.
Supported workbook modes:
.xlsx / .xlsm — read + write
.xls / .xlsb — discovery/read-oriented workflows only
## Powered by Formualizer
Default in-process calculation uses Formualizer — a permissively licensed (MIT/Apache-2.0) spreadsheet engine written in Rust: formula parsing, dependency-graph recalculation, 400+ Excel functions, dynamic arrays, and deterministic evaluation built for agents. No Excel COM or headless LibreOffice is required. Optional LibreOffice integration remains available, but Formualizer is the release-critical backend.
That native engine is why this project can offer what most spreadsheet tooling for agents cannot: recalculate the actual workbook, trace which cells changed and why, and prove it — not just read cached values or push blind edits.
Embedding spreadsheet logic in your own product rather than driving workbooks as an agent? Use Formualizer directly (Rust, Python, JS/WASM).
## Why agents use agent-spreadsheet
### Built for tool use, not just humans
deterministic JSON contracts
schema and example discovery from the CLI itself
explicit pagination and compact output modes
machine-readable warnings and error envelopes
### Safe mutation, not blind mutation
dry-run first workflows
stateless output modes and overwrite safety
event-sourced session editing
verification surfaces for proving downstream outcomes
structural impact analysis before risky workbook changes
### Spreadsheet-aware, not generic file editing
region detection