Skip to content

How to install Astral's plugin for Claude Code

by Tim Hopper · Markdown
AI Assistants uv Ruff ty

Astral, now part of OpenAI, publishes the Astral plugin for Claude Code that bundles three skills (/astral:uv, /astral:ruff, /astral:ty) and a ty language server. The skills give Claude up-to-date usage guidance for each tool, and the language server feeds live type-checking diagnostics into the conversation.

Tip

The project setup tutorial installs this plugin as part of a complete Claude Code configuration on a fresh uv project.

Prerequisites

Install the plugin for yourself

1. Add Astral’s marketplace

Run this slash command inside Claude Code:

/plugin marketplace add astral-sh/claude-code-plugins

2. Install the plugin 

/plugin install astral@astral-sh

Open /plugin to confirm the plugin is enabled. If Claude Code requests a reload, run /reload-plugins, then type / and confirm /astral:uv, /astral:ruff, and /astral:ty appear. The default install scope is personal; use the project configuration in the next section to share the recommendation with a team.

Install the plugin for your team

To enable the plugin for everyone who works in a repository, add the following to .claude/settings.json at the project root:

{
  "extraKnownMarketplaces": {
    "astral-sh": {
      "source": {
        "source": "github",
        "repo": "astral-sh/claude-code-plugins"
      }
    }
  },
  "enabledPlugins": {
    "astral@astral-sh": true
  }
}

Team members will be prompted to install the plugin when they trust the repository.

Use the skills

Once installed, invoke a skill by name to load its guidance:

Skill What it covers
/astral:uv Project setup, dependency management, scripts, and the pip compatibility interface
/astral:ruff Linting with ruff check, formatting with ruff format, and migration from Black, Flake8, or isort
/astral:ty Type checking with ty check, rule configuration, and migration from mypy or pyright

Claude can also select a skill from a matching natural-language request. Invoke the slash command explicitly when you want to ensure it loads. A project CLAUDE.md reminder can encourage use:

When working with Python, invoke the relevant `/astral:<skill>` for `uv`, `ty`, and `ruff` to ensure best practices are followed.

What the language server provides

The plugin declares a ty language server for .py and .pyi files. When the server starts successfully, it supplies diagnostics during editing. Inspect /plugin for startup errors and verify a known type error is reported; keep the project’s CLI type check in CI. The language server requires uvx to be available on PATH because it runs uvx ty@latest server under the hood.

A plugin supplies instructions and tool integrations, not a guarantee that their output is correct. Review its source before installation and keep the plugin updated through /plugin. Installation on your workstation does not make it available in every cloud session; cloud plugin support and scope differ from local sessions.

Last updated on