Skip to main content

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.

This recipe explains what chatjs add does to your project and how the registry install flow works under the hood. For the user-facing overview of the registry itself, start with Tool Registry.

​
Problem

You want to distribute a tool as source code that another ChatJS app can install, type-check, and render without manual wiring. That means installation needs to do more than download a single file. It has to:
  • copy the tool implementation into the app
  • copy its renderer and any shared helper files
  • install npm dependencies
  • register the tool so the model can call it
  • register the UI so tool parts render correctly

​
Solution

chatjs add installs a registry item into the app’s installable tools namespace at tools/chatjs by default. 
npx @chat-js/cli@latest add word-count
The command resolves the requested item, installs any registry dependencies, writes all declared files, then updates the CLI-managed registry files.

​
Install Flow

The current flow is:
  1. Load chat.config.ts and resolve paths.tools
  2. Fetch the requested registry item JSON
  3. Recursively resolve registryDependencies
  4. Write every declared file into the tools directory
  5. Rewrite @toolkit/* imports into local project imports under tools/chatjs/_shared
  6. Install the combined npm dependencies and dev dependencies
  7. Inject tool registrations into tools/chatjs/tools.ts and UI registrations into tools/chatjs/ui.ts

​
Registry Item Shape

Each installable item is a JSON manifest. It declares files to copy plus dependency metadata.
packages/registry/items/get-weather.json
{
  "name": "get-weather",
  "description": "Get the current weather at a location",
  "dependencies": ["ai", "date-fns", "zod"],
  "registryDependencies": ["toolkit-renderer"],
  "files": [
    {
      "path": "tool.ts",
      "type": "tool",
      "target": "get-weather/tool.ts",
      "content": "..."
    },
    {
      "path": "renderer.tsx",
      "type": "renderer",
      "target": "get-weather/renderer.tsx",
      "content": "..."
    }
  ]
}
registryDependencies let one registry item pull in another. In this branch, get-weather depends on toolkit-renderer, which installs shared files like _shared/lib/cx.ts and _shared/hooks/use-tool-is-compact.ts.

​
What Changes In Your Project

After installation, your project will usually gain: 
tools/
  chatjs/
    tools.ts
    ui.ts
    word-count/
      tool.ts
      renderer.tsx
    _shared/
      hooks/
      lib/
The CLI also updates the managed registry files:
tools/chatjs/tools.ts
// [chatjs-registry:tool-imports]
import { wordCount } from "@/tools/chatjs/word-count/tool";
// [/chatjs-registry:tool-imports]

export const tools = {
  // [chatjs-registry:tools]
  wordCount,
  // [/chatjs-registry:tools]
} as const;
tools/chatjs/ui.ts
// [chatjs-registry:ui-imports]
import { WordCountRenderer } from "@/tools/chatjs/word-count/renderer";
// [/chatjs-registry:ui-imports]

export const ui = {
  // [chatjs-registry:ui]
  "tool-wordCount": WordCountRenderer,
  // [/chatjs-registry:ui]
};
You do not edit this file by hand. The CLI owns the marker blocks and injects entries idempotently.

​
How The Installed Tool Becomes Available

Once tools/chatjs/tools.ts and tools/chatjs/ui.ts are updated, the rest of the app picks up the new tool through two static wrappers:
  • lib/ai/installed-tools.ts derives InstalledTools from the tools export
  • lib/ai/tool-renderer-registry.ts exposes the ui map as the renderer registry
This keeps installable tools separate from built-in platform tools while still making them first-class typed tools in the app.

​
Key Files

FileRole
packages/cli/src/commands/add.tsMain install flow for chatjs add
packages/cli/src/registry/resolve.tsRecursively resolves registry dependencies
packages/cli/src/utils/write-files.tsWrites files and rewrites @toolkit/* imports
packages/cli/src/utils/inject-tool.tsUpdates the CLI-managed registry files
apps/chat/lib/ai/installed-tools.tsDerives typed installed tools
apps/chat/lib/ai/tool-renderer-registry.tsRegisters installed renderers

​
Notes

  • The registry index is created automatically if it does not exist yet.
  • Re-installing a tool is safe because registration is idempotent.
  • Existing files are preserved unless you confirm an overwrite or pass --overwrite.
  • The registry can distribute more than tool.ts and renderer.tsx. It can also ship shared libs, components, and hooks.
  • Tool Registry for the conceptual overview
  • Tools for building and publishing registry tools
  • CLI add for the command reference