Skip to content

Gene Lifecycle Commands

Initialize a new Rotifer Agent workspace with Genesis genes and Arena preview.

Terminal window
rotifer init [workspace-name]

Arguments:

ArgumentRequiredDescription
workspace-nameNoAgent workspace directory name (defaults to my-agent)

Options:

FlagDescription
--domain <domain>Default gene domain (default: general)
--fidelity <level>Example gene fidelity: Wrapped | Hybrid | Native (default: Wrapped)
--no-genesisSkip genesis genes installation

What it creates:

my-agent/
├── rotifer.json # Agent workspace configuration
├── genes/ # Gene source directory
│ ├── genesis-web-search/
│ ├── genesis-web-search-lite/
│ ├── genesis-file-read/
│ ├── genesis-code-format/
│ └── genesis-l0-constraint/
└── .rotifer/
└── playground.db # Local Arena database

Example:

Terminal window
$ rotifer init my-agent
# Creates ./my-agent with Genesis genes and local Arena state
$ cd my-agent && rotifer arena list
# Shows Genesis genes pre-ranked in the local Arena

Scan source files for candidate functions that can be wrapped as genes.

Terminal window
rotifer scan [path]

Arguments:

ArgumentRequiredDescription
pathNoPath to scan (defaults to .)

Options:

FlagDescription
--skillsScan for SKILL.md files instead of source functions
--skills-path <dir>When using --skills, directory to scan (default: [path] or .cursor/skills)

Supported languages: TypeScript (.ts, .js), Rust (.rs)

Detection patterns:

  • export function name()
  • export async function name()
  • export const name =
  • pub fn name() / pub async fn name()

Example:

Terminal window
$ rotifer scan src/tools/
Scanning src/tools/search.ts...
Found 3 candidate functions:
┌────┬──────────────┬──────────────────────┬──────┐
│ # │ Name │ File │ Line │
├────┼──────────────┼──────────────────────┼──────┤
│ 1 │ webSearch │ src/tools/search.ts │ 12 │
│ 2 │ fileRead │ src/tools/file.ts │ 8 │
│ 3 │ codeFormat │ src/tools/format.ts │ 5 │
└────┴──────────────┴──────────────────────┴──────┘

Wrap a function as a Rotifer gene, generating a Phenotype and shim code.

Terminal window
rotifer wrap <gene-name> --domain <domain> [options]

Arguments:

ArgumentRequiredDescription
nameYesGene name

Options:

FlagDescription
-d, --domain <domain>Functional domain (e.g., search.web, file.read)
--fidelity <level>Fidelity level (default: Wrapped)
--from-skill <path>Create gene from a SKILL.md file (path to SKILL.md or its directory)
--from-clawhub <slug>Create gene from a ClawHub skill (downloads and converts automatically)

Generated files:

genes/<name>/
├── phenotype.json # Gene metadata (domain, schemas, fidelity)
├── index.ts # Express function wrapper
└── shim.ts # Compatibility shim

Example:

Terminal window
$ rotifer wrap my-search --domain search.web
✓ Gene 'my-search' wrapped successfully
Domain: search.web
Fidelity: Wrapped
Version: 0.1.0

Execute sandbox tests against a gene, validating schemas and behavior.

Terminal window
rotifer test <gene-name> [options]

Arguments:

ArgumentRequiredDescription
nameYesGene name to test

Options:

FlagDescription
--verboseShow detailed input/output for each test case
--complianceRun structural compliance checks (sandbox, L0, fuel metering, IR integrity)
--scaffoldWrite a starting testsuite.json from the phenotype and stop, without running any test. Refuses to overwrite an existing testsuite.json
--jsonAlso print the T1 results as JSON: requirements, gatePassed and the result of each case. Printed only when the gene has a testsuite.json; the rest of the report still prints as text
--allow-credentials <list>Let external genes use these credentials from your environment, each only at its host: KEY@api.example.com,KEY2@other.example.com. Without it, an external gene that declares a credential makes the command ask once at a terminal (default no), or exit 1 with credentials_not_granted elsewhere

Test cases run automatically:

  1. Schema validation — Phenotype conforms to Gene Standard
  2. Express function — express() is exported and callable
  3. Input/Output conformance — Output matches outputSchema
  4. Error handling — Graceful failure on invalid input
  5. Null check — express() returns non-null data
  6. Sandbox execution — Compiled genes execute through WASM sandbox; uncompiled genes fall back to Node.js with a warning
  7. IR verification — WASM module contains all required custom sections

With --compliance, 6 additional structural checks run:

  • C1: Sandbox execution verification (sandbox_type == “wasm”)
  • C2: Fuel consumption verification (fuel_consumed > 0)
  • C3: L0Gate pre-execution check pass
  • C4: Phenotype field completeness (Gene Standard)
  • C5: F(g) computability (all input metrics available)
  • C6: IR segment integrity (custom WASM sections)

