Gram

Code your recipes.

An open-source declarative and computational recipe DSL. Built to handle complex culinary logic, Gram compiles your plain-text instructions into structured, calculated, and relational data.

Website • Playground • Documentation

Contributions, issues, and discussions are welcome on any of these platforms.

Please see CONTRIBUTING.md for more information on how to get involved.

Gram turns plain-text recipes into structured, queryable data while keeping them easy to read and write.

• Plain Text: Recipes are saved as simple .gram text files, so you can track changes with Git and use any text editor.
• Modular Recipes (@use): Import and compose external base recipes (@use "./bases/shortcrust.gram" as &crust) with automatic yield scaling, timeline interleaving, and unified shopping lists.
• Dynamic Calculations: Declare Baker's percentages, relative quantities (@water{75% @&flour}), and automatic unit conversions directly in your recipe.
• Step References & Variables: Reuse intermediate preparations (->&dough) and sub-ingredients (<@lemons{2}) without messing up shopping list totals.
• Timers & Gantt Charts: Separate active steps (~{10min}) from background waiting times (~_{2h}) to generate recipe timelines and Gantt charts.
• Developer Tooling: Includes a Language Server (LSP), a VS Code extension with real-time diagnostics, a CLI tool, and a TypeScript API.

Gram reads like natural language but compiles like code.

---
title: Artisanal Bread
size: 2 loaves
description: A simple, highly hydrated dough.
---

## Dough

[Mix] The @flour{500g}, @water{70% @&flour}, and @salt{10g} in a #large bowl{}. ->&dough

[Rest] Let the &dough rest for ~_{2h} at ^{room temperature} until doubled in size.

## Baking

[Preheat] The #oven to ^{450F}.

[Bake] The &dough for ~{35min} until the crust is deeply golden.

Gram comes with tools to help write, inspect, and compile recipes.

Available on the VS Code Marketplace

• Live Preview & Gantt View: Side-by-side recipe rendering and real-time Gantt charts for active steps and background timers.
• Autocomplete: Contextual suggestions for ingredients from your database, units, and step references.
• Diagnostics: Real-time error checking for missing ingredients, unused references, or circular dependencies.

View on npmjs

• gram check & gram build: Validate syntax and compile .gram files to JSON.
• gram cook: Step-by-step cooking assistant in your terminal with live timers.
• gram scale: Resize recipes (e.g., --scale=2 or --scale flour=300g) with before/after comparison tables.
• gram diff: Semantic diff to compare quantities, timings, or temperatures between recipe versions.
• gram shop: Generate aggregated shopping lists across multiple recipes.
• gram suggest: Find recipes based on available ingredients (e.g., --with "butter, eggs").
• gram import: Convert recipes from external URLs into .gram files.

Commands to maintain your ingredients.yaml file:

• gram db sync: Scan recipes and add missing ingredients to your database.
• gram db enrich: Fill in missing density and nutrition data from AI suggestions, with an interactive review before anything is written.
• gram db lint: Find duplicates (e.g., scallion vs green onion) and fix plural inconsistencies.

The full technical documentation is available online: https://docs.gram-lang.org/

The source code for the Astro & Starlight documentation can be found locally in packages/docs/.

This monorepo is divided into specialized packages under packages/:

Package	Version	Description
@gram-lang/parser		The core parser using Ohm.js to generate the AST.
@gram-lang/modules		Resolves @use imports and composes multi-file recipe ASTs.
@gram-lang/kitchen		The compiler logic, transforming the AST into final JSON structures.
@gram-lang/scheduler		The scheduling engine: lays a recipe's tasks out on a timeline and places it on the calendar from a serving time and your availability.
@gram-lang/format		Canonical .gram source code formatter.
@gram-lang/analyzer		The physical resolver for mass normalization, yield, and nutrition.
@gram-lang/renderer		The display layer converting JSON into HTML, Markdown, or Gantt Charts.
@gram-lang/cli		The official command-line interface.
@gram-lang/i18n		Localization layer for units, categories, and AI prompts.
vscode-extension		The Visual Studio Code extension.
@gram-lang/language-server		The LSP providing autocomplete and diagnostics.
docs	-	The documentation website, which includes the web-based Playground IDE.

Gram uses Forgejo Actions to maintain the stability of the language and its tooling. On every push and pull request, the CI pipeline automatically runs:

• Linting & Formatting: Enforced by Biome (bun run lint).
• Typechecking: Across the entire TypeScript monorepo (bun run typecheck).
• Unit Tests: For isolated component logic (bun test).
• Conformance Tests: A custom suite of golden tests (bun run conformance) that ensures the parser and compiler produce stable, byte-for-byte identical AST and JSON outputs for any given .gram input.

Get started with Gram directly in your terminal:

npm install -g @gram-lang/cli
gram init
# or, with Bun
bun add -g @gram-lang/cli
gram init

The CLI runs on both Node.js (>=22) and Bun — pick whichever you already have installed.

Note: contributing to this monorepo (building every package, running the test suite, the docs dev server) requires Bun — see CONTRIBUTING.md.

# Install dependencies for all packages
bun install

# Build packages and start the docs dev server
bun run dev

import { getAST } from '@gram-lang/parser';
import { compile } from '@gram-lang/kitchen';

const ast = getAST("[Mix] @flour{200g} and @water{100g}.");
const result = compile(ast);

console.log(result.shopping_list);

Gram stands on the shoulders of giants.

• Cooklang: For pioneering the concept of plain-text recipe markup and authoring. Gram was heavily inspired by their concise syntax.
• Ohm.js: For making parsing accessible and incredibly robust.
• LLM Assistance: This project was developed with the assistance of AI for rapid prototyping, refactoring, and generating test cases. All logic and architecture were strictly verified by humans.

• Bugs & Feature Requests: Please use our primary Forgejo issues (or GitHub mirror).
• Chat & Discussions: Join us on Discord or visit r/gramlang for casual community discussions.

Distributed under the GPL-3.0 License.