Better Icons for AI agents and terminal icon workflows

The icon selection problem Better Icons addresses

Better Icons targets a narrow but repeated problem in AI-assisted development: an agent can recognize that a button needs an icon without reliably knowing which icon identifier exists, which collections are available, or how to add the result to the project correctly. The README describes failures involving invented SVG code, inconsistent styles, poor file organization, and token use from pasting inline SVG into chat. Better Icons moves that work behind a searchable interface.

The project serves two audiences. Coding agents can call its Model Context Protocol tools, while developers can use the `better-icons` command directly from a terminal. According to the README, the catalog contains more than 200,000 icons from more than 150 collections, including Material Design Icons, Lucide, Heroicons, Tabler Icons, Phosphor Icons, and Remix Icons. A collection is addressed through a prefix and icon name, such as `lucide:home` or `mdi:account`.

That approach is useful when icon choice is an implementation detail but becomes risky when the icon library is part of a strict design system. Better Icons can find and retrieve icons, but the documentation does not state that it validates whether a chosen icon follows an organization-specific usage policy. It also does not claim that its catalog reflects only approved assets. The tool reduces guesswork about availability; it does not replace design governance.

Search, retrieval, and project synchronization flow

The repository is a TypeScript package with an executable at `dist/index.js`. Its package metadata identifies Node.js 18 or later as the runtime requirement. The MCP server exposes search and retrieval operations, while the CLI maps the same core tasks to commands and structured output. This gives agents a tool interface without removing a direct terminal path for developers.

Search starts with a term such as `arrow`, `home`, or `settings`. The `search_icons` MCP tool can limit the result count, filter by a collection prefix, or filter by category. The CLI exposes the same idea through `better-icons search`. Once a developer selects an identifier, `get_icon` retrieves the asset as raw SVG, React or JSX component code, Iconify component usage, or a URL. Optional color and pixel-size settings apply to that retrieval.

The more distinctive operation is `sync_icon`. It requires an absolute icons-file path, a framework value, and an icon identifier. Supported framework values are `react`, `vue`, `svelte`, `solid`, and `svg`. The tool returns an import statement and usage example after adding the icon or finding that it already exists. `scan_project_icons` performs the complementary inventory operation, reporting which icons are already present in a selected file.

There is also local preference state. Better Icons records which collections are used and prioritizes them in later searches. `get_icon_preferences` exposes learned preferences and usage statistics, while `clear_icon_preferences` resets them. This is a ranking feature, not an access-control boundary. The documentation does not identify the preference file, synchronization behavior across machines, conflict resolution policy, or whether preference data is shared through the MCP setup.

Installing Better Icons for agents or direct CLI use

For an agent environment, the shortest documented route installs the Better Icons skill. The command reads the GitHub repository through `npx skills`, so it requires network access when the skill is fetched:

npx skills add better-auth/better-icons

For direct terminal use, install the package globally with either supported package manager:

npm install -g better-icons

The README also provides a Bun installation path:

bun add -g better-icons

The automated MCP setup command is:

npx better-icons setup

The setup flow is interactive and documents support for Cursor, Claude Code, OpenCode, Windsurf, VS Code Copilot, and Google Antigravity. It configures the MCP server for those clients based on the selection made in the prompt. The README does not publish the exact generated settings for every client, so a user reviewing that flow should inspect the resulting configuration before using an agent with project-write access.

After setup, begin with a narrow search that matches the intended collection:

npx better-icons search home --prefix lucide

This should return home-related Lucide icons. Retrieve a known result as raw SVG by redirecting output to a file:

npx better-icons get lucide:home > icon.svg

The redirection produces `icon.svg` in the current shell directory. Developers who want machine-readable results can request JSON:

npx better-icons search settings --json | jq '.icons[:5]'

That command limits the printed JSON to the first five entries in the `icons` array. It is a useful first check that `jq` is installed and that the output has the documented scriptable shape.

Manual MCP configuration and executable wiring

The package metadata declares `better-icons` as its command and points it to `./dist/index.js`. Manual MCP configuration therefore uses `npx` with `better-icons` as the package argument. The README gives the following Cursor configuration:

{
  "mcpServers": {
    "better-icons": {
      "command": "npx",
      "args": ["-y", "better-icons"]
    }
  }
}

For Claude Code, the destination changes but the server entry remains the same:

{
  "mcpServers": {
    "better-icons": {
      "command": "npx",
      "args": ["-y", "better-icons"]
    }
  }
}

The documented Claude Code file is `~/.claude/settings.json`. Google Antigravity uses `~/.gemini/antigravity/mcp_config.json` and the same `mcpServers` entry. The `-y` argument tells `npx` to proceed without an interactive package-install confirmation, which matters when an agent starts the server non-interactively.

The package also has a build path through Bun:

bun run build

