npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@ratel-ai/ratel-local

v0.9.0

Published

Ratel Local package: a project-scoped persistent MCP gateway with BM25, semantic, and hybrid capability search plus the ratel-local CLI.

Readme

Ratel Local gives coding agents one searchable catalog instead of every tool schema from every upstream MCP server. Tools and skill instructions enter context only when the agent needs them, with no agent-code changes.

It ships as the npm package @ratel-ai/ratel-local and the ratel-local CLI. The package also exposes library APIs for serving a Ratel ToolCatalog over MCP.

Why Ratel Local

  • Smaller context: upstream tool schemas and skill bodies stay out of the prompt until they are relevant.
  • Better tool selection: capability search gives the model a focused set of choices. See the benchmarks.
  • Fits existing setups: bring the MCP servers you already use in Claude Code, Codex, Cursor, and other MCP clients.
  • Runs locally: Ratel Local runs on your machine; configuration and upstream credentials are stored locally.

Quickstart

The recommended entrypoint is the complete setup wizard. It prepares the persistent daemon, detects Claude Code and Codex, connects the agents you select, and offers existing MCP servers and skills as a separate reviewed import.

This README tracks the 0.9.0 stable release, matching the package version pinned by the bundled plugin. Unqualified npm installs resolve the latest dist-tag; the examples below remain exact-versioned for reproducibility.

The CLI and UI prefer the ratel-local plugin when linking because it bundles the gateway and agent skills. Stable builds use the Ratel marketplace from the repository's default main branch. Prerelease builds alone pin the same marketplace identity to their immutable matching release tag: Codex uses --ref, while Claude Code uses the equivalent owner/repo@ref source. Stable 0.9.0 therefore carries no RC branch or tag override.

If an agent already has the plugin, link reconciles that marketplace channel and reinstalls the plugin. It verifies that an RC tag exists before changing a working installation and attempts to restore the stable plugin if an RC switch fails after removal. When stable is restored, the command preserves that connection but reports the RC setup as failed rather than claiming the requested channel is active. If no usable plugin remains, a new link uses the reviewed explicit MCP gateway fallback; a failed existing-plugin reconciliation stops with an error. Importing still recognizes an enabled plugin as an existing Ratel connection and does not add a second gateway. If the Codex plugin is enabled but its bundled Ratel MCP server is disabled, link re-enables that server. Agent Setup offers Fix duplicate installation when both the plugin and an explicit Ratel MCP entry are present, and Switch to plugin for MCP-only installations. Both actions preserve the existing MCP connection unless plugin installation succeeds, and only recognized Ratel entries are removed.

Complete interactive onboarding

1. Install the CLI

Node.js 20.6 or newer is required.

npm install --global @ratel-ai/[email protected]
ratel-local --version

2. Run setup

ratel-local setup

The wizard:

  • installs, upgrades, or starts the per-user daemon;
  • detects Claude Code and Codex and asks which agents to connect;
  • installs the Ratel Local plugin for each selected agent, using the reviewed explicit MCP connector only if plugin installation fails;
  • separately offers to preview MCP servers and skills from selected agents;
  • asks for confirmation before committing an import and backs up changed configuration.

Re-running setup is safe. A matching daemon is reported as a no-op, while existing plugin links are checked against the package's stable or prerelease marketplace channel.

If you do not have a global installation, run the release-pinned package:

npx -y @ratel-ai/[email protected] setup

3. Confirm Ratel Local and restart

# Claude Code
claude mcp get ratel-local

# Codex
codex mcp get ratel-local --json

Confirm that ratel-local is connected or enabled, then restart Claude Code or start a new Codex session.

Safe automation

Plain --yes retains the old safe behavior and changes only the daemon:

ratel-local setup --yes
ratel-local setup --daemon-only --yes

Agent changes require explicit selection. Repeat --agent, or use auto to connect every detected supported agent:

ratel-local setup --yes --agent claude-code --agent codex
ratel-local setup --yes --agent auto

Automated setup never imports native MCP servers or skills. Use the explicit expert command when migration is intended:

ratel-local import --yes --agent claude-code
ratel-local import --yes --agent codex

--port N selects the first-install daemon port. --daemon-only cannot be combined with --agent.

Expert commands

The lower-level workflows remain available for targeted repair, scripting, and debugging:

# Daemon lifecycle
ratel-local daemon install
ratel-local daemon start
ratel-local daemon status

