GitHub - rawbytess/hissab: Calculator for Humans and AI Agents

What is Hissab?

Hissab is built around a small expression language that reads like everyday math. You can write plain arithmetic, unit conversions, dates, statistics, probability, finance, health and fitness metrics, IP subnet math, symbolic algebra, complex numbers, coordinate-system geometry, shape area and volume, matrix algebra, colors, bitwise operations, graphing with draw/plot, random numbers / UUIDs / nanoids, text hashing (SHA, MD5, CRC32), and multi-line calculations with named labels.

15 kilometers to miles
240 - 15%
variance(45, 56, 67, 78, 89)
today - 15 jun 1995 to years
network(192.168.1.130/24)
derivative(2x^2 + 3x, x)
monthly_savings = 4500 - 1200 - 600
monthly_savings monthly to yearly

Unlike an LLM, Hissab does not try to infer a result from text. The app and agent integrations translate intent into Hissab expressions, then the engine parses and evaluates those expressions.

Why Hissab?

• Exactness — Hissab parses and evaluates expressions deterministically. It does not silently drop unknown words or ask a model to do arithmetic from memory.
• Breadth — everyday, business, developer, STEM, and agentic calculations share one expression language.
• Auditability — every answer comes from a short, visible expression you can edit, re-run, copy, or put in a script.
• Portability — the same engine runs in the app, CLI, TypeScript library, and agent skills.
• AI leverage — AI can translate messy language and explain the result while Hissab remains the deterministic calculator.

Who is it for?

• Calculator power users who need quick mixed-domain math without turning every question into a spreadsheet or script.
• Developers and sysadmins who need units, dates, IP/CIDR math, bitwise operations, base conversion, hashing, matrices, CLI workflows, or npm embedding.
• Students, teachers, and tutors who want readable calculation notebooks with inline results, graphing, symbolic algebra, geometry, statistics, and probability.
• AI users and agent builders who want models to call a deterministic math engine instead of guessing.
• Product developers who need an embeddable TypeScript expression evaluator with units, types, formatting, and documentation.

Features

Hissab currently supports these operation categories:

The canonical operation docs live in lib/documentation.

Basic Syntax

Write one expression per line.

14 + 88 / 11 * 23.56 - 17

Use natural unit conversion syntax.

15 kilometers to miles
25 celsius to fahrenheit
13 kilograms + 12 pounds

Use parentheses to make grouping explicit.

Call functions with comma-separated arguments.

avg(99, 34, 65, 213, 45, 123)
max(10m, 30k, 7.7m, 123123121234)
lcm(12, 15, 18, 25)

Assign labels with = and reuse them later in the same batch.

monthly_savings = 4500 - 1200 - 600
yearly_savings = monthly_savings monthly to yearly

Use prev for the immediately previous result.

78 kilometers to miles
prev - 45 miles

Important syntax notes:

• Dates use formats such as 2020.08.07, 07 aug 2020, or 2020 aug 07. Dashes and slashes are arithmetic operators.
• m means million, not meter. Use meter in compound units.
• Currency conversion is not built in because exchange rates change. Fetch or provide a rate first, then calculate with the literal value.

Using the App

Use the web app at hissab.io. It can be installed as a PWA on desktop and mobile browsers, and the same app is packaged as a Chrome extension.

The app provides:

• A notebook-style editor for expressions and multi-line calculations.
• Inline results while writing.
• Syntax highlighting for Hissab expressions.
• Local notebook/file storage in the browser.
• A documentation UI backed by the same docs used by the CLI and agent tools.

Core calculations run locally in the app shell. Notebooks, provider settings, MCP servers, and skills are stored in the browser profile. AI calls, model refreshes, realtime search, and remote MCP servers require network access.

AI Chat Features

Hissab includes an agentic math workflow for AI-assisted calculation. The AI does the language work, while Hissab does the deterministic math.

AI features include:

• Inline AI prompts for quick answers.
• Chat for multi-step math questions.
• Tool-backed calculation through the Hissab engine.
• Documentation retrieval before writing unfamiliar expression types.
• Name lookup for units and functions.
• File and image attachments in chat.
• Multilingual questions and answers.
• Realtime lookup hooks for current data such as exchange rates, stocks, crypto, weather, and news before calculating.
• Provider support for OpenAI, Anthropic, Gemini, DeepSeek, and custom OpenAI-compatible endpoints.

