ctx capability reference
| Namespace | Purpose | Required permission / declaration |
|---|---|---|
ctx.subscriptions | Disposable collector, cleaned up automatically on deactivation | — |
ctx.minitool | Self metadata (id, version, etc.) | — |
ctx.storagePath | Absolute path to the private persistent directory | — |
ctx.tools | Register agent tools / discover providers on demand | contributes.tools |
ctx.composerActions | Composer toolbar buttons | contributes.composerActions |
ctx.ui | Toast, confirm, modal, forms, Canvas windows | — |
ctx.storage | Simple key-value persistence | — |
ctx.secrets | Encrypted secret read/write | permissions.secrets |
ctx.settings | Read user settings declared in the manifest (read-only) | finch.settings |
ctx.oauth | OAuth login and proxied requests | permissions.oauth |
ctx.sessions | Create, send, wait on, and observe your own sessions | permissions.sessions + container declaration |
ctx.sessionContainers | Register container settings menus | Container settingsMenu declaration |
ctx.icons | Register runtime SVG icon packs | contributes.iconPacks |
ctx.capabilities | Provide / consume cross-mini-tool capabilities | provides / requires |
ctx.extensions | Read another mini tool's contribution snapshot | — |
ctx.i18n | Read strings from i18n/<locale>.json | — |
ctx.app | Finch version, platform, assistant name, etc. | — |
ctx.status | Runtime state snapshot | — |
ctx.logger | Log output | — |
Manifest field reference
Basics
| Field | Description |
|---|---|
manifestVersion | Fixed at 1 |
id | Immutable after install, must match the directory name |
name / description | User-facing name and description, in English by default |
main | The compiled entry file, e.g. dist/index.js |
activationEvents | Only ["onStartup"] is currently supported |
version | Inherited from package.json |
The manifest can live in finch.json (recommended, no finch wrapper) or package.json#finch (legacy). If both exist, finch.json wins.
contributes
| Field | Description |
|---|---|
tools | true to register agent tools |
composerActions[] | Composer button slots: id / icon / tooltip |
sessionContainers[] | Session containers: id / icon / title / mode / agentProfile / settingsMenu / starterPrompts |
agentProfiles[] | Persona definitions: id / name / description / prompt |
mcpServers[] | MCP server metadata (no secrets) |
iconPacks | Runtime SVG icon pack declarations |
skills | true to bundle skills with the package |
permissions
| Permission | Value | Purpose |
|---|---|---|
filesystem | none / read / readwrite | Local file access |
network | boolean | Outbound requests |
shell | boolean | Run shell commands |
secrets | string[] | Allowed secret names |
oauth | string[] | Allowed OAuth provider ids |
sessions | boolean | Use ctx.sessions |
Request the minimum permission needed — use read instead of readwrite whenever possible.
Other common fields
| Field | Description |
|---|---|
settings.fields[] | User settings, rendered natively by Finch |
provides / requires | Capability provision and dependency declarations |
categories | Catalog category |
promptGuides | Guide cards on the detail page that pre-fill the Composer when clicked |
privacyPolicyUrl / termsOfServiceUrl | Links shown on the detail page |