Finch Agent

Finch Agent is a lightweight, easy-to-use desktop AI agent for macOS and Windows.

You work with it in natural language. It reads and processes local files you authorize, remembers context across sessions, and extends through mini tools, skills, and MCP integrations. Built on the open source project Pi.

Download · Docs · Changelog · finchwork.app

Not to be confused with — several unrelated products share the name Finch: the container development tool, the payroll and HR API, Finch 3D for architecture, and FinchAI for text analysis. This repository belongs to the desktop AI agent at finchwork.app.

About this repository

This repository is the public release hub for Finch Agent. It hosts Finch release assets, official extension source code, and the community registries used by the Finch app and community website.

The repository contains:

• GitHub Releases — public Finch desktop app releases and downloadable assets.
• extensions/ — source code for official Finch extensions.
• community/ — recommended community extension and skill registries.
• skills/ — Finch skill configuration and documentation.
• docs/ — Finch user and developer documentation.

Finch extensions are also called mini tools. In Finch documentation, use extension as the unified term.

Mini tool publishing checklist

Before publishing an extension to npm, run:

npm run typecheck
npx @finchtoys/minitools doctor .
npm run build

Then verify that:

• package.json#version is bumped using SemVer and finch.id is stable.
• The npm package includes dist/, required assets, README.md, and package.json only; exclude src/, tests, build configuration, and every .env file.
• prepublishOnly runs the build, and @finchtoys/minitool-api is a types-only devDependency.
• The package is published successfully and can be installed with npx @finchtoys/minitools add <package>.
• Community submissions include a published icon.png at the package root (PNG, 128–300 px).

See the complete mini tool publishing guide for package layout, npm release, community listing, and maintenance requirements.

Submit your mini tool

Want to make your extension discoverable in Finch? Publish it, then request a listing — the community registry (community/mini-tools.json and community/mini-tools.zh-CN.json) is maintained by the Finch team, so please do not open a Pull Request editing these files directly.

1. Publish the extension to npm, or make its GitHub repository publicly downloadable.
2. Make sure it meets the publishing checklist above, including a valid icon.png.
3. Open an Issue with the minitool label, following the format of issue #22, and include:
   • npm package name (or GitHub repo)
   • finch.id (the extension identifier)
   • current version
   • a short English description (and Chinese translation if available)
   • confirmation that icon.png is included and meets the size requirement
   • declared permissions (filesystem, network, shell, etc.)
   • a suggested category from the list below

The Finch team will review the request and add the entry to mini-tools.json / mini-tools.zh-CN.json on your behalf.

Available categories: productivity, developer, creative, research, finance, commerce, and education.

How community mini tools are pulled

Finch does not bundle every community extension into the app. Instead, it pulls the recommended registry at runtime:

finchtoys/finch-releases
  └── community/mini-tools.json
  └── community/mini-tools.zh-CN.json
            ↓
Finch Toolbox

• mini-tools.json is the English source registry and contains complete extension metadata.
• mini-tools.zh-CN.json provides Chinese name and description overrides matched by id.
• When an override is unavailable, Finch falls back to the English metadata.
• Registry updates are published through community.finchwork.app; they can take up to about one hour to appear because of edge caching.
• Selecting an extension in Finch directs installation through its published npm package or public source.