---
title: "Debugging, installing & publishing · Finch Agent"
description: "Install locations, the debug workflow, and common pitfalls"
source: https://finchwork.app/en/docs/minitools-debugging
---

# Debugging, installing & publishing

## 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.

```bash
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

1.  `npm run build`
2.  `npx @finchtoys/minitools doctor .`
3.  `npx @finchtoys/minitools add .`
4.  Enable it in the Finch toolbox
5.  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](/en/docs/minitools-icons)) |
| 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](/en/docs/minitools-publishing).