Skip to content

AI client integrations#

SafeLint ships skills / project rules for AI coding clients so you can ask the agent things like "run safelint", "lint my changes", or "do a Power-of-Ten review on src/api/auth.py" and have it invoke safelint check correctly, parse the JSON output, and present the violations in a reviewable format.

Quick start#

# Pick the extra matching your project's language(s): v2.0.0+
# ships each grammar separately:
pip install 'safelint[python]'        # or: uv add 'safelint[python]'
# pip install 'safelint[javascript]'  # JS / Node
# pip install 'safelint[typescript]'  # TypeScript (bundles JS too)
# pip install 'safelint[all]'         # kitchen-sink

safelint skill install                # auto-detects AI clients AND language grammars

safelint skill install runs two auto-detections back-to-back:

  1. AI clients, looks for markers (CLAUDE.md, .cursor/, .github/copilot-instructions.md, etc.) in the current directory or your home directory, then installs each detected client's skill at the matching scope.
  2. Language grammars (new in v2.0.0rc1), walks the project tree for source-file extensions, compares against the extras currently installed, and emits one composed install line if any grammars are missing. Example output for a Python + TypeScript monorepo with neither grammar installed:
safelint: warning: Detected source files for 2 languages (python, typescript) whose tree-sitter grammar isn't installed. Run: pip install 'safelint[python,typescript]'

You run the single composed command and you're set up for every language in the repo. Silent when every needed grammar is already installed.

After install, restart the AI client (or reload its window) and ask things like "run safelint".

Supported clients#

