---
title: Adding Tools
description: Install and register a tool in an existing ChatJS app
---

Start in a ChatJS app containing `chat.config.ts` and `components.json`.

```bash
npx @chat-js/cli@latest add word-count --yes
```

The CLI validates the item's ChatJS metadata and existing registration outputs.
shadcn installs the item, supporting registry files, and npm dependencies using
your project's package manager. ChatJS then reads local descriptors and generates
typed imports in `tools/chatjs/tools.ts` and `tools/chatjs/ui.ts`.

```mermaid
flowchart LR
  A[Select item] --> B[shadcn installation]
  B --> C[Installed source and descriptor]
  C --> D[ChatJS sync]
  D --> E[Typed server and client registrations]
```

The app derives installed tool types through `lib/ai/installed-tools.ts` and
selects their renderers through `lib/ai/tool-renderer-registry.ts`.

## Customize and update

Edit installed `tool.ts` and `renderer.tsx` normally. Put additional registrations
in `custom-tools.ts` and `custom-ui.ts`. Leave generated indexes to `sync`.

Repeat `add` to update an item. Existing files use normal shadcn overwrite
behavior. Use `--overwrite` only when you want to replace installed source.

After a direct shadcn install, or a reported registration failure, run:

```bash
npx @chat-js/cli@latest sync
```

Sync validates descriptors, duplicate installed descriptor keys, and generated-index
integrity before writing registrations. Generated indexes detect collisions with
custom registrations when loaded. A missing or mismatched requested descriptor is
an error.

## Related

- [Tool Registry](./overview) for ownership and migration
- [Tools](./authoring) for building a registry item
- [CLI add](../cli/add) for command options