| name | compute-over-bash |
| description | Reach for the `compute` tool (sandboxed JavaScript) instead of shelling out to `python3 -c`, `node -e`, `bc`, `expr`, or `jq` whenever the task is pure calculation or data transformation - arithmetic, big-number math, base/radix conversion, date math, string/regex work, reshaping JSON, hashing (sha256), base64, or UTF-8 byte work. Skip it - and use bash - the moment the task needs files, network, environment, subprocesses, or anything asynchronous. |
Compute over bash
Models reflexively compute by shelling out (python3 -c "print(2**64)", node -e, bc, echo $((...))). In pi, the
compute tool is the better default for pure computation: it runs JavaScript in a sandboxed WASM VM, returns the value
of the final expression, and - because it has no filesystem, network, or process access - never triggers a permission
prompt. Use it as your first move for calculation and data shaping; reserve bash for work that genuinely touches the
system.
When to use compute
Route to compute when the task is self-contained computation over values you already have:
- Arithmetic and big numbers - exact integer math,
BigInt, modular arithmetic, combinatorics.
- Base / radix conversion - hex/binary/decimal, parsing or formatting numbers.
- Date and time math - day/second differences, ISO formatting, "N days from X" (
Date is available).
- String and regex work - parsing, reformatting, counting matches, slicing.
- Reshaping data - map/filter/reduce/group over an array or object; pass the data in via the
input argument.
- Hashing -
sha256(string | bytes) returns a hex digest.
- Encoding -
btoa / atob for base64; TextEncoder / TextDecoder for UTF-8 byte work.
When NOT to use compute (use bash instead)
compute is pure compute only. Use bash the moment the task needs anything outside the sandbox:
- Reading or writing files, listing directories, globbing.
- Network access (HTTP, DNS, sockets) - use
ai-fetch-web or curl.
- Environment variables, subprocesses, or installed CLIs.
- Running the project's own code or tests (
npm test, pytest, a build).
- Anything asynchronous -
compute is synchronous only (no await, no dynamic import).
If you find yourself wanting require('fs'), fetch, or process.env inside compute, that is the signal to switch
to bash.
How compute behaves
- Returns the last expression.
const n = 2 ** 16; n * n returns 4294967296. Use console.log(...) for
intermediate output - it is captured alongside the value.
- Pass data via
input. Large or structured inputs go in the input argument and appear inside the sandbox as the
global input (already parsed - no JSON.parse needed).
- Bounded. Calls are capped on wall-clock time, memory, and output size; an infinite loop is killed, not hung.
- Deterministic and prompt-free. No approval dialog, no side effects.
Before / after
Before (shells out, hits the permission dialog):
python3 -c "import hashlib; print(hashlib.sha256(b'hello').hexdigest())"
After (one compute call, no prompt):
sha256('hello');
Before:
node -e "const xs=[3,1,2]; console.log(xs.reduce((a,b)=>a+b,0))"
After - call compute with code: "input.reduce((a, b) => a + b, 0)" and input: [3, 1, 2].
Anti-patterns
- Shelling out to an interpreter purely to calculate.
python3 -c, node -e, bc, expr, echo $((...)) for a
value with no I/O is exactly what compute is for.
- Reaching for
compute to do I/O. It has no filesystem or network; do not try to read a file or fetch a URL
through it. Use bash / ai-fetch-web.
- Re-deriving a hash or base64 by hand when
sha256, btoa, or atob are already available in the sandbox.
- Asking
compute to run the project's tests or build. That is bash's job - compute cannot spawn processes.
