Your First Rotifer Gene in 5 Minutes

Source: Dev.to

Prerequisites

• Node.js 20 or later (download)
• A terminal (macOS Terminal, iTerm, Windows Terminal, etc.)

That’s it. No Rust toolchain, no Docker, no cloud account. Everything else comes with the CLI.

Install the Rotifer CLI

npm install -g @rotifer/playground

Or, if you prefer not to install globally, use npx to scaffold a project in one shot:

npx @rotifer/playground init my-first-gene && cd my-first-gene

Either way, you now have the rotifer command available. Verify it:

rotifer --version

You should see something like @rotifer/playground v0.x.x.

Create the Gene

mkdir -p genes/hello-world

Open genes/hello-world/index.ts in your editor and paste the following:

interface HelloInput {
  name: string;
}

interface HelloOutput {
  greeting: string;
}

export async function express(input: HelloInput): Promise {
  const name = input.name?.trim() || "World";
  return {
    greeting: `Hello, ${name}! Welcome to the Rotifer ecosystem.`,
  };
}

Things to notice

1. express() is the entry point. Every gene exports an async express function — this is the contract Rotifer uses to invoke your logic.
2. Typed input and output. The interfaces define the gene’s phenotype — what it accepts and what it produces. This schema makes genes composable.
3. Pure logic, no dependencies. A gene is self‑contained: no imports, no side effects, no framework boilerplate.

Generate the Gene’s Metadata

rotifer wrap hello-world

Typical output:

✔ Analyzed genes/hello-world/index.ts
✔ Generated genes/hello-world/phenotype.json

Phenotype:
  domain:   general.greeting
  fidelity: Native
  inputs:   { name: string }
  outputs:  { greeting: string }

The wrap command introspects your code, extracts the input/output schema, and produces a phenotype.json descriptor. This is what the ecosystem uses to discover, compose, and evaluate your gene — without needing to read the source code.

Test the Gene Locally

rotifer test hello-world

Expected output:

🧬 Testing gene: hello-world

─── Test 1: default input ───
Input:  { "name": "Rotifer" }
Output: { "greeting": "Hello, Rotifer! Welcome to the Rotifer ecosystem." }
Status: ✔ PASS (3ms)

─── Summary ───
Total: 1 | Passed: 1 | Failed: 0

You can also provide custom inputs:

rotifer test hello-world --input '{"name": "Alice"}'

Submit to the Arena

rotifer arena submit hello-world

Sample result:

🏟️ Submitting hello-world to Arena...

✔ Phenotype validated
✔ Gene uploaded
✔ Evaluation complete

Arena Results:
  Gene:     hello-world
  Domain:   general.greeting
  F(g):     0.72
  Rank:     #3 of 5 in domain
  Status:   Active

The Arena evaluates your gene using a fitness function (F(g)) — a composite score based on correctness, resource efficiency, robustness, and utilization. Your gene now competes with others in its domain. If it’s good enough, other agents can discover and adopt it through Horizontal Logic Transfer (HLT).

Full Gene Lifecycle (in five minutes)

Your gene is now a first‑class citizen of the ecosystem: it has a typed interface, a fitness score, and a ranking. Other genes can compose with it, agents can discover it, and the selection pressure of the Arena will determine whether it thrives. That’s the Rotifer philosophy: genes earn their place through demonstrated fitness, not manual curation.

Next Steps

• Gene Development Guide – deep dive into express() patterns, error handling, and multi‑output genes.
• Composition Patterns – chain multiple genes into pipelines and workflows.
• Cloud Publishing – publish your gene to the cloud registry so any agent in the world can use it.
• Getting Started guide – see the full 10‑step walkthrough.

This article was originally published on rotifer.dev. Follow the project on GitLab or install the CLI: npm i -g @rotifer/playground.