Extension manifest
The manifest is the closed terminay object in your package’s package.json.
Terminay validates it before importing your extension.
Minimal agent extension
JSON
{
"name": "@acme/codex-agent",
"version": "1.0.0",
"type": "module",
"exports": { ".": "./dist/index.js" },
"terminay": {
"manifestVersion": 1,
"id": "com.acme.codex-agent",
"displayName": "Acme Codex agent",
"api": "^1.2.0",
"engines": { "terminay": ">=1.0.0", "node": ">=20" },
"entrypoint": "dist/index.js",
"permissions": ["agent-observation"],
"contributes": {
"agentProviders": [{
"id": "com.acme.codex-agent/codex",
"displayName": "Codex",
"requiredEnvironmentCapabilities": ["agent-journal"]
}]
}
}
} name, version, and an export for the entrypoint are package requirements;
package name and extension id are deliberately separate.
Top-level fields
| Field | Required | Meaning |
|---|---|---|
manifestVersion | Yes | Manifest format. Use 1. |
id | Yes | Immutable, globally unique, lowercase DNS-style extension identity. |
displayName | Yes | Human-readable extension name. |
description | No | Short description shown by Terminay. |
api | Yes | SemVer range for the Terminay Extension API. |
engines | Yes | Both terminay and node SemVer ranges. |
entrypoint | Yes | Relative, forward-slash .js path inside the package. It must also be exported. |
platforms | No | Allowed operating systems: darwin, linux, or win32. |
permissions | Yes | Requested host capabilities; see Permissions. |
extensionDependencies | No | Other extensions: extensionId, apiRange, and optional optional. |
contributes | Yes | One or both contribution arrays below. At least one is required. |
contributes.projectEnvironments
Each item declares a project-environment provider. Its id must be namespaced by the extension ID.
| Field | Meaning |
|---|---|
id, displayName | Required provider identity and label. |
description, icon | Optional metadata. Icons are terminal, server, cloud, key, folder, network, database, warning, or info. |
capabilities | Required non-empty list: terminal, filesystem, filesystem-observation, git, process-observation, agent-journal, mcp-bridge, infrastructure, or shell-discovery. |
profileSave | Optional { createEnvironment: true }. Without it, saving a profile has no creation side effect. |
dependencyOperations | Optional allowlist of provider-owned public operation names that dependent extensions may request. |
contributes.agentProviders
Each item declares a coding-agent provider. Declaring one requires the agent-observation permission.
Field Meaning id, displayNameRequired provider identity and label. The ID is namespaced by the extension ID. description, icon, platformsOptional metadata and OS restriction. processMatchersOptional safe foreground matchers: an executableName and optional exact arguments tokens. mappingsOptional declared journal mappings: mappingVersion and providerVersionRange. requiredEnvironmentVariablesOptional exact variable names to request from the foreground or descendant process. requiredEnvironmentCapabilitiesRequired non-empty list of process-observation, filesystem-observation, and/or agent-journal.
Validation rules
- Unknown fields, duplicate identities, unsupported platforms, and incompatible API versions are rejected.
- Entrypoints cannot be absolute, escape the package, use backslashes, or point to a symlink/non-regular file.
- API major versions are breaking; Terminay activates an extension only when its supported API satisfies
api.