CLI

The CLI wraps the Hissab engine for terminal use. Install it from npm (requires Node ≥ 18):

npm install -g @rawbytes/hissab-cli
hissab eval "15 kilometers to miles"

Available commands:

hissab eval "<expr>"        # one-shot evaluation
hissab repl                 # interactive REPL
hissab run <file>           # one expression per line, shared variable scope
hissab list <kind>          # kind = functions | units | operators
hissab docs [tag]           # base docs or a specific docs chunk
hissab docs --list          # list documentation tags
hissab docs --all           # full docs dump for large-context LLMs

Use hissab docs --all when an LLM has enough context to ingest the full reference at once. For smaller contexts, use hissab docs --list and fetch only the needed tag chunks.

Running from source

From the repo root:

pnpm install
pnpm --filter ./cli dev eval "15 kilometers to miles"
pnpm --filter ./cli dev repl

pnpm --filter ./cli build produces the published, self-contained Node bundle in cli/dist/. To build the optional standalone per-platform binaries with Bun instead, run pnpm --filter ./cli build:bin (output in cli/bin/hissab-<platform>-<arch>).

Agent Skills

Hissab ships an agent skill that teaches AI agents to offload math to the engine instead of doing mental math:

Install with Vercel's Skills CLI — it works across Claude Code, Codex, Gemini, Cursor, and more (-a accepts claude-code, codex, …):

npx skills add rawbytess/hissab --skill hissab-cli
npx skills add rawbytess/hissab --skill hissab-cli -g -a claude-code

Or install it as a Claude Code plugin from the bundled marketplace:

/plugin marketplace add rawbytess/hissab
/plugin install hissab@rawbytes

See skills/README.md for OpenAI Codex and manual install paths.

Engine Library

Install the calculation engine from npm:

npm install @rawbytes/hissab

Use calculate for the simple path:

import { calculate } from "@rawbytes/hissab";

const result = await calculate("15 kilometers to miles");

console.log(result.result); // "9.3206 miles"
console.log(result.resultToken);

Use doLex and doParse when you need lower-level access to tokens or shared variables across several expressions:

import {
  doLex,
  doParse,
  type Variables,
} from "@rawbytes/hissab";

const variables: Variables = {};

const assignment = await doParse(doLex("distance = 15 km", variables, 1));
variables[assignment.meta.variableName] = assignment.resultToken;

const converted = await doParse(doLex("distance to miles", variables, 2));
console.log(converted.result);

Catch user-facing expression errors with UserError:

import { calculate, UserError } from "@rawbytes/hissab";

try {
  await calculate("10 meter to kilogram");
} catch (error) {
  if (error instanceof UserError) {
    console.error(error.message);
  }
}

The root export also includes Functions, Operators, Units, the symbolic and geometric token classes (ExprToken, SymbolToken, ComplexToken, PointToken, MatrixToken, PlotToken), exprToLatex for structured symbolic rendering, and the sampling helpers evalExpr / freeSymbols used to plot draw/plot curves — for consumers that need autocomplete catalogs or graphing.

Limits

Hissab is a practical calculation language, not a replacement for every quantitative tool.

• It does not fetch live currency or FX rates in the local engine. Provide a rate, or use an AI/realtime lookup flow before calculating.
• It does not solve equations yet. It does support symbolic simplification, expansion, derivatives, integrals, and limits.
• It does not replace Python, Jupyter, R, or Julia for datasets, ML, simulations, custom algorithms, or general programming.
• It does not replace spreadsheets for large tabular models and recurring business workflows.
• It does not replace full CAS systems such as Mathematica.

Development

This is a pnpm workspace.

pnpm install
pnpm -r build
pnpm -r test
pnpm check

Useful package commands:

pnpm --filter ./app dev
pnpm --filter ./cli dev eval "5 km to miles"
pnpm -F @rawbytes/hissab test

Before opening a PR, run:

License

MIT © Mufaddal Makati