Why your coding agent should install, not write, utility code

The friction

You ask your coding agent for a rate limiter. A real one — token-bucket, per-provider caps, respects Retry-After. Thirty seconds later it has produced 120 lines of plausible-looking Python. The structure is fine. The variable names are fine. There is a subtle off-by-one in the refill logic, and it swallows 429s from one provider because the header casing is wrong. You will find the first bug in a week and the second one in production.

The agent did this because writing from scratch was faster than the alternative. npm search for a package, reading three READMEs, comparing forks, picking one, reading its source to confirm it actually does what the README claims — that is ten minutes of token-heavy navigation. Generation is cheaper. Generation also loses.

Why agents don't use npm well

The failure is not laziness. It is the shape of the registry.

Package search returns noise ordered by download count, not fitness for purpose. READMEs are written for humans who already know what they want, not for an agent deciding whether this package matches an underspecified request. Quality varies across five orders of magnitude within a single search page. Peer-dependency resolution burns tokens before the agent has any signal that the package is even the right one. And there is a rational fear — not always articulated, but present in the behaviour — of pulling in something that transitively depends on left-pad, or a package that got sold to a sketchy maintainer last quarter.

Given that, writing 120 lines of new code is the locally correct choice. The agent minimises uncertainty by producing something it can reason about end-to-end. The global cost — accumulated bespoke, untested, slightly-wrong utility code scattered across every project — is somebody else's problem.

What a registry needs to be agent-friendly

If you want agents to install instead of generate, the registry has to be built for them, not adapted for them.

Curated, not a firehose. Two hundred vetted tools that actually solve their stated problem beats three million packages of varying quality. Curation is the moat. An agent choosing from 200 known-good options can decide in one call; an agent choosing from npm cannot decide at all without a human.

A machine-readable catalog. /api/catalog returning the full list as JSON. /llms.txt at the root so an agent can ingest the whole registry as context. /openapi.json so tool calls are typed. The agent should be able to answer "what rate limiters do you have" with one fetch, not a search-engine crawl.

One-command install. npx some-cli add <slug> with no config, no auth wall for the free tier, no build step. If it requires a project-scoped .env before the first install, you have already lost.

Pinned, minimal, known deps. Stdlib-only where possible. Every added dependency is a token tax on the agent's decision and a supply-chain risk on the user.

Stable slugs, forever. If response-cache works today it works in five years. Agents cache slugs implicitly — renaming is a breaking change for the whole ecosystem.

CustomClaw's bet

CustomClaw is built around this assumption. It is a curated registry of small, focused utilities for LLM and agent code — rate-limit-handler, json-repair, response-cache, and a few dozen others. Each one is a single file or a tight module. Each one is vetted, versioned, and has a stable slug.

The catalog lives at customclaw.company/api/catalog. The agent-readable summary is at customclaw.company/llms.txt. Pick a slug, install it:

npx customclaw-cli add rate-limit-handler

No config. No auth for the free tier. The file lands at a predictable path inside your project and you import it like any other module.

There is also an MCP server — customclaw-mcp — that plugs straight into Claude Desktop or Claude Code. Once connected, the agent can list utilities, search by tag, read the full spec for a given slug, and install — all without leaving the conversation. The MCP tools are the same shape as the HTTP API: list_utilities, search_utilities, get_utility_info, install_utility.

The goal is that when an agent is about to write a JSON repair function from scratch, it has a cheaper and more reliable option one tool call away.

What's next

More utilities (the backlog is longer than the shipped set). Tighter integration with the coding-agent harnesses — project-level install hints, CLAUDE.md snippets that teach an agent to check the registry before generating. And feedback, especially negative feedback: slugs you expected to exist and didn't, things the MCP server does awkwardly, tools that turned out to be wrong.

Repo is at github.com/onlythebestswfl-ops/customclaw. Issues and PRs welcome. If you are building a coding agent and want to wire CustomClaw into it, that conversation is also welcome.