New: Earn 20% as an AgentAlley affiliate. Share your link and earn on every sale you refer. Join now New: Earn 20% as an affiliate. Join now

Migration to Rust with Rust Anything

Migration to Rust with rust-anything

by erkamyaman · MIT license · ★ 1,854 on GitHub

Migration to Rust with rust-anything cover

Port TypeScript/JavaScript, Python, C, Go, Ruby or Java to Rust with the rust-anything CLI or MCP tools, from one hot function up to a whole app rewritten as a pure Rust app - profile, plan, bridge one unit at a time, record the…

---
name: rust-anything
description: Port TypeScript/JavaScript, Python, C, Go, Ruby or Java to Rust with the rust-anything CLI or MCP tools, from one hot function up to a whole app rewritten as a pure Rust app - profile, plan, bridge one unit at a time, record the original's behavior, port, diff, bench, shadow and gate; batch hot loops so they run in Rust on all cores. Use when asked to rewrite, port or migrate code or an app to Rust, to plan such a migration, or to make slow code faster with Rust.
---

# Migration to Rust with rust-anything

rust-anything gives you ground truth; you write the Rust. Port one unit at a time, even when the
goal is the whole app, and call a port done only when `gate` passes.

**Whole app to a pure Rust app** (the user wants the app rewritten in Rust, with the original kept
only as reference): read [whole-app.md](whole-app.md) first and follow it. It grills the user on
the decisions, researches the dependencies, records the whole app, puts a Rust front door in front
of the original, runs the steps below for every unit, then lifts the app to a standalone Rust
binary (or, for a library, one pure Rust crate). CLIs, HTTP servers and libraries.

