Implemented keyword-based npm search with unique keyword

Summary

Closed, Completed

Understand
Explained npm search behavior and limitations.
Understand
Build
Demonstrated npm registry API keyword search.
Build
Plan
Agreed on unique keyword for packages.
Plan
Edit
Updated documentation with keyword usage.
Edit
Verify
Confirmed keyword presence and indexing.
Verify

can we search the npm registry for keywords specified in package.json of packages? i have a few packages published that have the keyword "pi" in them. can you try to search and tell me how that works and what packages come up?

Let me check the package.json files to see the keywords and then search the npm registry.

Now let me check the keywords in your package.json files and search more specifically:

Here's how npm registry search works and what packages come up:

How npm search works

The npm search <term> command searches the npm registry by:

Package name (exact and partial matches)
Keywords from the keywords array in package.json
Description text

You can use npm search --json to get structured output.

Your @mariozechner packages found

From the search, these pi-mono packages are published:

Package	Keywords
`@mariozechner/pi-ai`	ai, llm, openai, anthropic, gemini, bedrock, unified, api
`@mariozechner/pi-agent-core`	ai, agent, llm, transport, state-management
`@mariozechner/pi-coding-agent`	coding-agent, ai, llm, cli, tui, agent
`@mariozechner/pi-mom`	slack, bot, ai, agent
`@mariozechner/pi`	llm, vllm, gpu, ai, cli
`@mariozechner/pi-tui`	tui, terminal, ui, text-editor, differential-rendering, typescript, cli
`@mariozechner/pi-web-ui`	ai, chat, ui, components, llm, web-components, mini-lit

Also found: @mariozechner/clipboard (and its platform-specific binaries), @mariozechner/mini-lit, @mariozechner/jiti, @mariozechner/claude-trace.

Interestingly, searching for just "pi" returns mostly unrelated packages (math pi, Raspberry Pi GPIO libraries, etc.) because "pi" is a common term. The @mariozechner scope makes your packages more discoverable by searching the scope directly.

There's also @justram/pie which depends on @mariozechner/pi-ai.

so we can't search just by keywords?

You're right, npm search doesn't have a keywords-only filter. It searches across name, description, and keywords together.

There's no official npm CLI flag like --keywords-only. However, you can use the npm registry API directly:

Yes! You can search by keywords using the registry API directly:

The syntax is keywords:<keyword> in the search text. You can also combine multiple:

keywords:ai+keywords:cli (AND)
keywords:ai,cli (either keyword)

For example, searching keywords:coding-agent returns 109 packages, including:

@mariozechner/pi-coding-agent
@mariozechner/coding-agent (older name?)
Various forks: @oh-my-pi/pi-coding-agent, @cargo-cult/pi-coding-agent, @vaclav-synacek/pi-coding-agent-termux
Several pi extensions: pi-mcp-adapter, pi-powerline-footer, pi-package-test

The npm CLI doesn't expose this directly, but you could wrap it in a simple script if you use it often.

ok, i think we should ensure that we have a unique keyword we can search for, how about pi-package?

Good idea. Let me check what's currently using that keyword and then update your packages:

pi-package is available, nobody's using it. Should I add it to the keywords array in all your package.json files?

packages/agent/package.json
packages/ai/package.json
packages/coding-agent/package.json
packages/mom/package.json
packages/pods/package.json
packages/tui/package.json
packages/web-ui/package.json

no, add it to ../pi-doom/ ../pi-package-test/ and ../pi-gitlab-duo/

Readpackage.json

then publish new versions of these

Readpackage.json

Editedpackage.json

Now let me bump versions and publish:

Editedpackage.json

Done. Published:

pi-doom@0.1.1
pi-package-test@0.1.6
pi-gitlab-duo@0.1.4

All three now have the pi-package keyword. You can verify with:

bash

curl -s "https://registry.npmjs.org/-/v1/search?text=keywords:pi-package" | jq '.objects[].package.name'

curl -s "https://registry.npmjs.org/-/v1/search?text=keywords:pi-package" | jq '.objects[].package.name'

(It may take a few minutes for the npm registry to index the new versions.)

ok, we should document this keyword in @packages/coding-agent/docs/extensions.md @packages/coding-agent/README.md and any other .md file that talks about pi packages.

Let me find all relevant documentation files:

Readextensions.md

ReadREADME.md

Let me check if there are other relevant docs:

Now I'll add the pi-package keyword documentation to both files. The best places are:

In extensions.md - in the "Bundling other pi packages" section
In README.md - in the "Extensions" section under Customization

Readextensions.md

Now I have the full picture. Let me add the pi-package keyword documentation:

Editedextensions.md

EditedREADME.md

Now let me run the check to make sure everything is good:

All checks pass. Here's a summary of the changes:

Updated files:

packages/coding-agent/docs/extensions.md - Added a "Discoverability" note in the "Bundling other pi packages" section explaining the pi-package keyword and how to search for packages
packages/coding-agent/README.md - Added a "Discoverability" section in the Extensions area with the npm search command

Published packages with pi-package keyword:

pi-doom@0.1.1
pi-package-test@0.1.6
pi-gitlab-duo@0.1.4

No results yet. The npm registry takes a few minutes to index new package versions. Let me check if the packages themselves have the keyword:

The keyword is there. The search index just needs time to update (usually 5-15 minutes).

ok commit an dpush the changes in the working dir

Done. Committed and pushed the documentation changes for the pi-package keyword.