# AI Tools catalog

One JSON file per AI coding CLI AgentHub can run in a lane. Loaded by
`server/lib/ai-tools.js`; the fields are described in
`docs/superpowers/specs/2026-09-28-ai-tools-a1-design.md` § 1. A file in
`DASHBOARD_AI_TOOLS_DIR` with the same `id` replaces the built-in one (it may
not set `launcher`).

## Install / update (A2)

Two optional fields, honoured only in built-in files and in the copy of the
newest release's catalog that `server/lib/ai-tools-sync.js` keeps in
`<data dir>/runtime/ai-tools-remote/` — a file in `DASHBOARD_AI_TOOLS_DIR`
carrying either is rejected, because an Install click would run what it names:

- `install`: `{ "kind": "npm", "package": "<npm name>" }` (runs
  `npm install -g <package>@latest` with the login shell's npm) or
  `{ "kind": "script", "url": "https://…" }` (https, same site — last two host
  labels — as `homepageUrl`; downloaded by the server, run as `bash <file>`).
- `update`: `{ "kind": "npm" }` or `{ "kind": "script" }` (reuse `install`),
  or `{ "kind": "self", "args": ["update"] }` (the tool's own updater).

Before adding an npm package, check its owner (`npm view <pkg> maintainers
repository.url`) and that its `bin` matches `detect`: a squatted name would
install a stranger's code on every machine that clicks Install.

## Attribution

The commands, prompt modes, permission-bypass flags and homepages of the tools
other than Claude Code, Codex and Antigravity come from Orca
(<https://github.com/stablyai/orca>, MIT License, Copyright (c) Stably AI):
`src/renderer/src/lib/agent-catalog.tsx`, `src/shared/tui-agent-config.ts` and
`src/shared/tui-agent-permissions.ts`.