Languages: TypeScript/JavaScript, Python, C, Go, Ruby, Java. The language is detected; `--lang`
overrides it. The steps are the same everywhere; only the bridge differs (napi-rs or wasm for

Overview

rust-anything gives you ground truth; you write the Rust. Port one unit at a time, even when the goal is the whole app, and call a port done only when gate passes.

Manual install (npx, ZIP)
Claude Codenpx skills add erkamyaman/rust-anything --skill rust-anything -g -a claude-code
Claude Code (degit)npx degit erkamyaman/rust-anything/skills/rust-anything#main ~/.claude/skills/rust-anything
Claude.ai / desktopZip the folder and upload it under Settings → Capabilities → Skills.
Codex, Cursor, other agentsPoint them at SKILL.md. The other files are plain text.

Connects with Agent Alley MCP · agentalley.io/mcp

Files included

  • SKILL.md10.3 KB
Read SKILL.md here
erkamyaman/main1 file shown
SKILL.md
Show the full text180 lines

Migration to Rust with rust-anything

rust-anything gives you ground truth; you write the Rust. Port one unit at a time, even when the goal is the whole app, and call a port done only when gate passes.

Whole app to a pure Rust app (the user wants the app rewritten in Rust, with the original kept only as reference): read whole-app.md first and follow it. It grills the user on the decisions, researches the dependencies, records the whole app, puts a Rust front door in front of the original, runs the steps below for every unit, then lifts the app to a standalone Rust binary (or, for a library, one pure Rust crate). CLIs, HTTP servers and libraries.

Languages: TypeScript/JavaScript, Python, C, Go, Ruby, Java. The language is detected; --lang overrides it. The steps are the same everywhere; only the bridge differs (napi-rs or wasm for TS, PyO3, a C ABI, cgo, a magnus extension, JNI), and the original's callers keep their API. PHP is in preview: analyze, and for a whole app app record, app replay and app front-door (CLIs, and servers run with php -S 127.0.0.1:{port} router.php); bridge does not take PHP units yet, so tell the user before planning a PHP port past the front door. C# is in preview the same way: record a built app (dotnet out/app.dll, servers with --urls http://127.0.0.1:{port}); bridge does not take C# units yet.

Tools: the rust-anything CLI, or the same steps as MCP tools (rust-anything mcp): profile, analyze, bridge, refresh, record, build, diff, bench, shadow, gate, and for a whole app app_record, app_replay, app_front_door, app_wire, app_lift. If the MCP tools are not available, use the CLI; if rust-anything is not installed, ask the user to install it (cargo install rust-anything) and run rust-anything setup, then restart the agent.

0. Profile: find what is worth moving

When the goal is speed, measure before choosing anything:

rust-anything profile <repo> -- node bench.mjs      # or: python3 bench.py, ruby bench.rb,
                                                #     java -cp out Main, go test -run X -bench . ./pkg

It runs a real workload under the runtime's own profiler and lists hot functions with their callers and advice. Go profiles only through go test; C is not supported (use perf).

  • A small function called once per item is not worth porting alone: one call into Rust costs more than its work, and JITs (V8, the JVM, Go) run it in nanoseconds. Port it together with its callers, or batch it (step 2b). The advice line says which, with the exact command.
  • Code that is already compiled (numba @njit, Cython, @jax.jit) runs as machine code: a Rust port gains little speed. profile lists it under "Already compiled" and says so in the advice of every hot function that calls it; tell the user before porting it for speed.
  • If the user only wants a migration, skip to step 1.

1. Plan, then stop

rust-anything analyze <repo> -o plan.md        # people
rust-anything analyze <repo> --json            # you: schema rust-anything/analyze@1
  • Present the start_here units (best first ports) and the order by package and wave.
  • Call out keep units (UI, editor code: they stay in the source language), blocked units and their reason, and dependencies with fit none or unknown. Do not hand-roll a missing crate silently: flag it.
  • Wait for the user's approval of the plan and of the first unit.

2. Port one unit

rust-anything bridge <repo> <unit-id>          # crate in <repo>/rust/<name>; never overwrites
rust-anything record <crate>                   # the original's behavior on edge-case inputs -> cases.jsonl
  • Add real-world inputs with --inputs cases.jsonl ({"fn": name, "args": [...]} per line) when the generated ones cannot reach the interesting paths (structured arguments, domain strings).
  • TS that cannot run directly in Node (extensionless imports, path aliases): record from built output with --module dist/x.mjs, or pass --node-arg=--import=tsx.
  • If the original has no tests, record is the characterization suite: keep cases.jsonl.

Write the port in src/port.rs only; src/lib.rs and the wrappers are generated. After changing a signature in port.rs, run rust-anything refresh <crate>.

  • Read each risk the plan lists for the unit, at its file:line, before writing code.
  • String offsets: JS and Java index UTF-16 code units, Rust UTF-8 bytes: use src/utf16.rs.
  • Errors: return Err("TypeName: message"); it becomes that exception in Python, Ruby and Java, and the error text in Go.
  • Numbers in Python and Ruby: ints that the original passes through must come back as ints; in Python ports use crate::pynum::Num for int-or-float, not serde_json::Value.
  • C: inputs recorded as crash: are undefined behavior; any result passes.
  • Ordered maps and object keys: indexmap where order reaches output.
  • Regex lookaround or backreferences: fancy-regex, not regex. Either way, \w, \b, \d and case-insensitive matching treat non-ASCII text differently from the source language's engine: passing the recorded cases is not enough. record adds regex traps (Turkish i, Kelvin sign, joiners, non-ASCII digits and spaces) to functions in files that use regexes; ask the user for real text the patterns see, record it with --inputs, and set unicode(false) or spell out ASCII classes ([A-Za-z0-9_]) where the original's \w is ASCII-only (JS without u, Java).
  • No unsafe. If truly needed: minimal, isolated, with a // SAFETY: comment.
  • Add Rust unit tests in port.rs for the cases you reason about.

2b. Batch a hot loop

For a function called over many items (search, scoring, formatting a list):

rust-anything bridge <repo> <unit> --batch fn:param    # or: rust-anything refresh <crate> --batch fn:param

This generates a class that takes the param values once and keeps them in Rust: new FnBatch(items) (TS, Python, Java), Mod::FnBatch.new(items) (Ruby), NewFnBatch(items) (Go). Per query, run(<other args>) returns every result as one array, and rank(<other args>, min) returns the item indexes, best first. It runs on all cores, and errors are the original's. Close the batch when done in Go and Java (finalizers are only a fallback).

  • Make the caller build the batch once, not per query. Map returned indexes back to items with a plain loop; in JS, Array.from(order, fn) costs 20x more.
  • To prepare items once (lowercase, masks, position tables), define pub struct FnIndex in port.rs with new(items) and run(<other args>) -> Result<Vec<R>, String>. It must give the same result as the function, item by item: test it against the function over every item.
  • When ranking can skip work, give the index its own rank(<other args>, min) -> Result<Vec<u32>, String> (narrowing to the last query's matches as the user types, table lookups). It must match ranking the function's results: score high to low, ties in item order.
  • A batch multiplies the port's per-item speed by the cores. Against compiled originals (Go, Java) the port itself must be fast: handle ASCII without Unicode tables, build each result in one pre-sized String, avoid intermediate copies. Keep diff passing.
  • Items and other arguments: numbers, booleans and strings (Ruby: any value); results: numbers, booleans or strings. Not for C.

3. Prove it

rust-anything build <crate>
rust-anything diff <crate>                     # must be N/N
rust-anything bench <crate>                    # original vs Rust, bridge included, with a verdict

A mismatch is a behavior difference: fix the port, never the recording. If the difference is intended, ask the user first, then re-record with their approval.

Numeric code (physics, statistics, graphics) rarely gives bit-identical floats once ported: operation order, fused multiply-add and the math library differ. When the user accepts that, record with --float-tolerance 1e-9 (their number): floats then match within that share of the larger value (absolute below 1), and diff and gate use it. Integers, strings and the same value written differently (3 and 3.0) still must match exactly. Never widen a tolerance to make a mismatch go away: a difference beyond it is a bug in the port.

Follow bench's verdict: ship, keep the slower functions in the source language, or port a bigger unit (batch or include the callers). Do not ship a port that makes callers slower without saying so.

4. Ship it safely

rust-anything shadow <crate>                   # drop-in with the original's API

Load the shadow where the app loaded the original. RUST_ANYTHING_MODE=shadow (default) returns the original's results and reports Rust mismatches; new switches to Rust; old turns Rust off. The public API does not change.

5. Done means gate passes

rust-anything gate <crate>

fmt, clippy with warnings as errors, cargo tests, unsafe only with SAFETY comments, nothing unimplemented!, every place the original fails on purpose (throw, raise, an error result) reached by a recorded failing case (add one with record --inputs when gate names it), no unwrap, expect or panic! in a function whose original returns an error (return Err; for a state the original also treats as impossible, a // INFALLIBLE: <why> comment), the port at most 3x the original's lines (over that, use the crates analyze lists and fold repeated code), the module builds, every export present, every recorded case matches. A Rust panic never matches a recorded error: return Err where the original throws.

Then report to the user, and wait for their go-ahead before the next unit:

  • what changed (files, functions, bridge, batches),
  • gate output, diff counts and bench numbers,
  • behavior differences or risks left (e.g. error messages differ, a napi String refuses lone surrogates), and what is left in the plan.
1---
2name: rust-anything
3description: Port TypeScript/JavaScript, Python, C, Go, Ruby or Java to Rust with the rust-anything CLI or MCP tools, from one hot function up to a whole app rewritten as a pure Rust app - profile, plan, bridge one unit at a time, record the original's behavior, port, diff, bench, shadow and gate; batch hot loops so they run in Rust on all cores. Use when asked to rewrite, port or migrate code or an app to Rust, to plan such a migration, or to make slow code faster with Rust.
4---
5 
6# Migration to Rust with rust-anything
7 
8rust-anything gives you ground truth; you write the Rust. Port one unit at a time, even when the
9goal is the whole app, and call a port done only when `gate` passes.
10 
11**Whole app to a pure Rust app** (the user wants the app rewritten in Rust, with the original kept
12only as reference): read [whole-app.md](whole-app.md) first and follow it. It grills the user on
13the decisions, researches the dependencies, records the whole app, puts a Rust front door in front
14of the original, runs the steps below for every unit, then lifts the app to a standalone Rust
15binary (or, for a library, one pure Rust crate). CLIs, HTTP servers and libraries.
16 
17Languages: TypeScript/JavaScript, Python, C, Go, Ruby, Java. The language is detected; `--lang`
18overrides it. The steps are the same everywhere; only the bridge differs (napi-rs or wasm for
19TS, PyO3, a C ABI, cgo, a magnus extension, JNI), and the original's callers keep their API.
20PHP is in preview: `analyze`, and for a whole app `app record`, `app replay` and
21`app front-door` (CLIs, and servers run with `php -S 127.0.0.1:{port} router.php`); `bridge` does not
22take PHP units yet, so tell the user before planning a PHP port past the front door. C# is in
23preview the same way: record a built app (`dotnet out/app.dll`, servers with
24`--urls http://127.0.0.1:{port}`); `bridge` does not take C# units yet.
25 
26Tools: the `rust-anything` CLI, or the same steps as MCP tools (`rust-anything mcp`): `profile`,
27`analyze`, `bridge`, `refresh`, `record`, `build`, `diff`, `bench`, `shadow`, `gate`, and for a
28whole app `app_record`, `app_replay`, `app_front_door`, `app_wire`, `app_lift`.
29If the MCP tools are not available, use the CLI; if `rust-anything` is not installed, ask the user
30to install it (`cargo install rust-anything`) and run
31`rust-anything setup`, then restart the agent.
32 
33## 0. Profile: find what is worth moving
34 
35When the goal is speed, measure before choosing anything:
36 
37```sh
38rust-anything profile <repo> -- node bench.mjs # or: python3 bench.py, ruby bench.rb,
39 # java -cp out Main, go test -run X -bench . ./pkg
40```
41 
42It runs a real workload under the runtime's own profiler and lists hot functions with their
43callers and advice. Go profiles only through `go test`; C is not supported (use `perf`).
44 
45- A small function called once per item is **not** worth porting alone: one call into Rust costs
46 more than its work, and JITs (V8, the JVM, Go) run it in nanoseconds. Port it together with its
47 callers, or batch it (step 2b). The advice line says which, with the exact command.
48- Code that is already compiled (numba `@njit`, Cython, `@jax.jit`) runs as machine code: a Rust
49 port gains little speed. `profile` lists it under "Already compiled" and says so in the advice of
50 every hot function that calls it; tell the user before porting it for speed.
51- If the user only wants a migration, skip to step 1.
52 
53## 1. Plan, then stop
54 
55```sh
56rust-anything analyze <repo> -o plan.md # people
57rust-anything analyze <repo> --json # you: schema rust-anything/analyze@1
58```
59 
60- Present the `start_here` units (best first ports) and the order by package and wave.
61- Call out `keep` units (UI, editor code: they stay in the source language), `blocked` units and
62 their reason, and dependencies with fit `none` or `unknown`. Do not hand-roll a missing crate
63 silently: flag it.
64- **Wait for the user's approval of the plan and of the first unit.**
65 
66## 2. Port one unit
67 
68```sh
69rust-anything bridge <repo> <unit-id> # crate in <repo>/rust/<name>; never overwrites
70rust-anything record <crate> # the original's behavior on edge-case inputs -> cases.jsonl
71```
72 
73- Add real-world inputs with `--inputs cases.jsonl` (`{"fn": name, "args": [...]}` per line) when
74 the generated ones cannot reach the interesting paths (structured arguments, domain strings).
75- TS that cannot run directly in Node (extensionless imports, path aliases): record from built
76 output with `--module dist/x.mjs`, or pass `--node-arg=--import=tsx`.
77- If the original has no tests, `record` is the characterization suite: keep `cases.jsonl`.
78 
79Write the port in `src/port.rs` only; `src/lib.rs` and the wrappers are generated. After changing
80a signature in `port.rs`, run `rust-anything refresh <crate>`.
81 
82- Read each risk the plan lists for the unit, at its `file:line`, before writing code.
83- String offsets: JS and Java index UTF-16 code units, Rust UTF-8 bytes: use `src/utf16.rs`.
84- Errors: return `Err("TypeName: message")`; it becomes that exception in Python, Ruby and Java,
85 and the `error` text in Go.
86- Numbers in Python and Ruby: ints that the original passes through must come back as ints;
87 in Python ports use `crate::pynum::Num` for int-or-float, not `serde_json::Value`.
88- C: inputs recorded as `crash:` are undefined behavior; any result passes.
89- Ordered maps and object keys: `indexmap` where order reaches output.
90- Regex lookaround or backreferences: `fancy-regex`, not `regex`. Either way, `\w`, `\b`, `\d`
91 and case-insensitive matching treat non-ASCII text differently from the source language's
92 engine: passing the recorded cases is not enough. `record` adds regex traps (Turkish i, Kelvin
93 sign, joiners, non-ASCII digits and spaces) to functions in files that use regexes; ask the user
94 for real text the patterns see, record it with `--inputs`, and set `unicode(false)` or spell out
95 ASCII classes (`[A-Za-z0-9_]`) where the original's `\w` is ASCII-only (JS without `u`, Java).
96- No `unsafe`. If truly needed: minimal, isolated, with a `// SAFETY:` comment.
97- Add Rust unit tests in `port.rs` for the cases you reason about.
98 
99## 2b. Batch a hot loop
100 
101For a function called over many items (search, scoring, formatting a list):
102 
103```sh
104rust-anything bridge <repo> <unit> --batch fn:param # or: rust-anything refresh <crate> --batch fn:param
105```
106 
107This generates a class that takes the `param` values once and keeps them in Rust:
108`new FnBatch(items)` (TS, Python, Java), `Mod::FnBatch.new(items)` (Ruby), `NewFnBatch(items)`
109(Go). Per query, `run(<other args>)` returns every result as one array, and `rank(<other args>,
110min)` returns the item indexes, best first. It runs on all cores, and errors are the original's.
111Close the batch when done in Go and Java (finalizers are only a fallback).
112 
113- Make the caller build the batch once, not per query. Map returned indexes back to items with a
114 plain loop; in JS, `Array.from(order, fn)` costs 20x more.
115- To prepare items once (lowercase, masks, position tables), define `pub struct FnIndex` in
116 `port.rs` with `new(items)` and `run(<other args>) -> Result<Vec<R>, String>`. It must give the
117 same result as the function, item by item: test it against the function over every item.
118- When ranking can skip work, give the index its own `rank(<other args>, min) -> Result<Vec<u32>,
119 String>` (narrowing to the last query's matches as the user types, table lookups). It must
120 match ranking the function's results: score high to low, ties in item order.
121- A batch multiplies the port's per-item speed by the cores. Against compiled originals (Go,
122 Java) the port itself must be fast: handle ASCII without Unicode tables, build each result in one
123 pre-sized `String`, avoid intermediate copies. Keep `diff` passing.
124- Items and other arguments: numbers, booleans and strings (Ruby: any value); results: numbers,
125 booleans or strings. Not for C.
126 
127## 3. Prove it
128 
129```sh
130rust-anything build <crate>
131rust-anything diff <crate> # must be N/N
132rust-anything bench <crate> # original vs Rust, bridge included, with a verdict
133```
134 
135A mismatch is a behavior difference: fix the port, never the recording. If the difference is
136intended, ask the user first, then re-record with their approval.
137 
138Numeric code (physics, statistics, graphics) rarely gives bit-identical floats once ported:
139operation order, fused multiply-add and the math library differ. When the user accepts that,
140record with `--float-tolerance 1e-9` (their number): floats then match within that share of the
141larger value (absolute below 1), and `diff` and `gate` use it. Integers, strings and the same
142value written differently (`3` and `3.0`) still must match exactly. Never widen a tolerance to make
143a mismatch go away: a difference beyond it is a bug in the port.
144 
145Follow `bench`'s verdict: ship, keep the slower functions in the source language, or port a
146bigger unit (batch or include the callers). Do not ship a port that makes callers slower without
147saying so.
148 
149## 4. Ship it safely
150 
151```sh
152rust-anything shadow <crate> # drop-in with the original's API
153```
154 
155Load the shadow where the app loaded the original. `RUST_ANYTHING_MODE=shadow` (default) returns the
156original's results and reports Rust mismatches; `new` switches to Rust; `old` turns Rust off.
157The public API does not change.
158 
159## 5. Done means gate passes
160 
161```sh
162rust-anything gate <crate>
163```
164 
165fmt, clippy with warnings as errors, cargo tests, `unsafe` only with SAFETY comments, nothing
166`unimplemented!`, every place the original fails on purpose (`throw`, `raise`, an `error` result)
167reached by a recorded failing case (add one with `record --inputs` when gate names it), no
168`unwrap`, `expect` or `panic!` in a function whose original returns an error (return `Err`; for a
169state the original also treats as impossible, a `// INFALLIBLE: <why>` comment), the port at most
1703x the original's lines (over that, use the crates `analyze` lists and fold repeated code), the
171module builds, every export present, every recorded case matches. A Rust panic never matches a
172recorded error: return `Err` where the original throws.
173 
174Then report to the user, and **wait for their go-ahead before the next unit**:
175 
176- what changed (files, functions, bridge, batches),
177- gate output, diff counts and bench numbers,
178- behavior differences or risks left (e.g. error messages differ, a napi `String` refuses lone
179 surrogates), and what is left in the plan.
180 
View all files on GitHub →

Details

License
MIT
Stars on the repo
★ 1,854
Checked
Source
erkamyaman/rust-anything ↗
Creator
erkamyaman · 1 listing
View creator

Similar skills

See all →
Xberg Document Extractorxberg-io/xberg · by xberg-ioExtract text, tables, metadata, and images from 107 document formats (PDF, Office, images, HTML, email, archives, academic) using Xberg. Use when writing code that calls Xberg APIs in Python, Node.js/TypeScript, Rust, or CLI. Covers installation, extraction (sync/async), configuration (OCR, chunking, output format), batch processing, error handling, and plugins.★ 9.4k GitHub starsCode Migration Validatorkucherenko/jscpd · by kucherenkoMove code from one implementation to another function by function, tests first and code second, and check two implementations of one app for parity, with jscpd --compare as the progress measure and a coverage map binding each function to its tests. Use when porting a library or app to another language or framework (Java to Kotlin, JavaScript to Rust, a Python library to TypeScript, an iOS app to Android), when asked what is left to port, or when comparing the Android and iOS versions of an app.★ 6.3k GitHub starsAhrefs API ManagerOpenClaudia/openclaudia-skills · by OpenClaudiaManages Ahrefs API usage in Python using `ahrefs-python` library. Use when working with SEO / marketing related tasks or with data including backlinks, keywords, domain ratings, organic traffic, site audits, rank tracking, and brand monitoring. Covers `ahrefs-python` usage including AhrefsClient / AsyncAhrefsClient, typed request/response models, error handling, and all API sections.★ 705 GitHub starsDocx to Markdown Translatordealfluence/adeu · by dealfluenceDocx ↔ LLM translator. Projects .docx office files to Markdown for editing. Projects edits back to OOXML as tracked changes (redlines). Python and Node.js implementations.★ 165 GitHub starsSendmux SDKSendmux/sendmux-sdk · by SendmuxOfficial monorepo of SDKs, CLI, and MCP servers for Sendmux email APIs across TypeScript, Python, Go, PHP, Rust, and Ruby.★ 65 GitHub starsSource-Driven Developmentaddyosmani/agent-skills · by addyosmaniGrounds every implementation decision in official documentation. Use when you want to verify an approach against the official docs before implementing it, or when you want authoritative, source-cited code free from outdated patterns. Use when building with any framework or library where correctness matters.★ 98.7k GitHub stars