This compiles `src/index.ts` into `dist/index.js` for Node. However, the README does not provide a production deployment procedure for a self-hosted binary, service manager, or pinned package revision. The manual examples invoke the published package through `npx`, so reproducibility depends on registry resolution and network availability unless the operator builds and invokes a local artifact by a separately managed process.

Batch retrieval, alternatives, and framework exports

Better Icons distinguishes exact retrieval from visual or semantic exploration. `find_similar_icons` accepts an icon identifier and can return up to 50 variations across collections. This is useful when a developer wants the same concept in a different library or visual style. `recommend_icons` works from a described use case, accepts optional style values such as `solid` or `outline`, and returns as many as 20 recommendations.

Batch retrieval is handled by `get_icons`, which accepts an array of icon identifiers with a maximum of 20. The README describes it as more efficient than separate `get_icon` calls. That efficiency claim is not accompanied by timing data or a benchmark, so the defensible comparison is operational: one request handles multiple identifiers rather than requiring the caller to manage the same number of individual retrievals.

For framework output, the project states that React, Vue, Svelte, Solid, and raw SVG are supported. The exact export template is not shown in the available documentation. This matters during adoption. A developer cannot assume that generated code will match an existing barrel file, named export, class-name convention, server-side rendering strategy, or accessibility policy simply because the framework selector is accepted.

A direct Iconify query or a project-specific icon package is a real alternative. Iconify supplies icon data and naming conventions, while a project-owned package gives the team one curated subset. Better Icons adds cross-collection discovery, agent-facing tools, preference-based ranking, recent history, and file synchronization. It is the better fit when discovery and agent integration matter; a committed local icon module is the better fit when every icon must already be approved and versioned with the application.

Limitations around generated code, state, and maintenance

The clearest limitation is that availability is not the same as correctness. The tool can return a valid icon identifier and generated usage, but the README does not document semantic checks for directionality, decorative versus interactive use, accessible labels, minimum stroke contrast, or licensing metadata for each collection. Those checks may still be required by the consuming project.

`batch retrieval` has a fixed boundary of 20 identifiers. Search supports larger limits, up to 999 results, and similar-icon lookup supports up to 50 results. These are explicit request constraints, not evidence that every upstream collection is equally searchable.

Learned preferences and recent icons introduce persistent-state questions. The README documents inspection and reset operations, but it does not state where CLI and MCP preference data are stored, whether the two interfaces share it, how team members receive it, or whether state is safe to commit. Automatic project synchronization also creates a failure surface if an icons file has unusual exports or formatting. The tool's confirmation response is not a substitute for reviewing a diff.

Maintenance status requires a factual reading of the repository record. Better Icons is not archived, but its last push was on 2026-04-02, which is more than six months before 2026-10-17. The repository should therefore not be described as actively developed. Version `v1.0.5` was released on 2026-03-14. Upgrade cost is reduced somewhat by the MIT license and compact package surface, but the package uses caret ranges for runtime dependencies, so an operator may still need lockfile or image-level control in a production environment. The MIT license permits use and modification under its terms; it does not resolve per-collection icon licensing questions.

A practical adoption path for icon-heavy repositories

Start with read-only discovery. Search for an icon term that already appears in the project, limit the collection when the expected style is known, and compare the result with an existing icon source. Retrieve that icon through both SVG and the framework format relevant to the application. This exposes formatting differences before an agent is allowed to change source files.

Next, test the stateful features explicitly. Search again after retrieving icons from the intended collection, inspect the preference result, and reset it to verify the documented reset operation. In an MCP-enabled agent, ask for similar alternatives rather than accepting the first recommendation. A recommendation can be semantically relevant while differing in stroke, fill, or naming conventions.

Only after those checks should `sync_icon` run against a repository copy. Review the added import, export name, component structure, and usage example. Check the diff for changes outside the intended icons file. The documentation does not state that the tool supports arbitrary naming collisions, barrel-file updates, or multiple destination files, so teams should not infer those capabilities.

For teams that already standardize on one icon library, Better Icons may add unnecessary catalog breadth and state management. Its distinctive value appears when several collections are acceptable, coding agents need discovery tools, or developers need to move an icon into React, Vue, Svelte, Solid, or SVG output without manually pasting asset markup.

Editorial conclusion

Adopt Better Icons when an AI coding workflow repeatedly needs to discover, compare, retrieve, or register icons from multiple collections. Do not adopt it as the sole source of truth for a tightly governed design system without first checking `sync_icon` output against your repository conventions. For a first evaluation, search a familiar term, retrieve one known icon, and inspect the generated TSX, JSX, Vue, Svelte, Solid, or SVG before allowing an agent to modify project files.

Frequently asked questions

Official sources

1. better-auth/better-icons on GitHub
2. Issues
3. License: MIT
4. README
5. Releases