Install & first run
v0.0.4Revision 587c8ae
Roster 0.0.4 is published.
The selected package is @npmmo/roster, with executable roster. Never use the unscoped npm package: it is an unrelated system-user utility. Registry state last checked 2026-09-14.
Set up Roster
Section titled “Set up Roster”Use Node 22.17 or newer within Node 22.x, or Node 24.2 or newer, with npm and npx installed. The standard Node installer includes both. Check your runtime with node --version; affected older Windows/libuv builds are refused before local state changes.
Choose your terminal, copy the command, and run it. It downloads the pinned scoped package into npm’s cache and runs init --no-dense. No global installation or separate init command is needed.
npx --yes @npmmo/roster@0.0.4 init --no-densenpx.cmd --yes @npmmo/roster@0.0.4 init --no-denseLook for the Day-0 receipt. Roster has discovered your setup and prepared private local state. It has not rewritten your client files or installed an embedding model.
The Windows command uses npx.cmd in either PowerShell or Command Prompt, without changing PowerShell’s execution policy. Your terminal choice follows you through these guides.
Discover without rewriting clients
Section titled “Discover without rewriting clients”init reads known client configuration locations and imports server definitions into ~/.roster/roster.json. It also discovers skill sources and prints a Day-0 receipt. It does not rewrite client configuration files.
Imported server definitions can contain environment credentials. The local configuration and backups are private; do not paste their raw contents or receipt paths into chat or public issues.
Review the receipt for discovered clients, server counts, skill counts, and parse errors. Counts are inventory, not a measured tool-selection accuracy or token-savings benchmark. If a client is missing, configure that client first, then repeat discovery using the command above.
Check the CLI or an existing installation
npx --yes @npmmo/roster@0.0.4 --helpnpx.cmd --yes @npmmo/roster@0.0.4 --helpRoster supports help and --help, but not --version. A bare command named roster can belong to another package. The pinned scoped commands in this guide select this project without relying on a global executable.
Keep the first run lexical
Section titled “Keep the first run lexical”Lexical retrieval works without a model. --no-dense skips the optional runtime-install question; it does not persistently disable embeddings.
A source checkout already includes the embedding runtime among its workspace dependencies. Before starting a client, change just the embeddings field in the existing ~/.roster/roster.json to "off". Preserve every other field, especially the imported servers. This prevents the source installation from starting a first-use model download.
Later, you can deliberately enable optional semantic retrieval.
Connect one client
Section titled “Connect one client”For example, if Cursor is your intended target:
npx --yes @npmmo/roster@0.0.4 sync --client cursornpx.cmd --yes @npmmo/roster@0.0.4 sync --client cursorUse the client you actually want to connect: claude-code, cursor, codex, or openclaw. Read the reported config path before proceeding. Sync selects the first existing supported path for that client, imports the server definitions, backs up the original, and replaces its MCP server map with one Roster launcher. URL-only servers and unsupported client-specific settings cause refusal before mutation.
Restart the client or its MCP connection. The client launches serve over stdio. You do not need to run a second Roster process in a terminal or start a hosted service.
Transparent mode is the default. Once this setup works, choose five mode.
Know the way back
Section titled “Know the way back”Use the matching scoped eject command:
npx --yes @npmmo/roster@0.0.4 eject --client cursornpx.cmd --yes @npmmo/roster@0.0.4 eject --client cursorDedicated configs restore byte-for-byte when unchanged since sync. Supported live-state files restore at key level while preserving later user changes. If eject refuses a conflict, inspect it; do not add --force as a routine workaround.
Prefer a global installation?
This is optional. The npx commands above already work without it.
npm install --global @npmmo/roster@0.0.4npm.cmd install --global @npmmo/roster@0.0.4After a successful global installation, you can use roster in place of the pinned npx prefix, or roster.cmd in Windows PowerShell. Check the package and path if a command with that name already exists. Do not use elevated permissions or force flags as an automatic workaround for an installation conflict.