Quickstart: Claude Code & Codex

Install Ratel Local

Install the CLI globally so the background service has a durable executable:

npm install --global @ratel-ai/ratel-local
ratel-local --version

The version command should print a version number. The package and CLI are @ratel-ai/ratel-local and ratel-local.

Run setup

ratel-local setup

The wizard:

• installs, replaces, or starts the per-user daemon;
• detects Claude Code and Codex, then asks which agents to connect;
• installs the Ratel Local plugin for each selected agent, with an explicit MCP fallback only if plugin installation fails;
• offers existing MCP servers and skills as a separate previewed import;
• confirms before committing an import and backs up changed configuration.

Stable packages use the Ratel marketplace from the repository's default main branch. Leave the marketplace reference at its default for stable releases.

Setup is idempotent. A matching running daemon is a no-op, and existing agent links are reconciled safely.

Check the daemon and agent link

ratel-local daemon status

The daemon should report running and its loopback endpoint. The earlier version check confirms the CLI is available. Then inspect the selected host:

claude mcp get ratel-local

codex mcp get ratel-local --json

The plugin runs npx -y @ratel-ai/ratel-local connect. The connector sends the resolved project root to the authenticated loopback daemon; it does not start a second full gateway process.

Add an upstream

Add servers directly to Ratel when you did not import existing ones:

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

Use --scope project for team configuration or --scope local for machine-specific project configuration. Reconnect the agent after changing the effective catalog.

If the first package download or upstream probe stalls, see First-run networking.

Verify capability search

Ask the agent to call Ratel 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. The full request and response contract is on Progressive disclosure tools.