---
title: "Appendix: ctx & manifest reference · Finch Agent"
description: "Quick reference for ctx capabilities and manifest fields"
source: https://finchwork.app/en/docs/minitools-reference
---

# Appendix: ctx & manifest reference

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