T1 test suite: if the gene’s folder has a testsuite.json (spec §47.5), rotifer test also runs it as T1, the same check rotifer publish runs. Without one, it warns that the publishing gate was not evaluated. A failing case makes the command exit with code 1. rotifer test <gene> --scaffold writes a starting suite.

  • Async express (0.37.0 and later): T1 waits for an async express and judges the value it resolves to. Before, it judged the Promise object, so a suite that passed on the Promise may now fail, and one that failed on it may now pass.
  • A call that never finishes: if a gene’s Promise never settles, the call fails with exit code 1 and the message says the gene never finished. Before 0.37.0 the command stopped partway with exit code 0. rotifer run and rotifer agent run behave the same way.
  • External genes without IR (0.38.0 and later): a gene installed from Cloud or wrapped from ClawHub that has no compiled IR is not run on Node.js. T1 fails and tells you to run rotifer compile <gene> first; once compiled, the suite runs in the sandbox. Genes you wrote in this workspace still run their suite on Node.js.

Example:

Terminal window
$ rotifer test my-search
Running tests for 'my-search'...
✓ Phenotype schema is valid
✓ express() returned successfully
✓ Output conforms to outputSchema
✓ Error handling works correctly
All 4 tests passed ✓
Fitness: F(g) = 0.8234 V(g) = 0.9100

Execute a single gene directly, checking its input and output against the gene’s schema.

Terminal window
rotifer run <gene-name> [options]

Arguments:

ArgumentRequiredDescription
gene-nameYesGene name to execute

Options:

FlagDescription
--input <json>Input JSON string (default: {"name":"world"})
--verboseShow detailed execution output
--no-sandboxRun without the WASM sandbox (Node.js only)
--trust-unsignedAllow Node.js execution for Cloud-installed or ClawHub-wrapped genes
--no-validateSkip checking the input and output against the gene’s inputSchema / outputSchema
--allow-credentials <list>Let external genes use these credentials, each only at its host: KEY@api.example.com,KEY2@other.example.com

External genes:

  • A gene installed from Cloud or wrapped from ClawHub runs in the WASM sandbox when it has been compiled (gene.ir.wasm). If it would have to run from source on Node.js, run refuses it and exits 1 unless you pass --trust-unsigned, or compile it first with rotifer compile <gene>.
  • If an external gene that runs in the sandbox declares a credential from your environment, run asks once at a terminal before running it (default no). Elsewhere it exits 1 with credentials_not_granted; --allow-credentials KEY@host allows that credential for this one command, sent only to that host. With --trust-unsigned the gene runs on Node.js instead: run does not ask, and the gene can read every environment variable you have.

Example:

Terminal window
rotifer run my-search --input '{"query":"rotifer"}'

Compile a gene to Rotifer IR (WASM with custom sections).

Terminal window
rotifer compile [gene-name] [options]

Arguments:

ArgumentRequiredDescription
gene-nameNoGene name (auto-detects if omitted)

Options:

FlagDescription
--checkValidate only, don’t produce artifacts
--wasm <path>Path to pre-compiled .wasm file to wrap as IR
--lang <ts|wasm>Force compilation mode (auto-detected by default)

Compilation pipeline:

TypeScript source
↓ esbuild (bundle + minify)
WASI-compatible JavaScript
↓ IR compiler (QuickJS → WASM)
Raw WASM module
↓ Rotifer IR Injector
gene.ir.wasm (with custom sections)

Custom sections injected:

  • rotifer.version — Protocol version
  • rotifer.phenotype — Serialized phenotype
  • rotifer.constraints — L0 constraint metadata
  • rotifer.metering — Fuel/resource limits

Example:

Terminal window
$ rotifer compile my-search
Compiling 'my-search'...
Pipeline: TypeScript → esbuild → IR compiler → IR
✓ Compiled successfully
IR Hash: a3f2b1...c4d5
Size: 142.3 KB
Sections: version, phenotype, constraints, metering

Output: genes/<name>/gene.ir.wasm


Check the toolchain that rotifer compile needs to turn TypeScript into WASM: esbuild and Javy.

Terminal window
rotifer doctor

It takes no arguments. It looks for esbuild on your PATH (then npx --no-install esbuild) and for javy on your PATH (then npx --no-install javy-cli and javy), and prints which npx and node are active. It does not download anything.

Example:

Terminal window
$ rotifer doctor
Rotifer Doctor — TS→WASM toolchain
────────────────────────────────────
esbuild: ok (esbuild)
javy: ok (javy)
active npx: /usr/local/bin/npx
node: /usr/local/bin/node
✓ Toolchain ready — `rotifer compile` can build Native WASM Genes.

When something is missing, it lists what it tried and prints the fix: npm i -g esbuild javy-cli (the javy-cli package installs a binary named javy), then make sure the Node prefix that owns rotifer comes first in your PATH. It exits with code 1 in that case, so it can gate a CI step.