Rows are ordered by approximate real-world usage as of mid-2026; the precise rank is subjective (no clean public dataset for AI-agent market share), but the rough buckets are mainstream (GitHub Copilot / Cursor / Claude Code), mid-tier (codex / Gemini / Windsurf), lower (Continue.dev / Cline / Zed / Warp / Kiro / aider), and niche (Antigravity / Trae). The registry order in _skill_install.py is unchanged by this ordering (it drives auto-detection, install-loop, and CLI-output sequencing where popularity isn't the right axis); only this table and the sidebar nav reflect the popularity view.

Client Native format Install destination Detection markers
GitHub Copilot Instructions Markdown ~/.github/copilot-instructions.md (user-global) or <cwd>/.github/copilot-instructions.md (project, canonical) .github/copilot-instructions.md, .github/copilot/, or .github/instructions/ in cwd; ~/.github/copilot-instructions.md for user-scope
Cursor Project Rule (.mdc file) ~/.cursor/rules/safelint.mdc (user) or <cwd>/.cursor/rules/safelint.mdc (project) .cursor/ or .cursorrules in cwd; ~/.cursor/ for user-scope
Claude Code Skill manifest (SKILL.md) ~/.claude/skills/safelint/SKILL.md (user) or <cwd>/.claude/skills/safelint/SKILL.md (project) CLAUDE.md, .claude/, or .claude.json in cwd; ~/.claude/ or ~/.claude.json for user-scope
codex Markdown instructions (.codex/instructions.md); also writes a delimited section into AGENTS.md when present ~/.codex/instructions.md (user) or <cwd>/.codex/instructions.md (project), plus <scope>/AGENTS.md (section-only edit) when that file already exists .codex/, AGENTS.md, or .opencode/ in cwd; ~/.codex/ for user-scope
Gemini Instructions Markdown (GEMINI.md) ~/GEMINI.md (user-global) or <cwd>/GEMINI.md (project, canonical, auto-discovered by Gemini CLI) GEMINI.md or .gemini/ in cwd; ~/.gemini/ for user-scope
Windsurf Project rules (.windsurfrules) ~/.windsurfrules (user-global) or <cwd>/.windsurfrules (project, canonical, auto-loaded by Windsurf) .windsurfrules or .codeium/ in cwd; ~/.codeium/ for user-scope
Continue.dev Markdown rule (.continue/rules/<name>.md) ~/.continue/rules/safelint.md (user) or <cwd>/.continue/rules/safelint.md (project) .continue/, .continuerc, or .continuerc.json in cwd; ~/.continue/ for user-scope
Cline Markdown rule (.clinerules/<name>.md) ~/.clinerules/safelint.md (user) or <cwd>/.clinerules/safelint.md (project) .clinerules/ in cwd; ~/.clinerules/ for user-scope
Zed Workspace rules (.rules) ~/.rules (user) or <cwd>/.rules (project) .rules or .zed/ in cwd; ~/.rules or ~/.zed/ for user-scope
Warp Instructions Markdown (WARP.md) <cwd>/WARP.md (project-scope only; Warp doesn't read any user-scope file, "Global Rules" go through Warp Drive UI) WARP.md or .warp/ in cwd
Kiro Steering file (.kiro/steering/<name>.md) ~/.kiro/steering/safelint.md (user) or <cwd>/.kiro/steering/safelint.md (project) .kiro/ in cwd; ~/.kiro/ for user-scope
aider Markdown conventions (CONVENTIONS.md), not auto-loaded; wire via read: in .aider.conf.yml ~/CONVENTIONS.md (user) or <cwd>/CONVENTIONS.md (project) .aider.conf.yml, .aider.conf.yaml, or CONVENTIONS.md in cwd; ~/.aider.conf.{yml,yaml} for user-scope
Antigravity Markdown rule (.antigravity/rules/<name>.md) ~/.antigravity/rules/safelint.md (user) or <cwd>/.antigravity/rules/safelint.md (project) .antigravity/ in cwd; ~/.antigravity/ for user-scope
Trae Markdown rule (.trae/rules/<name>.md) ~/.trae/rules/safelint.md (user) or <cwd>/.trae/rules/safelint.md (project) .trae/ in cwd; ~/.trae/ for user-scope

OpenCode (sst/opencode) isn't a separate client entry. OpenCode reads AGENTS.md for project context, which is the same file the codex spec's secondary install populates with a delimited safelint section. .opencode/ is therefore listed as a cwd marker on the codex spec, so --client=auto notices these projects. When the project has .opencode/ but no AGENTS.md yet, safelint auto-creates AGENTS.md (the file is OpenCode's only safelint integration point); when AGENTS.md already exists, existing content is preserved and the safelint section is appended via the section-delimited write path. See the codex page for the full lifecycle.

The registry in _skill_install.py is open-ended, adding a new client is a one-ClientSpec change. See Adding a new AI client for the full walkthrough. If you'd like to see another client supported, file a feature request with the marker convention you've seen in the wild.

How auto-detection works#

safelint skill install (no --client) is --client auto under the hood. The detection is two-tier:

[1] cwd has any client markers?
       │
       ├── yes ──→  install for each detected client, project-scoped
       │
       └── no
              │
              ▼
   [2] home has any client markers?
       │
       ├── yes ──→  install for each detected client, user-scoped
       │
       └── no  ──→  error: print explicit --client commands and exit 1

Step [2] (the home fallback) skips project-scope-only clients such as Warp: they have no user-scope file, so they're never installed at home scope. See Project vs user scope.

Multi-detection#

If multiple clients are present, all of them are installed in the same run. The output prints the detected clients and a per-client success block:

safelint: detected Claude Code (CLAUDE.md) and Cursor (.cursor) in current directory
safelint: Claude Code skill copied to /repo/.claude/skills/safelint/SKILL.md (project scope)
  → Restart Claude Code (or open a new session) to pick up the skill.
  → Then ask Claude Code "run safelint" or "lint with safelint".
safelint: Cursor rule copied to /repo/.cursor/rules/safelint.mdc (project scope)
  → Restart Cursor (or reload the window) to pick up the new rule.
  → Then ask Cursor "run safelint" or "lint with safelint".

--project flag with auto#

--client auto --project restricts detection to the current directory only, no home fallback. Useful when you want to commit the skill into your repo but don't want a surprise install at the home location if the cwd happens to have no markers yet.

Lifecycle and scope#

The dedicated topic pages cover everything past first-time install:

See also#