rtk-ai/rtk

Add `fnm` (Fast Node Manager) handler + hook routing

Open

#1538 opened on Apr 26, 2026

View on GitHub
 (2 comments) (0 reactions) (0 assignees)Rust (48,085 stars) (2,914 forks)batch import
effort-mediumenhancementgood first issue

Description

Summary

fnm is a popular Node version manager (Rust, ~14k stars) with no RTK handler in 0.37.2. Common dev shells initialize Node via eval "$(fnm env)" and switch versions via fnm use. rtk hook check returns "No rewrite" for both. From 30 days of rtk discover:

fnm use                    126    fnm use 20 2>&1
eval "$(fnm                123    eval "$(fnm env)"

249 invocations / 30 days, almost entirely from session-init / Node-version-switch context. Output is normally short (1-3 lines), but the volume + the fact that they appear in nearly every session that touches Node makes them a base-rate pain point — ~5-8% of all Claude Code Bash calls.

Why a handler matters even though output is small

  • Session init noise: every shell init runs eval "$(fnm env)". Even 3 lines × thousands of sessions = measurable.
  • Error path is verbose: fnm use <missing-version> prints multi-line install hints. RTK could compress to one-line "missing version 22, run fnm install 22".
  • Pairs naturally with existing npm/npx/pnpm/vitest/jest handlers — RTK already supports the JS/TS toolchain extensively; fnm is the standard env-bootstrap tool for that ecosystem on macOS/Linux.

Proposed approach (not prescribing)

Two-tier handling, similar to how pnpm/npx are wrapped:

  1. rtk fnm use <version> — strip the post-switch table that lists installed versions (typically 5-10 lines), keep just Using Node v<X>.
  2. rtk fnm env — passthrough as-is (the eval'd output IS the environment; can't compress without breaking).
  3. Hook routing whitelist additions: fnm, eval "$(fnm env)" (the latter needs lexer awareness — see PR #156's lexer for prior art on command/exec/noglob prefix stripping).

Related

  • #599 "Add support for Bun" — open, includes nvm use 30/30d in their rtk discover output (nvm is conceptually similar to fnm; could be addressed together as a "Node version manager family")
  • #361 / PR #156 (hook engine v2 — hook_lookup() whitelist will need fnm entry)

Environment

  • rtk: 0.37.2
  • fnm version observed: latest (Linux WSL2)
  • Multi-language project (Java/Spring Boot backend + Next.js frontend), so the Node toolchain is touched ~daily

Contributor guide

Tech stack
rustnodejsshell
Domain
clideveloper experience
Issue type
feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
half day
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
Rust programmingCLI developmentShell hook routing
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
70
Research direction
Review PR #156 for hook routing implementation and the lexer for command prefix stripping. Look at #599 for nvm handler as a reference for Node version manager handlers. The handler should be added in the module for Node toolchain handlers, and the hook lookup whitelist in hook lookup() needs to include 'fnm' and 'eval "$(fnm env)"'.