A mini tool is a small program that gives Finch new gear.
It's an npm-style TypeScript package, discovered and loaded by Finch from the filesystem, running in a plugin host process separate from the main process. A mini tool can contribute agent tools, Composer toolbar buttons, standalone session containers, skills, and MCP servers to Finch.
Terminology: the product surface consistently says "mini tool." The public type names in the SDK are
MiniToolContextand the rest of theMiniTool*family, exactly equivalent to the olderExtension*naming. This doc series uses "mini tool" throughout.
What's in scope
| A mini tool can | A mini tool cannot |
|---|---|
| Register agent tools so the model can call external services | Call Electron APIs or Finch internals directly |
| Add buttons and menus to the Composer toolbar | Render custom HTML pages (Canvas windows excepted) |
| Show native Finch dialogs and forms to collect input | Read or write the user's regular chat sessions |
| Create and manage its own session containers and sessions | Access another mini tool's sessions, secrets, or storage |
| Sign in to third-party services via OAuth and proxy authorized requests | Obtain the raw OAuth access token |
| Provide or consume capabilities shared with other mini tools | Bypass manifest declarations to use unauthorized capabilities |
Typical scenarios
| Scenario | Approach | Key capability |
|---|---|---|
| Third-party service integration — blogging, task systems, cloud storage | One agent tool with an action parameter + OAuth login | ctx.tools, ctx.oauth |
| External platform bot — WeChat, Feishu, Telegram messaging | An inbox container + one session per contact | ctx.sessions, containers |
| Vertical assistant — legal assistant, travel concierge, code reviewer | An assistant container + agentProfile persona | Containers, agentProfiles |
| Composer quick actions — switch branch, switch mode, pick a template | ComposerAction button + dynamic menu | ctx.composerActions |
| Multi-agent orchestration — break down tasks, run in parallel, aggregate results | Main tool creates child sessions and waits for results | Session Loop |
| Plugging into the MCP ecosystem — reuse an existing MCP server | Declare mcpServers + register the transport at runtime | mcp.client capability |
| Desktop widgets — a desktop pet, a floating timer | Canvas floating window | ctx.ui.createCanvasWindow |
| Packaging knowledge and process — teach the agent a specific methodology | Ship skills alongside the package | contributes.skills |
Mini tools vs. Skills
| Mini tool | Skill | |
|---|---|---|
| What it is | Executable code | A Markdown instruction document |
| Solves | Things the agent can't do (call an API, open a window, create sessions) | Things the agent doesn't know how to do (a process, a convention, a methodology) |
| Delivery | An npm package, needs installing and enabling | A SKILL.md directory |
| Choose when | You need network, files, UI, accounts, or sessions | You just need to give the model a reliable way of doing something |
A mini tool can bundle skills inside its package and combine both — see Skills.
Overall architecture
Three key points:
- Mini tools run in a separate process — a crash or a hang doesn't take down the Finch main process.
- Every capability is exposed through a single entry point,
ctx— there's no other channel to call into Finch. - Mini tools never import each other directly; they only cooperate through capabilities.
Developer guide map
Read in order to go from zero to published, or jump directly to the section you need.
| Section | Contents |
|---|---|
| Quickstart | Minimal directory layout, manifest, entry code, three hard rules, install & enable |
| Composition | Agent tool design rules, interaction/service capabilities, bundled skills |
| Lifecycle & capability registration | Full lifecycle, static declaration vs. dynamic registration, capability cooperation |
| MCP integration | When to choose MCP, the two-layer design, secret management |
| Standardized UI | Toast / dialog / form selection, ComposerAction, menus, modals |
| Accounts, settings & OAuth login | finch.settings, API keys, the two OAuth paths |
| Session containers | The inbox / assistant modes, agentProfile, container settings menu |
| Session Loop | Creating sessions, sending messages, getting results, Planner → Worker → Writer orchestration |
| Debugging, installing & publishing | Install locations, debug workflow, common pitfalls |
| ctx & manifest reference | Quick reference for ctx capabilities and manifest fields |
| Icon guidelines | The entry icon (icon.png) and UI icons (IconRef) |
| Publishing to the community | Packaging, publishing to npm, submitting to the official community catalog |
We strongly recommend building mini tools with Finch's built-in
finch-mini-tool-creatorskill: just describe what you need in natural language, and Finch helps with the project structure, manifest, implementation, build, and install checks. Before you start developing, it's worth refreshing the mini tool manual in the toolbox to get the latest capability list — and generally, feel free to just ask Finch directly rather than relying only on the docs.