Package naming for coding agents
When the product name, the package name and the import name differ, an agent has to guess a mapping. Sometimes it installs somebody else's package.
This is a small, unglamorous thing that costs real installs, and it is usually a one-hour fix.
The problem
An agent decides to use your product. It knows the product name, because that is what the documentation and the web call it. Now it has to install something.
If your product is "Acme Queue" and your package is @acme/queue, that is a short hop. If your product is "Acme Queue" and your package is @acmehq/aq-client, the agent has to guess.
A wrong guess produces one of three outcomes: nothing installs, an abandoned package installs, or somebody else's package installs. All three end the session, and the third is the worst because the code sometimes runs.
The rule
One name for one thing. Product name, package name in every registry, import name, CLI command, and the words in your documentation headings should be the same string.
Product: Acme Queue
Package: @acme/queue
Import: import { Queue } from '@acme/queue'
CLI: acme-queueWhen they match, nothing has to be inferred.
If you cannot change the names
Most companies cannot. The package has downloads, the CLI is in scripts, and renaming breaks people.
So write the mapping down, on every page that has runnable code:
## Names
| | |
| --- | --- |
| Product | Acme Queue |
| npm | `@acme/queue` |
| PyPI | `acme-queue` |
| Go | `github.com/acme/queue` |
| Import | `import { Queue } from '@acme/queue'` |
| CLI | `acme-queue` |Repeat it. A technical writer's instinct is to say this once and link to it. That instinct is right for a person reading in order and wrong for an agent that landed on one page from a search and will never see the page above it.
Check for near misses
Search your registries for names close to yours.
npm search acme queue
pip index versions acme-queueIf something plausible exists that is not yours, put a line on your install page:
The package is `@acme/queue`. There is an unrelated `acme-queue` package on npm
published by someone else; it is not ours and it does not work with this API.That single sentence is worth more than it looks. An agent that finds the wrong package and then reads your correction recovers. An agent that finds the wrong package and reads nothing does not.
The registries to cover
If you ship for several languages, every registry needs the same treatment, and the names will not always be available.
| Registry | Common trap |
|---|---|
| npm | A scope you do not own, or an unscoped squat |
| PyPI | Underscores against hyphens: acme_queue against acme-queue |
| Go | The module path differs from the repository name |
| Maven | Group and artifact split, so the "name" is two strings |
| Crates | No scopes, so the plain name may be taken |
| NuGet | Case-insensitive but case-preserving |
State the exact string for each. For Python, say which of the hyphen and underscore forms works, because both often resolve and only one is yours.
Keep the install command in the code
The install command belongs in the same block as the code that uses it. Not on the previous page, not in a sidebar.
// 1. npm install @acme/queue
// 2. Set ACME_API_KEY in your environment
import { Queue } from '@acme/queue'Why this also helps outside the install step
Consistent naming makes two other things easier.
Matching a query to a page. An agent searching for your product uses the product name. If your headings use it too, the match is direct.
Learning the association. Over training cycles, a model builds an association between a product and a package. Consistency across the whole web makes that association stronger, and inconsistency across your own properties actively weakens it.
The test
Ask a coding agent to install your product, in a fresh project, from nothing but the product name. No documentation link.
Do it five times. If it ever installs the wrong thing, or asks, you have found the bug.
Common questions
Why does package naming matter for coding agents?
An agent that knows your product name has to work out your package name. When they differ, it guesses, and a wrong guess means it installs nothing, installs an abandoned package, or installs somebody else's.
What should I do if my product name and package name already differ?
Write the mapping explicitly on every page with runnable code: product name, package name for each registry, import statement and CLI command. Redundancy is correct because the agent may have arrived at that page directly.
What if a similarly named package exists that is not mine?
Say so on the install page, plainly, with the correct name next to it. An agent guessing a plausible name may find the other one first, and you would rather it read your correction than your silence.
Does this affect anything besides installs?
Yes. Consistent naming makes it easier for a model to match a query to your page, and easier for the model to learn the association during training.
Where this comes from
Armature ran 5,292 judged sessions with Claude Code, Codex and Cursor inside 51 realistic codebases, and published every run. The numbers on this page come from that work.