# Connect without importing native entries
ratel-local link --agent claude-code
ratel-local link --agent codex

# Preview and confirm one agent migration
ratel-local import --agent claude-code
ratel-local import --agent codex

daemon start is idempotent: when the service is already healthy it leaves the daemon and active MCP sessions running. During a slow cold start, the connector waits for the daemon handshake and then exposes the complete catalog. Bootstrap tools appear only after attachment actually fails or a live connection is later lost; they check status before recovery and can safely attach to the running service. Set RATEL_FEATURE_CONNECTOR_RECOVERY=1 on connector processes to opt into bounded automatic reattachment after later daemon interruptions; this rollout flag is off by default.

Add new upstreams directly after onboarding:

ratel-local mcp add --scope user context7 -- npx -y @upstash/context7-mcp
ratel-local mcp list

Opt-in semantic and hybrid retrieval

BM25 remains the model-free default. The 0.7.0 feature line adds scoped semantic and hybrid retrieval with explicit model preflight:

ratel-local retrieval status
ratel-local retrieval configure --scope project --method hybrid --source built-in
ratel-local retrieval prepare --scope project

Reconnect the affected agent after changing retrieval so it acquires the new immutable gateway generation. See the retrieval configuration and preflight guide for local, Hugging Face, Ollama, and OpenAI-compatible embedding sources plus privacy and memory guidance.

Experimental Cloud telemetry

Native Claude Code and Codex telemetry relay plus Ratel runtime trace export ship dark. Enable the daemon-wide feature explicitly before configuring an API key or native exporter:

# New installation
RATEL_FEATURE_CLOUD_TELEMETRY=1 ratel-local setup

# Existing installed daemon
RATEL_FEATURE_CLOUD_TELEMETRY=1 ratel-local daemon restart

# Disable
RATEL_FEATURE_CLOUD_TELEMETRY=0 ratel-local daemon restart

ratel-local traces status

Only the exact value 1 enables the feature; any other value disables it. The setting is persisted into the installed launchd or systemd service, and omitting the variable leaves an installed daemon unchanged. See the Cloud OTLP relay and native exporter setup contract for privacy levels, precedence, failure behavior, and rollback instructions.

Experimental Cloud skill catalog

A project's skills published to Ratel Cloud can join the locally resolved skill set, served through the same gateway and the same capability search as local ones. Off by default:

# New installation
RATEL_FEATURE_CLOUD_CATALOG=1 ratel-local setup

# Existing installed daemon
RATEL_FEATURE_CLOUD_CATALOG=1 ratel-local daemon restart

# Disable
RATEL_FEATURE_CLOUD_CATALOG=0 ratel-local daemon restart

The flag follows same flag semantics as Cloud telemetry above, and the two are independent.

The catalog reuses the credential the trace relay stores in ~/.ratel/cloud-traces.json, read on every pull, so a rotated key applies without a restart.

A local skill with the same id wins, and the shadowed Cloud one is reported as a warning in the daemon UI. An unreachable or stale catalog is a warning too, never a failed context resolve.

Verify capability search

Ask the agent to call Ratel Local explicitly:

Call Ratel's search_capabilities tool with:
{"query":"look up current React framework documentation","topKTools":3,"topKSkills":1}
Return the raw result.

The result should contain a tools bucket with matching upstream tools and a skills bucket. You are now using Ratel Local's on-demand capability search.

For troubleshooting and the complete setup guide, see the Ratel Local quickstart.

For configuration scopes, OAuth, skills, the local UI, telemetry, and library usage, see the Ratel Local Docs. Repository contributors can also read the retrieval configuration and preflight guide and the Cloud OTLP relay and native exporter setup contract.

How it works

Ratel Local reads your layered mcpServers configuration, connects to each upstream, and registers its tools in one Ratel catalog.

Your MCP client sees capability tools instead of the full upstream catalog. search_capabilities finds relevant tools and skills, and invoke_tool runs a selected tool.

When skills are configured, get_skill_content loads their instructions.

The CLI manages upstreams, agent imports and links, OAuth, skills, backups, the browser UI, and the Claude Code statusline. The docs are the source of truth for commands and configuration.

Development

Development requires Node.js 24+ and pnpm 10+.

pnpm install
pnpm build
pnpm typecheck
pnpm lint
pnpm test

See CONTRIBUTING.md for the development workflow.

License

MIT. See LICENSE.md.