Developer FAQ

CLI & Setup

How do I install the CLI?

npm install -g @rotifer/playground

Or run directly without installing:

npx @rotifer/playground init my-project

Requirements: Node.js >= 20.0.0, npm >= 9.

How do I create my first Gene?

# 1. Initialize a project
rotifer init my-project && cd my-project

# 2. Write your Gene logic
# Edit genes/my-gene/index.ts:
# export async function express(input) { return { result: ... }; }

# 3. Wrap it (generates phenotype.json)
rotifer wrap my-gene --domain search

# 4. Compile to WASM (optional, for Native fidelity)
rotifer compile my-gene

# 5. Test it
rotifer test my-gene

See the Getting Started guide for a complete walkthrough.

How do I publish to Cloud Registry?

# 1. Log in via GitHub OAuth
rotifer login

# 2. Publish your Gene
rotifer publish my-gene

Your Gene will appear in the Gene Catalog and can be discovered via rotifer search.

How do I search and install Genes?

# Search by keyword
rotifer search "grammar"

# Install a Gene from the Cloud Registry
rotifer install grammar-checker

Installed Genes are placed in your project’s genes/ directory, ready to use.

Running Genes

How do I run a Gene?

There are three ways to run Native Genes:

1. Via Agent pipeline (recommended):

# Create an Agent with a genome
rotifer agent create content-checker --genes grammar-checker readability-analyzer

# Run the pipeline
rotifer agent run content-checker --input '{"text":"Your text here"}' --verbose

2. Direct import in TypeScript:

import { express as grammarCheck } from "./genes/grammar-checker/index.js";

const result = await grammarCheck({ text: "Check this text." });
console.log(result.score, result.issues);

3. Fan-out parallel composition — run multiple Genes on the same input and merge results. See tests/demo/content-pipeline-demo.ts for an example.

Can Wrapped Genes be executed?

No. Wrapped Genes have no express() function — they contain only metadata (phenotype.json) and a description (SKILL.md).

To make a Wrapped Gene executable, implement an index.ts file with an express() function, upgrading it to Native.

How does Seq pipeline composition work?

When an Agent has multiple Genes, they execute in sequential order (Seq composition):

Input → Gene 1 → Output₁ → Gene 2 → Output₂ → Gene 3 → Final Output

Each Gene’s output becomes the next Gene’s input. Adjacent Genes must have compatible schemas.

rotifer agent create my-pipeline --genes step1 step2 step3
rotifer agent run my-pipeline --input '{"data": "..."}'

What if input/output schemas don’t match between Genes?

The pipeline will fail at runtime. To solve this:

Ensure schema compatibility — design your Genes so that adjacent I/O schemas align
Write adapter Genes — create a small Gene that transforms one schema into another
Use fan-out composition — if Genes analyze the same input independently, run them in parallel instead of sequentially

Skill → Gene Migration

How do I migrate an existing MCP Tool to a Gene?

Migration is a progressive enhancement, not a tear-down:

# 1. Scan your project for migratable Skills
rotifer scan --skills

# 2. Auto-wrap into a Gene (generates phenotype.json from SKILL.md)
rotifer wrap my-tool --from-skill --domain search

# 3. (Optional) Implement express() for Native upgrade
# Edit genes/my-tool/index.ts

# 4. Compile and test
rotifer compile my-tool
rotifer test my-tool

What you can reuse: core business logic, inputSchema/outputSchema (maps directly to Phenotype), composition patterns (Workflow/Chain → Genome DataFlowGraph).

Troubleshooting

Why does rotifer publish fail with a 409 error?

A 409 Conflict means a Gene with the same name + version already exists in the Cloud Registry.

Fix: Bump the version field in your Gene’s phenotype.json, then publish again:

{
  "version": "0.2.0"
}

rotifer publish my-gene

How do I create an account / log in?

rotifer login

This opens a GitHub OAuth flow in your browser. After authorization, your session token is stored locally at ~/.rotifer/auth.json.

rotifer compile fails — what should I check?

Common causes:

Missing Javy runtime — rotifer compile requires the Javy binary. Check it’s installed and on your PATH.
TypeScript errors — your index.ts must compile cleanly. Run npx tsc --noEmit to check.
No express() export — the compiler expects export async function express(input) as the entry point.

rotifer agent run errors with “Gene has no source file”

The Gene directory must contain one of: index.ts, index.js, or index.mjs. Check:

ls genes/my-gene/

If only phenotype.json and SKILL.md exist, the Gene is Wrapped (not executable). You need to implement index.ts with an express() function.

Is the Cloud Registry open source?

The API gateway design and database schema are documented in the protocol specification. The infrastructure runs on managed services (Supabase). The REST API is publicly accessible for searching and installing Genes.