Install locations
| Level | Path | Use case |
|---|---|---|
| Personal (default) | <finchHome>/.finch/extensions/<id>/ | The everyday choice |
| Global | ~/.finch/extensions/<id>/ | Shared across all Finch instances on this machine |
There is no project-level install. Always use the official CLI — never copy the directory by hand.
npx @finchtoys/minitools add <npm-package|local-path|zip-url> [--global]
npx @finchtoys/minitools update <id>
npx @finchtoys/minitools list
npx @finchtoys/minitools remove <id>
npx @finchtoys/minitools enable|disable <id>
npx @finchtoys/minitools doctor [path]
npx @finchtoys/minitools where
doctor runs static checks: missing manifest fields, misuse of import type, direct electron imports, leftover references to deprecated API. Always run it before installing.
Debug workflow
npm run buildnpx @finchtoys/minitools doctor .npx @finchtoys/minitools add .- Enable it in the Finch toolbox
- Check the logs if activation fails
Common pitfalls
| Symptom | Cause |
|---|---|
| Mini tool doesn't load | activate uses export default instead of a named export |
| Code changes don't show up | Finch wasn't restarted; container-related changes only apply to newly created sessions |
| Icon renders as text | Used a nonexistent built-in icon id, without registering an SVG icon pack (see Icon guidelines) |
| Button doesn't appear | getBadge() threw an error; or the id isn't declared in the manifest |
| Clicking a menu item does nothing | An error inside execute() was swallowed — check the logs |
| Can't get a capability | The provider activated after you did, requiring a short poll; or requires is missing from the manifest |
| The model won't call your tool | description doesn't explain the capability clearly, or action isn't fully enumerated |
| Session creation fails | Missing permissions.sessions, or containerId isn't declared |
Publishing
Publish as a normal npm package — users can then install it directly with npx @finchtoys/minitools add <package-name>, no official Finch review required. For the full packaging allowlist, icon.png spec, npm publish steps, and how to submit for official listing, see Publishing to the community.