The InkCalc guide

01Introduction #

InkCalc is a calculation note. Unlike a single-shot scratchpad, it stores notes in folders of .inkcalc files so you can return to the same household budget, mortgage scenario, or trip estimate over time.

• One expression per line. Newlines separate statements. Empty lines and comments don't affect results.
• Results appear on the right. The overlay is read-only — copying the source never picks up the results.
• Plain text files. Notes live on disk as .inkcalc files you can open in Finder.
• AI is opt-in. AI features only run when you trigger them. Turn them off in Settings and the app makes zero outbound calls.

02Quick start #

Type these four lines into a fresh note. Results appear instantly to the right.

# Monthly comms
mobile = 85
internet = 65
mobile + internet         # → 150
(mobile + internet) * 12  # → 1,800

Lines starting with # or // are comments. x = ... declares a variable that you can reuse below. That alone turns a calculator into a re-runnable note.

The five-second workflow

1. Click ＋ at the bottom of the sidebar to add a note.
2. Type one expression per line. Enter advances.
3. Read results on the right. Errors turn the row red.
4. Need help? ⌘⇧I writes the expression, ⌘⇧F fixes the error, ⌘⇧M summarizes, ⌘⇧J infers intent.

03Basics: notes & math side by side #

In InkCalc, each line is an independent expression. Every newline triggers re-evaluation, and the result lands in the right gutter. Blank lines and comments are kept for prose; they don't compute (but line numbers stay stable).

Three kinds of line

• Expression: 1 + 2, 30km in mi. Result on the right.
• Assignment: x = 5. Stores the value for later lines.
• Comment: starts with # or //. Pure prose.

The right gutter

Results are rendered as a subtle overlay, so the file stays readable. Copying the text gives you the source you wrote — nothing more.

04Numbers, bases & bit ops #

Base literals

Hex, binary, and octal literals are first-class. Mixed-base expressions are evaluated normally; you can choose the display base later.

Bitwise operators

Base display

Convert the display base with in hex / in binary / in dec.

255 in hex          # → 0xff
10 in binary        # → 0b1010
0xff in dec         # → 255
0b1101 in hex       # → 0xd

05Operators & precedence #

Precedence matches standard math, with natural-language keywords layered on top. From lowest to highest:

Full-width × / ÷ and the Unicode minus − (U+2212) are accepted everywhere the ASCII forms are, so non-Latin input methods don't trip you up.

06Units #

Attach a unit and the value becomes a quantity. Quantities in the same category convert automatically.

Conversion keywords

in, to, and as are interchangeable. Use whichever reads best.

5 km in miles        # → 3.107 mi
1 kg as lb           # → 2.2046 lb
2 GB to MB           # → 2,000 MB
100 C in F           # → 212 °F
30 min + 45 s        # → 30.75 min

07Currency #

Currency works like any other unit. Exchange rates are fetched on launch and refreshed periodically, so conversions are live.

Supported currencies

Symbols & prefixes

$ € ¥ £ ₩ ₹ can be used inline. $200 means 200 USD.

100 USD in JPY            # rate-dependent
$50 + €30 in JPY          # cross-currency, normalized then summed
1500 JPY as USD           # → ~9.85 USD
sum(100 USD, 50 EUR) in JPY

08Percent #

The % postfix becomes a ratio at evaluation time, but it behaves intuitively: adds and subtracts as a delta, multiplies as a fraction. That lets you write tax and discount math in plain language.

09Dates & time #

Literals

ISO dates (YYYY-MM-DD) plus English keywords.

Arithmetic

You can add or subtract a time quantity (days, weeks, year, …) to/from a date. Subtracting two dates yields a quantity in days.

2025-04-25 + 7 days       # → 2025-05-02
today + 30 days           # 30 days from today
2025-05-02 - 2025-04-25   # → 7 days
tomorrow - today          # → 1 day

10Functions & constants #

Constants

Functions

sqrt(2)               # → 1.4142
sin(pi / 2)           # → 1
log(1000)             # → 3
avg(85, 92, 78, 90)   # → 86.25

Functions also apply to quantities (except units with offsets, like temperature). For example, round(1.7 kg) → 2 kg.

11Line refs & aggregates #

Reference other lines and your note becomes a lightweight spreadsheet.

Single refs

• ans — result of the previous line.
• line1, line2, … — result of the given line number.

