> ## Documentation Index
> Fetch the complete documentation index at: https://chatjs.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool Registry

> Install and distribute ChatJS tools through the registry

The ChatJS tool registry is the distribution layer for installable tools. It lets you ship a tool's server logic, UI renderer, and supporting files as a portable package that another ChatJS app can install with `chatjs add`.

This is the extension surface for ChatJS. Built-in product tools stay in `tools/platform`. Installable tools live in `tools/chatjs` and are managed by the CLI.

## What You Install

When you run `chatjs add`, the CLI:

1. Fetches a registry item by name
2. Resolves any registry dependencies that item depends on
3. Writes the tool files into the installable tools directory from `chat.config.ts`
4. Installs any npm dependencies declared by the registry item
5. Warns if installed items declare missing environment variables
6. Updates the CLI-managed registry files so the tool is available to the model and renderer

```bash theme={null}
npx @chat-js/cli@latest add word-count
```

## Why This Exists

The registry gives ChatJS a standardized way to distribute software between projects.

* You can publish self-contained tools instead of copying app-specific code by hand.
* Installed tools become part of the app's typed tool system automatically.
* Each tool can ship both execution logic and a custom UI renderer.
* Shared helpers can be distributed as registry dependencies and installed alongside the main tool.

If you have used `shadcn/ui`, the model is similar. The registry distributes source files into your project instead of mounting opaque runtime plugins.

## Installed Tool Layout

By default, installed tools are written into `tools/chatjs`:

```text theme={null}
tools/
  chatjs/
    tools.ts
    ui.ts
    word-count/
      tool.ts
      renderer.tsx
    _shared/
      hooks/
      lib/
```

`tools/chatjs/tools.ts` and `tools/chatjs/ui.ts` are the CLI-managed registry files. You should not edit them manually.

## Registry Boundaries

ChatJS separates tools into two layers:

| Location         | Ownership       | Purpose                                                     |
| ---------------- | --------------- | ----------------------------------------------------------- |
| `tools/platform` | ChatJS platform | Built-in product tools and tightly coupled internal tooling |
| `tools/chatjs`   | Registry + app  | Installable tools distributed through `chatjs add`          |

Use `tools/platform` when a tool depends on internal app contracts or product infrastructure.

Use `tools/chatjs` when a tool should be portable across ChatJS projects as a distributable package.

## Project Configuration

The registry installs files into the path configured by `paths.tools` in `chat.config.ts`:

```ts title="chat.config.ts" theme={null}
export default defineConfig({
  paths: {
    tools: "@/tools/chatjs",
  },
});
```

The CLI uses this path both to decide where files should be written and which import alias should be used inside the generated registry index.

## Tool Environment Variables

Installable tools can declare their own environment requirements directly in `tool.ts`.

```ts title="tools/chatjs/retrieve-url/tool.ts" theme={null}
import type { ToolEnvVars } from "@chat-js/registry";

export const toolEnvVars: ToolEnvVars = [
  {
    options: [["FIRECRAWL_API_KEY"]],
  },
];
```

The registry build extracts `toolEnvVars` into the generated registry manifest as `envRequirements`. `chatjs add` uses that metadata for install-time warnings, and `check-env` validates installed tools from their `tool.ts` source at app startup and build time.

## Using a Different Registry

You can point the CLI at a local or custom registry:

```bash theme={null}
npx @chat-js/cli@latest add word-count \
  --registry ./packages/registry/items/{name}.json \
  --cwd apps/chat
```

You can also set a default registry URL template with `CHATJS_REGISTRY_URL`.

## Manual Update And Troubleshooting

* Re-running `chatjs add` is safe. The CLI avoids duplicate registry entries.
* Pass `--overwrite` if you want to replace existing installed files.
* If `chat.config.ts` is missing, `chatjs add` will stop before making changes.
* If an item declares shared registry dependencies, those are installed automatically before the main item is registered.
* If the registry index does not exist yet, the CLI creates it for you.

## Related

* [CLI add](../cli/add) for the command reference
* [Adding Tools](../cookbook/add-tools) for how installation works under the hood
* [Tools](../cookbook/tools) for authoring and publishing registry tools