Numby

A powerful natural language calculator with both CLI and terminal user interface (TUI). Numby allows you to perform calculations, work with variables, convert between 40+ units across 9 categories, handle currency conversions, calculate percentages, and maintain a history of your computations—all with multi-language support.

Features

Core Capabilities

• Natural Language Calculations: Evaluate mathematical expressions with natural operators like "plus", "times", "divided by"
• Interactive TUI: Split-panel interface with live evaluation and syntax highlighting
• CLI Mode: Evaluate expressions directly from the command line or pipe input
• Variables & History: Store values, reference previous results with prev, sum, average
• File Support: Save and load calculation files (.numby extension) with multi-line expressions
• Clipboard Integration: Copy inputs or results with Ctrl+I / Ctrl+Y

Mathematical Operations

• Basic Arithmetic: +, -, *, /, %, ^ (exponentiation)
• Trigonometry: sin, cos, tan, asin, acos, atan, sinh, cosh, tanh
• Logarithms: log (base 10), ln (natural log)
• Other Functions: sqrt, abs, round, ceil, floor
• Constants: pi (π), e (Euler's number)
• Number Formats: Binary (0b101), octal (0o10), hex (0xFF), scale suffixes (5k, 2M, 3G)

Unit Conversions (40+ Units)

• Length: meter, km, cm, mm, foot, inch, yard, mile, nautical mile, hand, rod, chain, furlong
• Time: seconds, minutes, hours, days, weeks, months, years
• Temperature: Celsius, Fahrenheit, Kelvin (with proper conversion formulas)
• Area: m², hectare, acre
• Volume: liter, ml, m³, pint, quart, gallon, cup, teaspoon, tablespoon
• Mass/Weight: gram, kg, tonne, pound, ounce, stone, carat
• Speed: m/s, km/h, mph, knot
• Angles: degree, radian
• Data: bit, byte
• Energy: joule, calorie

Currency & Financial

• 300+ Currencies: USD, EUR, GBP, JPY, CAD, AUD, CHF, CNY, INR, BTC, ETH, and more
• Auto-Updates: Daily exchange rate updates from free API
• Offline Support: Cached rates work without internet
• Custom Rates: Override rates with --rate EUR:0.92

Percentage Calculations

• 20% of 100 → 20
• 100 + 10% → 110 (adds 10% of 100)
• 200 - 25% → 150 (subtracts 25% of 200)
• Works with currencies: 50% of 200 USD → 100 USD

Multilingual Support (9 Languages)

Available in English, Spanish, French, German, Japanese, Russian, Belarusian, Chinese (Simplified & Traditional). Switch with --locale or :lang command.

Developer Features

• Comments: Use // or # to annotate calculations (grayed out in TUI)
• Syntax Highlighting: Colorized numbers, operators, units, and errors
• Vim-like Commands: :w to save, :q to quit, :lang to switch language
• Configurable: JSON config at ~/.numby/config.json for custom units, rates, and aliases

Installation

Cargo (Recommended)

cargo install numby

Installs from crates.io.

Automated Installer Script

curl -fsSL https://raw.githubusercontent.com/vivy-company/numby/main/install.sh | bash

Automatically detects your OS/architecture and installs the latest release binary.

Download Pre-built Binaries

Download for your platform from GitHub Releases:

• Linux: x86_64, ARM64
• macOS: x86_64 (Intel), ARM64 (Apple Silicon)
• Windows: x86_64, ARM64

Extract and add to your PATH.

macOS App (Paid)

A native macOS app with graphical interface is available on the App Store for $6.

The CLI/TUI version remains free and open-source.

Building from Source

git clone https://github.com/vivy-company/numby.git
cd numby
cargo build --release

Binary available at target/release/numby.

Usage

Interactive TUI Mode (Default)

numby

Launches the split-panel terminal interface with live evaluation.

TUI Keybindings:

• Arrow keys: Navigate cursor
• Home / End: Jump to line start/end
• Enter: Evaluate line and insert newline
• Ctrl+Y: Copy current result to clipboard
• Ctrl+I: Copy current input to clipboard
• :q: Quit | :w: Save | :w <file>: Save as
• :lang <locale>: Switch language | :langs: List languages

CLI Mode (Quick Evaluation)

# Single expression
numby "2 + 3 * 4"

# With units
numby "100 USD in EUR"

# Natural language
numby "5 meters plus 3 feet in inches"

# Percentage
numby "15% of 200"

File Operations

# Open existing file
numby calculations.numby

# Or specify with flag
numby --file my_calculations.numby

Save from TUI with :w or :w filename.numby.

CLI Options

numby [OPTIONS] [EXPRESSION]

Options:
  -f, --file <PATH>        Open file for editing
      --locale <LOCALE>    Set language (en-US, es, fr, de, ja, ru, be, zh-CN, zh-TW)
      --rate <CURR:RATE>   Override currency rate (e.g., EUR:0.92)
      --update-rates       Force update currency rates from API
      --no-update          Skip automatic rate update
  -h, --help              Print help
  -V, --version           Print version

Currency Management

Exchange rates auto-update daily from free API (300+ currencies). Cached rates work offline.

# Force update
numby --update-rates

# Skip auto-update
numby --no-update

# Override specific rate
numby --rate EUR:0.92 --rate GBP:0.85

# Check current rates
numby "1 USD in EUR"

API Source: fawazahmed0/exchange-api (free, no limits)

Examples

Basic Arithmetic

numby "2 + 3 * 4"              # 14
numby "100 / 25"               # 4
numby "2 ^ 8"                  # 256
numby "sqrt(144)"              # 12

Trigonometry & Math Functions

numby "sin(45)"                # 0.85
numby "cos(pi/3)"              # 0.5
numby "log(1000)"              # 3
numby "abs(-42)"               # 42

Variables & History

# In TUI:
x = 100
y = 50
total = x + y                  # 150
prev + 10                      # 160 (uses previous result)
sum                            # Sum of all results
average                        # Average of all results

Unit Conversions

numby "5 meters to feet"       # 16.4 ft
numby "100 km in miles"        # 62.14 mi
numby "32 f to c"              # 0°C (Fahrenheit to Celsius)
numby "2 hours in seconds"     # 7200 s
numby "5 gallons to liters"    # 18.93 L

Currency Conversions

numby "100 USD in EUR"         # ~92 EUR (live rates)
numby "500 GBP to JPY"         # ~95000 JPY
numby "1 BTC in USD"           # Current Bitcoin price
numby "50 ETH to EUR"          # Ethereum conversion

Percentage Operations

numby "20% of 500"             # 100
numby "100 + 15%"              # 115 (adds 15% of 100)
numby "200 - 10%"              # 180 (subtracts 10% of 200)
numby "50% of 80 USD"          # 40 USD

Complex Multi-line Calculations

Create a file budget.numby:

# Monthly budget calculation
income = 5000 USD
rent = 30% of income           # 1500 USD
utilities = 200 USD
food = 500 USD
savings = income - rent - utilities - food
savings in EUR                 # Converted savings

Run: numby budget.numby

Natural Language

numby "5 meters plus 3 feet in inches"
numby "100 divided by 4 times 2"
numby "pi times 10"

Number Formats

numby "0b1010"                 # Binary: 10
numby "0xFF"                   # Hex: 255
numby "5k + 2M"                # 2,005,000
numby "1_000_000 / 2"          # 500,000

Comments

// Budget calculations
income = 4500 USD              # Monthly income
expenses = 3200 USD            // Fixed expenses
savings = income - expenses    # Remaining savings

Comments appear grayed out in TUI.

Multi-language Support

# Spanish
numby --locale es "100 + 50"

# Japanese
numby --locale ja "10 km to miles"

# Chinese
numby --locale zh-CN "50% of 200"

# Switch language in TUI
:lang de                       # Switch to German
:langs                         # List available languages

Supported: English, Spanish, French, German, Japanese, Russian, Belarusian, Chinese (Simplified/Traditional)

Configuration

Numby stores configuration at ~/.numby/config.json. Auto-generated on first run.

Configurable Options:

• Units: Custom unit definitions and conversion factors
• Currencies: Exchange rates (auto-updated from API)
• Currency Symbols: Symbol mappings ($, €, £, ¥, etc.)
• Operator Aliases: Natural language mappings ("plus" → "+")
• Locale: Default language
• Padding: TUI interface spacing

Example config.json:

{
  "locale": "en-US",
  "units": {
    "meter": 1.0,
    "foot": 0.3048,
    "mile": 1609.34
  },
  "currencies": {
    "USD": 1.0,
    "EUR": 0.92
  },
  "operator_aliases": {
    "plus": "+",
    "times": "*",
    "divided by": "/"
  }
}

Edit to add custom units or override defaults.

Development

Running Tests

# All tests
cargo test

# Specific test suites
cargo test --lib
cargo test --test cli_tests
cargo test --test localization_integration

# i18n tests (require single thread)
cargo test --lib i18n -- --test-threads=1

Building

# Development build
cargo build

# Optimized release
cargo build --release

# Platform-specific profiles
cargo build --profile release-cli   # CLI/TUI (with LTO)
cargo build --profile release-lib   # macOS app library

Architecture

Agent-Based Evaluation Pipeline:

1. History Agent: Handles sum, total, avg, prev
2. Variable Agent: Manages variable assignments
3. Percentage Agent: Processes percentage operations
4. Unit Agent: Handles conversions with in/to
5. Math Agent: Fallback for arithmetic expressions

Key Dependencies:

• ratatui - Terminal UI framework
• crossterm - Cross-platform terminal control
• fasteval2 - Expression evaluation engine
• fluent - Localization framework
• ropey - Efficient text buffer
• arboard - Clipboard integration
• serde + serde_json - Configuration serialization

Contributing

Contributions welcome! Please submit a Pull Request.

Areas for contribution:

• Additional unit conversions
• New language translations
• Bug fixes and performance improvements
• Documentation enhancements

License

MIT License - see LICENSE file.

Note: The CLI/TUI version is free and open-source. The macOS App Store version ($6) supports ongoing development.