Range aggregates

"Aggregate every line above this one." Blank lines, comments, and the previous aggregate row are skipped automatically.

100 + 200           # → 300
ans * 1.1           # → 330
500                 # → 500
sum above           # → 1,130
avg above           # → 376.7

12Variables & comments #

name = expression declares a variable. Re-assign at any point and lines below pick up the new value.

tax = 10%
price = 1980
price + price * tax     # → 2,178

# Update the rate and the totals re-flow.
tax = 8%
price + price * tax     # → 2,138.4

Comments

Anything after # or // on a line is a comment. Pairs especially well with intent inference (⌘⇧J) — a question-mark comment expands into a real expression.

# Total monthly comms?   ← ⌘⇧J asks AI to fill in below
mobile + internet        # AI inserts this row

13AI shortcuts #

InkCalc ships four AI shortcuts, all opt-in. Each sends only the minimum context required and runs only when you trigger it.

⌘⇧I — Natural language → expression

Type plain language on a row and press ⌘⇧I. A sheet opens with the AI-built expression; Replace swaps it in, or close to keep your original.

⌘⇧F — Fix the error

If a row goes red (e.g. (1 + 2 * 3), hit ⌘⇧F. AI proposes a corrected line with a side-by-side diff so you can apply with one click.

⌘⇧M — Summarize the note

Useful when notes get long. AI reads the source and computed results, then produces a sentence or three you can paste into a doc, chat, or daily log.

⌘⇧J — Infer intent

Write a question comment like # Total monthly comms? and press ⌘⇧J. AI scans the note, picks the relevant rows, and inserts an aggregating expression right under the question. You don't write the formula — the note answers itself.

14Choosing an AI backend #

Three backends are available in Settings → AI. API keys are stored in the macOS Keychain.

15Workspace & iCloud #

Notes are stored as .inkcalc files under a workspace folder you choose. Local or iCloud Drive — both are fine.

First-time setup

1. Open the sidebar folder picker → "Open workspace…".
2. Pick any folder via the macOS open panel.
3. Use ＋ at the bottom of the sidebar to add notes inside it.

iCloud Drive sync

Point the workspace at an iCloud Drive folder and your notes follow you across Macs. InkCalc uses NSFileCoordinator + NSFilePresenter for safe concurrent writes and external-edit detection.

16Menu bar / Dock / Always-on-top #

InkCalc is designed for resident use too. Choose how it sits in the system:

• Menu bar: small status-bar icon; click to toggle the window.
• Dock icon: hide it for menu-bar-only mode.
• Always-on-top: keep the window over other apps — useful when calculating alongside a video or reference doc.

Status-bar icons

The bottom-right status bar shows three icons that map to AI shortcuts:

17Export #

From the status bar you can export as Markdown or CSV. Markdown is great for reports, CSV for downstream spreadsheets.

Markdown

# Monthly comms

```
mobile = 85              # 85
internet = 65            # 65
mobile + internet        # 150
(mobile + internet) * 12 # 1800
```

CSV

line,expression,result
1,"mobile = 85",85
2,"internet = 65",65
3,"mobile + internet",150
4,"(mobile + internet) * 12",1800

18Settings #

Open with InkCalc → Settings… or ⌘,.

Display

• Language: English / Japanese / system. Switches without restart.
• Font size: editor body size.
• Decimal places: precision of the result overlay.
• Theme: dark (additional themes planned).

Window

• Menu-bar mode
• Dock icon visibility
• Always-on-top

AI

• Backend: Apple Intelligence / Claude / OpenAI.
• API key: Keychain (Claude / OpenAI only).
• Enable AI: turn it off and the shortcuts make zero outbound calls.

19Subscription #

InkCalc is delivered as a subscription covering reliable FX rates, AI features, iCloud sync, and ongoing updates.

Buying

1. The paywall appears on first launch or from Settings → Subscription.
2. Pick "Start free trial" (if eligible) or "Subscribe".
3. Confirm with your Apple ID via the StoreKit sheet.

Managing & cancelling

Use App Store → Subscriptions to manage or cancel at any time. Features stay enabled until the period ends, then the paywall takes over automatically.

Restoring

After reinstalling or migrating, tap Restore purchases on the paywall to reload your Apple ID's entitlement.

20Keyboard reference #

21FAQ #