Metadata-Version: 2.4
Name: amagi-name-check
Version: 0.1.0
Summary: Check a project name against PyPI, npm, crates.io, Homebrew, GitHub and common domains in one command, with near-collision warnings.
Author-email: "AmagiLabs (Amagisolutionsgroup, Inc.)" <dev@amagisolutionsgroup.com>
License: MIT
Project-URL: Homepage, https://github.com/amagilabs/amagi-name-check
Keywords: naming,package-name,pypi,npm,crates,homebrew,github,domains,rdap,cli
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# amagi-name-check

Check a name for your next package or repo on PyPI, npm, crates.io, Homebrew, GitHub and six domain TLDs in one command, and see which existing projects it is too close to.

![demo](https://raw.githubusercontent.com/amagilabs/amagi-name-check/master/assets/demo.gif)

## Install

```bash
pipx install amagi-name-check
```

Python 3.9 or newer. No dependencies outside the standard library.

## Usage

```bash
amagi-name-check vidscan
```

We wrote this after "vidscan", the first name we picked for one of our video tools, turned out to be taken. This is the check we had done by hand, as one command (output from 2026-10-21):

```
amagi-name-check: vidscan

  CHECK             NAME         STATUS     DETAIL
  PyPI              vidscan      taken      1.0.0 - Concurrent media library scanner - folder and...
  npm               vidscan      available
  crates.io         vidscan      available
  Homebrew formula  vidscan      available
  Homebrew cask     vidscan      available
  GitHub user/org   vidscan      taken      User vidscan
  GitHub repos      vidscan      in use     7 repos; top ompatel-io/vidscan (5 stars)
  Domain            vidscan.com  taken      registered 2018-05-14 (RDAP)
  Domain            vidscan.dev  available  not registered (RDAP)
  Domain            vidscan.io   available  not registered (WHOIS)
  Domain            vidscan.app  taken      registered 2026-06-04 (RDAP)
  Domain            vidscan.ai   available  not registered (RDAP)
  Domain            vidscan.org  available  not registered (RDAP)

Summary: 8 available, 4 taken, 1 in use
```

The exit code is 1 because something is taken.

### Names a registry will refuse

An exact-name lookup says `data-classes` is free on PyPI and npm. Neither registry will accept it:

```bash
amagi-name-check data-classes --only pypi,npm,crates
```

```
amagi-name-check: data-classes

  CHECK      NAME          STATUS     DETAIL
  PyPI       data-classes  available
  npm        data-classes  available
  crates.io  data-classes  taken      0.0.0-19 - Abbreviation of #[derive(xxx)]

Near-collisions:
  BLOCK  PyPI       dataclasses: PyPI treats it as your name (ignores - _ . and l/i/1, o/0)
  BLOCK  npm        dataclasses: npm treats it as your name (ignores - _ .)
  warn   npm        dataclass (80.1k downloads/month): 2 edits away

Summary: 2 available, 1 taken; 2 look-alikes will block registration; 1 near-collision warning
```

PyPI rejects a new name that matches an existing project once `-`, `_` and `.` are removed and `l`, `i`, `1` and `o`, `0` are treated as the same character. It also rejects standard-library module names. npm rejects names that match once punctuation is removed. amagi-name-check applies both rules and reports a hit as `BLOCK`.

### Typos of popular packages

```bash
amagi-name-check chalkk --only npm
```

```
amagi-name-check: chalkk

  CHECK  NAME    STATUS  DETAIL
  npm    chalkk  taken   0.0.1-security - security holding package

Near-collisions:
  warn   npm        chalk (2.1B downloads/month): 1 edit away

Summary: 0 available, 1 taken; 1 near-collision warning
```

Warnings come from the registries' search APIs, from probing every one-letter deletion of your name, and from stripping common affixes (`py-`, `-cli`, `-js` and others). `requests-cli` is free on PyPI, and amagi-name-check still warns that it is `requests` plus a suffix. To keep the list short, it drops projects under 1,000 npm downloads a month, 5,000 crate downloads or 10 GitHub stars, and shows at most three warnings per registry.

### What it checks

- **PyPI:** the JSON API, confirmed against the simple index so a registered project with no files still counts as taken.
- **npm:** the registry. A name whose package was unpublished still shows as taken, because npm keeps a record of it.
- **crates.io:** crates.io treats `-` and `_` as the same, so `serde-json` reports as taken by `serde_json`.
- **Homebrew:** formulae and casks.
- **GitHub:** whether a user or org owns the name, and how many repos use it as their exact name. An exact-name repo with 100 or more stars marks the name as taken. Smaller ones show as `in use`.
- **Domains:** `.com`, `.dev`, `.io`, `.app`, `.ai` and `.org` through RDAP, with a WHOIS fallback for TLDs that have no RDAP server. A name with separators also gets its joined `.com` (`amagi-name-check` checks `amaginamecheck.com` too).

Each name takes 30 to 40 lookups, run in parallel. Full checks of three names finished in one to three seconds each.

### Options

```bash
amagi-name-check quillo tessel marrow         # compare several candidates
amagi-name-check quillo --json                # machine-readable output
amagi-name-check quillo --markdown            # a table to paste into an issue or chat
amagi-name-check quillo --only pypi,github    # pypi, npm, crates, brew, github, domains
amagi-name-check quillo --skip domains
amagi-name-check quillo --tlds com,dev,sh     # a different domain list
amagi-name-check quillo --no-similar          # exact-name checks only, fewer requests
amagi-name-check quillo --links               # print the URL under each row
```

Exit codes: 0 means available everywhere checked with no blocking look-alike, 1 means taken, invalid or blocked somewhere, 2 means a usage error, and 3 means nothing was taken but some lookups failed.

### GitHub rate limits

GitHub allows 10 unauthenticated searches a minute, and each name uses one. To check more names than that, set a token. It needs no scopes:

```bash
export GITHUB_TOKEN=your-token
```

`GH_TOKEN` works too. When the limit is hit, the GitHub rows show `unknown` with a hint, and the rest of the report still runs. A rejected token also shows as `unknown`, with a note to check it.

## Use it from Claude Code

This repo ships a skill at `.claude/skills/amagi-name-check/SKILL.md`. Copy that folder into your own `.claude/skills/`, and Claude Code will check its name ideas while you brainstorm and tell you which ones are clear.

## Limits

- No tool can list every look-alike a registry might object to. PyPI also keeps a private list of prohibited names, so `available` on PyPI means no project and no detected look-alike. Registration can still fail.
- The standard-library name check needs Python 3.10 or newer. On 3.9 it is skipped.
- Typo detection catches deletions directly. Swapped or substituted letters are caught only when a registry's search returns them.
- WHOIS replies have no standard format. Replies the parser doesn't recognize show as `unknown` instead of a guess.
- `available` for a domain means it isn't registered. It says nothing about price; premium domains can cost far more.
- Results reflect the moment you ran it. Someone can register the name a minute later.

## If this saved you time

A star helps other people find it.

## More from AmagiLabs

- [amagilabs](https://github.com/amagilabs): other small open source dev tools from the same lab.
- [amagi-watch](https://github.com/amagilabs/amagi-watch): turn a video URL into a Claude-readable transcript and frame index.
- [amagi-legal-review-skills](https://github.com/amagilabs/amagi-legal-review-skills): Claude Code skills for contract and lease review.

## License

MIT, see [LICENSE](LICENSE). Copyright (c) 2026 Amagisolutionsgroup, Inc. (AmagiLabs)
