Gnumero

A fast, keyboard-first calculator and developer command palette for GNOME Shell.

Gnumero opens as a compact, Spotlight-style pop-up, evaluates expressions while you type, and copies the result without taking you away from your current task. It combines everyday arithmetic with unit conversion, programmer tools, dates, encodings, colors, networking helpers, and other developer-oriented utilities.

Try Gnumero online · Documentation · GNOME Extensions

The GNOME Extensions link is a temporary placeholder until the project is accepted.

Highlights

• Native GNOME Shell interface built with modern GJS ES modules and St widgets
• Global Super+C shortcut, configurable through GSettings
• Live results with a short debounce and compact, type-aware presentation
• Keyboard-only workflow with result copying and expression history
• Exact integer arithmetic where practical, including large factorials
• Physical quantities with dimension checking and useful automatic conversions
• Programmer tools for bases, bits, bytes, fixed-width integers, and IEEE-754
• UTF-8, hexadecimal, Base64, checksums, and cryptographic hash helpers
• Color parsing, conversion, accessibility calculations, and preview swatches
• Natural date, duration, and percentage expressions
• IPv4 and CIDR calculations
• Fully offline evaluation. Only explicitly random functions are nondeterministic
• Browser-based playground, using the same calculator engine as the extension

Quick examples

Input	Result
6 * 7	42
1 / 137	0.0072992700729927005
-2 ^ 2	-4
20!	2432902008176640000
10% of 450	45
1 km + 500 m	1.5 km
2 * pi * 6371 km	40030.17 km
100 C in F	212 °F
88 mph as km/h	141.6223 km/h
ohm(5 V, 20 mA)	250 ohm
0xCAFEBABE	3405691582
0xFF as int8	-1
hex("GNOME")	47 4E 4F 4D 45
base64("gnumero")	Z251bWVybw==
md5("password")	5f4dcc3b5aa765d61d8327deb882cf99
#eb4034 as hsl	HSL(4°, 82%, 56%)
255.255.255.0 as cidr	/24
today + 45 days	A calendar-aware date

See the complete usage guide for supported syntax, functions, units, keyboard controls, and tested examples. You can also type help in Gnumero and press Enter to open the guide.

Keyboard workflow

Key	Action
Super+C	Open or close Gnumero
Enter	Copy the primary result and close
Ctrl+C	Copy the selected input, or copy the result if nothing is selected
Up / Down	Navigate expression history
Escape	Close without copying

The last 100 successful expressions are stored locally. Consecutive duplicates are ignored. Clipboard contents never persist.

Requirements

• GNOME Shell 50
• GJS
• GLib schema compiler (glib-compile-schemas)
• GNU Make

The extension targets the modern GNOME Shell release used by Ubuntu Desktop 26.04. The calculator engine itself has no GNOME Shell dependencies.

Installation

GNOME Extensions

The public listing is not available yet. Its future location is represented by the temporary GNOME Extensions link.

Install from source

Clone the repository and install the extension into the current user's GNOME Shell extension directory:

git clone git@github.com:chrns/gnumero.git
cd gnumero
make test
make install
gnome-extensions enable gnumero@chrns.com

On a Wayland session, log out and back in after the first installation if GNOME Shell has not discovered the extension yet. During development, reinstalling updated files usually does not require recompiling the calculator engine because it consists of JavaScript ES modules.

The default shortcut can be changed directly through GSettings:

gsettings set org.gnome.shell.extensions.gnumero show-calculator "['<Super>c']"

Browser playground

The project includes a static browser interface that imports the same modules from core/ as the GNOME extension. Run any local static file server from the repository root, for example:

python3 -m http.server 8000

Then open http://localhost:8000/. Changes to the calculator engine are visible after refreshing the page; no extension installation or GNOME Shell restart is required.

Development

Run the complete test suite:

make test

Build the installable extension tree:

make build

Create a submission-ready GNOME Extensions archive:

make pack

Create the ZIP used by GitHub Releases:

make release-zip

Install the current build locally:

make install

To publish a release from a clean working tree, pass a semantic version tag to the release script:

./upload.sh v1.0.0

The script pushes the current branch, then creates and pushes an annotated tag. The tag starts the Ubuntu release workflow, which runs the tests and creates a GitHub Release containing the installable extension ZIP. Pushes to main deploy the browser playground and documentation to GitHub Pages at https://gnumero.chrns.com/.

The test suite currently covers lexer and parser behavior, precedence, typed evaluation, normalization, dates, durations, unit conversion, programmer tools, encodings, colors, networking, history, formatting, error handling, and known regressions.

Project structure

extension.js             GNOME Shell extension lifecycle and keybinding
popup.js                 Popup behavior, focus, history, and clipboard flow
result-view.js           Native type-aware GNOME result presentation
core/
  lexer.js               Tokenization
  parser.js              Expression grammar and AST construction
  evaluator.js           Typed evaluation
  operators.js           Type-directed operator dispatch
  functions.js           Function registry
  conversions.js         Type-directed `as` conversions
  unit-registry.js       Unit definitions and conversion formulas
  result-formatter.js    Display and clipboard presentation
tests/                   GJS unit and regression tests
index.html               Browser playground and GitHub Pages home page
usage.html               English usage documentation

The main architectural approach is:

source -> normalization -> lexer/parser -> typed evaluator -> result formatter -> UI

The GNOME and browser interfaces never evaluate expressions themselves. They only render structured results produced by the shared engine. The engine does not use eval(), Function(), or arbitrary JavaScript execution.

Privacy and safety

• Expressions are evaluated locally.
• No analytics or network-backed calculation services are required.
• Expression history stays in local GNOME settings or browser storage.
• Clipboard contents are not added to history.
• Interactive limits protect GNOME Shell from excessively expensive factorial, shift, hash, prime-search, and base-conversion requests.

License

Copyright © 2026 chrns <alex@chrns.com>.

Gnumero is free software licensed under the GNU General Public License v3.0 or later. You may redistribute and modify it under the terms of GPL-3.0-or-later. The software is provided without any warranty. See COPYING for the complete license text.