wolfram-hart

Wolfram Engine

Execute exact computation through the Wolfram Engine, either locally installed or via Wolfram Cloud. The full Wolfram Language is available: symbolic algebra, calculus, differential equations, linear algebra, number theory, statistics, optimization, plotting, data analysis, and image processing.

Autonomy Rules

Compute immediately. When a request falls within the trigger conditions above, translate the problem to Wolfram Language and execute it without asking the user for confirmation. Do not ask "would you like me to use Wolfram?" or "shall I compute this?" Just run the code and present the result.

Compute, don't guess. Do not answer mathematical questions from memory. The Wolfram Engine produces verified results; training data does not.

Batch related work into one call. Each invocation of wolframscript carries a 2-3 second kernel startup cost. Combine related computations into a single Module[...] rather than making multiple calls. For example, if the user asks to "solve this equation and plot the roots," do both in a single script.

Retry once on failure. If a computation returns an unevaluated expression or an error, consult ${CLAUDE_PLUGIN_ROOT}/skills/wolfram-hart/references/wolfram-language-guide.md to verify syntax, adjust the code, and try once more before reporting the problem.

Skip the pre-flight check unless something fails. Do not run wolfram-check.sh as a routine first step. Only run it if wolfram-eval.sh exits with code 1 (not installed) or the output starts with NOT_CONFIGURED, so the user gets actionable setup instructions.

Workflow

0. Signal routing

Before anything else, output exactly this line so the user knows the request was routed to the Wolfram Engine:

_ᴡ wolfram_

1. Translate

Convert the user's request to Wolfram Language. Consult ${CLAUDE_PLUGIN_ROOT}/skills/wolfram-hart/references/wolfram-language-guide.md when unsure about syntax.

Five rules that prevent the most common mistakes:

1. Function names are capitalized: Sin, Solve, Integrate
2. Arguments go in square brackets: Sin[x], never Sin(x)
3. Equations use ==: Solve[x^2 == 4, x]
4. Ranges and lists use braces: {x, 0, 10}, {1, 2, 3}
5. Constants are capitalized: Pi, E, I, Infinity

When a request is mathematically ambiguous (e.g., real vs. complex solutions, degrees vs. radians), choose a reasonable interpretation and state the assumption briefly when presenting the result.

Quick-reference mapping from natural language to Wolfram functions:

User says	Function	Example
solve / find x	Solve	Solve[x^2 - 4 == 0, x]
solve numerically	NSolve / FindRoot	NSolve[x^5 - x + 1 == 0, x]
integrate	Integrate	Integrate[Sin[x]^2, x]
definite integral	Integrate[f, {x, a, b}]	Integrate[x^2, {x, 0, 1}]
derivative	D	D[x^3 Sin[x], x]
limit	Limit	Limit[Sin[x]/x, x -> 0]
series / Taylor	Series	Series[Exp[x], {x, 0, 5}]
simplify	Simplify / FullSimplify	FullSimplify[Sin[x]^2 + Cos[x]^2]
factor	Factor	Factor[x^2 - 5x + 6]
expand	Expand	Expand[(x+1)^5]
plot / graph	Plot	Plot[Sin[x], {x, 0, 2Pi}]
scatter plot	ListPlot	ListPlot[data, PlotStyle -> Red]
line plot (data)	ListLinePlot	ListLinePlot[Table[Sin[x], {x, 0, 10, 0.1}]]
bar chart	BarChart	BarChart[{3, 1, 4, 1, 5}, ChartLabels -> labels]
histogram	Histogram	Histogram[data, 20, "ProbabilityDensity"]
contour / heatmap	ContourPlot	ContourPlot[x^2+y^2, {x,-2,2}, {y,-2,2}]
3D surface	Plot3D	Plot3D[x^2+y^2, {x,-2,2}, {y,-2,2}]
eigenvalues	Eigenvalues	Eigenvalues[{{1,2},{3,4}}]
ODE / diff eq	DSolve	DSolve[y'[x] == -y[x], y[x], x]
prime factors	FactorInteger	FactorInteger[360]
regression / fit	LinearModelFit	see ${CLAUDE_PLUGIN_ROOT}/skills/wolfram-hart/references/patterns-visualization.md
convert units	UnitConvert	UnitConvert[Quantity[100,"Miles"],"Kilometers"]
Fourier transform	FourierTransform	FourierTransform[Exp[-x^2], x, w]
optimize / minimize	NMinimize / Minimize	NMinimize[x^4 - 3x^2 + x, x]
sum of series	Sum	Sum[1/n^2, {n, 1, Infinity}]

2. Build

One-liner for simple expressions:

Integrate[Sin[x]^2, {x, 0, Pi}]

Module for multi-step work (use semicolons to suppress intermediate output):

Module[{f, roots, plot},
  f[x_] := x^3 - 6 x^2 + 11 x - 6;
  roots = Solve[f[x] == 0, x];
  plot = Export["/tmp/cubic.png",
    Plot[f[x], {x, -1, 5}, PlotTheme -> "Scientific", ImageSize -> 500,
      Epilog -> {Red, PointSize[0.02], Point[{x, 0} /. roots]}]];
  roots
]

Plots must be exported to a file. Graphics objects have no useful text representation. Always wrap in Export["/tmp/wolfram_descriptive_name.png", ...] and then use the Read tool to show the image to the user. Use a unique descriptive filename per plot to avoid overwriting previous results in the same session.

3. Execute

Before calling the script, output a single status line so the user knows computation is starting (the kernel takes 2-3 seconds to start):

_Running Wolfram Engine…_

Run all code through the wrapper script:

bash ${CLAUDE_PLUGIN_ROOT}/skills/wolfram-hart/scripts/wolfram-eval.sh '<code>' [timeout]

The default timeout is 30 seconds. Pass a higher value as the second argument for heavy computations (numerical ODEs, large plots, optimization):

bash ${CLAUDE_PLUGIN_ROOT}/skills/wolfram-hart/scripts/wolfram-eval.sh '<code>' 120

Evaluation mode. The script respects the WOLFRAM_MODE environment variable: auto (default, tries local then cloud), local, or cloud. No manual setup needed — auto mode works transparently. When the user has set WOLFRAM_MODE=cloud, the -cloud flag is added to the wolframscript invocation and no local Engine is required. If the local kernel is present but unlicensed, auto mode incurs the full local timeout before falling back; in that case, WOLFRAM_MODE=cloud avoids the extra wait.

Quoting. Use single quotes around the code argument. When the code contains derivative apostrophes (y'[x]), switch to double quotes and escape the inner double quotes with \":

# single quotes — normal case
bash .../wolfram-eval.sh 'Solve[x^2 == 4, x]'

# double quotes — code contains y'[x]
bash .../wolfram-eval.sh "DSolve[y'[x] + y[x] == 0, y[x], x]"

When using double quotes, escape dollar signs (\$) for any Wolfram system variable ($VersionNumber, $SystemID, $ProcessorCount).

Exit codes: 0 = success, 1 = not installed, 2 = execution error, 3 = timeout.

4. Interpret and Present

Output kind	What to do
Number	Present directly with context.
Symbolic expression	Render as LaTeX with ToString[TeXForm[expr]] for clean display. Fall back to Wolfram notation only for deeply nested procedural output.
List / Association	Format as a markdown table or bullet list.
File path (from Export)	Use the Read tool to display the image inline.
Unevaluated (output = input)	The function name or arguments are wrong. Check spelling and brackets.
Error message in output	Read the :: message tag. Adjust code and retry once.

Verify and state assumptions. Apply trust proportional to the computation type:

Computation	Trust	Action
Arithmetic, constants	Full	Present directly.
Symbolic algebra, calculus	High	State domain assumptions (real vs. complex, branch choice) when they affect the result. E.g., Integrate[Exp[-a x^2], {x, -Infinity, Infinity}] silently assumes Re[a] > 0.
Numerical optimization, root-finding	Moderate	Sanity-check convergence; try a second starting point if feasible.
Simplification (Simplify, FullSimplify)	Moderate	Verify equivalence — simplification can drop solutions or change domain.
Entity / knowledge-base queries	Low	Warn the user that data may be outdated or missing.

For high-trust results that are load-bearing, verify by substitution:

sol = Solve[x^2 - 5x + 6 == 0, x];
Simplify[x^2 - 5x + 6 /. sol]  (* expect {0, 0} *)

Output Formats

Goal	Wrapper	Produces
LaTeX	ToString[TeXForm[expr]]	\frac{x^3}{3}
Machine-readable	ToString[expr, InputForm]	x^3/3
CSV	ExportString[data, "CSV"]	1,2,3\n4,5,6
JSON	ExportString[assoc, "JSON"]	{"key":"value"}
Image file	Export["/tmp/f.png", plot]	file path on stdout

Timeouts

Computation	Timeout
Arithmetic, simple algebra	30 s (default)
Symbolic solving, series	30-60 s
Numerical ODE/PDE, optimization	60-120 s
3D plots, large datasets	60 s

Troubleshooting

Not installed (exit 1). The eval script prints setup instructions covering both the cloud option (wolframscript binary + free account) and the local Engine option. Relay them to the user.

Not configured (output starts with NOT_CONFIGURED). wolframscript was found but neither local nor cloud worked. Run wolfram-check.sh and relay its setup recommendations to the user.

Graphics prints -Graphics-. The code forgot to call Export. Wrap the plot in Export["/tmp/name.png", ...].

Computation hangs. Add TimeConstrained[expr, 20, "TIMEOUT"] inside the Wolfram code for an inner safety net on top of the script-level timeout.

Entity/knowledge-base queries are slow. They fetch data over the internet on first use. Warn the user or fall back to an approximate answer.

Cloud evaluation is slow. Cold-start latency for cloud kernels is higher than local. For repeated work, consider the local Engine option.

Reference Files

Detailed syntax and cookbook patterns, loaded on demand:

• ${CLAUDE_PLUGIN_ROOT}/skills/wolfram-hart/references/wolfram-language-guide.md -- Complete function reference by domain: algebra, calculus, linear algebra, statistics, plotting, data, strings, and programming constructs.
• ${CLAUDE_PLUGIN_ROOT}/skills/wolfram-hart/references/output-formats.md -- How the Wolfram Engine formats different expression types, how to control the format, and how to detect errors in output.

Computation Patterns (load by domain)

15 copy-paste-ready patterns split by domain. Load only the file relevant to the current query:

Domain	File	Patterns	Route when query mentions
Core workflow	references/patterns-core.md	#1 Quick calc, #2 Symbolic LaTeX, #3 Solve+format, #10 Data export, Anti-patterns	solve, simplify, expand, factor, algebra, LaTeX, CSV, JSON
Visualization	references/patterns-visualization.md	#4 2D plot, #5 3D surface, #6 Data analysis pipeline	plot, graph, chart, regression, fit, surface, 3D
Analysis	references/patterns-analysis.md	#7 Differential equations, #12 Optimization, #13 Fourier/Laplace	integral, derivative, ODE, calculus, series, optimize, transform
Discrete & structured	references/patterns-discrete.md	#8 Matrix ops, #9 Number theory, #14 Probability	matrix, eigenvalue, determinant, prime, factor integer, probability, statistics
Applied	references/patterns-applied.md	#11 Unit conversions, #15 Image processing	unit, convert, image

Scripts

• ${CLAUDE_PLUGIN_ROOT}/skills/wolfram-hart/scripts/wolfram-eval.sh -- The only interface to the engine. Always use this; never call wolframscript directly.
• ${CLAUDE_PLUGIN_ROOT}/skills/wolfram-hart/scripts/wolfram-check.sh -- Checks both local and cloud mode status. Run when wolfram-eval.sh exits with code 1 or produces NOT_CONFIGURED output.