Define custom formulas with GridOS macros

Create reusable named formulas in GridOS by asking the AI to propose a macro — then approve it and call it from any cell in your workbook.

Macros let you define named formulas composed from GridOS’s built-in primitives. Once approved, a macro works exactly like a built-in function — you call it from any cell with =MACRONAME(arg1, arg2). They’re useful when the same ratio or calculation pattern appears in many rows of a model and you want to keep the cell formulas clean.

How macros work

GridOS macros are pure, deterministic named formulas compiled from a body expression that may only reference built-in primitives (such as DIVIDE, MINUS, MULTIPLY, SUM, etc.) and the macro’s own declared parameters. The body is validated before anything is saved — invalid formulas are rejected with a clear error message.

Macro bodies are the one place in GridOS where nested primitive calls are allowed. Grid cells must always be flat single-function calls, but inside a macro body you can write =DIVIDE(MINUS(A, B), A) to compose two primitives.

Ask the AI to propose a macro

When you describe a reusable formula, the agent recognises the intent and proposes a macro_spec for your review. It does not save the macro automatically — you approve it first.

Create a MARGIN macro that calculates gross margin from revenue and cost

The agent responds with a proposal like:

{
  "name": "MARGIN",
  "params": ["A", "B"],
  "description": "Gross margin: (A - B) / A",
  "body": "=DIVIDE(MINUS(A, B), A)"
}

The proposal appears in the chat preview card. Review the name, parameters, body expression, and description before approving.

Review and approve

When a macro proposal appears in the chat:

1. Check the body expression

   Confirm the formula matches what you expect. The body must use only built-in primitives — you’ll see an error if the agent accidentally used an unknown function name.

2. Approve the macro

   Click Approve on the proposal card. GridOS compiles the macro, registers it in the formula evaluator, and saves it to data/user_macros.json.

3. Ask the agent to use it

   After approval, send a follow-up asking the agent to write cells using the new macro:

   Now use the MARGIN macro to calculate gross margin in D3:D10
   

   The agent can now call =MARGIN(C3, D3) in those cells.

In the same response where it proposes a macro, the agent intentionally leaves cell values null or writes unrelated cells. The macro isn’t registered yet at proposal time, so calling it in that same turn would fail. Always send a follow-up after approval.

Macro syntax rules

Rule	Detail
Name	Letters, digits, and underscores only. Must not collide with any built-in primitive.
Parameters	Uppercase single letters or short identifiers (e.g. A, B, RATE). Listed in the order they’ll be passed.
Body	Must start with =. May only call registered primitives — no infix operators, no references to other user macros.
Nesting	Primitive calls may be nested inside a macro body (this is the only place nesting is allowed in GridOS).
Recursion	Not supported. A macro body cannot call itself or another user macro.

Call a macro from a cell

Once approved, call the macro exactly like a built-in formula:

=MARGIN(C3, D3)

GridOS resolves MARGIN through the same evaluator registry as SUM, DIVIDE, and the rest. If you pass the wrong number of arguments, the evaluator raises an error that appears in the cell.

Example macros

MARGIN — gross margin ratio

Params: A (revenue), B (cost)

Body: =DIVIDE(MINUS(A, B), A)

Usage: =MARGIN(C3, D3) — gross margin for the row where C3 is revenue and D3 is cost.

MARKUP — cost markup percentage

Params: A (price), B (cost)

Body: =DIVIDE(MINUS(A, B), B)

Usage: =MARKUP(C5, D5)

GROWTH — period-over-period growth rate

Params: A (current period), B (prior period)

Body: =DIVIDE(MINUS(A, B), B)

Usage: =GROWTH(D3, C3) — growth from Q1 (C3) to Q2 (D3).

WTAVG — weighted average of two values

Params: A (value), B (weight), C (total weight)

Body: =DIVIDE(MULTIPLY(A, B), C)

Usage: =WTAVG(C3, D3, E3)

Macro persistence and management

• Storage: Approved macros are saved to data/user_macros.json and reloaded automatically every time the GridOS server starts.
• Updating a macro: Ask the agent to propose a new version with the same name. Approving it replaces the previous definition.
• Deleting a macro: Use the Tools panel in the UI, or send DELETE /tools/macros/{macro_name} to the API. Deleted macros are removed from the registry immediately — any cells that call them will error until you re-approve or rewrite them.
• Viewing macros: Open the Tools panel (accessible from the toolbar) to see all registered macros alongside the built-in primitives.

The agent always sees your approved macros in its context for every chat turn. You don’t need to remind it that MARGIN exists — it will automatically use it when the calculation fits.