The spreadsheet that explains itself.
Built by Ocean82 — MIT licensed. Forks and contributions welcome.
Someone sends you a spreadsheet. A budget, an expense report, a financial model. You open it and see a wall of numbers, formulas, and tabs. You don't know what half the cells do. You're afraid to change anything. You can't ask the spreadsheet what it means.
smartsh!t fixes that.
Import any spreadsheet. The app immediately tells you what it's tracking, flags formula errors, highlights unusual values, and answers questions about your specific data — in plain English.
| Feature | How It Helps |
|---|---|
| Auto-Insights | Import a file → instantly see key totals, structure, and what looks unusual |
| Formula Auditor | Catches broken references, skipped cells in SUMs, inconsistent formulas, and outliers |
| Natural Language Q&A | "Where am I overspending?" "What does this formula do?" "Is this number correct?" |
| Instant Actions | "Bold the headers" "Sort by amount" "Add a row" — no formulas needed |
| Templates | 50+ built-in templates for budgets, invoices, trackers, and more |
Import a budget → the auditor flags a formula that skips a cell → the AI explains what your spreadsheet is tracking and where the risk is.
| Tool | Version |
|---|---|
| Node.js | 22+ |
| Ollama | latest (optional — cloud AI works too) |
git clone https://github.com/Ocean82/smartshit.git
cd smartshit
npm install
npm install --prefix serverOption A — Local (Ollama, free, private):
npm run model:setup # dev model: Qwen2.5-Coder-1.5B (fast, lower quality)Production uses Spreadsheet-RL-4B (a 4B instruct model trained for spreadsheet tool-use). See
server/Modelfile.spreadsheet-rlfor the production Modelfile.
Option B — Cloud (faster, no GPU needed):
Copy .env.example to .env in server/ and add one API key:
GROQ_API_KEY=your-key-here
Groq is the primary cloud provider (fast inference via
qwen/qwen3.6-27b). OpenRouter and HuggingFace are supported as failover. See.env.examplefor all options.
# Terminal 1 — API server
npm run dev:server
# Terminal 2 — Web UI
npm run dev- Import any
.xlsxor.csvfile (a budget, expense report, anything) - Read the auto-insights summary
- Check the auditor findings
- Ask: "Explain this spreadsheet" or "What's my biggest expense?"
┌─────────────────────┐ ┌──────────────────┐
│ React + Vite │ SSE │ Express server │
│ Formualizer │◄──────►│ Pipeline Router │
│ Zustand store │ │ LLM failover │
│ Auditor engine │ │ (port 8787) │
└─────────────────────┘ └────────┬─────────┘
│
┌────────┴─────────┐
│ Groq / OpenRouter│
│ OR Ollama (4B) │
└──────────────────┘
| Layer | Tech |
|---|---|
| Frontend | React 19, Vite 7, Tailwind CSS 4, Zustand, Formualizer |
| Backend | Express 5, TypeScript, SSE streaming, PipelineRouter |
| AI | Groq (primary) / OpenRouter / Hugging Face / Ollama (fallback) / BYOK |
| Auditor | TypeScript-native, runs in-browser against Formualizer |
| Sandbox | QuickJS WASM — isolated script execution with allowlisted API |
| I/O | SheetJS (xlsx) for Excel import/export |
A rule-based engine that scans your spreadsheet for real problems:
- Error cells — #REF!, #VALUE!, #DIV/0!
- Range gaps — a SUM that skips an adjacent cell (the silent accounting error)
- Inconsistent formulas — one formula breaks the pattern in a column
- Magic numbers — constants buried inside formulas instead of in input cells
- Outliers — values that are statistically far from their column average
- Circular references — formulas that depend on themselves
Common operations are handled instantly on-device — no LLM round-trip, no latency. A local regex parser covers sorting, formatting (bold headers, highlight rules, font colour), setting a cell, adding a row of values, deleting a row, find & replace, and percentage tweaks; totals and group-bys ("sum column B", "spending by category") are matched locally by the goal router. Anything the parser can't resolve — including complex or open-ended questions — routes to the AI. Questions and hypotheticals ("Can I delete this?", "Should I add a total row?") are never treated as commands — they pass to the LLM for proper clarification.
Deterministic analysis (budget breakdowns, outlier detection, auditor findings) runs locally in the browser. Only open-ended questions or complex requests go to an LLM. This means most of the app works without any AI backend at all.
Copy .env.example to .env in the server/ directory. The common variables
are below; server/.env.example and docs/ENV.md are the
authoritative, complete list — the table here is a starter subset. Auth,
billing, and cloud-sync variables are only needed to run a hosted, account-gated
instance (see "Running locally" above to run without them).
| Variable | Default | Description |
|---|---|---|
PORT |
8787 |
API port |
TRUST_PROXY |
loopback |
Express trust-proxy setting (real client IP behind nginx) |
OLLAMA_BASE_URL |
http://127.0.0.1:11434 |
Ollama endpoint |
SMARTSHIT_MODEL |
smartshit |
Ollama model name (prod: Spreadsheet-RL-4B) |
NUM_CTX |
8192 |
Context window size |
NUM_PREDICT |
1024 |
Max tokens per response |
GROQ_API_KEY |
— | Primary cloud provider (fast inference) |
GROQ_MODEL |
qwen/qwen3.6-27b |
Groq model identifier |
OPENROUTER_API_KEY |
— | Failover cloud provider |
HUGGINGFACE_API_KEY |
— | Failover cloud provider |
LLM_PROVIDER_ORDER |
groq,openrouter,ollama |
Failover order |
FREE_DAILY_LIMIT |
7 |
Free-tier AI requests per day per user |
FREE_CLOUD_WORKBOOK_LIMIT |
1 |
Max cloud workbooks for free users (must match client) |
WORKBOOK_BODY_LIMIT |
25mb |
Max request body for workbook save routes |
MAX_WORKBOOK_VERSIONS |
50 |
Version-history entries retained per workbook |
CLERK_SECRET_KEY |
— | Clerk auth (hosted instance only; blank = open/no-login) |
CLERK_PUBLISHABLE_KEY |
— | Clerk publishable key (hosted instance only) |
STRIPE_SECRET_KEY |
— | Stripe billing (hosted instance only) |
STRIPE_PRICE_ID / STRIPE_PRICE_ID_ANNUAL |
— | Pro plan price IDs (required for checkout) |
STRIPE_WEBHOOK_SECRET |
— | Stripe webhook signature verification |
DATABASE_URL |
— | Postgres for cloud save / sharing / usage (blank = disabled) |
S3_BUCKET / S3_REGION / S3_SMARTSHT_PREFIX |
— | S3 storage for version history |
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY |
— | AWS credentials for S3 |
smartsh!t runs fully without any login. Leave VITE_CLERK_PUBLISHABLE_KEY blank and the app starts in open mode — no sign-in wall, unlimited local usage, and no upgrade prompts. This is the default for a fresh clone.
The pk_live_... / sk_live_... values in .env.example are placeholders for the hosted deployment at smartsht.com; you do not need them to run or develop locally. Clerk (auth), Stripe (billing), and the RDS/S3 cloud-sync layer are only required if you want to run your own hosted, account-gated instance:
- Auth — set
VITE_CLERK_PUBLISHABLE_KEY+CLERK_SECRET_KEYfrom your own Clerk app. Publishable keys are domain-locked, so the project's keys won't authenticate from another origin. - Billing — set the
STRIPE_*variables from your own Stripe account. - Cloud save / sharing — set
DATABASE_URL+ theS3_*/AWS_*variables.
Everything else (the editor, auditor, intent parser, and — with a GROQ_API_KEY or a local Ollama model — the AI) works with none of the above.
See CONTRIBUTING.md for setup and PR guidelines.
Areas where help is welcome:
- Auditor rules (new error patterns to detect)
- Intent parser patterns (more instant-response phrases)
- Accessibility improvements
- Import format support (Google Sheets export, Numbers)
- Documentation and tutorials
See docs/project_outline/roadmap-v1.md for the full plan.
Shipped since v1 planning: auto-insights on import, auditor auto-run with a findings panel, and the cell inspector (precedents/dependents + plain-English formula explanation).
Next up (guided navigation):
- Smart search — find things by description, not cell reference ("where are the expenses?")
- Section detection — auto-outline of a sheet (income / expenses / totals) with click-to-navigate
- Contextual suggestions on selection (sum/average/outliers for a selected range)
- Selection-aware chat — "explain this" without asking "explain what?"
MIT License — Copyright (c) 2026 Ocean82.
Note: the formula engine uses @ocean8219/formualizer, a permissively-licensed fork. The earlier GPLv3 licensing conflict with HyperFormula no longer applies.
See LICENSE. Free to use, modify, and distribute with attribution.
If smartsh!t saves you from spreadsheet confusion, consider sponsoring:
Topics: spreadsheet · ai · formula-auditor · budget · react · typescript · formualizer · open-source · self-hosted