Soap Calc
[!CAUTION]
Handle Lye with Care. Sodium Hydroxide (NaOH) and Potassium Hydroxide (KOH) are caustic chemicals that cause severe burns. Always wear safety goggles and gloves. Verify all calculations before use.
The first Python-based soap formulation library. Define recipes in JSON, calculate lye and water amounts, predict soap properties, and export printable instructions—all from the command line or through AI agents like Claude Code.
Traditional web calculators lock your formulas in HTML forms. Soap Calc treats recipes as code: version them with git, iterate programmatically, and collaborate with AI to brainstorm oils, debug formulations, and scale batches. Ask "Create a moisturizing bar soap for dry skin" or "Why is this recipe too soft?" and get structured, chemically sound answers.
Every calculation is transparent and reproducible. No proprietary formulas, no hidden assumptions—just saponification chemistry you can audit and extend.
Claude Code Plugin
Skip the CLI — formulate soap through conversation. This repository doubles as a Claude Code plugin. Ask "Create a moisturizing bar with shea butter" or "Why is my soap too soft?" and get validated, calculated recipes with full chemistry explanations.
pip install soap-calc
claude plugin install https://github.com/mikewolfd/soap-calc
The plugin adds two skills to your Claude Code sessions:
🧪 Soap Formulation
Expert formulation guidance combined with the calculation engine. Design, troubleshoot, and refine recipes through conversation.
- Generate recipes from plain English ("conditioning shampoo bar", "gentle baby soap")
- Troubleshoot problems ("why is my soap soft?", "how do I fix DOS?")
- Get oil substitution advice based on fatty acid profiles and SAP values
- Validate against formulation best practices before calculation
- Safety guidance for lye handling and pH testing
The skill consults a built-in expert reference for fatty acid balance targets and formulation archetypes, verifies oil names against the database, writes recipe files, validates, calculates, and exports — all while explaining the chemistry.
📦 Inventory Management
Track your oils, butters, and additives. The skill cross-references items against the verified database and saves them for use in formulation.
- Resolves ambiguous names (e.g., "coconut oil" → prompts for specific variant)
- Flags unverified items not in the database
- Saves inventory to
~/.soap_calc/inventory.md (global) or ./inventory.md (project-specific)
Try: "I have olive oil, coconut oil, shea butter, and sodium lactate" then later "Create a recipe using my inventory"
Note: Inventory is only used when you explicitly ask. Otherwise, formulations draw from the full oil database.
Background
Inspired by Soapmaking Friend, this project reimagines soap calculation as a Python library. Built collaboratively with AI tools including antigravity by Google, Gemini 3 Pro, and Claude Opus 4.6.
Features
Core Calculation
- Multi-Lye Support
- Sodium Hydroxide (NaOH): For hard bar soaps.
- Potassium Hydroxide (KOH): For liquid soaps.
- Dual Lye (Hybrid): Create hybrid recipes (e.g., shaving soap, cream soap) with any ratio of NaOH:KOH.
- Flexible Water Calculation Modes
- Water:Lye Ratio: Specify water relative to the lye amount (e.g., 2:1).
- Lye Concentration: Calculate water needed to reach a specific lye concentration %.
- Water as % of Oils: Traditional method (discouraged but supported).
- Superfatting
- Apply lye discount directly (standard superfat).
- Define "Superfat Oils" added post-cook or after the gel phase (Hot Process).
