Caruso is a tool that bridges the gap between AI coding assistants. It allows you to take "steering documentation" (rules, context, capabilities) from Claude Code Marketplaces and make them available to Cursor.

Enable Cursor to consume Claude Code plugins from marketplaces by converting them to Cursor-compatible rules.

• One-time Configuration: Initialize once with caruso init --ide=cursor and all commands automatically use the right settings.
• Universal Fetcher: Downloads plugins from local paths, HTTP URLs, or GitHub repositories.
• Smart Adapter: Automatically converts Claude Plugin Markdown files into Cursor Rules (.mdc), injecting necessary metadata (globs: [], alwaysApply: false) to ensure they work out of the box.
• Package Manager: Install, uninstall, and list plugins selectively. Tracks project configuration in caruso.json and local state in .caruso.local.json.

gem install caruso

Verify the installation:

caruso version

For development or testing unreleased features:

git clone https://github.com/pcomans/caruso.git
cd caruso
gem build caruso.gemspec
gem install caruso-*.gem

Caruso mirrors the Claude Code CLI structure, providing a familiar interface for marketplace and plugin management.

Before using Caruso, initialize it in your project directory:

# Navigate to your project
cd /path/to/your/project

# Initialize for Cursor (currently the only supported IDE)
caruso init --ide=cursor

This creates a caruso.json config file for project settings and .caruso.local.json for local state. You only need to do this once per project.

What happens during init:

• Creates caruso.json and .caruso.local.json in your project root
• Configures target directory (.cursor/rules for Cursor)
• All subsequent commands automatically use this configuration

Version Control:

• ✅ Commit to VCS: caruso.json - Contains project plugin configuration (shared with team)
• ❌ Add to .gitignore: .caruso.local.json - Contains local state (machine-specific)
• ❌ Add to .gitignore: .cursor/rules/caruso/ - Generated plugin files (build artifacts)

Add these to your .gitignore:

# Caruso
.caruso.local.json
.cursor/rules/caruso/

Manage plugin marketplaces to discover and install plugins from different sources.

Add the official Claude Code marketplace:

caruso marketplace add https://github.com/anthropics/claude-code

The marketplace name is automatically read from the marketplace.json file in the repository (in this case, claude-code-plugins).

Supported marketplace sources:

• GitHub repositories: https://github.com/owner/repo
• Git repositories: Any Git URL (e.g., https://gitlab.com/company/plugins.git)
• Local paths: ./path/to/marketplace or ./path/to/marketplace.json

View all configured marketplaces:

caruso marketplace list

Remove a marketplace from your configuration:

caruso marketplace remove claude-code

Discover, install, and manage plugins from configured marketplaces.

See all available plugins across configured marketplaces:

caruso plugin list

This shows:

• All plugins from each marketplace
• Installation status for each plugin
• Plugin descriptions

Install from a specific marketplace:

caruso plugin install frontend-design@claude-code

Install when only one marketplace is configured (marketplace name is optional):

caruso plugin install frontend-design

What happens during installation:

1. Fetches plugin files from the marketplace
2. Scans commands/, agents/, and skills/ directories
3. Converts Claude Plugin Markdown to Cursor Rules (.mdc format)
4. Injects Cursor-specific metadata (globs: [], alwaysApply: false)
5. Saves converted files to .cursor/rules/caruso/ (vendor directory)
6. Updates .caruso.local.json with installed file list

Remove a plugin and update the manifest:

caruso plugin uninstall frontend-design

Here's a complete workflow from initialization to plugin installation:

# 1. Initialize Caruso in your project
caruso init --ide=cursor

# 2. Add the official Claude Code marketplace
caruso marketplace add https://github.com/anthropics/claude-code

# 3. Browse available plugins
caruso plugin list

# 4. Install a plugin
caruso plugin install frontend-design@claude-code

# 5. Your Cursor rules are now updated!
# 5. Your Cursor rules are now updated!
# Files are in .cursor/rules/caruso/ and tracked in .caruso.local.json

caruso init [PATH] --ide=IDE

Initialize Caruso in a directory. Creates caruso.json and .caruso.local.json.

Arguments:

• PATH - Project directory (optional, defaults to current directory)

Options:

• --ide - Target IDE (required). Currently supported: cursor

Examples:

caruso init --ide=cursor                    # Initialize current directory
caruso init . --ide=cursor                  # Explicit current directory
caruso init /path/to/project --ide=cursor   # Initialize specific directory

caruso marketplace add URL             # Add a marketplace (name from marketplace.json)
caruso marketplace list                # List configured marketplaces
caruso marketplace remove NAME         # Remove a marketplace

caruso plugin list                     # List available and installed plugins
caruso plugin install PLUGIN[@MARKETPLACE]  # Install a plugin
caruso plugin uninstall PLUGIN         # Uninstall a plugin

caruso version                         # Print Caruso version

Caruso translates the interface between Claude Code and Cursor (file formats, event names, output protocols), but it cannot translate plugin internals. Hooks and scripts that depend on Claude Code-specific runtime behavior — such as reading the session transcript, checking stop_hook_active, or using CLAUDE_ENV_FILE — will not work in Cursor because those conventions don't exist there. Plugins that rely on these internals need to be adapted upstream to handle missing fields gracefully.

1. Init: Creates caruso.json and .caruso.local.json (one-time setup)
2. Fetch: Resolves marketplace URI and clones Git repositories if needed
3. Scan: Finds "steering files" in commands/, agents/, and skills/ directories
4. Adapt: Converts Claude Plugin Markdown to Cursor Rules (.mdc) with metadata injection
5. Manage: Tracks installations in .caruso.local.json and project plugins in caruso.json

After checking out the repo:

# Install dependencies
bundle install

# Build and install the gem locally
gem build caruso.gemspec
gem install caruso-*.gem

# Run tests
bundle exec rake spec

Caruso includes comprehensive test coverage with RSpec integration tests.

Quick test (offline tests only):

bundle exec rake spec

All tests including live marketplace integration:

bundle exec rake spec:all
# or
RUN_LIVE_TESTS=true bundle exec rspec

Only live tests:

bundle exec rake spec:live

Run specific test file:

bundle exec rspec spec/integration/init_spec.rb

Integration tests are organized in spec/integration/:

• init_spec.rb - Initialization and configuration tests
• marketplace_spec.rb - Marketplace management (add, list, remove)
• plugin_spec.rb - Plugin installation and uninstallation
• file_validation_spec.rb - .mdc file structure and manifest validation

Tests marked with :live tag require network access and interact with the real Claude Code marketplace:

• Plugin installation
• File conversion validation
• Marketplace fetching

To run live tests, set RUN_LIVE_TESTS=true or use rake spec:all.

✓ Initialization

• Config file creation and validation
• IDE selection
• Double-init prevention
• Error handling

✓ Marketplace Management

• Adding marketplaces (GitHub, Git, local)
• Listing marketplaces
• Removing marketplaces
• Manifest structure

✓ Plugin Management

• Listing available plugins
• Installing plugins (explicit/implicit marketplace)
• Uninstalling plugins
• Installation status tracking

✓ File Validation

• .mdc file structure (frontmatter, globs, content)
• File naming conventions
• Manifest accuracy
• No orphaned files

For detailed testing documentation, see TESTING.md.

The gem is available as open source under the terms of the MIT License.