# CLI and Local APIs
Source: https://docs.enconvo.ai/advanced/cli-local-api
Discover installed commands and local API schemas.
Enconvo includes a command-line interface with the desktop app. Open **Settings → Developer → CLI Guide** to see the installed extensions that expose CLI commands.
## Discover commands
```bash theme={null}
enconvo -h
enconvo knowledge_base -h
```
Append `-h` to the command you are investigating to see its current subcommands and options. The installed extension list is the authority for what your app supports.
If your shell cannot find `enconvo`, open the app's CLI Guide and check your installed app version and command-line setup. Keep Enconvo running for commands that use its local runtime.
## Inspect APIs
Open **Settings → Developer → APIs** to inspect the available routes and request schemas. Use the schema for your installed build when writing an integration; route parameters can change as extensions evolve.
For an AI client that only needs knowledge-base retrieval, use the dedicated [Knowledge Base MCP](/advanced/knowledge-base-mcp) connection instead of exposing the general local API.
## Develop an extension
See [Developing Extensions](/extensions/developing) for project layout and build commands, and [Extension API Reference](/extensions/extension-api-reference) for SDK entry points. [Hooks](/configuration/hooks) handles lifecycle automation; [Scheduled Tasks](/workflows/scheduled-jobs) handles work that runs at a chosen time.
Treat local API and shell access as powerful capabilities: commands can read or modify local data according to their implementation. Keep scripts explicit about the command, input, and destination.
# Context Awareness Deep Dive
Source: https://docs.enconvo.ai/advanced/context-awareness-deep-dive
How Enconvo understands your screen and provides relevant assistance
## Overview
Context Awareness is the foundation of EnConvo's intelligent assistance. Instead of asking you to explain what you are working on, EnConvo observes your active environment -- the application you are using, the text you have selected, the URL you are viewing, and the files you are working with -- and uses this information to provide relevant, targeted help.
This guide explains how context awareness works under the hood, what data is collected, and how to configure it.
For basic usage, see the [Context Awareness introduction](/features/context-awareness). This guide covers the technical details and advanced configuration.
## How It Works
### Accessibility API
EnConvo reads screen content through macOS Accessibility APIs (the same APIs used by screen readers and assistive technologies). When you grant EnConvo Accessibility permission, it can:
* Detect the frontmost application
* Read the title of the active window
* Access selected text in supported applications
* Identify the current URL in web browsers
* Read file paths from Finder selections
This is a read-only, event-driven system. EnConvo listens for focus changes and selection events rather than continuously scanning your screen.
### Context Detection Pipeline
When you invoke EnConvo (via SmartBar, Dynamic Island, App Sidebar, or keyboard shortcut), the system collects context through this pipeline:
```
User triggers EnConvo
→ Detect frontmost application (bundle ID, app name)
→ Read active window title
→ Check for selected text (Accessibility API)
→ If browser: extract current URL and page content
→ If Finder: read selected file paths
→ If code editor: detect language, file path, project
→ Assemble context object
→ Pass to AI along with user query
```
### Context Resolution Time
Context is captured at the moment you trigger EnConvo. The system does not continuously monitor your screen -- it takes a snapshot when needed. This means:
* Context reflects what is on screen when you press the hotkey
* Switching apps after triggering EnConvo does not change the captured context
* Each new query captures fresh context
## Context Types
### Active Application
EnConvo detects the frontmost application and adapts its behavior accordingly.
| Application Category | Context Gathered | AI Behavior |
| - | - | - |
| **Web Browsers** (Safari, Chrome, Arc, Firefox) | URL, page title, visible page content | Offers summarization, translation, content extraction |
| **Code Editors** (VS Code, Xcode, JetBrains) | Programming language, file path, selected code | Provides debugging help, code explanations, refactoring |
| **Finder** | Selected files, current directory path | File operations, content analysis, organization |
| **Text Editors** (TextEdit, Notes, Pages) | Selected text, document content | Writing assistance, grammar, tone adjustment |
| **Other Applications** | Window title, screenshot (when requested) | General assistance based on visible content |
### Selected Text
When you select text in any application before invoking EnConvo, the selected text is automatically included as context. This is the most common context type -- select some code, a paragraph, or an error message, then ask the AI about it.
### Screen Content
The `#screen` context modifier captures a screenshot of your current screen. This is processed through EnConvo's vision capabilities to understand visual content like charts, diagrams, error dialogs, or UI elements that cannot be read through text-based APIs.
### Clipboard
The `#clipboard` modifier includes the current clipboard content. This is useful when you have copied something and want to ask about it without pasting it into the input field.
### Browser Content
For web browsers, EnConvo can read:
* **URL**: The full URL of the active tab
* **Page title**: The document title
* **Page content**: The visible text content of the page (extracted via the browser extension or Accessibility API)
### File Context
When working in Finder or when files are selected, EnConvo can access:
* File paths and names
* File types and sizes
* For supported formats: file content (with your confirmation)
## Configuration
### Enabling Context Sources
Configure which context sources are active in **Settings** -> **Context Awareness**:
| Source | Default | Description |
| - | - | - |
| **Active app detection** | On | Detect the frontmost application |
| **Selected text** | On | Include highlighted text |
| **Browser URL** | On | Read current browser URL |
| **Browser content** | On | Read page content from browsers |
| **Clipboard** | Off | Include clipboard automatically |
### Application Exclusion List
You may want to exclude specific applications from context awareness for privacy reasons. For example, you might exclude a password manager or a private messaging app.
1. Go to **Settings** -> **Context Awareness**
2. Click **Exclusions**
3. Add applications to the exclusion list
4. EnConvo will not read context from excluded applications
### Manual Context Modifiers
Use `#` prefix modifiers to manually control what context is included in your query:
| Modifier | Description |
| - | - |
| `#screen` | Capture and include current screen content |
| `#finder` | Include current Finder file selection |
| `#clipboard` | Include clipboard content |
| `#browser` | Include current browser tab content |
| `#xcode` | Include current Xcode project context |
| `#safari` | Include current Safari tab specifically |
These modifiers override the automatic context detection, letting you be explicit about what information the AI should consider.
## Context in AI Conversations
### How Context is Used
When context is available, it is included in the AI prompt as additional information. The AI can:
* Reference the context directly in its response
* Use context to understand ambiguous queries ("Fix this" -- fix what? The selected code)
* Provide more specific suggestions based on what you are working on
* Avoid asking clarifying questions when the answer is visible on screen
### Context Priority
When multiple context sources are available, they are prioritized:
1. **Explicitly requested context** (`#screen`, `#browser`, etc.) -- highest priority
2. **Selected text** -- included when present
3. **Active application context** -- when enabled and available
4. **Clipboard** -- only when explicitly requested or auto-enabled
### Token Usage
Context data consumes tokens from the AI model's context window. Larger context (full page content, screenshots) uses more tokens, which may:
* Increase response latency
* Increase API costs for cloud models
* Leave less room for conversation history
For long conversations, use specific context modifiers rather than including everything. Asking `#browser summarize this page` is more efficient than including full page content with every message.
## Privacy and data flow
Captured context can become part of a saved conversation or knowledge base item. Model requests and selected OCR, embedding, transcription, or other tool providers may receive relevant content. Review [Privacy & Security](/configuration/privacy-security) for the distinction between local storage and provider processing.
A local chat model alone does not make every tool offline. Check the whole flow, including browser access, captures, and provider-based processing. App exclusions and macOS permissions reduce available context; they are not a promise that every third-party app field can be classified as sensitive.
## Troubleshooting
Ensure EnConvo has **Accessibility** permission in **System Settings** -> **Privacy & Security** -> **Accessibility**. Restart EnConvo after granting permission.
The browser content feature works best with the EnConvo browser extension installed. Without the extension, EnConvo falls back to Accessibility API which may not capture URL content in all browsers.
Not all applications expose selected text through the Accessibility API. If selected text is not detected, try using `#clipboard` after copying the text instead.
Context is captured at the moment you trigger EnConvo. If you switch applications quickly before the hotkey registers, the context may come from the wrong app. Wait for the previous app to be fully focused before triggering.
## Related Features
Introduction to context awareness
Use context in SmartBar queries
Per-app AI context
Extract text from screen content
# Knowledge Base Deep Dive
Source: https://docs.enconvo.ai/advanced/knowledge-base-advanced
Advanced configuration and optimization for your knowledge bases
## Overview
This guide covers the technical architecture and advanced configuration options for EnConvo's knowledge base system. If you are new to knowledge bases, start with the [Knowledge Base introduction](/ai/knowledge-base) first.
EnConvo's knowledge base is built on a dual-database architecture: **LanceDB** for vector storage and similarity search, and **SQLite** (via Drizzle ORM) for metadata management. This combination provides fast semantic search with rich metadata capabilities.
## Architecture
### Dual Database Design
```
Document → Chunking → Embedding → Storage
│
┌──────────┼──────────┐
│ │
LanceDB SQLite
(Vector Store) (Metadata)
│ │
Embedding vectors Knowledge base records
Text chunks Attachment details
Similarity search Content chunk metadata
```
**LanceDB** stores document embeddings for semantic similarity search. Each knowledge base gets its own LanceDB table plus an attachments table. Data is stored locally at `~/.config/enconvo/cache/knowledge_base/{dbName}`.
**SQLite** stores structured metadata: knowledge base records, attachment details, and content chunk information. Schema migrations are managed through Drizzle ORM.
### Knowledge Base Identifiers
Each knowledge base is identified by a composite key in the format `{dbName}|{tableName}`. This key is used throughout the system when referencing a specific knowledge base.
## Document Processing Pipeline
When you add content to a knowledge base, it flows through a multi-stage pipeline.
### Stage 1: Content Loading
The `AttachmentLoader` routes content to the appropriate loader based on type:
| Content Type | Loader | Description |
| - | - | - |
| **PDF** | pdf-parse | Extracts text from PDF documents |
| **DOCX** | mammoth | Converts Word documents to text |
| **PPTX** | officeparser | Extracts text from PowerPoint presentations |
| **EPUB** | epub2 | Parses e-book content |
| **XLSX / CSV** | xlsx, d3-dsv | Reads spreadsheet data |
| **TXT / MD** | Direct read | Plain text and Markdown files |
| **HTML** | cheerio, html-to-text | Parses and extracts text from HTML |
| **XML / JSON** | fast-xml-parser | Structured data parsing |
| **Images** | OCR Provider | Optical character recognition |
| **Audio / Video** | Transcription Provider | Speech-to-text conversion |
| **Webpages** | Link Reader Provider | Scrapes page content (supports sitemap.xml for entire websites) |
| **YouTube** | Dedicated handler | Extracts transcript and metadata |
### Stage 2: Text Chunking
After content is extracted, it is split into manageable chunks using `RecursiveCharacterTextSplitter` from LangChain:
| Parameter | Value | Description |
| - | - | - |
| **Chunk size** | 6,000 characters | Maximum size of each text chunk |
| **Chunk overlap** | 100 characters | Overlap between consecutive chunks for context continuity |
The recursive splitter tries to split on natural boundaries in this order:
1. Double newlines (paragraphs)
2. Single newlines
3. Sentences (periods, exclamation marks, question marks)
4. Words (spaces)
5. Characters (last resort)
The 6,000-character chunk size balances retrieval precision with context completeness. Smaller chunks improve precision but may lose context. Larger chunks preserve context but may include irrelevant information.
### Stage 3: Embedding
Each text chunk is converted to a vector embedding using your configured embedding model. EnConvo uses a custom `EnConvoEmbeddingFunction` that wraps the platform's embedding provider system.
Embeddings are generated in batches with concurrent processing for performance.
### Stage 4: Storage
Embedded chunks are stored in LanceDB with the following schema:
| Field | Type | Description |
| - | - | - |
| `text` | Source text | The original text chunk |
| `vector` | Float32 array | The embedding vector |
| `id` | UTF-8 string | Unique chunk identifier |
| Additional metadata | Various | Source file, position, timestamps, etc. |
## Embedding Model Selection
Choose an embedding provider available in the [Provider Catalog](/providers/catalog#embeddings) and the knowledge base's settings. Keep the same model and dimensions for indexing and query embeddings. Changing the model can require re-embedding the stored content; a new model selection alone does not convert existing vectors.
Test a representative document and query before importing a large collection. Consider language support, local resource use, cloud processing, and the provider's current limits.
## Search and Retrieval
EnConvo uses a hybrid search approach combining vector similarity with full-text search.
### Vector Similarity Search
The primary search method. When you query the knowledge base, your query is embedded using the same model, then compared against all stored vectors using cosine similarity.
```
Query "How does authentication work?"
→ Embed query → [0.12, -0.45, 0.78, ...]
→ Compare against all chunk vectors
→ Return top-K most similar chunks
```
### Full-Text Search (FTS)
LanceDB also supports full-text search with fuzzy matching for keyword-based retrieval. This catches cases where exact terms matter more than semantic meaning.
```
Query "OAuth2 PKCE flow"
→ Full-text index lookup with fuzziness
→ Return matching chunks
```
### Hybrid Search Strategy
For best results, EnConvo combines both approaches:
1. Run vector similarity search for semantic matches
2. Run full-text search for keyword matches
3. Merge and deduplicate results
4. Apply reranking (if configured) to produce the final ranking
### Reranking
Reranking models re-score search results for improved relevance. After the initial retrieval, a reranker evaluates each result against the query and reorders them.
Use the rerankers offered by your installed build; see [Provider Catalog](/providers/catalog#reranking). Reranking may involve a separate local model or cloud request.
Reranking is especially useful when you have large knowledge bases. The initial search retrieves a broad set of candidates, and the reranker narrows them down to the most relevant results.
## Performance Optimization
### Batch Embedding
When adding multiple documents, EnConvo processes embeddings in batches with concurrent processing. This significantly reduces the time to index large document collections compared to sequential processing.
### Index Management
LanceDB supports creating indexes for faster search:
* **Vector index**: Speeds up similarity search for large tables
* **FTS index**: Enables full-text search with fuzzy matching
Indexes are created automatically when needed. For very large knowledge bases, you may want to trigger re-indexing after bulk imports.
### Storage Considerations
Storage depends on the original assets, extracted text, chunk count, and embedding dimensions. Monitor actual disk use for your collection instead of estimating it only from the number of documents. Keep source files and backups independently of the search index.
## Multi-Knowledge Base Management
You can create multiple knowledge bases for different purposes. Each operates independently with its own:
* Embedding model
* Document collection
* Search index
* Storage location
### Organization Strategies
| Strategy | Description | Example |
| - | - | - |
| **By project** | One KB per project | `project-alpha`, `project-beta` |
| **By type** | Separate KBs by content type | `code-docs`, `meeting-notes`, `research` |
| **By team** | Team-specific knowledge | `engineering`, `marketing`, `support` |
| **By scope** | Personal vs shared | `personal-notes`, `company-wiki` |
### Querying Multiple Knowledge Bases
Attach the intended knowledge bases with the context picker, or configure the Agent's attached knowledge bases. Available choices depend on the installed build and Agent settings.
## Knowledge Base API
The knowledge base extension exposes API endpoints for programmatic access. These are used internally by EnConvo and can be accessed by other extensions and workflows.
### Key Endpoints
| Endpoint | Purpose |
| - | - |
| **Create Knowledge Base** | Create a new knowledge base with specified embedding model |
| **Delete Knowledge Base** | Remove a knowledge base and all its data |
| **Add Content** | Ingest files, text, URLs, or media into a knowledge base |
| **Search / Retrieve** | Perform semantic search against a knowledge base |
| **List Knowledge Bases** | List all available knowledge bases |
| **List Attachments** | List all documents in a knowledge base |
| **Delete Attachment** | Remove a specific document from a knowledge base |
| **Summarize** | Generate an AI summary of knowledge base content |
### Using in Workflows
Knowledge base operations can be used as steps in workflows:
```
Trigger: New file in ~/Documents/research/
→ Add to Knowledge Base "research"
→ Search for related content
→ Generate summary
→ Save summary to notes
```
## Advanced Configuration
### Chunking
The current text loader uses 6,000-character chunks with a 100-character overlap. These are implementation defaults, not a universal user-facing settings control. Parsing and indexing changes should be tested on a small collection before a rebuild.
### Monitoring and Maintenance
* **Re-index**: If search quality degrades after many incremental updates, re-index the knowledge base to rebuild indexes
* **Embedding model upgrades**: When better models become available, create a new knowledge base with the new model and re-ingest your content
* **Storage cleanup**: Delete knowledge bases you no longer need to reclaim disk space
## Troubleshooting
Try these steps in order:
1. Check that the embedding model is appropriate for your content language
2. Re-index the knowledge base to rebuild search indexes
3. Consider enabling reranking for better result ordering
4. If content is very domain-specific, try a more capable embedding model
Large documents take longer to process. To improve speed:
* Use a cloud embedding provider for batch processing
* Ensure your Mac has sufficient RAM (embedding models are memory-intensive)
* For local models, check that your Mac supports Metal acceleration
If a file type is not directly supported, try converting it to a supported format (PDF, TXT, or MD) before adding it to the knowledge base.
Knowledge bases are identified by composite keys (`dbName|tableName`). Ensure you are referencing the correct name. Check **Settings** -> **Knowledge Base** for the list of available knowledge bases.
## Related Features
Getting started with knowledge bases
Chat with your knowledge base
Automate knowledge base tasks
Configure embedding and reranking providers
## Linked-folder and indexing checks
For a missing item, inspect the source folder's import and synchronization status first. Then inspect the item's content-extraction status and embedding status separately: readable extracted text does not guarantee that vector indexing has finished. Retry the failed stage after fixing its provider or file-access error.
The source folder remains the authority for linked files. Keep offline-drive recovery separate from file deletion, and review skipped-file counts before treating an import as complete.
For client access, use [Knowledge Base MCP](/advanced/knowledge-base-mcp). It exposes selected knowledge bases through a local, read-only service; it does not export Agent Memory or recordings.
# Connect AI Clients to Knowledge Base
Source: https://docs.enconvo.ai/advanced/knowledge-base-mcp
Let local AI clients search selected Enconvo knowledge bases.
Enconvo can serve your knowledge bases to MCP-compatible AI clients on the same Mac. This is separate from **Settings → Plugins → MCP Servers**, which adds external tools to Enconvo's Agents.
This feature is available in builds that include **Connect AI Clients (MCP)**. If it is absent, check your [update channel](/configuration/updates).
## Connect a client
1. Open the **Knowledge Base** window.
2. Open its **Settings → Connect AI Clients (MCP)** dialog.
3. Enable the Knowledge Base MCP server.
4. Review **MCP visible** for every knowledge base you want the client to access. Dictation History is hidden by default.
5. Copy the setup instructions for your client from the dialog. Use **Streamable HTTP** for clients that support it.
6. Ask the client to list knowledge bases, then search one and read a matching item.
The local endpoint is:
```text theme={null}
http://localhost:54535/knowledge_base/mcp
```
Keep Enconvo running while the client uses the endpoint. Clients that require a stdio bridge should use the client-specific instructions shown in the dialog.
## Available tools
| Tool | Purpose |
| - | - |
| `kb_list` | List visible knowledge bases |
| `kb_search` | Search a visible knowledge base |
| `item_list` | List items in a visible knowledge base |
| `item_read` | Read indexed item text in pages |
The tools are read-only. This endpoint does not expose general Memory or Recordings tools. Reading an item can return its source path or URL as metadata.
## Access and processing
The server accepts loopback connections only and does not require a token. Enabling it allows local processes to access the knowledge bases you make visible. A connected AI client can send returned content to its own model provider; review that client's configuration as well.
Search uses the knowledge base's configured embedding provider and can incur that provider's normal usage. “Local endpoint” does not mean every part of retrieval and answering runs offline.
## Troubleshooting
| Symptom | Check |
| - | - |
| Connection refused | Enconvo and its local API must be running |
| Forbidden / 403 | Server switch, local connection, and supported client configuration |
| Knowledge base not found | Its **MCP visible** setting; hidden and missing bases look the same to clients |
| Opening the URL in a browser shows 405 | A browser GET is not an MCP initialization request; connect with an MCP client |
| Incomplete long document | Ask the client to request further pages with `item_read` |
Disable the server to stop access, or hide individual knowledge bases to narrow what clients can retrieve.
# Creating Custom MCP Servers
Source: https://docs.enconvo.ai/advanced/mcp-advanced
Build a small local MCP tool and connect it to Enconvo.
A custom MCP server exposes tools that an Enconvo Agent can call. Start with a small local server, verify its inputs and result, then add the service-specific work you need. For installing existing servers, see [MCP setup](/features/mcp).
## A minimal local server
This example uses the TypeScript SDK's **1.x JavaScript API**, pinned to 1.29.0. SDK major versions can use different imports and setup; consult the [official MCP server guide](https://modelcontextprotocol.io/docs/develop/build-server) when choosing another version.
```sh theme={null}
mkdir hello-mcp
cd hello-mcp
npm init -y
npm install @modelcontextprotocol/sdk@1.29.0 zod@3
```
Save this as `server.mjs`:
```javascript theme={null}
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
const server = new McpServer({ name: "hello-enconvo", version: "1.0.0" });
server.registerTool("greet", {
description: "Return a greeting for the supplied name.",
inputSchema: { name: z.string().min(1).describe("Name to greet") },
}, async ({ name }) => ({
content: [{ type: "text", text: `Hello, ${name}!` }],
}));
await server.connect(new StdioServerTransport());
```
A stdio server waits for protocol messages; starting it in a terminal does not display a chat interface. Keep diagnostics on stderr (for example, `console.error`) because stdout carries MCP protocol messages. The [official guide](https://modelcontextprotocol.io/docs/develop/build-server) explains this transport requirement.
## Connect it to Enconvo
Open **Settings → Plugins → MCP Servers**, add a server, and select **stdio**. Set the command to your Node executable and the argument to the absolute path of `server.mjs`.
Equivalent configuration:
```json theme={null}
{
"command": "node",
"args": ["/absolute/path/to/hello-mcp/server.mjs"]
}
```
Replace the example path with your file's actual path. If Enconvo cannot find Node, use its absolute executable path. Confirm the server connects and exposes `greet`, then make it available to your Agent and ask it to greet “Ada.” The expected tool result is `Hello, Ada!`.
## Design useful tools
* Give each tool a specific action and description.
* Validate input at the tool boundary and return useful error messages.
* Separate reading data from mutations such as sending or deleting.
* Return a compact result that the Agent can interpret.
* Keep credentials in the server's appropriate configuration, outside source examples and logs.
## Remote servers and authentication
For a remote server, use the HTTP or SSE transport offered by its setup instructions and the corresponding Enconvo form. The server URL must be the MCP endpoint rather than an ordinary website URL. Complete any supported authorization flow and confirm the connection before enabling its tools.
Remote transport, authentication discovery, and session behavior depend on the server and protocol version. Use the official SDK and protocol documentation for implementation details rather than inventing an `auth` manifest that Enconvo does not consume.
## Troubleshooting
| Symptom | Check |
| - | - |
| Process exits immediately | Executable path, dependencies, syntax errors, and stderr |
| Connected but no tool appears | Registration, tool enablement, and the selected Agent |
| Invalid protocol response | Accidental stdout logging or launching the wrong program |
| Schema validation error | The actual input shape and SDK version |
| Remote connection failure | Endpoint URL, transport, authentication, and network access |
For exposing Enconvo's own documents to another AI client, use the built-in [Knowledge Base MCP server](/advanced/knowledge-base-mcp); a custom server is not required.
# Agents
Source: https://docs.enconvo.ai/ai/agents
Create an assistant with instructions, models, and tools.
An Agent combines instructions, a model, and tools for a particular kind of work. Open **Settings → Agents → Agent List** to manage Agents.
## Create an Agent
1. Choose **New Agent** or run **Create Agent** from SmartBar.
2. Give it a clear name and purpose.
3. In **Definition**, describe what it should do, what input it needs, and how it should present results.
4. Choose its model and configure the tools and context sources it needs.
5. Save, open a new conversation with it, and test a small representative task.
Example instruction:
```text theme={null}
Help me turn meeting notes into actionable follow-ups.
Separate decisions, open questions, and action items.
For action items, preserve the owner and due date if stated;
otherwise mark them as unspecified.
```
## Choose tools deliberately
| Need | Capability |
| - | - |
| Read and edit documents | [File tools](/ai/file-tools) |
| Find current information | [Web Search](/ai/web-search) and [Web Fetch](/ai/web-fetch) |
| Work in websites | [Browser Control](/features/browser-control) |
| Operate desktop apps | [Computer Use](/features/computer-use) |
| Search your material | [Knowledge Base](/ai/knowledge-base) |
| Reuse a procedure | [Skills](/configuration/skills) |
| Connect an external service | [MCP Servers](/features/mcp) |
| Run code | [Code Runner](/ai/code-runner) |
A model must support the required tool and input capabilities. Tools also need their own credentials, access, and setup. An Agent instruction does not itself grant a missing permission.
## Approve actions
The **Permissions** chip next to the run mode sets when an Agent stops to ask before it acts. It appears in Agent mode in the chat window, SmartBar, the app sidebar, and the Dynamic Island, and every one of them changes the same setting for that Agent, so a change in one shows in the others:
| Mode | Asks before |
| - | - |
| **Ask for approval** | Running commands, editing files outside the working folder, and acting in apps, browsers, or online services |
| **Approve for me** (default) | Only actions that look potentially unsafe, such as deleting files, sending messages, publishing, or paying |
| **Full access** | Nothing. The Agent acts without asking |
Reading files, searching, and looking at the screen never ask. The question appears in the window the chat runs in; if that window is not showing the chat (for example it is hidden, or it is the Inline Panel), it moves to the Dynamic Island. If nobody answers it there within 30 seconds, your paired iPhone gets a reminder notification, even when the chat's window is still open behind the app you're using. If you close the island's card without answering, click the waiting step in the island's chat to see the options again. Questions the Agent asks you work the same way. Choose **Yes, allow once**, **Yes, and don't ask again** for the rest of that chat (remembered even after Enconvo restarts), or type what the Agent should do instead. While a chat waits, it shows **Waiting for approval** instead of running in the chat window's list, SmartBar's recent chats, and the Dynamic Island, and the iPhone app's chat list marks it **Needs approval**. Subagents ask in their parent chat, and the question says a subagent is asking and which task it is working on. Scheduled tasks, workflows, and IM channels run without asking, because nobody is at the window to answer.
## Subagents
In Agent mode, an Agent can split a task into parts and start up to six subagents that work at the same time, each in its own conversation, and it answers once they report back. It does this only when splitting clearly helps, such as several independent searches, or when you ask. If an AI error such as a rate limit stops a subagent partway, the Agent still gets what it found so far and can let it continue once the error clears. A card in the chat lists each subagent by its task, with an icon showing whether it is running, waiting for your approval, done, or failed, and a running subagent's row also shows what it is doing right now; click a row to open that subagent's conversation, whose Workspace panel and `@` file search show the working folder of the chat that started it (in SmartBar and the Dynamic Island its work opens in place). You can also type in a subagent's conversation: it answers you there, can ask you questions, asks for approval in that conversation, and keeps working in the same folder. The Agent that started it waits while it answers you, and then sees its newest answer. In the chat window's sidebar, a chat's subagents are listed under it, and a button on the chat's row folds the list. Every subagent starts in a role:
| Role | What it does |
| - | - |
| **Default** | Works as the Agent that started it, with the same instructions, tools, and model |
| **Explorer** | Only reads files, searches, and looks at apps. It cannot edit, run commands that change anything, or act online, whatever the Permissions chip says |
| **One of your Agents** | Runs as that Agent, with its own instructions, tools, and model, in the same working folder as the chat that started it |
| **A project helper** | Defined by the project in `.claude/agents`, `.codex/agents`, or `.enconvo/agents`, in the working folder or a folder above it up to the repository root. Works as the Agent that started it, following the helper's own instructions. It uses only the tools the file lists, only reads when the file says so, and uses the helper's model when your model provider offers it |
To choose one yourself, type `@` in an Agent-mode chat and pick it from the **Subagents** group, which lists the project's helpers, **Explorer**, and a general **Subagent**. The Agent starts that Subagent for your message, writes it the task, and answers once it reports back. Your own Agents stay in the menu's Agents group.
Describe each Agent clearly in its settings: the Agent that splits the work reads those descriptions to decide which one fits a task.
Project helpers use the same files as Claude Code subagents and Codex agent roles, so a repository that already has them needs no extra setup. A Claude Code file (Markdown with `name` and `description` in its frontmatter) is read-only when it sets `permissionMode: plan` or lists only reading tools such as `Read`, `Grep`, and `Glob`; a Codex file (TOML with `description` and `developer_instructions`) is read-only with `sandbox_mode = "read-only"`. When the provider does not offer the helper's model, the helper uses the chat's model instead.
A Claude Code file's `tools` and `disallowedTools` decide which of the Agent's tools the helper may use. Enconvo matches each name to its own tool:
| In the helper file | The helper may |
| - | - |
| `Read`, `Grep`, `Glob`, `LS` | Read and search files |
| `Edit`, `MultiEdit`, `Write` | Edit and create files |
| `Bash` | Run any shell command |
| `Bash(git diff:*)` | Run only commands that start with `git diff` |
| `WebSearch`, `WebFetch` | Search the web and read web pages |
| `mcp__github__get_issue`, `mcp__github` | Use one tool, or every tool, of a connected MCP server |
With no `tools` line, the helper has every tool except the ones `disallowedTools` names. A call outside the list is not run, and the helper is told which tools it has. Every helper can still load skills and ask you questions. In an `.enconvo/agents` file, you can also list Enconvo tools by their API path, such as `browser-use/*`.
## Ways to reach an Agent
Use Chat Window, SmartBar, or the Dynamic Island. Configure **Voice Trigger** to dispatch spoken requests to selected Agents. [Live Voice](/features/live-voice) provides conversation, and [Avatars](/features/avatar) add a desktop character. [IM Channels](/integrations/messaging) connects messaging apps. [Scheduled Tasks](/workflows/scheduled-jobs) can run an Agent later.
## Defaults and continuity
Review [model defaults](/ai/model-selection-guide) when changing an Agent used by multiple conversations or channels. Configure [Memory](/ai/memory) when you want reusable facts, and organize documents in a knowledge base rather than putting everything into the instruction.
## Improve a failing Agent
Inspect the tool error or missing input first. Test the same request without optional tools to isolate model access, then add capabilities one at a time. For actions that modify files or external systems, review the requested destination and effect.
# Chat
Source: https://docs.enconvo.ai/ai/chat
Manage conversations, projects, context, and model choices.
The Chat Window is Enconvo's main space for ongoing conversations. Choose an Agent, add the material it needs, and keep related work together.
## Start a conversation
1. Open **Chat Window** from Enconvo.
2. Select an Agent and create a **New chat**.
3. Type your request and attach any relevant files, app context, or knowledge-base material.
4. Check the model and reasoning selection.
5. Send the request and follow tool progress if the Agent is using tools.
Use a complete request: “Summarize the attached proposal in five bullets and list open questions” gives the Agent both input and an expected result.
## Organize work
Use the sidebar to return to recent conversations and organize related conversations in projects where available. Check a conversation's menu for renaming, moving, archiving, or deletion actions supported by your build. Read the confirmation before deleting history.
### Model choices
A top-level **New chat** can set the Agent's model default. A new conversation inside a project uses that project's model preference. Each created chat can keep its own model and reasoning override. See [Model Selection](/ai/model-selection-guide) before changing defaults used elsewhere.
## Context and attachments
Use only the sources relevant to the request. A file attachment, screen capture, knowledge-base lookup, and browser page provide different kinds of context. See [Context Awareness](/features/context-awareness) for source selection and [Files and Folders](/ai/file-tools) for Agent file access.
The Agent's [Memory](/ai/memory) and a [Knowledge Base](/ai/knowledge-base) have different purposes: memory holds reusable facts; a knowledge base stores material for retrieval.
## Read and reuse responses
Expand work details to inspect tool calls and their results. The reply action row offers **Copy**, **Read Aloud**, and **More** in current builds. [Visual Answers](/features/visual-answers) can embed diagrams or interactive content directly in a reply.
Use [Dictation](/features/dictation) to compose with speech, or [Live Voice](/features/live-voice) for a two-way spoken conversation.
## Troubleshooting
If a response uses the wrong model, inspect this conversation's selection as well as the Agent default. If the Agent cannot see a file or screen, review its attachments and permissions. If a tool is unavailable, check the Agent's enabled tools instead of repeatedly rephrasing the same request.
# Code Runner
Source: https://docs.enconvo.ai/ai/code-runner
Run shell commands and interact with persistent terminal sessions from an Agent.
Code Runner gives an Agent a real terminal on your Mac. Use it for builds, tests, scripts, package tools, and development servers. Enable the tool for the Agent you are using; installed command-line programs and your account permissions determine what can run.
## Start with a small command
Give the Agent a directory and a specific task:
> In my sample project, run the existing test command and report the result. Do not change files.
The Agent should show command output and distinguish successful completion from a command that is still running. Use [File Tools](/ai/file-tools) for reading, editing, and searching files.
## Terminal sessions
All execution modes use a pseudo-terminal, so a command that asks for input can be answered without starting a new process.
| Mode | Intended use |
| - | - |
| **oneshot** | Commands expected to finish, such as tests, builds, or a script |
| **long\_running** | Servers, watchers, and processes waiting for an external event |
| **interactive** | REPLs, terminal applications, and interactive CLI sessions |
A result with `status: running` and a `session_id` means the process continues. The Agent can **read** output, **write** input, or **stop** that session. Starting another command is not a substitute for answering a prompt in the existing session.
## Working directory and time limits
The tool accepts `workDir` for the command's working directory and uses the user's shell with project and Python virtual-environment setup. Separate command launches do not share temporary shell variables unless they are in the same running session.
The initial wait is separate from the command's hard timeout. Current oneshot commands default to a 30-minute hard deadline; the initial response can arrive much earlier while work continues. Use long-running mode for a server or watcher rather than treating it as a failed oneshot command.
## Output compression
**Enable RTK** in the Code Runner command preferences compresses verbose output for the Agent. If an important detail is missing, ask for a more focused command or the relevant log section. Truncated output is not proof that the command succeeded.
## Troubleshooting
* **Command not found:** verify the program is installed and available in the shell environment.
* **Waiting for input:** continue the existing session and answer its prompt.
* **Permission denied:** check the target path and macOS permissions.
* **Timed out:** inspect the last output; use the appropriate execution mode before retrying.
* **Server still running:** stop its session when it is no longer needed.
Commands execute with real filesystem and network access. Review commands that install software, change files, or affect external services before running them. Code Runner does not make those operations a sandbox simulation.
# Files and Folders
Source: https://docs.enconvo.ai/ai/file-tools
Let an Agent find, read, and edit local files.
Enconvo's file tools help an Agent work with files in its allowed directories. Enable only the tools needed for the task in the Agent's settings and give the Agent an explicit folder or file to work with.
## Start with a read-only task
1. Open the Agent's settings and review its file tools and directory access.
2. In the conversation, identify a folder or attach the file you want to use.
3. Ask a bounded question, such as “Find Markdown files in this project and summarize the README.”
4. Review the files and tool output the Agent used before asking it to make changes.
| Tool | Purpose |
| - | - |
| Glob | Find files by path pattern, such as `**/*.md` |
| Grep | Search text inside files, with file patterns and line numbers |
| Read File | Read text or extract supported document/media content |
| Edit File | Replace matching text and return a diff |
| Write File | Create a file or replace its complete contents |
Write File can overwrite an existing file. Use a copy or version control for important documents, and review the destination and requested changes before approving an action.
## Documents and media
Reading a PDF, Office document, image, audio file, or video can invoke parsing, OCR, or transcription rather than returning raw bytes. Supported formats and processing depend on the installed tools and configured providers. See [OCR](/ai/ocr), [Transcription](/features/transcription), and [Knowledge Base](/ai/knowledge-base).
## Troubleshooting
For an access error, check the Agent's allowed directories and macOS permissions. For an empty extraction, confirm the file type and parser support. A scanned PDF may need OCR. For an edit that cannot match the requested text, have the Agent read the current file again before editing.
[Code Runner](/ai/code-runner) executes code and shell commands; file tools can inspect and edit without requiring a shell for every operation.
# Image Generation
Source: https://docs.enconvo.ai/ai/image-generation
Generate and edit images with a configured image provider.
Configure image creation under **Settings → Global Providers Settings → Image Generation**. The image provider is separate from the model used for ordinary chat.
## Generate an image
1. Choose a provider and model in Image Generation settings and configure its access.
2. Use an Agent with image-generation tools, or the image-generation command available in your build.
3. Describe the subject, composition, style, and intended use.
4. Choose size, aspect ratio, or quality only from options supported by that model.
5. Wait for completion, open the result, and save the output you need.
Example:
```text theme={null}
Create a square illustration for a guide to organizing research.
Show three labeled folders on a tidy desk, with a warm neutral palette.
Leave the top third clear for a title.
```
## Edit an image
Attach the source image and describe the specific changes. Choose a model that supports image editing/reference input. State what should stay consistent, and review the result for unintended changes.
The [image provider catalog](/providers/catalog#image-generation) includes OpenAI, Gemini, xAI, OpenRouter, Kie.ai, Topview, Azure, Together, and supported Cloud variants. Capabilities are model-specific; a provider name alone does not guarantee every editing mode.
## Troubleshooting
Check access, model availability, supported input formats, and the provider error. Generation can take longer than a text reply. If an edit ignores the attachment, confirm that the chosen model accepts image input and that the file was attached to the request.
For an inline diagram or interactive explanation, see [Visual Answers](/features/visual-answers). For compression, see [Media Utilities](/features/media-tools).
# Knowledge Base
Source: https://docs.enconvo.ai/ai/knowledge-base
Collect documents, notes, webpages, and linked folders, then use them in conversations.
A Knowledge Base holds material you want Enconvo to retrieve later. Use it for reference documents, project notes, captured webpages, and spoken notes. [Memory](/ai/memory) serves a different purpose: information an Agent retains across conversations.
## Create and open a knowledge base
1. Open **KnowledgeBase** from Settings, or search for **Create Knowledge Base** in SmartBar.
2. Give it a clear name and review its provider settings.
3. Open the knowledge base and use **Add** to import material.
4. Wait for processing to finish, then open an item to inspect the extracted content.
Use the knowledge base switcher to keep unrelated projects separate. Within a knowledge base, folders organize items; grid and list views provide different ways to browse them.
## Add content
| Entry | Use it for |
| - | - |
| **Add → Files** | Supported documents, images, audio, or video from your Mac |
| **Add → Note** | A new editable Markdown note |
| **Add → Single Web Page** | Content from one URL |
| **Add → Youtube Video** | A video and its available captions |
| **Import Folder** | A local folder with its structure and optional synchronization |
| Drag or paste files into the knowledge base | Fast import from Finder |
| [Quick Capture](/features/quick-capture) | Save the current app's content |
| [Voice Note](/features/voice-notes) | Record and save a spoken note |
Document loaders support common text, Markdown, PDF, Office, EPUB, and structured-data formats. Images need OCR; audio/video needs transcription. Parsing quality and supported formats depend on the selected loader and providers. Check the import preview and each item's processing status for files that are skipped or fail.
## Linked folders
1. Choose **Import Folder** from the folder area or empty-state action.
2. Select a source folder, review file counts and skipped files, and confirm.
3. Open its folder inspector to review the source path, synchronization status, and controls.
4. Choose **Sync Now**, or turn on **Auto-sync** to follow changes while Enconvo runs.
The source folder remains on disk. New and changed files are imported; deleted source files are removed from the linked knowledge base content. Hidden files, unsupported formats, and files above the import size limit are skipped. Enconvo's folder sync does not edit the source files.
If a source drive is disconnected, restore access or relink the folder before syncing. A missing source is handled separately from an intentionally deleted file. See [Knowledge Base Deep Dive](/advanced/knowledge-base-advanced) for processing and sync troubleshooting.
## Ask questions using your sources
Attach a knowledge base or a specific item using the context picker available in your chat or SmartBar. Review the attached source before submitting; the picker's available entries are the source of truth, rather than typing a special `@kb` command.
Try:
> Using the attached project notes, list the decisions about authentication and cite the source for each decision.
An Agent with knowledge tools can search and read available material. Retrieval selects relevant passages rather than sending every document. Open cited items to verify important details. If a passage is missing, attach the specific document or inspect whether it finished processing.
## Edit and maintain
Open a note to edit its Markdown. Use item and folder menus to rename, organize, export, or remove content where those actions are offered. Read the removal confirmation: removing knowledge base content and deleting a source file are different operations.
When an item fails, inspect whether extraction or embedding failed before retrying. A document may be readable before all search indexing is complete. Changing an embedding provider can require rebuilding embeddings; see the deep-dive guide before changing a populated knowledge base.
## Connect another AI app
Open the knowledge base's **Settings → Connect AI Clients (MCP)** to expose selected knowledge bases to a local MCP client. This is a separate, opt-in, read-only service. Follow [Knowledge Base MCP](/advanced/knowledge-base-mcp) for setup and visibility controls.
## Data handling
Knowledge base files and indexes are stored locally. Selected cloud OCR, transcription, embedding, reranking, or chat providers can receive the content needed for their work. Local storage does not imply that provider processing is offline. Review [Privacy & Security](/configuration/privacy-security) and the selected providers before importing sensitive material.
# Local Models
Source: https://docs.enconvo.ai/ai/local-llm
Choose on-device processing and connect local model servers.
Enconvo supports local inference through MLX, Ollama, and LM Studio. Choose the runtime that serves the model you need and verify each stage of your task if you want to keep processing on-device.
| Runtime | Setup | Hardware/location |
| - | - | - |
| [MLX](/providers/mlx) | Download a supported model in its provider settings | Apple Silicon Mac |
| [Ollama](/providers/ollama) | Start a model server and configure its URL | Same Mac or reachable server |
| [LM Studio](/providers/lm-studio) | Load a model and start its API server | Same Mac or reachable server |
## Start small
1. Configure the local provider and download/load a model.
2. Send a short text-only request.
3. Add larger documents or tools after the basic request succeeds.
4. Check memory use and response time before choosing a larger model.
Model parameter count, quantization, context size, and concurrent tasks all affect memory. Use the model manager’s actual size and compatibility information instead of a fixed RAM table.
## Keep the whole task local
Review more than the chat model: speech recognition, text-to-speech, OCR, document parsing, embeddings, reranking, search, and MCP tools can use separate providers. Enconvo offers local providers for several of these categories, listed in the [catalog](/providers/catalog).
Web search and external services still require network access. A local model can also call tools that send content outside the Mac.
## LAN connections
When using a server on another computer, configure its LAN address and listen interface. Check macOS **Local Network** permission if connection errors mention the network being blocked. `localhost` refers to the Mac running Enconvo, not the remote model server.
See [Privacy and Security](/configuration/privacy-security) for data-flow checks.
# Memory
Source: https://docs.enconvo.ai/ai/memory
Review and maintain facts an Agent can reuse.
Memory stores reusable information for Agents, such as preferences or facts that should carry beyond one reply. It is different from a conversation transcript and from a knowledge base of documents.
## Review memory
1. Open **Settings → Memory → Memory**.
2. Search or filter by the categories, types, and Agents shown in the interface.
3. Open a memory to review its content and associated information.
4. Edit inaccurate or outdated facts, or delete them after reviewing the confirmation.
The management interface also supports adding a memory directly. Keep entries concise, factual, and specific about who or what they concern.
## Use memory deliberately
Check the Agent's memory configuration when testing whether a fact should be reused. A fact in one Agent's context is not proof that every other Agent or chat will use it. Verify with a new, ordinary request rather than assuming memory capture or retrieval happened automatically.
Do not store credentials or sensitive information simply to avoid re-entering it. Model requests can include retrieved memory, depending on the Agent and provider configuration.
## Memory, knowledge, and capture
| Material | Best place |
| - | - |
| A short reusable preference or fact | Memory |
| Documents and reference material | [Knowledge Base](/ai/knowledge-base) |
| A quick spoken idea | [Voice Note](/features/voice-notes) |
| Content visible in another app | [Quick Capture](/features/quick-capture) |
| A temporary discussion | [Chat](/ai/chat) |
If an answer uses an old fact, inspect the stored memory and current conversation context. Correct the underlying entry rather than only correcting one reply.
# Choose a Model
Source: https://docs.enconvo.ai/ai/model-selection-guide
Match the model to your task, access method, and input.
Use the model picker in Enconvo as the current list of models your configured provider can use. Model availability, limits, and pricing change; a model name alone does not establish access or capabilities.
## Choose by task
| Task | Check before choosing |
| - | - |
| Quick rewrite or short answer | Latency, output quality, and cost |
| Multi-step Agent work | Reliable tool calling and suitable reasoning support |
| Screenshot or image question | Image input support |
| Long document | Supported context length and how the document is extracted |
| Private/offline work | Local inference plus local processing for any supporting tools |
| Voice conversation | [Realtime Voice](/features/live-voice) access, configured separately |
| Image or video creation | The appropriate generation provider, not merely a chat model |
## Defaults, projects, and conversations
In current builds, selecting a model in a top-level **New chat** sets the Agent’s default. Starting a new chat inside a project uses that project’s own model preference. Once created, a chat keeps its selected model and reasoning effort until you change them in that chat.
Existing chats without an explicit override, and IM channels, can continue to follow the Agent default. Check the model shown in the conversation before sending a request if you have just changed a default elsewhere.
## Reasoning and generation controls
Reasoning effort changes how a supported model approaches a task and can affect latency and usage. Temperature and other generation controls vary by model; use the controls available in your selected provider rather than assuming all providers share the same range or settings.
## Compare fairly
Try the same small, representative task on two candidate models. Check correctness, tool completion, latency, and usage. For important work, validate the result against the source material rather than judging only fluency.
See [Providers](/providers/overview), [Credentials](/configuration/credentials), and [Cloud pricing](https://www.enconvo.com/cloud-pricing).
# OCR
Source: https://docs.enconvo.ai/ai/ocr
Extract text from images and selected screen regions.
Enconvo provides OCR commands and a selectable OCR provider. Use local Apple OCR, local MLX OCR, an AI model, or a supported cloud OCR provider according to the material you need to read.
## Extract text from the screen
1. Open **Settings → Global Providers Settings → OCR** and choose a provider.
2. Run **Screenshot OCR** and select the relevant screen region.
3. Review the extracted text before copying or using it in another command.
**Silent Screenshot OCR** copies its result to the clipboard. **OCR** processes supplied image input. **Screenshot Translate** and **Screenshot Explain** add a follow-up task to a screen capture.
## Choose a provider
| Provider | Processing |
| - | - |
| Apple Native OCR | Native local text recognition |
| PP-OCRv6 (MLX) | Local detection and recognition on supported Apple Silicon hardware |
| AI Model OCR | Use a configured AI model and instruction |
| Mistral OCR / Cloud variant | Remote OCR through configured access |
See [Provider Catalog](/providers/catalog#ocr) for current configuration fields.
## Improve accuracy
Capture a tight, readable region at a useful scale. Check columns, tables, punctuation, code indentation, and ambiguous characters manually. A scanned document may require OCR even when it has a PDF file extension.
If screen capture is blank or unavailable, check [Permissions](/configuration/permissions). If recognition fails, test a simple image and read the selected provider's error. For asking about a visual element rather than extracting text, try [Appshots](/features/appshots) or [Screen Doodle](/features/screen-doodle).
# Speech Recognition
Source: https://docs.enconvo.ai/ai/speech-recognition
Configure speech models for dictation, recording, files, and captions.
Enconvo uses separate speech-model settings for different jobs. Choose the recognition model in the feature you are actually using.
| Feature | Settings entry | Guide |
| - | - | - |
| Speech inserted as text | Dictation Models | [Dictation](/features/dictation) |
| Meeting or lecture recording | Recording Models | [Meeting Recording](/features/meeting-recording) |
| Existing audio/video file | Transcription Models | [Transcription](/features/transcription) |
| Realtime subtitles | Captioning Model | [Live Captioning](/features/live-captioning) |
## Choose a model
Open the corresponding model settings, choose a provider, and review language and model options. Cloud Plan variants use your Enconvo account; direct providers use their own configured access. Local MLX and CoreML options process recognition on-device after required models are available.
See the [complete speech-provider catalog](/providers/catalog#speech-recognition) for the declared providers, including cloud services and local Parakeet, Qwen, Whisper, SenseVoice, Paraformer, and Nemotron variants. Hardware and availability depend on the selected runtime and build.
## Match capabilities to the task
* **Streaming:** produces partial text during recording; use a realtime-capable model.
* **Batch transcription:** processes a file after capture/upload.
* **Language hints and hot words:** guide recognition when the provider supports them.
* **Speaker diarization:** separates voices; it does not guarantee the correct person's name.
* **Live translation:** only offered by supported providers/models, with source and target options.
* **Timestamps and structured output:** depend on the provider and transcription output format.
## Verify with a small sample
Test a short recording with the language, microphone, and terms you actually use. Review the result before processing a long meeting. For a failure, read the error for file-size, format, extraction, account, or network details.
Model downloads can be much larger than the app. Check the actual download size and free space instead of assuming every local speech model has the same requirements.
Related: [Speech Assets](/configuration/speech-assets), [Permissions](/configuration/permissions), [Local Models](/ai/local-llm).
# Text-to-Speech
Source: https://docs.enconvo.ai/ai/text-to-speech
Read text aloud or create an audio file.
Enconvo offers two related commands: **Read Aloud** plays text in a floating playback bar; **TTS (Text To Speech)** creates an audio file using the selected provider.
## Read a passage
1. Open **Settings → Global Providers Settings → Text-to-Speech** and configure a provider and voice.
2. Select text and run **Read Aloud**, or use a chat reply's read-aloud action.
3. Use the floating bar to pause, resume, or stop playback.
4. Adjust the voice or speed in provider settings when supported.
## Create an audio file
Run **TTS (Text To Speech)** with the text you want to speak. Review the provider, voice, speed, and available output format. Open the generated file to check pronunciation and pacing.
The [TTS provider catalog](/providers/catalog#text-to-speech) lists Cloud, direct-service, macOS System, and local MLX options. Controls differ: some providers support style instructions or expressive tags, while others expose a fixed voice list.
## Local and cloud voices
Local Kokoro and Qwen3 MLX providers require supported hardware and model resources. System TTS uses macOS voices. Online providers, including services that do not require an API key, still send the input text over the network.
## Troubleshooting
If there is no sound, check the system output device and playback state. If generation fails, check provider access and supported text length/format. For mispronounced names, test a shorter sample and the provider's supported pronunciation or style controls.
For two-way conversation rather than reading a passage, use [Live Voice](/features/live-voice).
# Translation
Source: https://docs.enconvo.ai/ai/translate
Translate text, screenshots, and dictated input.
Use **Translator** for text or **Screenshot Translate** for content on screen. Translation uses the configured model and command settings; review the target language before running it.
## Translate selected text
1. Select the passage in another app.
2. Choose the translation command in PopBar or find **Translator** in SmartBar.
3. Set the target language in the available command controls.
4. Review the result before replacing or sending the original text.
## Translate a screenshot
Run **Screenshot Translate**, select the relevant region, and review both recognition and translation. An OCR mistake can change the translated meaning. See [OCR](/ai/ocr) for provider setup.
## Translate speech
Use **Dictation Translate** as a dictation post-action to convert recognized text into a target language. For realtime translated captions, choose a speech provider that exposes the supported live-translation options under [Live Captioning](/features/live-captioning).
## Customize results
Translation and Writing Toolkit commands follow the global AI model unless a command override is set. For recurring terminology, provide a glossary in a custom [AI Command](/features/ai-commands) or Agent instruction. Tell the model what to preserve, such as names, technical identifiers, or quoted passages.
If output uses the wrong language, check both the command's target and any post-action. If text is missing, review selected-text permissions or screenshot OCR first.
# Video Generation
Source: https://docs.enconvo.ai/ai/video-generation
Create video from text or an input image.
Use **Text to Video** or **Image to Video** with a configured video-generation provider. Video settings are separate from image generation and ordinary AI chat.
## Create a clip
1. Open **Settings → Global Providers Settings → Video Generation** and configure a provider/model.
2. Run **Text to Video**, or use **Image to Video** with a source image.
3. Describe the subject, action, camera behavior, and desired scene.
4. Choose the duration, resolution, and other options supported by that model.
5. Wait for the generation job to finish, then preview and save the result.
Start with a short clip when testing a new provider; generation can take time and use the selected provider's credit or Cloud points.
## Providers and input support
The [video provider catalog](/providers/catalog#video-generation) includes xAI, Gemini, OpenRouter, Kie.ai, Topview, and supported Cloud variants. Different models accept different inputs and resolutions. For example, Grok Imagine Video 1.5 adds a 1080p option that the base Grok Imagine Video model does not support.
An image-to-video request should specify what moves and what stays consistent. If the model accepts only one image or a limited duration, use those constraints in the request.
## Troubleshooting
If submission fails, check account access and supported request options. If a submitted job is still processing, inspect its status rather than immediately submitting another paid generation. Keep the input and returned error/status when asking for help, without sharing credentials.
For downloading, extracting audio, or compressing a completed clip, see [Media Utilities](/features/media-tools).
# Read Web Pages
Source: https://docs.enconvo.ai/ai/web-fetch
Fetch a URL as context or import web material into a knowledge base.
Use Web Fetch when you already have a URL and want the Agent to read its content. Use [Web Search](/ai/web-search) when you need to discover relevant pages.
## Read a page
1. Open **Settings → Global Providers Settings → Web Fetch** and choose a provider.
2. Paste the URL into your Agent conversation and ask a specific question about it.
3. Check the retrieved content and source before relying on the answer.
| Provider | Use |
| - | - |
| Local Fetch | Retrieve content through local fetching, with browser-assisted options |
| Jina AI Link Reader | Retrieve readable content through Jina |
| Firecrawl Link Reader | Retrieve content through Firecrawl |
| Enconvo Cloud Plan | Use the Cloud link-reading service |
A provider that retrieves a public URL does not automatically have access to your signed-in browser session. For authenticated or interactive pages, use the supported [Browser Extension](/features/browser-extension) or [Browser Control](/features/browser-control) flow.
## Keep web content
Add supported URLs or crawled content to a [Knowledge Base](/ai/knowledge-base) when you want to retrieve it later. Review the imported pages and indexing status; web pages can change after import.
## Troubleshooting
For empty content, check that the page is readable without extra interaction and whether browser-assisted fetching is needed. Login screens, blocked requests, dynamically loaded content, and unsupported sites can prevent extraction. Ask the Agent to identify what it actually retrieved instead of inferring missing page contents.
# Web Search
Source: https://docs.enconvo.ai/ai/web-search
Find current sources and use them in an Agent response.
Web Search supplies current search results to Enconvo. Configure it independently from the model that writes the answer.
## Search with an Agent
1. Open **Settings → Global Providers Settings → Web Search** and configure a provider.
2. Enable the needed search tool for your Agent.
3. Ask a specific question, including a date range or geography when relevant.
4. Open the cited sources and check that they support the answer.
Example: “Find the official release notes for this library's latest stable version and summarize breaking changes with links.”
## Choose the right web capability
| Need | Use |
| - | - |
| Discover relevant sources | Web Search |
| Read a known URL | [Web Fetch](/ai/web-fetch) |
| Open results in your browser | [Quick Links](/features/quick-links) |
| Interact with a signed-in website | [Browser Control](/features/browser-control) |
| Search X posts/profiles/threads | xAI X Search provider with supported access |
See [Provider Catalog](/providers/catalog#web-search) for available search services. Some models also expose built-in grounding/search options in their own provider settings.
## Troubleshooting
If sources are missing, check that the Agent actually used search rather than answering from the model alone. For provider errors, verify the selected search credential and account allowance. For a result behind a login or an interactive page, use a supported browser flow; fetching a public URL does not grant authenticated access.
# Changelog
Source: https://docs.enconvo.ai/changelog
Stay up to date with the latest EnConvo updates and improvements
# Changelog
***
# Enconvo 2.5.6 Changelog (2026-10-05)
Thanks for your patience and all the feedback during the beta. I've spent this
release making Enconvo feel more connected: to your apps, your other Macs, and
the things you want your assistant to remember.
## Highlights
* **Talk to an Avatar or use Voice Command hands-free**, with spoken replies,
live captions, screen awareness, and voice calls from Dynamic Island.
* **Pick up where you left off on another Mac** with Sync for chats, files,
knowledge bases, Agents, workflows, skills, and preferences.
* **Connect your everyday apps** so your Agent can work with email, calendars,
documents, and other services without switching between windows.
* **Ask AI about your documents, recordings, and saved posts**, with answers
that cite the passage or moment they came from.
* **Let Agents work together** on independent tasks, with clearer progress,
permissions, and control over changes to your files.
* **Build and schedule workflows by describing them**, then follow each step
in a visual editor with an Assistant to help fix failed runs.
* **See where your AI usage goes**, including estimated cost, tokens, cache
savings, subscription limits, and response speed.
* **Run local MLX models on your Mac**, or use your API keys, supported AI
subscriptions, and Enconvo Cloud from one model picker.
## Voice and Avatars
* Added desktop Avatars with their own appearance, voice, expressions, and
gestures, including Puppy, Bear, and Cat.
* Added voice calls from Chat Window, SmartBar, and Dynamic Island, with live
transcripts, screen and camera sharing, and optional automatic hang-up.
* Added spoken Voice Command replies with captions that follow the speech.
* Changed Dynamic Island to keep your words, the Agent's progress, and its
answer visible while a voice task runs.
* Added Avatar appearance and motion controls, saved looks, and a lighter
rendering mode that reduces resource use.
* Fixed voice calls losing their chat context, ending while waiting for your
answer, or failing to pass along photos and files.
* Fixed Dictation startup, post-actions, recording recovery, and local speech
model loading.
* Added richer Screen Doodle controls with more reliable screenshot and
annotation handoff.
## Sync and Memory
* Added Sync across Macs for chats and their attachments, Projects, knowledge
bases, settings, AI commands, Agents, workflows, skills, and snippets.
* Added optional API key sync, encrypted with a passphrase and off by default.
* Changed Sync to recover more quickly after a Mac reconnects and to explain
files or settings that stay on one Mac.
* Changed Sync to keep new chats flowing when storage fills by removing the
oldest cloud copies while preserving copies already on your Macs.
* Changed Memory to recall relevant preferences and older facts more reliably,
update information that has changed, and handle dates more accurately.
* Changed Memory settings to use the same card and list views as Knowledge Base.
* Fixed Quick Memory and voice-note saving, transcription, and cancellation.
## Knowledge Base and Saved Posts
* Added Ask AI alongside documents, books, recordings, and saved posts, with
citations that open the relevant passage or playback position.
* Changed knowledge base search to find exact names and codes as well as
related ideas, with clearer source references.
* Added saving X posts and threads, including images, into your knowledge base.
* Added readable saved-post views, video transcripts, and questions about
individual posts or collections.
* Added a Knowledge Base MCP server for searching your saved material from
Claude Code, Codex, Cursor, and other compatible apps.
* Fixed importing, previewing, and searching documents and recordings.
## Agents and Everyday Automation
* Added parallel subagents for independent tasks, with support for project
helpers and visible progress.
* Added per-Agent skill selection, shared and workspace skills, and safer
folder imports and deletion.
* Added permission choices, task checklists, file-change undo, message editing,
and conversation forks.
* Added faster Browser Operator and Computer Operator modes that pause before
sensitive actions.
* Fixed a conversation with a custom Agent unexpectedly switching to the
default Agent while a task was running.
* Fixed typing, scrolling, file picking, browser tab control, and interrupted
tool requests across Computer Use and Browser Use.
* Changed tools on Mac to use Enconvo's bundled Node.js for a more dependable
environment, even when another Node.js is installed.
## Connectors and MCP
* Added Connectors for Gmail, Google services, Outlook, Notion, Slack, and more
everyday work tools, with guided account setup.
* Changed Agents to recognize your connected accounts so requests such as
"email me" or "add it to my calendar" use the right account.
* Added local-file attachments to emails sent or drafted with Gmail and
Outlook, with download links for files too large for an email.
* Added interactive MCP Apps inside chat and clearer server and tool controls.
* Fixed Gmail migration, account sign-in, credential refresh, and reconnection.
## Workflows and Scheduled Tasks
* Added an Assistant that creates and edits workflows from a description,
with templates and workflow YAML import.
* Added a searchable step palette, recently used tools, clearer step cards,
run summaries, and individual step results.
* Added input forms, value pickers, and warnings for missing or unavailable
inputs, with an Assistant to help fix failed steps.
* Changed the Workflows page to a list and details view with recent runs,
scheduling, and quick actions.
* Added setting up scheduled tasks by chatting, with plain-language schedules,
run history, notifications, and delivery to connected chats.
* Added scheduling saved workflows with their own inputs and links back to
each run.
## Chat and Sharing
* Added public or password-protected chat links and Continue in Enconvo to
copy a shared conversation into the app.
* Added Share and Copy menus to Chat Window, SmartBar, and Dynamic Island,
including Copy as Markdown and chat links.
* Changed new shared chat links to open at app.enconvo.com in the reader's
language while keeping earlier links working.
* Fixed chat scrolling over code blocks, tables, and wide content, including
on shared chat pages.
* Changed long conversations to stream more smoothly, with clearer code
highlighting, message queues, and history navigation.
* Fixed pinning chats, restoring empty chats, and sidebar chat names.
## Models and Usage
* Added support during this release for GPT-6.1 Sol, Claude Opus 5.5 and
Sonnet 5.5, GLM-5.3 models, and other supported provider updates.
* Added an MLX Models page for downloading, loading, and choosing local models,
with OpenAI- and Anthropic-compatible endpoints for other apps.
* Added prompt caching for local MLX models and more reliable cancellation.
* Added Response Timeout settings to LM Studio and Ollama, with no time limit
by default for local models.
* Added Usage Statistics across AI providers with estimated costs, token and
cache breakdowns, model details, and a request log.
* Added clearer credential labels and subscription usage in the model picker.
* Added Cloud points visibility per conversation and spending checkpoints
during long Agent runs.
* Added more image, video, and speech providers, including ElevenLabs voices
through Enconvo Cloud.
## Setup and Companion
* Added a shorter narrated first-launch guide, settings search, and expanded
interface languages.
* Added pairing with the iPhone Companion to continue Mac chats, answer Agent
questions, and receive task notifications.
* Changed the iPhone Companion experience with native chats, voice calls,
Avatars, and settings shared with your Mac.
* Changed iPhone Companion notifications about activity on your Mac to play
the alert sound.
* Changed the free plan to monthly allowances for Recording, Live Captioning,
and Live Talk, with clearer limits for scheduled tasks and connected devices.
* Changed Sync to require an Enconvo Cloud plan or lifetime license.
* Changed the Mac app to use Enconvo's company signing identity; when updating
from 2.5.5, macOS will ask you to grant permissions such as Accessibility,
Screen Recording, and Microphone again.
***
# Enconvo 2.5.5 Changelog (2026-09-10)
Friends, thanks for waiting and for all your feedback along the way. I've spent
this release making Enconvo easier to reach, more useful in your daily work,
and smoother from the first voice command to the finished result.
## Highlights
* **Dynamic Island feels faster and more capable**, with a live voice HUD,
immediate recording, richer attachments, and easier Default Agent switching.
* **Meetings and live captions are easier to follow**, with speaker recognition,
word-by-word playback, live translation, and local transcription models.
* **CoreML dictation runs on your Mac's Neural Engine**, with smaller downloads,
lower memory use, and fast on-device speech recognition.
* **Build workflows with your AI Agent**, combining Enconvo features and MCP
tools in a visual editor with live progress and step-by-step results.
* **Projects keep related work together**, bringing chats, files, and shared
instructions into a single workspace.
* **Knowledge Base has a new asset browser**, while Quick Memory lets you save
app content or voice notes with the right Shift key.
* **DeepSeek V4.1 Flash is now supported** through your own DeepSeek API key or
Enconvo Cloud, with image understanding, a 1M-token context window, and tool use.
* **Enconvo Cloud gives you more DeepSeek usage**: Pro uses half the standard
points and Max uses one quarter for all DeepSeek models.
## Dynamic Island And Everyday Interaction
* Added a live Voice Command HUD with a waveform, transcript, and clear
recording and processing states.
* Improved hotkey response so recording starts immediately and captures your
first words while the panel opens.
* Added screenshots, file attachments, Screen Doodle, and automatic read-aloud
controls to Dynamic Island.
* Added Default Agent switching from the agent icon in SmartBar, Chat Window,
and the Dynamic Island panel.
* Fixed commands returning their results to the wrong window.
* Improved App Sidebar opening, window following, closing, and remembered width
for each app.
* Added Inline Mode for applying commands directly to selected text, with a
compact progress indicator and the result pasted back in place.
* Improved SmartBar input, Chinese text composition, command ordering, and
PopBar behavior around window dragging and design apps.
## Voice, Recording, And Live Captioning
* Added CoreML Parakeet, SenseVoice, and Paraformer dictation models with
download, load, unload, and delete controls.
* Added speaker diarization and recognition to meeting recording, with
word-level transcript alignment during playback.
* Added Live Captioning with realtime transcripts, speaker labels, translation,
local model support, and saved history.
* Fixed Voice Command on macOS 27, Dictation post-actions, and local speech
model loading.
* Improved recording sounds, volume restoration, dictation translation, and
the way spoken input merges with your typed edits.
* Improved Read Aloud reliability and refreshed xAI voice selection.
## Workflows, Agents, And Visual Results
* Added a visual workflow builder with step configuration, live execution
status, individual step runs, and YAML editing.
* Added AI-assisted workflow creation and editing using Enconvo capabilities,
MCP tools, and supported VS Code tools.
* Added the Visualize plugin for SVG, HTML previews, and interactive widgets
inside chat, alongside native tables, charts, weather cards, and other
generated results.
* Improved workflow cancellation and output so runs are easier to follow and
stop.
* Added immediate Steer messages so you can correct an active Agent task while
its tools continue running, including messages from Telegram and Discord.
* Improved long-conversation memory, model switching, prompt caching, and
cancellation of stopped requests.
* Added settings to open Dynamic Island or send a system notification when a
task finishes, with fewer duplicate prompts for conversations already visible.
## Projects, Knowledge, And App Context
* Added Projects with shared instructions, folder-backed chats, a file browser,
and Git branch controls.
* Added file and folder mentions from your current project, alongside workflow,
MCP server, Finder file, Notes, and Mail context.
* Redesigned Knowledge Base with a folder tree, previews, tags, an inspector,
drag-and-drop imports, and a standalone window.
* Added Quick Memory: double-tap right Shift to save the current app context,
or hold right Shift to record a voice note for your knowledge base.
* Improved imports and retrieval for PDFs, images, and larger knowledge bases.
* Added app presets and site Command Packs for more direct automation, plus
improved Office, Finder, Browser Use, and Computer Use support.
* Added inline attachment previews and live progress for video and audio
downloads.
## Models And Cloud Plans
* Expanded model choice with GPT-6 Astra, the GPT-5.6 family, Grok 4.6,
Gemini 3.8 Flash, GLM-5.3-Flash, Kimi K3, MiniMax M3, and DeepSeek V4.1 Flash
through their supported providers.
* Added GPT Image 2.5 Flare and Sunburst for image creation and editing, with
support for API keys, Enconvo Cloud, and supported ChatGPT sign-in workflows.
* Added Google Gemini and Kie.ai video-generation options and expanded xAI
voice, image, video, and search support.
* Improved custom provider model lists, fuzzy model search, and saved choices.
* Added clearer Cloud plan comparisons and upgrades, with DeepSeek usage at
half the standard point rate on Pro and one quarter on Max.
* Redesigned Points Usage with clearer balances, usage breakdowns, and monthly
allowance reset history.
## Settings And Reliability
* Added new Skills, Plugins, MCP Servers, and Permissions management pages.
* Improved MCP setup, OAuth sign-in, credential refresh, and reconnection.
* Added account device management and clearer recovery when you reach your
device limit or move to a new Mac.
* Added the Pet desktop companion with live task cards and community packs.
* Added a help menu for companion setup, release notes, and keyboard shortcuts.
* Fixed high background CPU usage, slow app switching, Dock icon hiding, and
workspace preview close controls.
* Improved chat syntax highlighting, scrolling, panel transitions, and startup
performance throughout the app.
***
# Enconvo 2.5.4 Changelog (2026-06-26)
Hi friends, thanks for testing this round. Enconvo 2.5.4 is mostly about making
the app feel cleaner and steadier in daily use: Dynamic Island is easier to
control, Sidebar handoff is quicker, chat rendering is smoother, analytics are
more privacy-conscious, and the macOS app package is lighter.
## Highlights
* **Dynamic Island is easier to control** with a new menu bar toggle, more
reliable hover activation, better keyboard handling, and an optional notch
exclusion setting.
* **Ask Sidebar is now available from selected text or file context**, so you
can send content into Enconvo from Finder or other right-click workflows.
* **Chat answers and long conversations feel cleaner** with better answer
formatting and improved message list rendering for longer histories.
* **Analytics are more privacy-conscious** with consistent signed-in user
identity and filtering for sensitive values such as API keys, passwords, and
tokens.
* **The macOS app package is lighter** after removing unused Swift packages and
dead UI helper code.
* **OpenRouter Claude reasoning options are clearer** for newer Opus and Sonnet
model families.
## Dynamic Island
* Added an Enable or Disable Dynamic Island item to the menu bar menu.
* Improved Dynamic Island event handling to match SmartBar behavior more
closely, including Escape, Cmd+W, Cmd+N, and Return key flows.
* Replaced raw event monitors with stack-based hotkey monitors for more reliable
open and close cycles.
* Fixed repeated compact hover entries sometimes failing to open.
* Hover validation now respects the padded hover target, so activation is less
fragile around the visible pill.
* Added an optional Exclude Notch Area setting. When enabled, hover inside the
physical notch area will not trigger Dynamic Island, while hover below or
beside the notch still works.
* Removed streaming text preview from compact and expanded Dynamic Island modes
when agent auto-read is active.
## Chat And Sidebar
* Added the Ask Sidebar command for sending selected text or file context into
the app sidebar.
* Registered Ask Sidebar as a Finder service and general right-click action.
* Chat With AI now avoids fenced code blocks unless you ask for code, commands,
structured data, logs, or exact copyable text.
* Formula-style answers now stay in normal prose or Markdown math instead of
code-style boxes.
* Improved long chat rendering by stabilizing Streamdown props and using
content visibility for off-screen cached messages.
## Privacy And App Package
* Signed-in users are identified more consistently across the Mac app, Node.js
runtime, and web settings app.
* Sensitive values such as API keys, passwords, and tokens are filtered before
analytics events are sent.
* Event names are clearer for command runs, panels, providers, settings,
login/logout, and feature flags.
* Removed unused Swift packages including OpenAISwift, ActivityIndicatorView,
SwiftUIPager, OpenAI by MacPaw, Blackbird, GoogleSignIn, GoogleSignInSwift,
MenuBarExtraAccess, MSDisplayLink, SpringInterpolation, and Splash.
* Deleted unused WindowAnimation helpers and cleaned dead Swift imports in views
and services.
## Models And Providers
* OpenRouter Claude Opus and Sonnet model ids now match reasoning effort
profiles by model family and version, even when naming order or separators
vary.
* Opus 4.7 and 4.8 now show adaptive Low, Medium, High, X-High, and Max effort
choices instead of legacy token-budget choices.
* Other Claude fallback models, including Sonnet 4.5 and latest aliases, now use
the simpler Low, Medium, High, and Max effort list.
***
# Enconvo 2.5.3 Changelog (2026-06-25)
Friends, thanks for waiting. This release took longer than usual because I spent
time polishing the whole app experience: Dynamic Island, Chat Window, SmartBar,
Computer Use, and more model and media tools should all feel smoother in daily
use.
## Highlights
* **Dynamic Island is more capable** with voice command input, smoother session
reuse, better hover behavior, cleaner model picking, app-context screenshots,
and more reliable handoff back into chat.
* **Voice input is easier to use** in the places where quick capture matters,
including Chat Window and Dynamic Island workflows.
* **Chat Window and SmartBar feel more refined** across long conversations,
history navigation, model selection, mentions, paste behavior, and follow-up
prompts.
* **Computer Use and Browser Use are more dependable** for clicks, drags,
scrolling, file picking, app targeting, and browser tab control.
* **Knowledge, context, and search are easier to navigate** with better
Knowledge Base access, clearer context actions, and improved app, website,
plugin, and window mentions.
* **More models and media tools are available**, including Claude Opus 4.8,
GLM-5.2, MiniMax M3, Soniox v5, xAI Imagine, xAI speech-to-text, and GPT
Image 2 through OpenAI OAuth.
## Dynamic Island And Voice
* Added voice command input for Dynamic Island so you can capture an idea or
ask for help without switching into the full chat window.
* Improved Dynamic Island session reuse, hover behavior, model picker behavior,
handoff state, and app-context screenshots.
* Added voice input to Chat Window for a faster way to start or continue a
conversation.
* Improved how conversations move between native surfaces and web chat so the
same session stays consistent.
## Chat Window And SmartBar
* Improved Chat Window history syncing, titlebar navigation, row actions,
prompt mentions, paste routing, footer controls, and model picker spacing.
* Improved SmartBar command mentions, slash model picking, status handling,
paste behavior, mention chip removal, and follow-up flow.
* Made long conversations and repeated quick actions feel steadier across both
main chat surfaces.
## Computer Use And Browser Use
* Improved native app control with faster app state loading, stronger app and
window targeting, better action waiting, and safer background behavior.
* Improved clicking, coordinate clicking, dragging, scrolling, low-level mouse
control, and native panel actions.
* Added better support for native file picker selection, app menu element
indexes, clipboard access, and permission prompts.
* Improved browser automation with exact tab targeting, cross-origin iframe
handling, cleaner page state output, drag-safe clicks, and clipboard proxy
support.
## Knowledge Base, Context, And Search
* Improved Knowledge Base navigation, access, local API behavior, and settings
history navigation.
* Added a Knowledge Base context manager and clearer search context actions.
* Added Docling document loader support.
* Improved application and website mentions, local SmartBar mention icons,
installed plugin mentions, and window context capture.
## Models, Providers, And Media
* Added Claude Opus 4.8 Cloud Plan support.
* Added GLM-5.2 and MiniMax M3 Cloud Plan support.
* Added xAI Imagine image generation and xAI video local media upload support.
* Added xAI OAuth credentials, xAI speech-to-text, and improved Grok model
visibility.
* Added OpenAI OAuth GPT Image 2 and OpenAI OAuth Transcribe support.
* Added Soniox v5 speech-to-text models.
* Improved Anthropic OAuth account info, account switching, cancel behavior,
high reasoning defaults, and image fallback behavior.
## Settings, Skills, And Polish
* Improved hooks configuration, manual documentation, sound notifications, and
agent monitor callbacks.
* Improved Skills Manager multi-source install reliability.
* Simplified Settings sidebar labels for General and Shortcuts.
* Improved Settings layout, Knowledge Base settings navigation, provider rows,
and reset behavior.
* Improved PopBar row density, keyboard dismissal, copy shortcut conflicts,
App Sidebar empty states, and window exclusions.
* Fixed TTS provider voice preview selection and IM channel launch lock
recovery.
* Improved tool-result compaction, multimodal tool results, agent prompt
cleanup, thinking message behavior, and chat stream rendering.
***
# Enconvo 2.5.2 Changelog (2026-06-20)
Enconvo 2.5.2 focuses on a smoother everyday chat experience, clearer update
prompts, stronger voice input, more reliable Computer Use, and broader model
and provider support.
## Highlights
* Chat Window and SmartBar are more polished, more responsive, and easier to
use across long conversations.
* New update indicators can appear directly in Chat Window and SmartBar when a
new Production or Beta version is available.
* Voice input is now available in more places, including Chat Window and
Dynamic Island voice commands.
* Computer Use and Browser Use are more reliable for clicking, dragging,
scrolling, file picking, tab targeting, and native app control.
* Knowledge Base context, settings, and search flows are easier to navigate.
* More providers and models are available, including Claude Opus 4.8,
GLM-5.2, MiniMax M3, Soniox v5, xAI Imagine, xAI speech-to-text, and GPT
Image 2 through OpenAI OAuth.
## Chat Window And SmartBar
* Added voice input to the Chat Window prompt, so you can dictate directly
where you already type.
* Added an **Update** button in both Chat Window and SmartBar when Enconvo
detects a new version.
* Improved Chat Window history syncing, titlebar navigation, row actions,
prompt mentions, paste routing, footer controls, and model picker spacing.
* Refined message readability, text selection, realtime assistant history, and
table rendering in chat messages.
* Improved SmartBar status handling, command mention routing, slash model
picking, paste behavior, mention chip removal, and follow-up flow.
## Update Experience
* Simplified update channels to **Production** and **Beta**.
* Beta releases now publish to the matching Beta distribution path and appcast,
so users on the Beta channel can detect the correct update.
* Update checks now run when Chat Window or SmartBar is shown, with a
10-minute throttle to avoid repeated background checks.
* Automatic update downloads are off by default.
## Voice, Dictation, And Dynamic Island
* Added Dynamic Island voice command input.
* Improved voice command session reuse, so follow-up voice commands feel more
continuous.
* Added xAI speech-to-text provider support.
* Added OpenAI OAuth Transcribe support.
* Added Soniox v5 speech-to-text models.
## Computer Use And Browser Use
* Improved native app control with faster app state loading, stronger app and
window targeting, better action waiting, and safer background behavior.
* Improved clicking, coordinate clicking, dragging, scrolling, low-level mouse
control, and native panel actions.
* Added better support for native file picker selection, app menu element
indexes, clipboard access, and permission authorization prompts.
* Improved browser automation with exact tab targeting, cross-origin iframe
handling, cleaner page state output, better readable snapshots, drag-safe
clicks, and clipboard proxy support.
## Knowledge Base, Context, And Search
* Improved Knowledge Base navigation, access, local API behavior, and settings
history navigation.
* Added a Knowledge Base context manager and clearer search context actions.
* Added Docling document loader support.
* Improved hierarchical local API schema lookup and API schema explorer runtime
paths.
## Models, Providers, And Media Generation
* Added Claude Opus 4.8 Cloud Plan support.
* Added GLM-5.2 and MiniMax M3 Cloud Plan support.
* Added xAI Imagine image generation and provider feature APIs.
* Added xAI video local media upload support.
* Added xAI OAuth credentials, Grok 4.3 model filtering, and improved xAI
model visibility.
* Added OpenAI OAuth GPT Image 2 support and improved OpenAI OAuth credential
sync and LLM stability.
* Improved Anthropic OAuth account info, account switching, cancel behavior,
high reasoning defaults, and image base64 fallback behavior.
## Workflows, Hooks, And Developer Tools
* Added a Workflow YAML management editor.
* Added workflow reference checkout support.
* Improved local API descriptions, local API common tool availability, module
API schema hygiene, and inline API schemas in generated module skills.
* Added unified tagged logging across Swift, web, and Node.js flows.
* Added a logging clear button.
## Capture, Translation, And Polish
* Improved screenshot translation with SSE streaming.
* Added AppShots capture sound controls and exact paired-option hotkeys.
* Improved AppShots context hotkey behavior and live screen attachment sending.
* Improved PopBar row density, keyboard dismissal, and copy shortcut conflict
handling.
* Fixed TTS provider voice preview selection, IM channel launch lock recovery,
post-tool thinking loading, and collapsed thinking message behavior.
***
# Enconvo 2.5.1 Changelog (2026-05-08) 🚀
## OpenClaw
* Enconvo now supports **OpenClaw** as an LLM provider — bring any of your OpenClaw agents into Enconvo and run them seamlessly across **SmartBar**, **PopBar**, **App Sidebar**, and every other Enconvo surface
## Hermes
* Enconvo now supports **Hermes** as an LLM provider — every Hermes agent is instantly available across **SmartBar**, **PopBar**, **App Sidebar**, and the rest of Enconvo, so you can use them anywhere you work
## File Preview
* Added **File preview** support — you can now preview files (images, video, audio, Markdown, PDF, and more) right inside SmartBar, beside the chat
* Action buttons on the right side stay visible while previewing
* Fixed an issue with PDF page numbers
## MLX
* **Local MLX models** (beta) — run models on‑device for writing and translation use cases, keeping everything private and fully offline
## AI Model Provider
* New provider: **Xiaomi MiMo** (BYOK & Cloud Plan)
## TTS
* New provider: **Xiaomi MiMo TTS** (BYOK & Cloud Plan)
* New local TTS providers, all powered by **MLX** and running fully on‑device:
* **Kokoro 82M** — lightweight and multilingual
* **Qwen TTS** — multilingual with natural prosody
## Dictation
* New on‑device ASR providers, powered by **MLX**:
* **Parakeet ASR**
* **Whisper ASR**
* New realtime / sync ASR providers (BYOK & Cloud Plan):
* **Azure** (realtime)
* **ElevenLabs Scribe v2** (realtime / sync)
* **AssemblyAI** (realtime / sync)
* **Soniox** (realtime / sync)
* **Volcengine** (realtime / sync)
* Your personal **Memory** is now used as the dictation dictionary, improving recognition of names, jargon, and custom terms you frequently use
* Added **Dictation History**, with support for using dictation records as Knowledge Base context
* Smoother dictation experience in SmartBar with full **realtime / sync** mode support
## SmartBar
* SmartBar now shows an **Update** button at the bottom when a new version is available
* **Explain follow‑up** — keep the conversation going naturally after an explanation
* **"Use as context"** is now the first action when you use `@`
* Improved **paste image** flow and refined screenshot logic for a smoother experience
* You can now **delete queued messages** while an agent is still running
* Context is now **automatically compacted** to keep long conversations responsive
* Fixed an issue with `@` mention switching
## Chat Window
* **Message history search** lets you quickly find past conversations in the chat window
* Fixed table rendering issues in chat messages
* Fixed: model selection not being applied correctly
* Fixed: model selector dismissing unexpectedly
* Fixed a history switching issue
* Added a **Show in Finder** icon for delivered files
## Settings
* Optimized the shortcut settings page for a smoother configuration experience
## Knowledge Base
* **Local embeddings** — embeddings now run on‑device, so your knowledge base data never leaves your machine
* Knowledge Base entries can now be referenced directly with **`@` context mentions**
* Knowledge Base search now accepts `query: string[]`, enabling multi‑query searches in a single call
## IM Channels
* Fixed: IM channels no longer disconnect when an error occurs
* Added a **verbose mode** — streams the agent's step‑by‑step execution details directly into your IM channel, so you can follow exactly what the agent is doing in real time
## Web Search
* New web search provider: **Brave Search**
## Analytics
* Integrated **PostHog** as the analytics platform — you can opt out at any time from **Settings → About**
## New Logo
* Enconvo has a fresh new look — meet the refreshed app logo
## Bug Fixes
* Fixed context handling when returning from another view
* Improved explain context handling
* Fixed links being blocked unexpectedly
* Fixed paste issues in WeChat
* Fixed an issue with the mail notification sound
* Fixed lost context messages
* Fixed an incorrect session directory being used
* Fixed a livescreen image issue
***
# Enconvo 2.5.0 Changelog (2026-04-28) 🚀
## SmartBar
* Resizable SmartBar window — position and size are persisted independently for Command List mode and Chat mode
* New SmartBar suggestion panel
* Dynamic Context: agents now read a live overview of your foreground context and pull in specific items only when needed (for example, ask about the current page directly in your open browser without manually attaching context or opening the App SideBar)
* Smoother task switching with optimized switch logic
* Ask AI: select text inside a SmartBar response and use it as context for follow-up questions
* SmartBar list: menu opens on both click and right-click; added a search box for quickly filtering options
* Pending messages — append new messages while the agent is still running; they are queued and consumed automatically
## Dictation
* Refreshed Dictation UI/UX
* Added Qwen ASR support (local, MLX-powered)
* New setting: toggle the start/stop sound effect when dictation is activated
* New setting: toggle whether system audio is muted while dictation is active
* Optimized post-dictation actions — defaults now include Polish and Translate
* New shortcut mode: "Hold or Toggle", default shortcut is `Right Command` (hold for push-to-talk, tap to toggle)
* AI-powered voice input dictionary for improved recognition of names, jargon, and custom terms
## Agent
* New Voice Trigger feature — use `Right Option` to trigger voice input directly to the agent
* Improved session management
* Optimized context-compression logic
## Cron Scheduling
* Cron-scheduled execution for agents — let agents run tasks on a schedule
* Cron logs UI with fixed-height dialog and syntax-highlighted JSON detail view
* Manage cron schedules from both the UI and the API
## IM Channels
* Unified IM Channels module supporting Discord and Telegram
* In-channel bot commands: `/new`, `/stop`, `/voice`, `/status`, `/audio`
* Access control: pairing-based system with approve/deny notifications
## Skills Support
* Skills Store with curated skills (PPT, DOCX, Excel, Obsidian, photo dedup, and more)
* Use skills with the `/` slash command
* Custom skills directories — pick your own folders or symlinked directories
## Knowledge Base
* Reindex ability — rebuild the knowledge base on demand from the UI
* Added xlsx support for knowledge base ingestion
* Audio/video transcription supported in the file loader
* Indexing errors are surfaced in the UI
## Memory
* New Memory management UI
* Optimized memory use logic with smarter retrieval and compression strategies
## Recording
* Standalone, draggable recording bar with per-screen position persistence
## API System
* Expose Enconvo abilities through HTTP API — call Enconvo capabilities from external apps
* Base URL: `http://localhost:54535/`
* Example:
```bash theme={null}
curl -X POST "http://localhost:54535/tts/tts" \
-H 'Content-Type: application/json' \
-d '{ "input_text": "hello, world" }'
```
## Enconvo CLI
* Expose Enconvo abilities through a command-line interface
* `enconvo -h` shows the help message
## Computer Use
* New `computer-use` extension for native macOS control
## TTS Improvements
* New providers: xAI TTS, Edge TTS (free), Gemini 3.1 Flash TTS
* New Read Aloud UI/UX: horizontal bar with a live waveform and loading state
## AI Model Provider
* New providers: MiniMax, [Z.AI](http://z.ai) (Anthropic-compatible)
* Claude Opus 4.7 (Cloud Plan, Subscription, BYOK)
* Kimi 2.6 / Moonshot updates (Cloud Plan, BYOK)
* DeepSeek V4 Flash and V4 Pro (BYOK and Enconvo Cloud routing)
## Image Create
* gpt-image-2 model support (Cloud Plan & BYOK)
## Web Fetch
* When fetching x.com, requests are redirected to the Enconvo fetch provider (jina.ai, free tier)
## Extensions Improvements
* `apple-apps-and-services` consolidates all macOS app integrations: Mail, Notes, Calendar, Reminders, Contacts, Messages, and Maps. Replaces the legacy `apple_mail` and `apple_reminders` extensions
* `media-utils` (renamed from `video_utils`) absorbs `audio_utils` and adds online video download (YouTube, TikTok, Instagram, etc.) plus audio compress and transcript APIs
* `bash` util uses RTK to reduce LLM token consumption by 60–90% on common dev commands
* `read_file` tool now reads images, audio, and video
* `image-utils` replaces bundled binaries with auto-download from GitHub Releases
* New standalone `config` module (split out of `enconvo`) with `get` / `set` / `preferences` endpoints, auto-resolved `storeType`, and password auto-encryption
* New `ai-command` extension with migration path from the legacy `custom_bot` (preserves message history)
## UI/UX Improvements
* Refreshed tool-call display
* Tools like `write_file` now stream their text content live
* Workspace sidebar — quick access to the working directory and deliverables
* Customizable command icons
* Smoother agent flow
* Command settings now jump to a unified settings page
## PopBar
* Ask AI integration in PopBar
## Other Improvements
* `read_file` can read image content
* Prompts can reference settings parameters
* Screenshot explanation: clears prior conversation history and no longer auto-copies by default
* Anthropic SDK linked locally with a fork; added `jsonrepair` for robust streaming parses
* App shutdown: SIGTERM is sent to Python subprocess groups on app termination
## Bug Fixes
* Fixed up/down/enter behavior in settings input fields
* Fixed Ollama cloud model issues
* Fixed shortcut handling for menus
* Fixed `pasteIn` so keyboard events target the last frontmost app
* Fixed reasoning component flicker when content is empty or whitespace
***
# Enconvo 2.2.23 Changelog (2026-02-08) 🚀
## Enconvo in Excel
* Read and edit Excel files directly in the app sidebar, with real-time updates to the currently open Excel file
* Recommended to use Anthropic Claude series models
## Claude Opus 4.6 is now live on Enconvo
💡 You can use the new model in the following ways:
* Enconvo Cloud Plan
* Your Claude Pro/Max subscription
* Your own API key
## GPT-5.3 Codex is now live on Enconvo
💡 You can use the new model in the following ways:
* Your OpenAI subscription
## Meeting/Lectures Recording
* Added meeting recording functionality
* Entry points available in Companion Orb and menu bar
* Records history accessible in Settings
* Can ask questions about recordings
* @Recordings (Meetings/Lectures) allows chatting with all meeting records
* Button to generate meeting summaries (readable version of recording)
* Regenerate transcript support
* Redesigned recording bar to vertical layout
* New transcription model selection UI
## Knowledge Base / Memoimization
* Data structuring improvements
* UI logic adjustments
* Batch deletion support
* View detail content
* Note/text types are now editable
* PDF loader defaults to Mistral OCR (supports image recognition, improved content quality)
## Ask AI on PopBar
* Select text as context and chat with Mavis in the Smartbar conversation window
## Dictation Models UI/UX Optimization
* More intuitive selection and configuration of STT models
## Nvidia Parakeet V3
* Added speech recognition model with multi-language support
## Hotkey Enhancements
* Support for right-side Command, Option, and Shift keys
* Support for F1–F20 keys in normal mode
* Support for Single Click mode (single-click Command, Option, etc.)
## Optimizations
* **Chat Window UI/UX Improvements**:
* Search chats history
* Rename chat
* optimize delete chat functionality
* Chats now grouped and displayed by date for easier history browsing
* **Optimized Markdown Rendering Performance**:
* Enhanced markdown rendering efficiency reduce CPU usage
* Full LaTeX formula rendering support
* Code block syntax highlighting support
* Optimized dictation speed and stability
* Sidebar and App Sidebar close behavior now properly resizes application windows
* Improved markdown rendering performance for large text blocks
* Markdown code syntax highlighting
* Sidebar icon improvements (less intrusive)
* Select Area Screenshot now defaults to Mavis bot instead of image compression bot
* rename mini smart bar to companion orb
## Bug Fixes
* Fixed Companion Orb positioning issues
* Fixed Smartbar layout issues (1470×956)
* Fixed "Open link in response" issue
* Fixed text highlighting issues
* Fixed messages auto-scrolling to top
* Fixed intermittent message sending failures
* Fixed AI Edit interface display abnormalities
* Fixed Notion MCP installation failure
* Fixed Screenshot Explain/Translation settings page scrolling issue where bottom settings were inaccessible
* Fixed App Sidebar icon not appearing after opening Finder
## SKILLs Feature Coming Soon!
# Enconvo 2.2.22 Changelog (2025-11-29) 🚀
## New Features
* Model Management: Set model properties, delete models, and add custom models
## Optimizations
* Optimized credential duplication
* Optimized provider duplication
## Bug Fixes
* Improved French language support for getting selected text
* Extension store pagination
* Fixed Nano banana thought\_signature issue
* Fixed SwiftData-related crashes
* Fixed LazyVStack crash in SmartBarView
* Fixed issue where eM Client couldn't get selected text
* Fixed AI Edit not getting selected text
* Fixed OpenRouter image generation issue
* Fixed Google account re-authorization issue
* Fixed issue where dropping multiple files from Finder to Smartbar would replace previous files instead of combining them
* Fixed JPG file extension image compatibility
* Fixed Chat Window position and size not saving properly
* Fixed disable app sidebar setting not taking effect
* Fixed Companion Orb visibility and positioning issues
* Fixed SwiftUI-related startup errors
* Fixed issue where launching Companion Orb to Smartbar carried message history
***
## 2.2.21 (2025-11-25)
### Claude Opus 4.5 is now live on EnConvo
You can use the new model in the following ways:
* EnConvo Cloud Plan
* Your Claude Pro/Max subscription
* Your own API key
### New System Toggle Tools
* Toggle System Appearance
* Toggle Full Screen
* Toggle Mute
* Toggle Hidden Files
### OpenAI OAuth Additional Models
* `gpt-5.1`
* `gpt-5-codex`
* `gpt-5.1-codex`
* `gpt-5.1-codex-max`
* `gpt-5.1-codex-mini`
### Bug Fixes
* Fixed UI issue with extension update button
* Fixed issue where user messages sometimes rendered incorrectly
***
## 2.2.20 (2025-11-23)
### Optimizations
* Chat Window issue fixes and performance improvements
* New Chat / Switch Chat logic optimizations and performance improvements
* Writing Tools now support using the language set in Profile, with multiple language variants (US English, UK English, etc.)
* MiniSmartbar adds screenshot translation
* Smartbar/Small Smartbar are unpinned by default
### Bug Fixes
* Fixed issue where clicking elsewhere would trigger the app side bar hint icon menu
* Fixed "App Sidebar icon hide for all" issue
***
## 2.2.19 (2025-11-22)
### Memory Support
* Add to EnConvo Memory (via right-click menu and dedicated command)
* Use "Add to Memory" in PopBar to quickly add content to EnConvo Memory
* Memory management is available in the Settings page
### New Features
* Support for Nano Banana Pro (gemini-3-pro-image-preview)
* Added region-specific language options (American English vs British English)
* Add to EnConvo Knowledge Base (via right-click menu and dedicated command)
* Add "Add to Knowledge Base" to the PopBar
### Optimizations
* No AI response needed when using the Knowledge Base tool
### Bug Fixes
* Performance issues (especially when using EnConvo in Mail)
* Fixed repeated appearances of the shell runner popup
* Fixed the settings page freezing issue
* Fixed sound when dragging in mail.app on OS26
* Fixed incomplete reading of app content in Safari adaptation
***
## 2.2.18 (2025-11-08)
### New Features
* Jinja2 syntax is now supported in Prompts
* Quickly select commands in the SmartBar by holding down Command and pressing number keys 1–10
### Improvements
* Optimized when the App Sidebar Handle icon is displayed
* Added an App Sidebar toggle and hide option in the right-click menu of the MenuBar and SideBar icons
* Straico now supports image input
* App window content will now include the URL if available
* The SmartBar can now be reset to the global model
* Added a new variable: `history_messages`
### Bug Fixes
* Resolved the issue where the input cursor would automatically jump to the end of a sentence
* Shortened the prompt asking for shell execution permissions
* Improved compatibility for chat window light mode
* Fixed repeated Bun installation issues
***
## 2.2.17 (2025-11-04)
### Context Optimization
* Support obtaining the content of application windows as context
* Improved interaction settings
* Support selecting available contexts with the `#` character when inputting text
* You can use `@` to specify which tool to use when you input text
### Global Sidebar Panel
* A new always-on-top sidebar panel opens on the right side
* The SideBar supports invoking features with `@`, `#`, and `>`
* Default shortcut: `Shift + Command + U`
### Application Sidebar Panel
* Launches an always-on-top sidebar panel on the right within the current application
* Automatically switches to the Bot dedicated to the current Application (such as Finder)
* SideBar supports invoking features with `@`, `#`, and `>`
* Default shortcut: `Shift + Command + T`
### Multitasking
* Multiple tasks can now run simultaneously in the background
* Create a new session with `Command + N`
* Switch between different tasks by inputting `>`
### Voice Command
* Run a voice command to trigger voice input
* You can specify Window Mode to choose whether the command runs in the Smart Bar or Side Bar
* Set a Default Command to decide which Bot should handle your input after voice transcription
* Default shortcut: `Shift + Command + A`
### My Profile Settings
* You can set your personal description as context to provide to the AI Model
* You can set a global reply language
* Location: Settings > Account > My Profile
### Variables (Dynamic Parameters)
* When editing prompts, you can specify dynamic Variables
* Supported Variables are viewable under Settings > Extensions > Variables
* While editing a prompt, activate the Variables list by typing `{{ ` (double curly brace + space)
### Custom Bot Creation Optimization
* Improved workflow for creating Custom Bots
* Support for `Duplicate Command`: Create a new command based on an existing one
* Set reply language independently
* Option to use `My Profile` or not
### Application Support
* Search all installed applications from the SmartBar and press Enter to open
* Every application is an Agent. Use `@` to begin a conversation with an application
### Screenshot Explain
* Support for taking a screenshot first, then running Explain on it
***
## 2.2.16 (2025-09-26)
### New Features
* Added Finder right click menu: Add to EnConvo
### SmartBar
* Can configure **Knowledge base used by Bot** on SmartBar
* Support directly enable **"Create Video"** on the smart bar
### Video Generation Provider Added
* Added `Kling Video v2.5 Turbo Pro` video generation model
* Added `Wan 2.5 Preview` video generation model
### Apple Shortcuts
* Added `Apple Shortcuts` support, usable in Workflow, Agent, PopBar, SmartBar, etc.
### Workflow
* Optimized the logic of deleting edges and nodes in workflow
* Added the ability to reconnect edges in workflow
* Fixed workflow drag variable is undefined
### Chat with File
* Optimized file chat (chat mode can directly chat with files)
* Added `read document type file` tool to agent model (supports pdf, epub, audio, video, word, ppt documents)
### New AI Model Provider
* Added `Qwen AI Model Provider` with API Key
### Improvements
* Safety concern for shell runner (alert before execute sensitive commands)
* Optimized Tool Use UI/UX on SmartBar
* Support azure (Microsoft speech) as a provider for live closed captions
### Bug Fixes
* Optimized token acquisition for Live Closed Captions
* Fixed screen shot translate bug
* Fixed ollama embedding model not showing up bug
* Optimized message structure (solve the problem of tool use in claude thinking mode)
***
## 2.2.15 (2025-09-11)
### Web Search Enhancements
* **Gemini Search** - Use Google Gemini for web search with 2000 free requests per day
* **Search UI/UX Optimization** - Quickly specify the AI search provider on SmartBar
* **Anthropic Built-in Search** - Support for Anthropic's built-in web search tool
* **OpenAI Built-in Search** - Support for OpenAI's built-in web search tool
### Image Generation Enhancements
* **Image Generation UI/UX Optimization** - Quickly specify the image generation provider on SmartBar
* **Added fal.ai provider** - Support for Seedream 4.0
### OCR Enhancements
* **AI Model OCR Provider** - Choose to use AI models for OCR, supporting all vision models
### Improvements
* **GPT-5-codex** - Use GPT-5-codex for code-related tasks (requires OpenAI OAuth)
* **Browser Tab Context** - Vivaldi, Wavebox, and other Chromium-based browsers now support getting current tab context
### Bug Fixes
* Fixed Screenshot OCR issues
* Optimized Claude authorization
* Improved Qwen OAuth
* Fixed issue where SmartBar opened from PopBar had no actions
***
## 2.2.14 (2025-09-11)
### Workflow Enhancements
* **If Node** - Workflows now support conditional logic with **If** flow control nodes
* **Loop-Items Node** - Workflows now support looping through a list of items
* **File Change Trigger** - Added file change monitoring capability to workflows
* **Structure Output** - Workflow nodes now support structured output format
* **Auto Compress Downloads Images** - Monitor newly added image files in the download directory and automatically compress them
### New Features
* **Qwen OAuth Integration** - 2,000 free requests per day with no token limits
* **Azure Image Generation Support** - Added support for Azure OpenAI image generation
* **Quit Confirmation** - Added Command+Q prompt notification in SmartBar
### UI/UX Improvements
* **File Settings Item View** - Optimized the File Settings Item View interface
### Bug Fixes
* Fixed display chaos issues on low-resolution screens
* Fixed Facebook Messenger multiple message copying issue
* Fixed Azure OpenAI error reporting
* Fixed Google Gemini tool use issue
* Fixed input field crash issue
***
## 2.2.13 (2025-09-05)
### Workflow Enhancements
* **Share Workflows via File** - Export workflows as JSON files and share them with other users
* **Publish Workflows to Extension Store** - You can now publish your workflows to the Extension Store
### New Workflow Templates
* **Sync to Apple Notes** - Sync content to Apple Notes
* **Nano Banana + Hailuo Video Generation** - Workflow based on Nano Banana and Hailuo Video Generation
### fal.ai Supports EnConvo Cloud
* Hailuo 02 Standard/Pro Text-to-Video (Free: 5 uses per 24 hours)
* Hailuo 02 Standard/Pro Image-to-Video (Free: 5 uses per 24 hours)
* Veo3 Fast/Standard and Image-to-Video
* Seedance V1 Lite Text-to-Video
### Optimized Features
* **Edit Command Description** - Edit command descriptions for better Agent utilization
### Bug Fixes
* Fixed issue where workflow links sometimes become invalid
* Disabled commands/bots are showing up
***
## 2.2.11 (2025-08-28)
### New Features
* **ChatGPT Plus/Pro in EnConvo** - Use your ChatGPT Plus/Pro subscription in EnConvo, no API key needed
### New Models
* **Nano Banana (Gemini 2.5 Flash Image)** - Google DeepMind's Gemini 2.5 Flash model with image generation and editing capabilities
### Optimized Features
* **Image Compression** - Images are now compressed before being sent to models
* **Node Performance Optimization** - Automatically clean up idle workers
* **Youtube Downloader Update** - Upgraded yt-dlp to version 2025.08.22
### Bug Fixes
* Fixed incorrect path handling issue in video compression
* Fixed Terminal.app not syncing issue
* Fixed AI model global display issue
***
## 2.2.10 (2025-08-19)
### New Features
* **Claude Pro/Max in EnConvo** - Use your Claude Pro/Max subscription in EnConvo, no API key needed
### Optimized Features
* **Thinking Effort** - Quickly configure the model's deep thinking capability (Command + E)
* **MCP OAuth** - Use MCP services that support OAuth, such as Notion (Official)
### New Free Services
* **Voyage-3.5-lite (embedding)** - Powerful multilingual embedding capabilities for free
### UI/UX Improvements
* **Custom bots** - Added New Bot button for quickly creating custom bots
* **Model selection** - Model selection is now displayed in a double-row layout
### Others
* Allow uninstallation of some non-essential pre-installed Extensions
***
## 2.2.9 (2025-08-12)
### UI/UX Improvements
* **Model Card** - Show detailed model information and parameters when hover on the model name
### Optimized Features
* **Global Model Provider Settings** - Switch the model provider between global settings and custom settings
* **Add/Edit Model** - Adjust the model's parameters based on actual attributes and preferences
### New TTS Models
* **MiniMax Speech 2.5 Model** - Enhanced Multilingual Expressiveness Exceptional Voice
### New MCP Server
* **Excel MCP Server** - Manipulate Excel files without needing Microsoft Excel installed
***
## 2.2.8 (2025-08-07)
### Brand New Extension Store
* **One-click installation** - Say goodbye to tedious configuration
* **Multiple Registries** - Choose from EnConvo official, Smithery, or mcphub extension sources
* **DXT One-Click Installation** - Quickly install plugins from dxt files
* **Extension Upgrade** - Independent extension upgrades with one-click functionality
* **Manual Installation** - Support for Stdio/Http/Sse type MCP extensions
### New AI Models (Limited Time Free, Ending on September 30th)
* OpenAI **gpt-oss-120b**, **gpt-oss-20b**
### Link Reader Providers
* **Local Fetch** - (locally, free)
* **Crawl4AI** - (locally, free)
### Website Crawler Providers
* **Crawl4AI** - (locally, free)
### New Features
* **Points Usage Log** - Added points usage log page (Settings->Account->Points Usage)
### Optimized Features
* **MCP Server Auto-shutdown** - MCP servers automatically shut down after 3 minutes of inactivity
***
## 2.2.7 (2025-07-22)
### Added Speech Recognition Model
* **mlx parakeet-tdt-0.6b-v2** - Faster speed and better quality, local & privacy-focused
### New AI Model Provider
* **302.ai** - Added 302.ai LLM provider
### Optimized Features
* **App Size Optimization** - Reduced application size from 367MB to 224MB
* **Moonshot BaseURL Support** - Added support for custom BaseURL settings
### Bug Fixes
* Fixed Online Video Downloader `audio only` option and mp4 suffix issues
* Fixed MCP runtime error issues
* Fixed Summarize YouTube/Link response language setting not taking effect
* Resolved fireworks.ai error issues
***
## 2.2.6 (2025-07-18)
### Knowledge Base
* **Enhanced Knowledge Base UI/UX** - Streamlined interface for easier management
* **YouTube Video Import** - Import videos with automatic subtitle extraction
* **Image Import with OCR** - Extract and index text content from images automatically
* **Audio File Import** - Convert speech to text and add to knowledge base
* **Video File Import** - Extract audio and convert speech to searchable text
* **Single Web Page Import** - Extract content from any webpage
* **Whole Website Import** - Crawl and import entire websites using Firecrawl
* **Direct Text Addition** - Quickly add custom text content
### New AI Models
* **Grok 4** - Added support for Grok 4 (EnConvo Cloud Plan and API key)
* **Kimi K2** - Added support for Kimi K2 (EnConvo Cloud Plan and API key)
### TTS
* **TTS Voice Preview** - Support for previewing TTS Voice sounds
### New Features
* **Firecrawl** - Added Firecrawl as `Link Reader Provider`
* **Website Crawl** - Added `Website Crawl provider` support
* **Translator (Interactive)** - Added `Translator (Interactive)`
### Optimized Features
* **Summarize Url / Chat with Url** - Optimized continuation conversation logic
* **YouTube Video Download** - Optimized download and subtitle download logic
* **Chat with Youtube** - Optimized logic and improved prompt
* **ElevenLabs V3** - Support for ElevenLabs V3
### Bug Fixes
* Fixed copy/paste compatibility for Ukrainian language
* Fixed video playback issues for downloaded videos
***
## 2.2.5 (2025-06-23)
### Mini SmartBar
* Mini SmartBar now supports custom commands with Application Awareness and Browser Tab URL Awareness
### Dictation
* Added Dictation `Post Actions` feature (Fix Spelling, Translate, customized workflow)
* Renamed `Voice Input` to `Dictation`
### Prompt Management
* Added `Prompt Store` for installing curated prompts
* Added `Installed Prompt` management
* Added `Create new prompt` command
### SmartBar
* Added `SmartBar Navigation bindings` (Control+P/N or vim-like Control+J/K)
* Added `SmartBar Auto clear conversation`
### New Commands
* `French Teacher`: A French teacher to help users learn French
### Optimized Features
* `Disable command` feature: disabled commands won't appear in SmartBar
* `PopBar` now supports detecting current browser tab URL
* `Shortcut` settings UI/UX optimization
### Bug Fixes
* Fixed issue where Dictation Bar couldn't be closed
* Fixed issue where PopBar window position exceeded screen boundaries
* Fixed Shortcut settings invalidating existing shortcuts
* Fixed Post Action not working in PopBar
***
## 2.2.4 (2025-06-21)
### PopBar (Big Update)
* **Application-Awareness**: PopBar can detect the current application and display different toolbars
* Built-in `Writing Tools` PopBar Instance for writing apps
* Added option to automatically replace current text after tool returns result
* Optimized PopBar appearance timing and position
* Added `Open Link` tool, `Search Google` tool
* Added `PopBar disable in this application` feature
* Added `Duplicate of PopBar Instance` feature
* Added `Modifier flags action` feature
### New Commands
* Added more writing tools: `proofread`, `rewrite`, `changeToneToProfessional`, `makeConcise`, `extractKeyPoints`, `convertToList`, `convertToTable`
* Added `AI Editor` command (similar to Cursor.app's `Quick Edit`)
### New Extension (Fal.ai)
* Generate video with Veo3
* Fal.ai text-to-video with Minimax Hailuo02 Standard/Pro
* Fal.ai generate video with Bytedance Seedance 1.0 Lite
### Optimized Features
* Added custom bots management in settings
* Adjusted Mini SmartBar expansion timing
* Added `PopBar` and `MiniSmartBar` toggles in menu bar
* Added `delete command` and `reset configuration` features
* Optimized Command search UI/UX
### EnConvo Cloud Plan New Models
* Claude Sonnet 4, Opus 4
* O3, O3 Mini, O4-Mini
* Gemini 2.5 Pro, Gemini 2.5 Flash, Gemini 2.5 Flash Lite Preview
### Workflow
* Added `Generate Video with Veo3` workflow template
* Added `Text to Audio` workflow template
***
## 2.2.3 (2025-06-15)
### New Features
* Configurable option for whether new chats in Chat window will be displayed in Smartbar
### Optimized Features
* Optimized `Installed Extensions` management page
* Optimized `Explain` prompt
* Optimized PopBar settings page UI/UX
* New settings UI/UX for Smartbar, MiniSmartbar, ChatWindow, Langchain, Developer Tools
### Bug Fixes
* Fixed `Create New bot` editing issue
* Fixed `Google Cloud Search` errors
* Fixed chatbot name change issue
* Fixed model list refresh issue
***
## 2.2.2 (2025-06-11)
### New Features
* Added scheduled trigger functionality for Workflows with cron expressions support
* Pre-built workflow template for daily weather information with TTS and email
### Optimized Features
* Workflow/Agent supports Gmail attachment sending
* Ability to rename nodes in Workflows
* Optimized auto-scroll issue when outputting text in chat
### Fixed Issues
* Straico AI issues fix
* Fixed Shortcuts Center display issue
* Fixed Google Gemini error issues
* Fixed clipboard-related crash issues
***
## 2.2.1 (2025-06-07)
### Workflow
* Brand new **visual workflow editor**
* Built-in 200+ tools, **native support for MCP Servers in workflows**
* **Smart parameters support** - automatically generate tool parameters through AI
* New **Workflow Templates Store**
* Workflow parameter settings support **jinja2** template syntax
### Brand new Credentials Management
* Optimized Credentials management logic
* Support for **OAuth 2.0** authentication
* Added more Provider Credentials management
### New Plugins
* New **Gmail** with OAuth2 authorization
* New **Firecrawl** (including EnConvo Cloud support)
* New **Gemini TTS**, **Gemini TTS Multi Speaker**
### MCP Feature Improvements
* MCP can now **individually configure** whether to enable specific tools
* MCP is now bound to Agent, no longer globally applied
* MCP management add/delete UI/UX improvements
### Context Awareness Feature Improvements
* Support for more Context awareness (screenshots, clipboard text, etc.)
* Users can freely configure the context that each Command can perceive
### Feature Improvements
* Fix Spelling\&Grammar supports **text highlight comparison**
* Stability and performance optimizations
* Settings page UI/UX improvements
* Chat Window new session creation UI/UX improvements
* Mini smartbar automatically shrinks and hides after 1s of no operation
* Mini smartbar automatically snaps to edges
* `Create New Bot` UI/UX improvements
***
## 2.1.9 (2025-05-02)
### Improvements
* **Language Settings for Chat Responses** - Configure the language your agent responds in
* **Toggle for Mini Window** - Enable or disable the Mini Window feature
* **Enhanced Voice Dictation Stability** - More reliable speech recognition
***
## 2.1.8 (2025-04-22)
### New Features
* **Introduced Mini SmartBar** - A compact desktop companion with quick access to features
* **Integrated Hailuo Voice** as default TTS Provider (EnConvo Cloud Plan)
* **New OCR Providers**
* Apple Native OCR: Fast, offline, privacy-focused local processing
* Mistral OCR: Integrated solution supporting EnConvo Cloud Plan and custom API Keys
* **Added new Mistral models** to EnConvo Cloud Plan
* Mistral Large (300 points per message)
* Mistral Small (Free)
* **Introduced EnConvo Cloud Plan** for Speech-to-Text Provider
* Supporting whisper turbo, gpt-4o-transcribe, and gpt-4o-mini-transcribe
### Improvements
* **Startup optimization** and bug fixes
* Enhanced Image Generation with **Flux1.1 pro**
* Added close button to Voice Input Method
* Added direct model configuration in Chat Window
* Expanded **Google Gemini model support**
* OCR Improved: Automatic language detection with **Japanese** support
* Optimized audio auto play logic
* Enhanced Speech-to-Text stability
***
## 2.1.7 (2025-04-07)
### New Features
* **Introduced MCP Store** - Your One-Stop Shop for MCP Servers
* One-click installation for quick and easy setup
* Online access at [https://app.enconvo.ai/mcp\_store](https://app.enconvo.ai/mcp_store)
* Share your favorite MCP Servers with friends via shareable links
* Added dedicated MCP configuration toggle in SmartBar
* Integrated support for gemini-2.5-pro-preview-03-25 (EnConvo Cloud Plan)
* Introduced Command + S shortcut to toggle AI search
***
## 2.1.6 (2025-03-25)
### New Features
* **Introduced Mavis** - The general AI Agent for your Mac
* Vibe Coding: Generate clickable project links and ready-to-run applications
* Report Writing: Create detailed, clickable reports from simple descriptions
* Added multi-language UI support (German, French, Japanese, Spanish)
* Introduced `Text to Sound Effect` feature powered by ElevenLabs
### Improvements
* Rewrote message list for enhanced loading and scrolling performance
* Added resolution settings for Online Video downloads
* Enhanced video downloader with browser cookie support for private content
* Improved knowledge base addition speed and stability
***
## 2.1.5 (2025-03-05)
### New Features
* Added support for new Perplexity models: `r1-1776` and `sonar-deep-research`
* Added configurable result count for AI Web Search
* Added ability to hide Chat Window using the `ESC` key
* Added voice playback functionality for existing responses
* Added Elevenlabs Scribe speech-to-text integration
* Added Elevenlabs TTS and Speechify TTS integration
### Improvements
* Optimized Live Captions with customizable caption height
* Enhanced stability when adding large files to knowledge base
### Bug Fixes
* Fixed longPress shortcut key issue with `Voice input method push`
***
## 2.1.4 (2025-03-01)
### New Features
* Added SmartBar default command setting functionality
* Added `reasoning_effort` parameter for LLM
### Improvements
* Optimized PopBar hotkey logic to toggle display/hide mode
* Enhanced SmartBar UX logic
### Bug Fixes
* Fixed issue where "New Chat" couldn't use web browsing functionality
* Fixed SmartBar hotkey deletion not working
***
## 2.1.3 (2025-02-25)
### New Features
* Added support for `Claude 3.7 Sonnet` and `Claude 3.7 Sonnet Thinking` models
* New `Local Link Reader` provider for faster, more stable webpage content extraction
* New `Read Aloud Webpage` Tool
### Improvements
* Optimized prompts to improve agent instruction following capabilities
* Enhanced MCP (Model Context Protocol) stability
***
## 2.1.2 (2025-02-22)
### New Features
* New `Online Video Downloader` tool (TikTok, YouTube, Twitter, Instagram, Reddit, Vimeo, etc.)
* New `App Context Awareness` feature
* New `post-action` settings (paste, insert, copy)
* New `PopBar` display style settings
### Improvements
* Enhanced AI Web Search with source references
* Improved Chat Window's `new chat` and `clear conversations` logic
* Upgraded Speech-to-text Deepgram Provider with `Nova 3` model support
* Optimized `DeepSeek R1` model speed and stability
* Added support for custom Google Gemini and DeepSeek LLM Provider BaseUrl
### Bug Fixes
* Fixed auto duplicate issue in Preview\.app
* Fixed text input issues with Voice Input Method
* Fixed Claude image format compatibility issues
* Fixed Insert Below compatibility issues
* Fixed model display not updating after switching models
***
## 2.1.0 (2025-02-13)
### New Events
* DeepSeek R1 and DeepSeek V3 are now available for unlimited free use (2025-02-13 \~ 2025-03-13)
### Improvements
* Optimized default configuration settings logic
### Bug Fixes
* Fixed shortcut key settings not taking effect
* Fixed issue where models could not be selected via mouse click
***
## 2.0.9 (2025-02-11)
### New Features
* Added model switching with / character
* Added Context deletion features
* Deep Research Agent now shows research process
* Added custom shortcut keys support for @ and / trigger characters
### Improvements
* Improved startup stability
* Enhanced Context display
* Improved copy/paste compatibility
***
## 2.0.8 (2025-02-10)
### New Features
* Added Recraft integration for enhanced design workflows
* Added Image Editor Agent for advanced image manipulation
* Added New Chat functionality
* Added Duplicate Command functionality
* Recraft tools: Crisp Upscale, Generate Image, Image to Image, Vectorize Image, Creative Upscale, Remove Background, Replace Background
### Bug Fixes
* Fixed Exa Websearch Provider issues
* Fixed incorrect tab detection in Safari
***
## 2.0.7 (2025-02-07)
### New Features
* Added Deep Research Agent
### Feature Updates
* Changed default LLM model to gpt-4o
### Bug Fixes
* Fixed background crash issues
* Added multi-screen centered display support for Smart Bar
***
## 2.0.6 (2025-02-06)
### Google Gemini Updates
* Updated Gemini 2.0 Flash to stable release
* Added gemini-2.0-flash-lite model
* Added gemini-2.0-pro-exp model
### Subscription Management
* Added subscription cancellation management interface
### Bug Fixes
* Fixed Hailuo TTS (Chinese) related issues
* Fixed missing text issue when activating PopBar with hotkey
* Fixed Double Click hotkey configuration issue
* Fixed Voice Input Method unable to stop when connection is lost
***
## 2.0.5 (2025-02-03)
### Video Downloaders
* **Twitter Video Downloader**: Added support for downloading Twitter videos
* **YouTube Video Downloader**: Added support for downloading YouTube videos
### Apple Extensions Enhancements
**Apple Reminders**
* Update reminders, Delete reminders, Toggle reminder status, Get all incomplete reminders
**Apple Calendar**
* Delete events, Update events, Get calendar events list
**New Apple Mail Extension**
* View unread emails, Delete emails, Toggle read/unread status, View email content, Send emails
### Screenshot Extension Updates
* Capture current application, Capture current screen, Manual window selection capture
### AI Model Improvements
* Optimized thinking process display for Ollama R1 and other reasoning models
* Added DeepSeek R1 and DeepSeek V3 model support to EnConvo Cloud Plan
* Enhanced Jarvis prompt for improved Agent task execution capabilities
* Updated Perplexity models: `sonar`, `sonar-pro`, `sonar-reasoning`
### Other Updates
* **Conch TTS**: Split into Chinese and international servers
* **LM Studio**: Added model list display
* Fixed straico-related issues
***
## 2.0.4 (2025-01-24)
### Agent Features
* **Jarvis**: Now automatically completes tasks using tools based on your needs
* Available tools include: AppleScript, Shell, Python, NodeJS, Image Generation, Apple Calendar, Apple Reminders, Image Compression, HTTP Requests, TTS, Audio/Video Transcription, Video Compression, Web Search, Link Reader, YouTube Loader, File System Operations
* Added "Create New Agent" feature
### MCP (Model Context Protocol) Support
* EnConvo as MCP Client supports installation and use of any MCP Server
* MCP Settings page with real-time server status monitoring
### DeepSeek r1 Model Support
* Added support for DeepSeek r1 model
* Added Thinking interaction mode
### New Plugins
* **Video Compress**, **Extract Audio**, **Audio Compress**, **Transcribe Audio/Video Files**
* **Python Code Runner**, **NodeJS Code Runner**, **Shell Script Executor**, **AppleScript Executor**
* **Conch TTS Support**
### Google LLM Provider Updates
* Updated to latest gemini-2.0-flash-thinking-exp-01-21
* Native support for audio message types
### Optimizations
* Improved TTS performance
* Optimized Python environment initialization
* Added parameter display in Workflows
***
## 2.0.3 (2024-12-20)
### Chat Window Enhancements
* New UI design for improved aesthetics
* Performance optimization with reduced CPU usage
* Expanded functionality: Voice Input, Screenshot, Web Search, Live Screen, Live Camera, File Attachment, and Realtime Call
### YouTube Plugin Integration
* Chat With YouTube, Summarize YouTube, YouTube Transcript Loader, YouTube Context Awareness
### Code Runner Plugin
* Run shell, Node.js, Python, and AppleScript code
### Straico Integration
* Straico LLM Provider, Image Generate Provider, and Plugin (Chat, RAG, Agent)
### Google Gemini Update
* `gemini-2.0-flash-exp`, `gemini-2.0-flash-thinking-exp-1219`, `gemini-exp-1206`
### X.AI-GROK Update
* `grok-2-vision-1212`, `grok-2-1212`
### New Setting Option
* Added "Context Message Count Limit" setting
***
## 2.0.2 (2024-12-12)
### Performance Improvements
* **Voice Input Efficiency**: CPU usage reduced from 40% to 5%
* **SmartBar Optimization**: CPU usage reduced from 1.9% to 0.2%
* **Live Screen Preview Enhancement**: CPU usage reduced from 30% to 12%
### New Features
* **Ollama Embedding Integration**: Chat with Document and Knowledge Base features now work completely offline
* **Audio Input Selection**: Voice Input Method now supports custom audio source selection
### Improvements
* UI Enhancements: Fixed "Untitled" display issue, resolved text styling in SmartBar, fixed pinyin input display issue
* Voice and TTS Improvements: Fixed TTS speed settings, resolved incomplete voice recognition
### Integrations
* **Google TTS Support**
***
## 2.0.1 (2024-11-27)
### New Features
* **Deeplink Support**: Generate deeplink for command in SmartBar for quick access
* **Markdown-to-Image Extension**: Convert Markdown content into beautiful images
* **EnConvo Companion Chrome Extension**: Directly capture and access current browser content
* **ChatGPT Website Integration**: Quick access to ChatGPT directly from SmartBar
* **Claude Website Integration**: Launch Claude instantly from SmartBar
### Improvements
* **Context Awareness**: Added ARC browser support
* **Voice Input Method Enhancements**: Stream Insert mode toggle, 2-second pause detection for automatic line breaks
* Other Improvements: Reduced default keyboard shortcuts, Slovak language support, new extension removal feature
### Bug Fixes
* Fixed workflow selection issue during creation
* Resolved "Untitled" workflow display problem in PopBar
***
For older changelog entries, please visit our [GitHub releases page](https://github.com/enconvo/releases).
# Account, Profile, and Usage
Source: https://docs.enconvo.ai/configuration/account
Manage your Enconvo account and inspect Cloud usage.
Open the **Account** section of Settings to find **My Profile**, **Account**, and **Points Usage**.
| Entry | Purpose |
| - | - |
| My Profile | Information you choose to provide so Enconvo can tailor responses |
| Account | Your Enconvo account, app license, and plan information |
| Points Usage | Cloud usage records for your account |
## Check access and usage
1. Open **Account** and confirm which Enconvo account is signed in.
2. Review the current license or plan shown there.
3. Open **Points Usage** to inspect Cloud consumption.
4. If a request fails, also check the provider and authentication method used by that feature.
An Enconvo account, a provider API key, and a provider subscription sign-in are different connections. BYOK requests use the provider account's billing and limits. Supported subscription connections show their own usage in provider settings, separate from Enconvo Cloud points.
See [Pricing](/pricing) for official plan links and [Credentials](/configuration/credentials) for provider profiles. Only put information in My Profile that you want to use as personalization context.
# Credentials and Provider Profiles
Source: https://docs.enconvo.ai/configuration/credentials
Configure API keys, account connections, and shared provider profiles.
Configure the service you want to use under **Settings → Global Providers Settings**, then open the relevant provider. **Credential Management** groups credentials by provider and shows unused keys separately.
## Add a provider
1. Open a category such as **AI Model**, **Image Generation**, or **Text-to-Speech**.
2. Select a provider, or choose **Add New Provider** for another profile.
3. Under **Authentication**, choose the method available for that provider: API key or its supported account/subscription sign-in.
4. Enter your own credentials or complete the provider's connection flow.
5. Validate if the provider exposes a validation action, select a model, and try a small request.
An API key and a subscription connection have different billing and service limits. Use the explanatory text beneath Authentication to check which method requests will use.
## Shared profiles
A provider profile such as **OpenAI 2** shares its API key and account connection across supported categories. Renaming or deleting the profile applies to the profile across those categories, not just the page you are viewing.
Model, voice, and generation settings remain specific to their feature. Changing an API key can affect several features that use the same profile.
## Account connections and usage
Supported subscription connections show account information and available usage limits. A value such as **% left** is remaining allowance. The account card's menu can expose **Reconnect** and **Refresh usage**. Missing usage information does not mean unlimited usage.
Availability varies by provider and feature. For example, an account connection offered for AI chat does not guarantee that provider's realtime voice API is included.
## Custom endpoints
Custom OpenAI Compatible and Anthropic Compatible providers expose an API base URL. Some built-in providers keep endpoint configuration in Credential Management. For servers on another computer, see [Local Models](/ai/local-llm).
## Troubleshooting
If validation fails, check the selected profile, authentication method, endpoint, and provider account access. If one feature works but another fails, confirm that the account supports that feature and model. After changing a shared profile, test the other categories that use it.
Related: [Providers](/providers/overview), [Privacy and Security](/configuration/privacy-security).
# Hooks
Source: https://docs.enconvo.ai/configuration/hooks
Run commands or webhooks automatically when EnConvo events happen
## Overview
Hooks let you run a shell command or send an HTTP request when something happens
inside EnConvo, such as an agent starting, completing, failing, or using a tool.
They are configured with a JSON file, so you can add notifications, logs, local
automation, or integrations without building an extension.
Most hooks are fire-and-forget: they run in the background and do not block
EnConvo. `PreToolUse`, `Stop`, and `SubagentStop` are the exception during
agent runs — the agent waits for them, so they can block a tool call or send the
agent back to work. See [Blocking Hooks](#blocking-hooks).
## Config File
Create your hooks config at:
```text theme={null}
~/.enconvo/hooks.json
```
EnConvo also reads the legacy file at `~/.config/enconvo/hooks.json` when the
new file does not exist. If both files exist, `~/.enconvo/hooks.json` wins.
The file is checked again whenever an event fires, so you can edit hooks while
EnConvo is running. No restart is required.
## Manage Hooks in Settings
Open **Settings → Hooks** to inspect hooks from `~/.enconvo/hooks.json`.
The settings panel groups entries by event, lets you toggle an entry on or off,
and can open the JSON file for editing. Toggling writes `enabled: false` or
`enabled: true` on that hook entry without changing the command or webhook
definition.
## Quick Start
```bash theme={null}
mkdir -p ~/.enconvo
```
```json theme={null}
{
"hooks": {
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "echo 'Agent status changed' >> /tmp/enconvo-hooks.log"
}
]
}
]
}
}
```
Start any agent or chat command. When its status changes, EnConvo runs the
configured command and appends a line to `/tmp/enconvo-hooks.log`.
## How Hooks Work
When an event fires, EnConvo:
1. Loads `~/.enconvo/hooks.json`.
2. Falls back to `~/.config/enconvo/hooks.json` only if the new file is absent.
3. Finds entries inside the top-level `hooks` object whose key matches the event name.
4. Applies the optional `matcher` regex.
5. Skips entries where `enabled` is `false`.
6. Runs every configured hook concurrently.
Hook event names follow the Claude Code and Codex lifecycle set:
`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`,
`PostToolUse`, `Stop`, and `SubagentStop`. The old EnConvo event names and old flat JSON shape are still readable
for existing installs, but new writes use the wrapped Codex-style format.
## Configuration Reference
```json theme={null}
{
"hooks": {
"event_name": [
{
"matcher": "optional_regex_filter",
"enabled": true,
"hooks": [
{ "type": "command", "command": "..." },
{ "type": "http", "url": "..." }
]
}
]
}
}
```
| Field | Type | Required | Description |
| - | - | - | - |
| `hooks` | object | Yes | Event map keyed by event name. |
| `event_name` | string | Yes | Event to listen for. Use this as a key inside `hooks`. |
| `matcher` | string | No | Regex filter. For tool events, it matches `toolName`, `toolTitle`, or `path`; for other events, it matches the hook event name. |
| `enabled` | boolean | No | Set to `false` to keep the entry in config but skip execution. Defaults to `true`. |
| `hooks` | array | Yes | Command and HTTP hooks to execute. |
### Command Hook
A command hook runs a shell command. EnConvo writes the event payload to the
command's stdin as JSON.
```json theme={null}
{
"type": "command",
"command": "bash ~/.enconvo/hooks/on-status-change.sh",
"timeout": 30000
}
```
| Field | Type | Default | Description |
| - | - | - | - |
| `type` | `"command"` | - | Required hook type. |
| `command` | string | - | Shell command to execute. |
| `timeout` | number | `30000` | Timeout in milliseconds. |
### HTTP Hook
An HTTP hook sends the event payload as the JSON request body.
```json theme={null}
{
"type": "http",
"url": "https://example.com/webhook",
"method": "POST",
"headers": {
"Authorization": "Bearer your-token"
},
"timeout": 30000
}
```
| Field | Type | Default | Description |
| - | - | - | - |
| `type` | `"http"` | - | Required hook type. |
| `url` | string | - | HTTP endpoint URL. |
| `method` | string | `"POST"` | HTTP method. |
| `headers` | object | `{}` | Additional request headers. |
| `timeout` | number | `30000` | Timeout in milliseconds. |
## Blocking Hooks
During an agent or bot run, three events run as blocking hooks. The agent waits
for every matching hook (they run in parallel) before it continues, and reads
their result the same way Claude Code and Codex do.
| Event | When | What the hook can do |
| - | - | - |
| `PreToolUse` | Right before a tool call runs. The `matcher` is checked against the tool name, title, and route path. | Block the call, or rewrite its input. |
| `Stop` | Right before the agent ends its turn with an answer. | Send the agent back to work with an instruction. |
| `SubagentStop` | Right before a subagent finishes. | Send the subagent back to work with an instruction. |
A hook decides in one of two ways:
* **Exit code 2** blocks. The text the command writes to stderr is the reason.
* **Exit code 0 with JSON on stdout.** Any other output, exit code, error, or
timeout decides nothing, and the run continues as if the hook were not there.
```json theme={null}
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Writing outside the project is not allowed."
}
}
```
| JSON output | Effect |
| - | - |
| `hookSpecificOutput.permissionDecision: "deny"` | `PreToolUse`: the call does not run. The model sees `permissionDecisionReason` as the tool result and can choose another way. |
| `hookSpecificOutput.permissionDecision: "ask"` | Treated as `deny`. EnConvo has no confirmation prompt for hooks yet. |
| `hookSpecificOutput.permissionDecision: "allow"` | `PreToolUse`: the call runs. |
| `hookSpecificOutput.updatedInput` | `PreToolUse`: the call runs with this input instead of the model's. |
| `{ "decision": "block", "reason": "..." }` | `Stop` / `SubagentStop`: the agent keeps working, with `reason` as its next instruction. On `PreToolUse` it blocks the call. |
| `{ "decision": "approve" }` | Same as `allow`. |
HTTP hooks decide with a 2xx response whose body is the same JSON.
When several hooks match, a deny wins over ask, which wins over allow; the
reasons are joined, and the last `updatedInput` is used.
A `Stop` hook can send the agent back at most 5 times in one turn. On the second
and later checks, `stop_hook_active` is `true`, so a hook can let the agent stop
once its instruction has been followed. `Stop` blocking only applies when the
agent finishes normally; a failed or stopped run still fires `Stop` in the
background.
The agent waits for blocking hooks, so a slow `PreToolUse` hook slows every tool
call and a slow `Stop` hook delays the end of the turn. Keep them fast, set a
short `timeout`, or run slow work in the background (`command &`).
Blocking hooks receive the regular [event payload](#event-payload) plus the
Claude Code fields at the top level:
```json theme={null}
{
"hook_event_name": "PreToolUse",
"session_id": "Qx2...",
"cwd": "/Users/you/project",
"tool_name": "bash",
"tool_input": { "command": "rm -rf build" },
"tool_use_id": "call_1",
"event": "PreToolUse",
"sourceEvent": "agent_tool_step_changed",
"params": { "toolName": "bash", "status": "running", "sessionId": "Qx2..." },
"timestamp": 1742313600000
}
```
`Stop` and `SubagentStop` receive `stop_hook_active` and
`last_assistant_message` instead of the tool fields. Command hooks run in the
agent's working directory.
### Block a Dangerous Command
```bash theme={null}
#!/bin/bash
# ~/.enconvo/hooks/guard.sh
COMMAND=$(jq -r '.tool_input.command // empty')
if echo "$COMMAND" | grep -q 'rm -rf /'; then
echo "Deleting from the filesystem root is not allowed." >&2
exit 2
fi
```
```json theme={null}
{
"hooks": {
"PreToolUse": [
{
"matcher": "bash",
"hooks": [{ "type": "command", "command": "bash ~/.enconvo/hooks/guard.sh", "timeout": 5000 }]
}
]
}
}
```
### Make the Agent Run Tests Before Finishing
```bash theme={null}
#!/bin/bash
# ~/.enconvo/hooks/require-tests.sh
[ "$(jq -r '.stop_hook_active')" = "true" ] && exit 0
echo '{"decision":"block","reason":"Run the test suite and fix any failures before you finish."}'
```
## Event Payload
Command hooks receive this JSON on stdin. HTTP hooks receive the same JSON as
the request body.
```json theme={null}
{
"event": "UserPromptSubmit",
"fullEvent": "event-UserPromptSubmit",
"sourceEvent": "run_status_changed",
"sourceFullEvent": "event-run_status_changed",
"params": {
"commandKey": "agent|main",
"runStatus": "running"
},
"timestamp": 1742313600000
}
```
| Field | Description |
| - | - |
| `event` | Short event name. |
| `fullEvent` | Internal event name with the `event-` prefix. |
| `sourceEvent` | Original EnConvo event that produced this hook event, when the event is mapped for Codex compatibility. |
| `sourceFullEvent` | Original internal event name with the `event-` prefix. |
| `params` | Event-specific payload. |
| `timestamp` | Unix timestamp in milliseconds. |
## Available Events
| Event | Params | When |
| - | - | - |
| `SessionStart` | `{ command, commandKey }` | A new chat session is created. |
| `UserPromptSubmit` | `{ commandKey, runStatus, status?, sessionId? }` | An agent, chat, or bot run starts from user input. |
| `PreToolUse` | `{ toolCallId, toolName, toolTitle?, status, sessionId?, commandKey? }` | A tool call starts. Blocking during agent runs. |
| `PermissionRequest` | `{ toolCallId, toolName, toolTitle?, status, sessionId?, commandKey? }` | A tool call reaches a permission or denied state. |
| `PostToolUse` | `{ toolCallId, toolName, toolTitle?, status, sessionId?, commandKey? }` | A tool call succeeds, fails, completes, or is denied. |
| `Stop` | `{ commandKey, runStatus, status?, sessionId? }` | An agent, chat, or bot run reaches a terminal status. Blocking when an agent finishes normally. |
| `SubagentStop` | `{ commandKey, runStatus, status?, sessionId? }` | A subagent is about to finish. Blocking. Subagents do not fire `Stop`. |
Legacy EnConvo names such as `run_status_changed` and
`agent_tool_step_changed` still work, so existing hook files do not need to be
migrated immediately.
## Recipes
### macOS Notification on Agent Failure
```json theme={null}
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "STATUS=$(cat | jq -r '.params.runStatus // .params.status') && [ \"$STATUS\" = \"failed\" ] && osascript -e 'display notification \"An agent failed\" with title \"EnConvo\"'"
}
]
}
]
}
}
```
### Log Agent Status Changes
```json theme={null}
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "jq -c '{time: (.timestamp / 1000 | strftime(\"%Y-%m-%d %H:%M:%S\")), agent: .params.commandKey, status: (.params.runStatus // .params.status)}' >> ~/.enconvo/agent-status.log"
}
]
}
]
}
}
```
### Log Agent Tool Calls
```json theme={null}
{
"hooks": {
"PostToolUse": [
{
"hooks": [
{
"type": "command",
"command": "jq -r '.params | \"\\(.status) \\(.toolName) \\(.toolCallId)\"' >> ~/.enconvo/agent-tools.log"
}
]
}
]
}
}
```
### Send to Slack
```json theme={null}
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "http",
"url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
}
]
}
]
}
}
```
### Custom Script
Create a script that reads the event payload from stdin:
```bash theme={null}
#!/bin/bash
# ~/.enconvo/hooks/on-status-change.sh
INPUT=$(cat)
STATUS=$(echo "$INPUT" | jq -r '.params.runStatus // .params.status')
AGENT=$(echo "$INPUT" | jq -r '.params.commandKey')
echo "[$(date)] $AGENT -> $STATUS" >> /tmp/enconvo-hooks.log
if [ "$STATUS" = "failed" ]; then
osascript -e "display notification \"$AGENT failed\" with title \"EnConvo\""
fi
```
Reference it from `~/.enconvo/hooks.json`:
```json theme={null}
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "bash ~/.enconvo/hooks/on-status-change.sh"
}
]
}
]
}
}
```
Make the script executable:
```bash theme={null}
chmod +x ~/.enconvo/hooks/on-status-change.sh
```
## Troubleshooting
Confirm that `~/.enconvo/hooks.json` is valid JSON, the top-level key matches
the event name, and the command works when run manually. If you still have
`~/.config/enconvo/hooks.json`, remember that it is ignored when the new file
exists.
Pipe a sample payload into the script:
```bash theme={null}
echo '{"event":"Stop","params":{"commandKey":"agent|main","runStatus":"failed"},"timestamp":1742313600000}' | bash ~/.enconvo/hooks/on-status-change.sh
```
Only `PreToolUse`, `Stop`, and `SubagentStop` during agent runs, which the
agent waits for. Every other hook is fire-and-forget. If any hook fails or
times out, EnConvo logs the failure and continues as if the hook were not
there.
Prefer absolute paths for scripts and binaries. Shell `~` expansion works
when the command is executed through a shell, but absolute paths are easier
to debug.
Learn about EnConvo agents and custom bots
Build extensions that emit or listen to events
# Keyboard Shortcuts
Source: https://docs.enconvo.ai/configuration/keyboard-shortcuts
Find and customize shortcuts without relying on another Mac’s bindings.
Open **Settings → General → Shortcut** for the shortcut list. Feature pages also expose their relevant hotkey controls. Saved bindings on your Mac take precedence over examples in documentation.
## Common entry points
| Feature | Where to configure |
| - | - |
| SmartBar | Settings → Primary Function Area → SmartBar; commonly Shift + Command + D |
| Dynamic Island | Settings → Primary Function Area → Dynamic Island |
| PopBar | Settings → Primary Function Area → PopBar |
| App Sidebar | Settings → App Sidebar; commonly Shift + Command + T |
| Dictation | Settings → Dictation |
| Voice Trigger | Settings → Agents → Voice Trigger |
| Appshots | Settings → Context → Appshots |
| Screen Doodle | Settings → Context → Screen Doodle |
| Voice Note | Settings → Memory → Voice Note |
| Quick Capture | Settings → Memory → Quick Capture |
| Individual command | That command's settings, when a Hotkey field is offered |
## Record a shortcut
1. Click the hotkey field for the intended action.
2. Press the desired combination.
3. Select a gesture mode if the field offers one, such as Hold, Double Tap, or Modifier Keys.
4. Read the explanation next to the field and test the gesture from another app.
5. Clear or change a conflicting binding if a different action runs.
Hold and double-tap gestures behave differently from an ordinary key combination. Follow the description displayed in that feature's settings.
## Inside SmartBar
Use the configured command/context characters to open the relevant picker. The default settings expose **@** for command search, **#** for context mentions, and **>** for recent tasks. The slash menu provides actions such as model and reasoning selection.
Navigation bindings are configurable in SmartBar settings. Check that selection before assuming a particular Control-key sequence is enabled.
## Troubleshooting
If a shortcut works only inside Enconvo, review global permissions and app conflicts. If a modifier gesture fails, check whether the setting expects a press, hold, simultaneous modifier keys, or double tap. Avoid relying on a documentation shortcut if you have customized that feature.
# Notifications
Source: https://docs.enconvo.ai/configuration/notifications
Choose how Enconvo tells you an Agent has finished.
Open **Settings → Agents → Notifications** to control what happens when an Agent session finishes.
| Setting | Result |
| - | - |
| Open the Dynamic Island | Automatically expand the island when a session started there finishes |
| Send a system notification | Post a macOS notification when a session finishes |
Clicking a completion notification reopens the session in the window it started from.
## Configure notifications
1. Open the Notifications page and review the permission notice.
2. If needed, allow Enconvo notifications in macOS.
3. Set the two completion controls independently.
4. Start a short Agent request and check the result when it finishes.
macOS Focus and notification settings can suppress banners even when Enconvo's setting is enabled.
## Scheduled results
A system notification is different from sending a scheduled result to Telegram or another IM chat. Configure result delivery in a [scheduled task](/workflows/scheduled-jobs)'s editor. A scheduled task can also post its own Mac notification when a run finishes (**Notify me when it runs**); that notification follows the **Send a system notification** setting too. Check the run history for both execution and delivery status.
# macOS Permissions
Source: https://docs.enconvo.ai/configuration/permissions
Grant the permissions required by the features you use.
Open **Settings → General → Permissions** in Enconvo to review feature access. macOS permission names can vary by system version; use **System Settings → Privacy & Security** for the system controls.
| Permission | Features that need it |
| - | - |
| Accessibility | Selected-text access, inserting text, and app interaction |
| Screen Recording / Screen & System Audio Recording | Screen context, OCR captures, Appshots, and screen/system-audio capture |
| Microphone | Dictation, voice notes, microphone recording, and Live Voice |
| Automation | Controlling apps through supported macOS integrations |
| Notifications | macOS banners for completed Agent sessions |
| Local Network | Connecting to model servers on another computer in your network |
## Enable a feature
1. Try the feature and read its permission explanation.
2. Open the corresponding macOS permission pane.
3. Enable access for the Enconvo app you use.
4. Follow macOS instructions to quit and reopen the app if requested.
5. Try a small example again.
You can grant permissions as needed. Text-only chat does not require every screen and microphone capability.
## Common problems
* **A permission is enabled but capture fails:** quit and reopen Enconvo, then retry. Make sure you enabled the running app rather than an older copy.
* **Dictation produces text but cannot insert it:** check Accessibility and that the target field accepts typing/paste.
* **A remote local model server fails:** check Local Network permission and whether the server listens on its LAN interface.
* **No completion banner:** check macOS notifications and Focus as well as Enconvo's notification setting.
Related: [Troubleshooting](/getting-started/troubleshooting), [Privacy and Security](/configuration/privacy-security).
# Privacy and Security
Source: https://docs.enconvo.ai/configuration/privacy-security
Understand which data stays local and which services process your requests.
Enconvo combines local storage, macOS capabilities, and optional online services. Where your data is processed depends on the feature, selected provider, enabled tools, and connected integrations.
## Where content is processed
| Action | Data involved |
| - | - |
| Cloud AI chat | Prompt, conversation context, and selected attachments sent for model processing |
| Cloud speech recognition | Captured audio sent to the selected speech service |
| Cloud text-to-speech | Text sent to the selected voice service |
| Cloud embeddings or reranking | Document/query content needed for retrieval |
| Web search or fetch | Search query or URL sent to the selected service or website |
| Local model inference | Model processing on the Mac after required resources are downloaded |
| Browser or computer tools | Content and actions available through that tool's granted access |
| IM channel | Messages exchanged with the connected messaging service and Agent |
Using a local chat model alone does not make every tool offline. A web search, remote MCP tool, cloud transcription provider, or cloud embedding model may still send content over the network.
## Control context
Review attachments and context sources before submitting a request. Appshots, screenshots, selected text, clipboard content, and browser pages can contain information beyond the sentence you intend to ask about.
Use [Context Awareness](/features/context-awareness) to choose sources. Grant [macOS permissions](/configuration/permissions) for the features you use and revoke access through System Settings when no longer needed.
## Credentials
API keys and account connections are managed through provider Authentication and [Credential Management](/configuration/credentials). Treat local Enconvo configuration, backups, exported settings, and support logs as sensitive. Do not include keys or account tokens in prompts, screenshots, or shared diagnostic files.
Provider profiles can share credentials across several capabilities. Review all consumers before deleting or replacing a profile. Revoke a compromised key through the provider itself; removing a local profile is not the same as revoking a server-side credential.
## Tools and integrations
An Agent can act through enabled tools. Browser control, computer use, shell execution, file edits, Gmail, and external MCP servers have different effects and access. Review the Agent's tools and the proposed action when working with important data.
Extension worker isolation is not a guarantee that an extension cannot access local files or networks. Install tools from sources you trust and review their configuration.
## Local AI clients
[Knowledge Base MCP](/advanced/knowledge-base-mcp) is opt-in and accepts local connections. Its visibility switches control which knowledge bases are exposed. A local client may send retrieved content to its own AI provider; configure that client too.
## Usage analytics and diagnostics
Enconvo records product usage events. The analytics identity is a device client identifier; analytics events are designed not to include email addresses, conversation text, or media payloads. Diagnostic logs are a separate surface and can include operational details needed to explain failures.
When sharing a report, inspect it first and remove private prompts, paths, keys, account information, and document contents that are not needed to diagnose the problem.
## Keep or remove local data
Use each feature's own history, knowledge-base, recording, and credential controls to manage its data. Read deletion confirmations and keep backups of anything you need. Removing the app does not necessarily remove its configuration and data, and removing local data does not delete copies already processed by an external service.
For provider retention and account policies, consult the provider you selected. This guide describes Enconvo's data flows; it does not replace those providers' policies.
# Settings Reference
Source: https://docs.enconvo.ai/configuration/settings-reference
Find every current settings section and its task guide.
Open Settings from the Enconvo menu. Use **Search settings** to find an entry by name. The sections below follow the current settings sidebar; each links to its task guide.
Provider lists, available models, saved shortcuts, and defaults can vary by installed build and your configuration. Read the value in your app before changing it.
## Global Providers Settings
| Entry | What to configure |
| - | - |
| [AI Model](/providers/overview) | Models, provider profiles, and authentication |
| [Text-to-Speech](/ai/text-to-speech) | Voice and audio output |
| [Web Search](/ai/web-search) | Search services |
| [Image Generation](/ai/image-generation) | Image services and models |
| [Video Generation](/ai/video-generation) | Video services and models |
| [Web Fetch](/ai/web-fetch) | URL readers |
| [OCR](/ai/ocr) | Text extraction |
## Agents
| Entry | What to configure |
| - | - |
| [Agent List](/ai/agents) | Create and configure Agents |
| [Avatar](/features/avatar) | Character gallery and Agent assignment |
| [Realtime Voice](/features/live-voice) | Voice access and automatic hang-up |
| [Voice Trigger](/features/dictation) | Spoken Agent requests |
| [IM Channels](/integrations/messaging) | Messaging connections |
| [Computer-Use](/features/computer-use) | App interaction |
| [Scheduled Tasks](/workflows/scheduled-jobs) | Scheduled Agents and scripts |
| [Notifications](/configuration/notifications) | Completion behavior |
| [Variables](/workflows/variables) | Reusable context values |
## Workflows
| Entry | What to configure |
| - | - |
| [Manage](/workflows/creating-workflows) | Build and edit workflows |
## Context
| Entry | What to configure |
| - | - |
| [Context Awareness](/features/context-awareness) | Context sources |
| [Screen Doodle](/features/screen-doodle) | Screen annotation |
| [Appshots](/features/appshots) | Capture an app window |
## Plugins
| Entry | What to configure |
| - | - |
| [Plugins](/extensions/overview) | Installed tools and command settings |
| [Skills](/configuration/skills) | Reusable Agent instructions |
| [MCP Servers](/features/mcp) | External tools for Agents |
## Primary Function Area
| Entry | What to configure |
| - | - |
| [SmartBar](/features/smartbar) | Layout, default Agent, and shortcuts |
| [Dynamic Island](/features/dynamic-island) | Top-screen assistant |
| [PopBar](/features/popbar) | Selected-text actions |
| [Chat Window](/ai/chat) | Conversation interface |
| [Pet](/features/pet) | Desktop Pet and session cards |
## App Sidebar
| Entry | What to configure |
| - | - |
| [App Sidebar](/features/app-sidebar) | Sidebar access |
| [Applications](/features/app-sidebar) | App destinations |
| [Websites](/features/app-sidebar) | Website destinations |
## Credential Management
| Entry | What to configure |
| - | - |
| [Credential Management](/configuration/credentials) | Shared provider credentials |
## Speech Assets
| Entry | What to configure |
| - | - |
| [Dictionary](/configuration/speech-assets) | Vocabulary |
| [Speakers](/configuration/speech-assets) | Speaker names |
## Dictation
| Entry | What to configure |
| - | - |
| [Dictation](/features/dictation) | Voice input behavior |
| [Dictation Models](/ai/speech-recognition) | Dictation provider |
| [Dictation History](/features/dictation) | Past dictated text |
## Recording
| Entry | What to configure |
| - | - |
| [Recordings](/features/meeting-recording) | Recorded sessions |
| [Recording Models](/ai/speech-recognition) | Recording recognition |
## Transcription
| Entry | What to configure |
| - | - |
| [Transcription](/features/transcription) | Imported media |
| [Transcription Models](/ai/speech-recognition) | File recognition |
## Captioning
| Entry | What to configure |
| - | - |
| [Live Captioning](/features/live-captioning) | Realtime subtitles |
| [Captioning Model](/ai/speech-recognition) | Captioning recognition |
## AI Commands
| Entry | What to configure |
| - | - |
| [AI Commands](/features/ai-commands) | Reusable prompts |
## Memory
| Entry | What to configure |
| - | - |
| [Memory](/ai/memory) | Agent memory |
| [KnowledgeBase](/ai/knowledge-base) | Documents and retrieval |
| [Voice Note](/features/voice-notes) | Save spoken notes |
| [Quick Capture](/features/quick-capture) | Save app content |
## Account
| Entry | What to configure |
| - | - |
| [My Profile](/configuration/account) | Personal response context |
| [Account](/configuration/account) | License and plan |
| [Points Usage](/configuration/account) | Cloud usage |
## General
| Entry | What to configure |
| - | - |
| [General](/configuration/settings-reference) | App behavior and updates |
| [Shortcut](/configuration/keyboard-shortcuts) | Hotkey list |
| [Permissions](/configuration/permissions) | macOS access |
| [About](/configuration/updates) | Installed version |
## Developer
| Entry | What to configure |
| - | - |
| [Developer Tools](/advanced/cli-local-api) | Runtime diagnostics |
| [Hooks](/configuration/hooks) | Lifecycle automation |
| [APIs](/advanced/cli-local-api) | Installed route schemas |
| [CLI Guide](/advanced/cli-local-api) | Command-line help |
## Reset a command or provider
Where offered, open **More → Reset configuration** in the command or provider settings. Read the confirmation before restoring defaults. A shared provider profile can affect multiple categories; see [Credentials](/configuration/credentials).
# Skills
Source: https://docs.enconvo.ai/configuration/skills
Extend EnConvo with task-specific AI capabilities using Agent Skills
## Overview
Use Agent Skills to extend EnConvo with task-specific capabilities. A skill packages instructions, resources, and optional scripts so EnConvo can follow a workflow reliably. You can share skills across teams or with the community.
Skills use **progressive disclosure** to manage context efficiently: EnConvo starts with each skill's metadata (name, description, file path). Full instructions are loaded only when a skill is activated.
## Skill Structure
A skill is a directory with a `SKILL.md` file plus optional scripts and references.
```
my-skill/
├── SKILL.md # Required: instructions + metadata
├── scripts/ # Optional: executable code
├── references/ # Optional: documentation
└── assets/ # Optional: templates, resources
```
### SKILL.md Format
The `SKILL.md` file must include a frontmatter block with `name` and `description`:
```markdown theme={null}
---
name: my-skill
description: Explain exactly when this skill should and should not trigger.
---
Step-by-step instructions for EnConvo to follow.
```
Because implicit matching depends on the `description` field, write descriptions with clear scope and boundaries. Be specific about **when** and **when not** to use the skill.
## How Skills Are Activated
EnConvo can activate skills in two ways:
Mention the skill directly in your prompt using the `/` prefix. Use this when you know exactly which skill you need.
EnConvo automatically selects a skill when your task matches its description. No manual selection needed.
### Explicit Invocation
Type `/` followed by the skill name in SmartBar or chat to invoke it directly:
```
/code-reviewer Review this function for security issues
/meeting-notes Format these raw notes into a structured summary
/api-checker Check the health of api.example.com
```
This is the most reliable way to invoke a skill -- you get exactly the one you want.
### Implicit Invocation
When you do not specify a skill, EnConvo automatically matches your request to the most relevant skill based on the `description` field:
1. You type: "Summarize these meeting notes into action items"
2. EnConvo scans all available skill descriptions
3. The `meeting-notes` skill matches ("...format raw meeting transcripts into structured notes with action items...")
4. The skill is activated and its instructions guide the response
### How to Write Descriptions That Match Well
Good implicit matching depends entirely on well-written `description` fields:
| Quality | Example |
| - | - |
| **Too vague** | "Helps with code" |
| **Too broad** | "Does anything related to programming" |
| **Good** | "Review code for bugs, security issues, and best practices. Use when the user asks for a code review or wants to improve code quality. Do not use for code generation or writing new code." |
The key elements:
* **What it does**: "Review code for bugs, security issues, and best practices"
* **When to trigger**: "Use when the user asks for a code review"
* **When NOT to trigger**: "Do not use for code generation or writing new code"
## Skill Locations
EnConvo reads skills from multiple locations, with different scopes:
| Scope | Location | Use Case |
| - | - | - |
| **Project** | `$PROJECT/.agents/skills/` | Skills specific to a project or workspace |
| **User** | `~/.agents/skills/` | Personal skills that apply across all projects |
| **System** | Bundled with EnConvo | Built-in skills available to everyone |
If two skills share the same name in different locations, both remain available -- EnConvo does not merge them.
### Project Skills
Project-scoped skills are stored inside your project directory. They are available only when that project is active:
```
my-project/
├── .agents/
│ └── skills/
│ ├── deploy-checklist/
│ │ └── SKILL.md
│ └── pr-template/
│ └── SKILL.md
├── src/
└── package.json
```
This is ideal for skills that depend on project-specific conventions, file structures, or tools.
### User Skills
User-scoped skills in `~/.agents/skills/` are available across all projects. Use this for personal productivity skills that are not project-specific:
```
~/.agents/skills/
├── email-composer/
│ └── SKILL.md
├── meeting-notes/
│ └── SKILL.md
└── code-reviewer/
└── SKILL.md
```
## Creating a Skill
### Using the Skill Creator
The fastest way to create a skill is with the built-in creator:
```
/skill-creator
```
The creator walks you through:
1. What the skill does
2. When it should trigger
3. Whether it should be instruction-only or include scripts
**Instruction-only** is the default and recommended approach. Use scripts only when you need deterministic behavior or external tooling.
### Manual Creation
Create a folder with a `SKILL.md` file:
```bash theme={null}
mkdir -p ~/.agents/skills/my-skill
```
```bash theme={null}
cat > ~/.agents/skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: Summarize selected text into bullet points. Use when the user asks for a summary or key takeaways. Do not use for translation or rewriting tasks.
---
## Instructions
1. Read the selected text from the user's input.
2. Identify the 3-5 most important points.
3. Return a bullet-point summary.
4. Keep each bullet under 20 words.
EOF
```
EnConvo detects skill changes automatically. If the new skill doesn't appear, restart EnConvo.
### Writing Effective Instructions
The body of `SKILL.md` (below the frontmatter) contains the instructions the AI follows. Write them as clear, imperative steps:
```markdown theme={null}
---
name: changelog-generator
description: Generate a changelog from git commits. Use when the user asks to create a changelog, release notes, or commit summary. Do not use for general git operations.
---
## Instructions
1. Read the git log for the specified date range or number of commits.
2. Group commits by category:
- **Features**: New functionality (commits starting with "feat:")
- **Fixes**: Bug fixes (commits starting with "fix:")
- **Breaking Changes**: Changes that break backward compatibility
- **Other**: Everything else
3. For each commit, write a user-facing description (not the raw commit message).
4. Format as markdown with version header, date, and categorized bullet points.
5. Highlight breaking changes with a warning callout.
## Output Format
```
## v1.2.0 (2024-01-15)
### Features
* Added dark mode support for all pages
* New export to PDF option in reports
### Fixes
* Fixed login timeout on slow connections
* Resolved duplicate notification issue
### Breaking Changes
⚠️ API endpoint `/v1/users` now requires authentication
```
```
State exactly where the input comes from: "Read the selected text", "Parse the attached file", "Use the URL from the user's message".
Include a concrete example of what the output should look like. This prevents ambiguity and ensures consistency.
Add instructions for common edge cases: "If no commits are found, report that the range is empty" or "If the input is not valid JSON, ask the user to check the format".
One skill should do one thing well. If you find yourself writing a skill with 10+ steps covering multiple tasks, split it into separate skills.
## Adding Scripts
For skills that need executable logic, add a `scripts/` directory:
```
my-skill/
├── SKILL.md
└── scripts/
└── fetch_data.sh
```
Reference scripts in your `SKILL.md`:
````markdown theme={null}
---
name: api-checker
description: Check API endpoint health and response times.
---
## Instructions
1. Run the health check script:
```bash
bash scripts/fetch_data.sh $URL
````
2. Parse the JSON output.
3. Report status, response time, and any errors.
```
### When to Use Scripts
| Use Scripts When | Use Instructions Only When |
|-----------------|---------------------------|
| You need deterministic output (exact formats, calculations) | The task is primarily about reasoning and language |
| You interact with external APIs or databases | The task uses only the AI's built-in capabilities |
| You need to process or transform data programmatically | The task is about writing, summarizing, or analyzing |
| You require authentication or credential handling | The instructions alone are sufficient |
## Adding References
Include documentation or context files that the skill can consult:
```
my-skill/
├── SKILL.md
├── references/
│ ├── api-docs.md
│ └── examples.md
└── scripts/
└── run.sh
````
Reference them in instructions:
```markdown
Consult `references/api-docs.md` for the API schema before making requests.
````
References are useful for:
* API documentation the skill needs to follow
* Style guides or brand guidelines
* Code examples and templates
* Domain-specific knowledge
## Installing Skills
EnConvo supports two methods to install skills using `/skill-installer`:
### From EnConvo Skills Store
Search and install skills by name from the built-in skills store:
```
/skill-installer pdf
```
This searches the EnConvo skills store and installs the matching skill. EnConvo detects newly installed skills automatically.
### From GitHub
Install skills directly from a GitHub repository URL -- including subdirectories:
```
/skill-installer https://github.com/anthropics/skills/tree/main/skills/pptx
```
GitHub installation supports **subdirectory paths**, so you can point to a specific skill folder within a larger repository. No need to clone the entire repo.
### Browsing the Skills Store
The Skills Store provides a curated collection of community-built skills:
1. Open **Settings**
2. Navigate to **Skills Store**
3. Browse categories or search by keyword
4. Click **Install** on any skill
5. The skill is downloaded and ready to use immediately
Popular skill categories:
* **Development**: Code review, documentation generation, testing
* **Writing**: Email composition, blog posts, technical writing
* **Data**: Analysis, visualization, reporting
* **Productivity**: Meeting notes, task management, scheduling
## Managing Skills
### Viewing Installed Skills
See all your installed skills in **Settings** -> **Skills**:
* System skills (built-in)
* User skills (from `~/.agents/skills/`)
* Project skills (from current project)
* Store-installed skills
### Updating Skills
* **Store skills**: Check for updates in the Skills Store
* **GitHub skills**: Re-run the installer with the same URL
* **Custom skills**: Edit the `SKILL.md` file directly -- changes are detected automatically
### Disabling Skills
You can disable a skill without deleting it:
1. Go to **Settings** -> **Skills**
2. Find the skill
3. Toggle it off
Disabled skills will not be available for implicit or explicit invocation until re-enabled.
## Best Practices
One skill = one job. A skill that does too many things is harder to trigger correctly and harder to maintain.
Use plain-language instructions unless you need deterministic behavior or external tooling. Instructions are easier to write, debug, and iterate on.
Be explicit about inputs, steps, and expected outputs. Vague instructions lead to inconsistent results.
Try various prompts against your skill's `description` field to confirm it triggers (and doesn't trigger) correctly.
In the description, state both what the skill **should** handle and what it **should not** handle.
For team-shared skills, keep them in version control (git). This makes it easy to track changes, roll back, and collaborate.
## Example Skills
### Code Reviewer
```markdown theme={null}
---
name: code-reviewer
description: Review code for bugs, security issues, and best practices. Use when the user asks for a code review or wants to improve code quality. Do not use for code generation or writing new code.
---
## Instructions
1. Read the provided code carefully.
2. Check for:
- Logic errors and edge cases
- Security vulnerabilities (injection, XSS, etc.)
- Performance issues
- Code style and readability
3. Provide feedback as a numbered list.
4. For each issue, include:
- Severity (Critical / Warning / Suggestion)
- Line reference
- Explanation and fix
```
### Meeting Notes
```markdown theme={null}
---
name: meeting-notes
description: Format raw meeting transcripts into structured notes with action items. Use when the user provides meeting notes, transcripts, or asks to organize meeting content. Do not use for scheduling or calendar tasks.
---
## Instructions
1. Parse the meeting transcript or raw notes.
2. Extract and organize into sections:
- **Attendees**: List all participants
- **Key Decisions**: Bullet-point decisions made
- **Discussion Summary**: 3-5 sentence overview
- **Action Items**: Table with Owner, Task, Deadline
3. Use markdown formatting for readability.
```
### Git Commit Message
```markdown theme={null}
---
name: commit-message
description: Generate conventional commit messages from staged changes. Use when the user asks for a commit message or wants to commit changes. Do not use for general git operations like branching or merging.
---
## Instructions
1. Read the staged diff (use `git diff --staged`).
2. Identify the type of change:
- feat: New feature
- fix: Bug fix
- docs: Documentation
- refactor: Code restructuring
- test: Adding tests
- chore: Maintenance
3. Write a commit message following Conventional Commits format:
```
type(scope): concise description
* Detail 1
* Detail 2
```
4. Keep the subject line under 72 characters.
5. Include a body only if the change needs explanation.
```
### API Documentation Generator
````markdown theme={null}
---
name: api-docs
description: Generate API documentation from source code. Use when the user asks to document an API, endpoint, or function. Do not use for general code documentation or README files.
---
## Instructions
1. Read the source code file(s) provided.
2. For each endpoint or public function, document:
- **Method & Path** (for HTTP) or **Signature** (for functions)
- **Description**: What it does in one sentence
- **Parameters**: Name, type, required/optional, description
- **Response**: Structure and example
- **Errors**: Possible error codes and meanings
3. Format as markdown with code examples.
4. Include a curl example for each HTTP endpoint.
## Output Format
### `POST /api/users`
Create a new user account.
**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| email | string | Yes | User's email address |
| name | string | Yes | Display name |
**Response (201):**
```json
{ "id": "usr_123", "email": "user@example.com", "name": "John" }
````
```
## Resources
Browse open-source extensions and skills
Share skills and get help from the community
Browse and install community skills
Combine skills with MCP tools
```
# Dictionary and Speakers
Source: https://docs.enconvo.ai/configuration/speech-assets
Maintain recognition vocabulary and speaker names.
Open **Settings → Speech Assets** to manage vocabulary and speakers used by speech features.
## Dictionary
Add product names, technical terms, acronyms, or unusual spellings to **Dictionary**. Each entry contains a word and an optional description.
1. Open **Dictionary** and add an entry.
2. Enter the preferred spelling and a short explanation if useful.
3. Save it and try a short recording containing the word.
4. Review the transcription; provider support and audio quality still affect recognition.
For batch entry, use one term per line. Separate its description with `|`:
```text theme={null}
Enconvo | AI assistant for macOS
Project Atlas | Internal project name
PostgreSQL
```
Use search and edit controls to maintain the list. Batch deletion requires selecting the intended entries and confirming the action.
## Speakers
**Speakers** manages known speaker names for recordings and transcripts. Review speaker assignments within a recording before renaming a speaker. A recognized voice or diarization label can be wrong, especially with overlapping speech.
## Choose where to use them
[Dictation](/features/dictation), [Meeting Recording](/features/meeting-recording), [Transcription](/features/transcription), and [Live Captioning](/features/live-captioning) use different speech configurations. Check the provider settings for language hints, hot words, diarization, and other supported options rather than assuming all providers apply the same vocabulary behavior.
## Watch the steps
Enter a term and description, switch to Batch add, and enter three example lines. The draft is discarded; no dictionary entry is saved. This silent walkthrough uses real interface captures with pauses added for reading. The written steps above provide the same instructions.
# Updates
Source: https://docs.enconvo.ai/configuration/updates
Choose Production, Beta, or Dev updates and install new EnConvo versions
## Overview
EnConvo can check for new app versions in the background and show an **Update**
button when a newer build is available for your selected channel.
## Update Channels
| Channel | Best for | What you receive |
| - | - | - |
| **Production** | Most users | Stable releases after beta testing |
| **Beta** | Early testers | New builds before they are promoted to Production |
| **Dev** | Development testing | More frequent development builds, separate from Beta |
Use **Production** unless you want to test new features early. Use **Beta** if
you are helping validate a release or need a fix before the stable release is
published.
## Change Your Update Channel
Open EnConvo Settings from the app menu or press `Cmd + ,`.
Open **General** in the Settings sidebar.
Scroll to the **Updates** section.
Set **Update Channel** to **Production**, **Beta**, or **Dev**.
A fresh Dev installation defaults to Dev. Existing saved channel choices are preserved. Switching channels does not necessarily downgrade an already installed newer build.
## Where The Update Button Appears
When EnConvo detects a new version for your selected channel, an **Update**
button can appear in:
* **Chat Window** titlebar
* **SmartBar** titlebar
Click **Update** to open the update flow. EnConvo will then show the available
version and guide you through downloading, installing, and relaunching when
needed.
## When EnConvo Checks For Updates
EnConvo checks for updates when you open or show the surfaces where the update
button can appear:
* Chat Window
* SmartBar
To avoid repeated network requests, EnConvo does not repeat the same background
check more than once within 10 minutes.
Automatic update downloads are off by default. EnConvo can detect that an
update exists and show the button before downloading the update.
## Check Manually
Use the macOS menu bar item when you want to check immediately:
1. Click the EnConvo menu bar icon.
2. Choose **Check for Updates**.
3. If a newer version is available for your current channel, follow the update
prompt.
If no window appears, you may already be on the latest version for your selected
channel.
## Troubleshooting
Confirm **Settings → General → Updates → Update Channel** is set to
**Beta**. Then open Chat Window or SmartBar again. EnConvo throttles
background checks for 10 minutes, so wait a few minutes if you just checked.
Production only shows builds published to the stable channel. If the newest
build is still beta-only, you will not see it until it is promoted to
Production.
The update may already have been installed, dismissed, or no longer match
your selected channel. Run **Check for Updates** from the menu bar to
confirm.
Quit and reopen EnConvo, then run **Check for Updates** again. Also make
sure your network can reach EnConvo's release server.
## Related
See all app settings in one place.
Read what changed in each release.
# Built-in Command Catalog
Source: https://docs.enconvo.ai/extensions/built-in-extensions
Find built-in commands and the guides for their behavior.
Built-in capabilities are grouped below by the task they support. Availability depends on installed extensions and the app build. Provider implementations are listed separately in the [Provider Capability Catalog](/providers/catalog).
Use SmartBar to find a command by title. Open **Settings → Plugins** to review installed extensions and their command settings. Agent tools may be selected in Agent settings rather than appearing as standalone launcher commands.
## Agent
[Open the guide](/ai/agents).
| Command | Purpose |
| - | - |
| Mavis | Your personal AI assistant for macOS — automate tasks, control apps, browse the web, manage files, and handle everything on your Mac |
| Latin Teacher | Your personal Latin tutor that helps with translations, grammar analysis, and verb conjugations. Perfect for both beginners and advanced learners seeking to master Latin. |
| Spanish Teacher | A comprehensive Spanish language tutor that provides translations, grammar explanations, verb conjugations, and detailed linguistic analysis to help you master Spanish effectively. |
| Create Agent | Opens the Agent creation page where you can manually configure name, avatar, character, tools, and other settings for a new agent |
## AI Command
[Open the guide](/features/ai-commands).
| Command | Purpose |
| - | - |
| Create AI Command | Opens the AI Command creation page where you can manually configure title, prompt, model, and other settings for a new AI command |
## Computer Use
[Open the guide](/features/computer-use).
| Command | Purpose |
| - | - |
| Quick Type | Type text into the focused app from the latest clipboard content or cycle through a configurable list of text segments. Assign a hotkey to run it without opening a window. |
## Credentials
[Open the guide](/configuration/credentials).
| Command | Purpose |
| - | - |
| Enconvo Cloud | Use Enconvo Cloud Plan Service. |
| OpenAI | OpenAI API key credentials for language models, realtime voice, speech, images, and embeddings. |
| OpenAI OAuth | Sign in with your ChatGPT account for OpenAI language models. Use the OpenAI credential for API keys and audio services. |
| OpenClaw | OpenClaw OpenAI-compatible gateway credentials. Enable once with `openclaw config set gateway.http.endpoints.chatCompletions.enabled true`, set LAN access with \`openclaw config set gateway.bind… |
| Hermes Agent | Hermes Agent OpenAI-compatible API server credentials. Enable by adding `API_SERVER_ENABLED=true` and `API_SERVER_KEY=token` to `~/.hermes/.env`, then run `hermes gateway`. The base URL is… |
| Anthropic | Anthropic API key credentials |
| Anthropic OAuth | Anthropic OAuth account credentials |
| Vercel AI Gateway | Chat with Vercel AI Gateway, learn more : vercel ai gateway |
| Qwen | Qwen API key credentials |
| Qwen OAuth | Qwen OAuth account credentials |
| Gemini AI | Gemini AI API key credentials |
| Gemini AI OAuth | Gemini AI OAuth account credentials |
| Gmail (Enconvo Cloud) | Gmail Provider that allows you to use Enconvo Cloud's Gmail API |
| Gmail | Gmail Provider that allows you to use your Google client\_id and client\_secret |
| Deep Seek | Chat with DeepSeek , learn more : DeepSeek developers |
| Groq AI | Chat with Groq ai, learn more : groq.com/ |
| Poe | Chat with Poe, learn more : poe.com/ |
| Z.AI | Chat with Z.AI, learn more : z.ai |
| Xiaomi MiMo | Chat with Xiaomi MiMo, learn more : xiaomimimo |
| Kie.ai | Use Kie.ai Market image and video generation APIs. |
| Topview | Use Topview AI avatar, image, and video generation APIs. |
| X.AI-GROK | X.AI-GROK API key credentials |
| X.AI-GROK OAuth | X.AI-GROK OAuth account credentials |
| Mistral AI | Chat with Mistral AI, learn more : mistral.ai |
| OpenRouter | Chat with OpenRouter, learn more: openrouter.ai |
| Firecrawl | Firecrawl Provider that allows you to use Firecrawl's online search service |
| Together AI | Chat with together.ai, learn more : together.ai, get chat models from together models |
| Tavily AI | Tavily Search Provider that allows you to search for information on the web, learn more : Tavily |
| Bing Search | Bing Search Provider that allows you to search for information on the web, learn more : Bing Web Search API |
| Brave Search | Brave Search Provider that allows you to search for information on the web, learn more : Brave Search API |
| Google Cloud Search | Google Cloud Search Provider that allows you to search for information on the web, learn more : Google Cloud Search API |
| Cloudflare Workers AI | Chat with Cloudflare Workers AI, learn more : workers-ai |
| Azure OpenAI | Azure OpenAI , learn more : azure openai |
| Ollama | Chat with Ollama, learn more : ollama.ai |
| AIMagicX | Chat with AIMagicX, learn more : aimagicx.com |
| 1min AI | Chat with 1min AI, learn more : 1min.ai |
| Microsoft Speech | Microsoft TTS Provider that allows you to use Microsoft Azure's online text-to-speech service |
| Eleven Labs | Eleven Labs Provider that allows you to use Eleven Labs's online text-to-speech service |
| Speechify | Speechify Provider that allows you to use Speechify's online text-to-speech service |
| MiniMax | MiniMax credentials provider, learn more: MiniMax \| API Reference |
| Assembly AI | Assembly AI Speech-to-Text Provider that allows you to use Assembly AI's online Speech-to-Text service |
| Deepgram | Deepgram Speech-to-Text Provider that allows you to use Deepgram's online Speech-to-Text service |
| Soniox | Soniox Speech-to-Text Provider that allows you to use Soniox's online Speech-to-Text service |
| Volcengine (ByteDance) | Volcengine Speech-to-Text credentials provider for ByteDance BigASR (Doubao). Get your App ID and Access Token from Volcengine Console. |
| Fireworks | Chat with Fireworks, learn more : fireworks.ai, get all models from fireworks models |
| Exa Search | Use Exa to get real time information, go to Exa to get your api key. |
| Smithery | Use Smithery to manage MCP servers, go to Smithery to get your api key. |
| Jina AI | Use Jina AI to get real time information, go to Jina AI to get your api key. |
| Voyage | Use Voyage to get real time information, go to Voyage to get your api key. |
| Cohere AI | Chat using Cohere, get API KEY |
| Perplexity | Chat with Perplexity, learn more: perplexity.ai |
| Replicate | Replicate, learn more: replicate.com |
| SiliconFlow | Chat with SiliconFlow , learn more : SiliconFlow developers |
| LM Studio | Chat with LM Studio, learn more : lmstudio.ai |
| kimi.ai | Chat with kimi.ai, learn more : kimi.ai |
| Kimi Code | Kimi for Coding credentials provider, learn more: Kimi Code |
| DashScope | Chat with 阿里云百炼 , learn more : 阿里云百炼 |
| Sambanova AI | Chat with sambanova.ai, learn more : sambanova.ai |
| DeepInfra | Chat with DeepInfra. Learn more: DeepInfra documentation |
| Phala | Chat with Phala. Learn more: Phala documentation |
| Cerebras AI | Chat with cerebras.ai, learn more : cerebras.ai |
| Arli AI | Chat with arli.ai, learn more : arliai.com |
## Enconvo
[Open the guide](/quickstart).
| Command | Purpose |
| - | - |
| Ask AI | Ask AI |
| Ask Sidebar | Ask Sidebar |
## File System
[Open the guide](/ai/file-tools).
| Command | Purpose |
| - | - |
| write file | Create a new file or completely overwrite an existing file with new content. Use with caution as it will overwrite existing files without warning. Handles text content with proper encoding. Only… |
| read File | Read a file from the file system. Supports text files (txt, js, ts, json, md, etc.) by reading content directly, document files (pdf, epub, docx, xlsx, pptx, etc.) by extracting readable text,… |
| edit File | Make line-based edits to a text file. Each edit replaces exact line sequences with new content. Returns a git-style diff showing the changes made. Only works within allowed directories. |
| Grep | Fast content search tool that works with any codebase size |
| Glob | Fast file pattern matching tool that works with any codebase size |
## Gmail
[Open the guide](/integrations/gmail).
| Command | Purpose |
| - | - |
| Gmail Send Email | Sends a new email |
| Gmail Draft Email | Draft a new email |
| Gmail Read Email | Retrieves the content of a specific email |
| Gmail Search Emails | Searches for emails using Gmail search syntax |
| Gmail Modify Email | Modifies email labels (move to different folders) |
| Gmail Delete Email | Permanently deletes an email |
| Gmail List Email Labels | Retrieves all available Gmail labels |
| Gmail Batch Modify Emails | Modifies labels for multiple emails in batches |
| Gmail Batch Delete Emails | Permanently deletes multiple emails in batches |
| Gmail Create Label | Creates a new Gmail label |
| Gmail Update Label | Updates an existing Gmail label |
| Gmail Delete Label | Deletes a Gmail label |
| Gmail Get or Create Label | Gets an existing label by name or creates it if it doesn't exist |
## Image Utils
[Open the guide](/features/media-tools).
| Command | Purpose |
| - | - |
| Image Compress | Compress images with adjustable quality using the Caesium engine. Supports batch compression, overwrite or output to a custom folder. |
## Knowledge Base
[Open the guide](/ai/knowledge-base).
| Command | Purpose |
| - | - |
| Create Knowledge Base | Opens the Knowledge Base creation page where you can manually configure name, data sources, and provider settings for a new knowledge base |
## Media Utils
[Open the guide](/features/media-tools).
| Command | Purpose |
| - | - |
| Video Compress | Compress video files. |
| Extract Audio | Extract audio from video files. |
| Audio Compress | Compress audio files. |
| Online Video Downloader - Youtube, Tiktok, Instagram, Reddit, Twitter, Vimeo, etc. | Download the video or audio from url, support youtube, tiktok, instagram, reddit, twitter,vimeo, etc. |
## OCR
[Open the guide](/ai/ocr).
| Command | Purpose |
| - | - |
| OCR | Convert image to text |
| Silent Screenshot OCR | Select the screen area for OCR and copy the OCR results to the clipboard. |
| Screenshot OCR | Select the screen area for OCR and show the OCR results in a smartbar window. |
## Quick Links
[Open the guide](/features/quick-links).
| Command | Purpose |
| - | - |
| Quick Link | Open a quick link in the default browser |
| Google Search in Browser | Open a Google search with a query in browser |
| YouTube Search in Browser | Open a YouTube search with a query in browser |
| Twitter/X Search in Browser | Open a Twitter/X search with a query in browser |
## Transcribe
[Open the guide](/features/transcription).
| Command | Purpose |
| - | - |
| Transcribe | Transcribe audio and video files to text with structured JSON output, word/segment timestamps, and speaker diarization |
## Translate
[Open the guide](/ai/translate).
| Command | Purpose |
| - | - |
| Translator | translate text or word |
| Screenshot Translate | Select the screen area for OCR and translate the OCR results |
## TTS
[Open the guide](/ai/text-to-speech).
| Command | Purpose |
| - | - |
| Read Aloud | User-facing read-aloud command. Opens the floating read-aloud bar panel and hands off playback to the native TTS player. The panel exposes pause/resume/stop controls plus a live waveform, so the… |
| TTS(Text To Speech) | Convert text to audio file using TTS providers |
## Variables
[Open the guide](/workflows/variables).
| Command | Purpose |
| - | - |
| Input Text | The user input text in Smart Bar |
| Active Application | Get information about the currently active application |
| Active Application Screenshot | Capture a screenshot of the currently active application window |
| Active Screen Screenshot | Capture a screenshot of the active screen |
| Focused Window Content | Get the content from the currently focused window |
| Latest Clipboard | Get the most recent content from the system clipboard |
| Selection Text | Get the currently selected text from any application |
| History Messages | Get the history messages from the current chat |
| Finder Current Directory | Get the current directory path from Finder |
| Finder Selected Files | Get the list of files currently selected in Finder |
| Browser Active Tab | Get the URL and webpage content from the currently active browser tab |
| Now | Get the current date and time |
| Opened Applications | Get all currently opened applications on macOS |
| Opened Application Names | Get the names of all currently opened applications on macOS |
## Video Create
[Open the guide](/ai/video-generation).
| Command | Purpose |
| - | - |
| Text to Video | An text to video generator , can generate videos based on text descriptions. |
| Image to Video | An image to video generator , can generate videos based on images. |
## Writing Toolkit
[Open the guide](/features/writing-tools).
| Command | Purpose |
| - | - |
| Emoji | Give An Emoji Suggestion for given text |
| Explain | Explain the text |
| Screenshot Explain | Explain the selected area |
| Summarize | Summarize the text |
| Fix Spelling & Grammar | Fix Spelling and Grammar |
| Polish Email | Polish an email draft — fix grammar, make the tone native and friendly, and append the signature |
| AI Edit | AI Edit |
| Improve Writing | Improve Writing |
| Polish | Improve Writing |
| Make Longer | expand the text to make it longer |
| Make Shorter | Make Shorter |
| Change Tone Friendly | Change Tone to Friendly |
| Change Tone Confident | Change Tone to Confident |
| Change Tone Casual | Change Tone to Casual |
| Proofread | Proofread the text |
| Rewrite | Rewrite the text |
| Change Tone Professional | Change Tone to Professional |
| Make Concise | Make the text more concise |
| Extract Key Points | Extract key points from the text |
| Convert to List | Convert the text to a list format |
| Convert to Table | Convert the text to a table format |
| Dictation Polish | Clean up voice input text by removing filler words and fixing typos |
| Dictation Translate | Translate voice input text into the target language |
## Native app commands
| Command family | Guide |
| - | - |
| Show SmartBar, Chat Window, App Sidebar, PopBar, Dynamic Island, Pet, and Knowledge Base | [Feature Directory](/reference/feature-directory) |
| Voice Dictation and Voice Command | [Dictation and Voice Trigger](/features/dictation) |
| Start to Record (Meeting/Lecture) | [Meeting Recording](/features/meeting-recording) |
| Start Live Captioning | [Live Captioning](/features/live-captioning) |
| Screen captures and Screen Doodle | [OCR](/ai/ocr), [Screen Doodle](/features/screen-doodle) |
| App, browser, Finder, clipboard, selected-text, and screenshot context | [Context Awareness](/features/context-awareness) |
| Clear conversation, new chat, pin window, and settings | [Chat](/ai/chat), [Window Management](/features/window-management) |
## Supporting services
Some extensions provide infrastructure rather than a command you launch directly: local APIs, configuration, credential routing, document parsing, model runtimes, message storage, search indexing, plugin management, and channel delivery. Use the task guide for the feature they support, or [CLI and Local APIs](/advanced/cli-local-api) for integration work.
The Mobile Companion connects the Enconvo iPhone app (beta) to your Mac; see [iPhone App](/integrations/iphone-app) to pair a phone. For access through messaging apps, use [IM Channels](/integrations/messaging).
# Developing Extensions
Source: https://docs.enconvo.ai/extensions/developing
Create a TypeScript command or Local API route with the Enconvo SDK.
An Enconvo plugin is an ESM package with metadata in `package.json`, commands under `src/`, and optional API routes under `src/api/`. Commands run through Enconvo's extension runtime; a plugin command is a default-exported function, not a class implementing a `Command` interface.
You need Node.js 18 or later, npm or another package manager, and Enconvo running on your Mac.
## Quick start
Create a plugin project in a new folder:
```sh theme={null}
npx -p @enconvo/api enconvo plugin create hello-enconvo
cd hello-enconvo
npm install
npm run dev
```
The project has one command (**Say Hello**), one Local API route, a placeholder icon, and a README. `npm run dev` builds the plugin into Enconvo and rebuilds it whenever you save. Search Enconvo for **Say Hello** to run it.
The plugin name comes from the folder name. Pass `--name`, `--title`, `--description` or `--author` to set them yourself. Pick a name that no plugin installed in Enconvo already uses, because building replaces the installed plugin's files; `plugin create` refuses such names.
To make a plugin that also installs in Codex and Claude Code, start from `--template skills` (a skill) or `--template mcp` (an MCP server) instead. See [Plugin Formats](/extensions/plugin-formats) for those packages, and [Installing Plugins](/extensions/installing-plugins) to try any plugin from a folder, GitHub or a marketplace.
`plugin create`, `plugin validate` and publishing for review need an `@enconvo/api` release newer than 0.1.173. If your version doesn't have them, set the project up by hand as described below.
## Set up a project by hand
```text theme={null}
hello-enconvo/
├── package.json
├── tsconfig.json
├── src/
│ ├── hello.ts
│ └── api/
│ └── echo.ts
└── assets/
└── icon.png
```
Create `package.json`:
```json theme={null}
{
"$schema": "https://enconvo.com/schemas/extension.json",
"name": "hello_enconvo",
"version": "0.1.0",
"title": "Hello Enconvo",
"description": "A small example command and API.",
"author": "Your Name",
"icon": "icon.png",
"type": "module",
"categories": ["Productivity"],
"commands": [
{
"name": "hello",
"title": "Say Hello",
"description": "Return a greeting for the input text.",
"commandType": "command",
"mode": "no-view"
}
],
"scripts": {
"build": "enconvo plugin build",
"dev": "enconvo plugin build --dev",
"validate": "enconvo plugin validate"
}
}
```
The first entry in `categories` picks the section the plugin appears in on the Plugins page and in the store: Productivity, Communication, Developer Tools, Data & Analytics, Finance, Creativity, Business & Operations, Education & Research or Security.
Install the SDK, and the build tools as development dependencies:
```sh theme={null}
npm install @enconvo/api
npm install --save-dev tsup typescript @types/node
```
`enconvo plugin build` compiles your code with the plugin's own `tsup`. Without it, the build has nothing to compile with; newer SDKs stop with an error, and older ones finish without building your commands.
Create `tsconfig.json`:
```json theme={null}
{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"moduleResolution": "Bundler",
"lib": ["ES2023", "DOM"],
"types": ["node"],
"strict": true,
"skipLibCheck": true,
"noEmit": true
},
"include": ["src"]
}
```
Put a square PNG, JPEG, WebP or GIF icon of up to 5 MB at `assets/icon.png`.
## Add a command
`commands[].name` matches the source filename. Put this in `src/hello.ts`:
```typescript theme={null}
import { EnconvoResponse, type RequestOptions } from "@enconvo/api";
export default async function main(request: Request) {
const options = await request.json() as RequestOptions;
const name = String(options.input_text || "").trim() || "World";
return EnconvoResponse.text(`Hello, ${name}!`);
}
```
The command key is `hello_enconvo|hello`. Runtime preferences and request parameters are merged into the request body.
## Add a Local API route
Files in `src/api/` are discovered during the build and need no `commands[]` entry. Put this in `src/api/echo.ts`:
```typescript theme={null}
interface EchoParams {
/** Text to return. @required */
text: string;
}
/** Return the supplied text. */
export default async function main(request: Request) {
const params = await request.json() as EchoParams;
if (typeof params.text !== "string") {
return Response.json({ error: "text must be a string" }, { status: 400 });
}
return Response.json({ text: params.text });
}
```
This becomes `hello_enconvo/echo`. A directory such as `src/api/items/list.ts` becomes `hello_enconvo/items/list`. Use the installed [Local API schemas](/advanced/cli-local-api) for exact request shapes.
## Build and test
```sh theme={null}
npm run build
npm run dev
npx enconvo plugin generate-schema
```
Build from the plugin directory. A good build ends with `ready - built extension successfully`. If it prints an `error` line, fix what it names and build again. Development mode watches files for rebuilds. API schemas are generated into the plugin's `skills/` directory.
Call the route while Enconvo is running:
```sh theme={null}
curl -X POST http://localhost:54535/api/hello_enconvo/echo \
-H "Content-Type: application/json" -d '{"text":"hi"}'
```
Test a greeting and invalid API input before sharing the plugin. A successful build alone does not test native operations or every provider call.
## Publish to the plugin store
```sh theme={null}
npm run validate
npx enconvo plugin publish
```
`plugin validate` checks the plugin against the store rules without uploading anything; [Validation Codes](/extensions/validation-codes) explains each problem it reports. After a build, it also shows how many files the package will contain and which files are left out. It checks that the name uses only letters, digits, dots, dashes and underscores, that `version` looks like `1.2.3`, that the plugin has a title, and that the icon is a PNG, JPEG, WebP or GIF of up to 5 MB. You can add up to 8 screenshots in a `metadata/` folder; the plugin's page in the store shows them under its description, in file name order.
`plugin publish` builds the plugin and uploads it with the Enconvo account you're signed in with, so Enconvo has to be running and signed in. Enconvo reviews every version before it appears in the store. Until a new plugin is approved, only you can see it; while an update is in review, the store keeps offering the previous version. Raise `version` in `package.json` for every update. Before it builds anything, `plugin publish` asks the store which version it released, and stops with the next version to use when yours isn't higher. A version that is in review, or was turned down, can be submitted again as it is; the new upload replaces it.
The package is made from the built plugin. `.env` files, `node_modules`, version-control folders and `.zip` archives are left out, but check that no other credentials or private files end up in it.
Reviewers follow the [Plugin Store Guidelines](/extensions/publishing-guidelines). Add a `review` object to `package.json` with the prompts they should try, and pass sign-in details for a demo account with `--review-notes`; only reviewers see them.
To add your own AI model or text-to-speech voice to Enconvo's pickers, see [AI Model and Voice Plugins](/extensions/provider-plugins). For SDK building blocks, see [Extension API Reference](/extensions/extension-api-reference). For reusable multi-step processes that do not need a plugin, use [Workflows](/workflows/introduction).
# Extension API Reference
Source: https://docs.enconvo.ai/extensions/extension-api-reference
SDK patterns and API entry points for developing Enconvo extensions
## Overview
The `@enconvo/api` SDK provides the full API surface for building EnConvo extensions. Extensions run as isolated Worker threads communicating with the native macOS app over a Unix Domain Socket using JSON-RPC.
All imports in this reference come from `@enconvo/api` unless otherwise noted. The SDK is linked locally from `enconvo.nodejs/enconvo_api/` during development.
## Commander API
The `Commander` namespace handles all communication between extension Worker threads and the EnConvo host process.
### Commander.addClickListener
Registers the main entry point handler for a command. The build/runtime adapter uses this registration mechanism. For ordinary plugin command files, use the default-exported handler shown in [Developing Extensions](/extensions/developing), rather than registering the same handler twice.
```typescript theme={null}
import { Commander, EnconvoResponse } from "@enconvo/api";
Commander.addClickListener(async (req: Request) => {
const options = await req.json();
// Process the request
return EnconvoResponse.text("Hello from my extension!");
});
```
The `req` parameter is a standard `Request` object. Use `req.json()` to access the merged command configuration and user-provided parameters.
### Commander.send
Send a request to the native macOS app. Returns a Promise for the matching response. Use `sendAsync` only when the operation does not need a result.
```typescript theme={null}
// Send a custom method with payloads
await Commander.send("responseStream", {
type: "messages",
messages: [message]
});
```
### Commander.sendRequest
Request/response communication with the native app. Returns a Promise resolved when the host sends back a matching response.
```typescript theme={null}
const result = await Commander.sendRequest({
method: "getSelectedText",
payloads: {},
extensionName: "enconvo",
commandName: "get_selected_text"
});
```
### Commander.sendAsync
Non-blocking fire-and-forget message. Does not wait for acknowledgment.
```typescript theme={null}
Commander.sendAsync("responseStream", { type: "text", content: "partial result" });
```
## Request Object
When `Commander.addClickListener` fires, you receive a standard `Request`. The body contains `RequestOptions` -- a merged object of command configuration, user preferences, and runtime parameters.
```typescript theme={null}
Commander.addClickListener(async (req: Request) => {
const options: RequestOptions = await req.json();
// Common fields
options.input_text; // User input text
options.commandType; // "agent" | "chat" | "tool" | "provider" | etc.
options.commandName; // Current command name
options.extensionName; // Current extension name
options.messages; // Conversation history (for chat/agent)
options.context; // Context data (screen, clipboard, browser)
options.tools; // Available tools (for agent mode)
options.system_prompt; // System prompt
options.temperature; // LLM temperature
options.max_tokens; // Max token limit
// All preference values are accessible by their name
options.my_custom_preference; // Value of preference named "my_custom_preference"
});
```
## EnconvoResponse
The return type for command handlers. Multiple factory methods create different response types.
### EnconvoResponse.text
Returns a simple text response displayed as a chat message.
```typescript theme={null}
return EnconvoResponse.text("Here is your result");
```
### EnconvoResponse.messages
Returns one or more structured chat messages with rich content.
```typescript theme={null}
import { BaseChatMessage, ChatMessageContent } from "@enconvo/api";
return EnconvoResponse.messages([
BaseChatMessage.assistant([
ChatMessageContent.text("Here is the analysis:"),
ChatMessageContent.image({ url: "https://example.com/chart.png" })
])
]);
```
### EnconvoResponse.json
Returns a JSON object as a text response (serialized).
```typescript theme={null}
return EnconvoResponse.json({ status: "ok", count: 42 });
```
### EnconvoResponse.none
Returns nothing -- useful for commands that produce side effects only.
```typescript theme={null}
await Clipboard.copy("copied text");
return EnconvoResponse.none();
```
### EnconvoResponse.error
Returns an error message displayed to the user.
```typescript theme={null}
return EnconvoResponse.error("API key is missing", 401);
```
### Returning a string
You can also return a plain string, which is automatically wrapped as a text response.
```typescript theme={null}
Commander.addClickListener(async (req: Request) => {
return "Simple text response";
});
```
## NativeAPI
The `NativeAPI` namespace provides typed methods for calling native macOS operations and invoking other extension commands.
### NativeAPI.callCommand
Invoke any other extension command programmatically.
```typescript theme={null}
import { NativeAPI } from "@enconvo/api";
// Call Gmail to send an email
const result = await NativeAPI.callCommand("gmail|send_email", {
to: "user@example.com",
subject: "Hello",
body: "Message content"
});
```
### NativeAPI.request / NativeAPI.api
Call extension API routes (files in `src/api/`).
```typescript theme={null}
// Call an API endpoint
const response = await NativeAPI.request("knowledge_base/search", {
query: "machine learning",
limit: 10
});
```
### NativeAPI.localApi
Call the local HTTP server API endpoint directly.
```typescript theme={null}
const response = await NativeAPI.localApi("enconvo/cache", {
action: "get",
key: "my_cache_key"
});
```
## Clipboard
Read and write clipboard content, paste into the active application, or insert text below the cursor.
```typescript theme={null}
import { Clipboard } from "@enconvo/api";
// Copy text to clipboard
await Clipboard.copy("text to copy");
// Paste text into the frontmost application
await Clipboard.paste("text to paste");
// Insert text below the current cursor position
await Clipboard.insertBelow("text below cursor");
// Read current clipboard content
const content = await Clipboard.read();
```
## Toast & HUD
Display notifications and heads-up messages.
```typescript theme={null}
import { showToast, showHUD } from "@enconvo/api";
// Show a toast notification
await showToast({ title: "Success", message: "File saved" });
// Show a brief HUD message overlay
await showHUD("Operation complete");
```
## SmartBar & Window
Control the SmartBar and window display modes.
```typescript theme={null}
import { SmartBar } from "@enconvo/api";
// Close the SmartBar
await SmartBar.close();
```
## environment
The `environment` object exposes runtime context about the current command execution.
```typescript theme={null}
import { environment } from "@enconvo/api";
environment.extensionName; // Current extension name
environment.commandName; // Current command name
environment.commandTitle; // Display title of the command
environment.assetsPath; // Path to extension's assets/ directory
environment.supportPath; // Per-extension support directory
environment.rootSupportPath; // Root support directory
environment.cachePath; // Cache directory
environment.isDevelopment; // true if running in dev mode
environment.appearance; // "light" | "dark"
environment.textSize; // "medium" | "large"
environment.sessionId; // Current session ID
environment.enconvoVersion; // EnConvo app version
environment.runType; // "command" | "api" | "flow"
environment.flowId; // Workflow ID (if running in a workflow)
```
## KV (Key-Value Storage)
Persistent key-value storage for extension data. Values persist across command invocations.
```typescript theme={null}
import { KV } from "@enconvo/api";
// String operations
await KV.set("last_query", "machine learning");
const query = await KV.get("last_query", "default_value");
// Number operations
await KV.setNumber("run_count", 42);
const count = await KV.getNumber("run_count", 0);
// Boolean operations
await KV.setBool("feature_enabled", true);
const enabled = await KV.getBool("feature_enabled");
```
## Stream
The `Stream` class provides utilities for working with streaming responses, particularly SSE (Server-Sent Events) from LLM APIs.
### Stream.fromSSEResponse
Parse an SSE response into an async iterable of typed objects.
```typescript theme={null}
import { Stream } from "@enconvo/api";
const response = await fetch("https://api.openai.com/v1/chat/completions", {
method: "POST",
body: JSON.stringify({ stream: true, /* ... */ })
});
const controller = new AbortController();
const stream = Stream.fromSSEResponse(response, controller);
for await (const chunk of stream) {
// Process each SSE chunk
console.log(chunk.choices[0].delta.content);
}
```
### Stream.fromReadableStream
Parse a newline-delimited JSON `ReadableStream` into typed objects.
```typescript theme={null}
const stream = Stream.fromReadableStream(readableStream, controller);
for await (const item of stream) {
// Process each JSON item
}
```
### Stream.tee
Split a stream into two independent streams that can be read at different speeds.
```typescript theme={null}
const [stream1, stream2] = stream.tee();
```
### Stream.toReadableStream
Convert back to a `ReadableStream` of newline-delimited JSON.
```typescript theme={null}
const readable = stream.toReadableStream();
```
## res (Response Streaming)
The `res` namespace provides methods for streaming partial results back to the UI during command execution.
### res.write
Stream content incrementally to the chat UI.
```typescript theme={null}
import { res, BaseChatMessage, ChatMessageContent } from "@enconvo/api";
// Stream text content
await res.write({
content: "Partial result...",
action: EnconvoResponse.WriteAction.AppendToLastMessageLastTextContent
});
// Stream a structured message
await res.write({
content: new AssistantMessage([ChatMessageContent.text("Updated content")]),
action: EnconvoResponse.WriteAction.OverwriteLastMessage
});
```
### res.writeLoading
Display a loading indicator in the chat UI.
```typescript theme={null}
await res.writeLoading("Analyzing document...");
```
### Write Actions
Control how streamed content updates the UI:
| Action | Behavior |
| - | - |
| `AppendToLastMessageLastTextContent` | Append text to the last message's text content |
| `OverwriteLastMessage` | Replace the entire last message |
| `OverwriteLastMessageAllContent` | Replace all content in the last message |
| `AppendToLastMessageContent` | Append a new content block to the last message |
| `AppendMessage` | Add a new message to the conversation |
## LLMProvider Base Class
The abstract base class for implementing LLM provider extensions.
```typescript theme={null}
import { LLMProvider, Stream, BaseChatMessage, BaseChatMessageChunk } from "@enconvo/api";
class MyLLMProvider extends LLMProvider {
constructor(options: LLMProvider.LLMOptions) {
super(options);
}
// Required: non-streaming completion
protected async _call(params: LLMProvider.ResolvedParams): Promise {
const response = await myApiCall(params.messages, {
model: this.options.model,
temperature: this.options.temperature
});
return BaseChatMessage.assistant([
ChatMessageContent.text(response.content)
]);
}
// Required: streaming completion
protected async _stream(params: LLMProvider.ResolvedParams): Promise> {
const response = await myStreamingApiCall(params.messages, {
model: this.options.model,
stream: true
});
return Stream.fromSSEResponse(response, new AbortController());
}
}
// Entry point
export default function main(options: LLMProvider.LLMOptions) {
return new MyLLMProvider(options);
}
```
### LLMProvider.LLMOptions
Key options available on `this.options`:
| Field | Type | Description |
| - | - | - |
| `model` | `string` | Selected model identifier |
| `temperature` | `number` | Sampling temperature (0-2) |
| `max_tokens` | `number` | Maximum tokens to generate |
| `top_p` | `number` | Top-p sampling parameter |
| `tools` | `AITool[]` | Available tools for function calling |
| `messages` | `BaseChatMessageLike[]` | Conversation history |
## TTSProvider Base Class
The abstract base class for implementing TTS provider extensions.
```typescript theme={null}
import { TTSProvider } from "@enconvo/api";
class MyTTSProvider extends TTSProvider {
constructor(options: TTSProvider.TTSOptions) {
super({ options });
}
// Required: convert text to audio file
protected async _toFile(params: TTSProvider._ToFileTTSParams): Promise {
const audioBuffer = await myTTSApi(params.text, {
voice: this.options.voice?.value,
speed: this.options.speed?.value
});
const filePath = `${params.outputDir}/${params.audioFileName}.mp3`;
fs.writeFileSync(filePath, audioBuffer);
return { audioFilePath: filePath };
}
}
export default function main(options: TTSProvider.TTSOptions) {
return new MyTTSProvider(options);
}
```
## ServiceProvider.load
Load and instantiate any provider extension dynamically.
```typescript theme={null}
import { ServiceProvider } from "@enconvo/api";
// Load an LLM provider
const llm = ServiceProvider.load(options);
// Load a TTS provider
const tts = ServiceProvider.load(options);
```
The `options` object must include `extensionName` and `commandName` identifying the provider to load. Provider instances are cached by their options hash for reuse.
## Extension & Command Management
Utilities for working with extension metadata and configuration.
```typescript theme={null}
import { CommandManageUtils, ExtensionManageUtils, PreferenceManageUtils } from "@enconvo/api";
// Load a command's full configuration
const config = await CommandManageUtils.loadCommandConfig({
commandKey: "gmail|send_email",
useAsRunParams: true
});
// Get raw command info (synchronous)
const rawCmd = CommandManageUtils.getRawCommandInfo("llm|open_ai");
```
## NativeEventUtils
Send and listen for events across extensions and the native app.
```typescript theme={null}
import { NativeEventUtils } from "@enconvo/api";
// Send a custom event
await NativeEventUtils.sendEvent("my_custom_event", {
key: "value"
});
```
Events sent through this system can be hooked by the user via `~/.config/enconvo/hooks.json`.
## Action
Response actions displayed as buttons below chat messages.
```typescript theme={null}
import { Action } from "@enconvo/api";
return EnconvoResponse.messages(
[BaseChatMessage.assistant([ChatMessageContent.text("Done!")])],
[
Action.OpenLink({ url: "https://example.com", title: "Open Website" }),
Action.OpenConfig({ page: "key_management", title: "Configure Keys" }),
Action.Retry({ sessionId: environment.sessionId })
]
);
```
## src/api/ Auto-Discovery
Files placed in `src/api/` are automatically discovered and registered as API routes during build. No `package.json` entry is needed.
### Single File Route
```
src/api/status.ts → extensionName/status
```
```typescript theme={null}
// src/api/status.ts
export default async function main(request: Request) {
return Response.json({ status: "ok", uptime: process.uptime() });
}
```
### Directory Route
```
src/api/users/ → extensionName/users (auto-generated router)
src/api/users/list.ts → extensionName/users/list
src/api/users/create.ts → extensionName/users/create
```
```typescript theme={null}
// src/api/users/list.ts
interface ListParams {
/** Maximum number of users to return @default 20 */
limit: number;
/** Page offset @required */
offset: number;
}
export default async function main(request: Request) {
const params = await request.json() as ListParams;
// The interface is parsed for automatic schema generation
return Response.json({ users: [], total: 0 });
}
```
### JSDoc Annotations
| Annotation | Effect |
| - | - |
| `@private` on export | Hides from generated API docs and schemas |
| `@required` on interface field | Marks parameter as required |
| `@default ` on interface field | Sets default value in schema |
### Generated Files
The build system generates:
* `skills/schemas.json` -- JSON schema for all API endpoints
* `skills/docs.md` -- Human-readable API documentation
* `skills/SKILL.md` -- Skill metadata for AI agent discovery
## Command Entry Point Pattern
### Standard Command
```typescript theme={null}
// src/my_command.ts
import { Commander, EnconvoResponse } from "@enconvo/api";
export default async function main(req: Request): Promise {
const options = await req.json();
const result = processInput(options.input_text);
return EnconvoResponse.text(result);
}
```
### Provider Command
```typescript theme={null}
// src/my_provider.ts
export default function main(options: any) {
return new MyProvider(options);
}
```
### API Route
```typescript theme={null}
// src/api/my_endpoint.ts
export default async function main(request: Request) {
const params = await request.json();
return Response.json({ result: "ok" });
}
```
## Building Extensions
```bash theme={null}
# Build for production
npx enconvo plugin build
# Dev mode with hot reload
npx enconvo plugin build --dev
# Generate API schema
npx enconvo plugin generate-schema
# Publish to store
npx enconvo plugin publish
```
## Next Steps
Step-by-step guide to creating extensions
Explore all available extensions
Package AI instructions as reusable skills
React to extension events with hooks
# Installing Plugins
Source: https://docs.enconvo.ai/extensions/installing-plugins
Install Enconvo, Codex, Claude Code and portable plugins from the store, an archive, GitHub, git, npm, a folder or a plugin marketplace, and keep them up to date.
Most people install plugins from the plugin store on Enconvo's **Plugins** page. Enconvo also installs plugins from other places, including the Codex and Claude Code plugins their developers publish on GitHub and in plugin marketplaces. See [Plugin Formats](/extensions/plugin-formats) for the packages Enconvo reads.
Only plugins in the Enconvo store are reviewed by Enconvo. A plugin from anywhere else can run programs on your Mac through its MCP servers, so install it only from a source you trust.
## From the Plugins page
Click **Add** on the **Plugins** page:
| Option | What it does |
| - | - |
| **Create plugin** | Starts a chat in which Enconvo's agent builds a plugin with you. |
| **Upload plugin archive…** | Installs a file: an `.enconvo` package, a `.dxt` desktop extension, or a `.zip` of a Claude Code or Codex plugin. |
| **Add from GitHub…** | Installs a plugin, or one from a plugin marketplace, from GitHub, git, npm or a folder (see below). |
| **Add MCP server…** | Opens MCP settings, to connect one server without a plugin around it. |
| **Add PopBar extension…** | Installs a PopBar extension from a link, a file or a `#popclip` snippet (see [PopBar extensions](/features/popbar#popbar-extensions)). |
| **New skill…** | Opens Skills settings, to write a skill of your own. |
| **Developer guide** | Opens [Developing Extensions](/extensions/developing). |
What you've added is under **Installed**, at the top of the **Enconvo** tab: the Connectors you've connected and the plugins you installed or made, by name. Click **Installed** to see all of them. Plugins that come with Enconvo aren't listed there. PopBar extensions have their own **PopBar Extensions** tab, with Enconvo's reviewed catalog; see [PopBar extensions](/features/popbar#popbar-extensions).
### Add from GitHub
Paste where the plugin is and press **Preview**:
* `owner/repo`, or a GitHub link, including one to a folder (`/tree//`)
* `owner/repo/folder` for a plugin inside a repository, with `@branch` or `@tag` to pin a version
* any https git address
* `npm:`, with `@version` to pin one
* an https link to a plugin's `.zip`
* a folder on your Mac
Enconvo shows the plugin before installing anything: its format (Codex, Claude Code, portable, desktop extension or Enconvo), version, developer, skills, MCP servers and hooks, and any ChatGPT apps it includes, which Enconvo doesn't load. For each MCP server it says whether it starts on your Mac or connects over the internet. A plugin's hooks run commands on your Mac, so they stay off unless you check **Allow its hooks to run**. Click **Install**, and Enconvo opens the plugin's page. Its **Source** row says where the plugin came from (for GitHub and git, with the commit) and links to the repository or npm page, and the note at the bottom names the developer the plugin gives: only Enconvo's own plugins and plugins from its store say they're made by Enconvo. Plugins installed this way are listed under **Personal**. Installing again from the same place updates the plugin. If a plugin of the same name is already installed from somewhere else, uninstall it first.
When the address is a plugin marketplace, the dialog lists its plugins with an **Install** button on each. Installing one adds the marketplace, which then shows under **Your marketplaces** the next time you open the dialog.
An Enconvo plugin's source code has to be built before it works, so the dialog gives you the `enconvo plugin install` command to run in Terminal instead.
## From a chat
When you ask Enconvo's agent for something your plugins can't do, it can look for a plugin in the plugin marketplaces on your Mac: the ones you've added in Enconvo, and the ones Codex or Claude Code has that Enconvo doesn't have yet, including the OpenAI Curated marketplace that comes with Codex (see [Marketplaces you added in Codex or Claude Code](#marketplaces-you-added-in-codex-or-claude-code)). It reads the copies of their catalogs already on your Mac and downloads nothing while it looks. It leaves out plugins you've installed, and plugins named like one you've installed from somewhere else.
When it finds one, the agent shows a card in the chat, and nothing installs until you click **Install**:
* From a marketplace you've added in Enconvo, the card says which MCP servers the plugin starts on your Mac or connects to, its skills, and the other plugins it needs.
* From a marketplace only Codex or Claude Code has, the card says that installing adds that marketplace to Enconvo. Enconvo can't read the plugin's contents before then, so the card can't list them.
Either way, the plugin's hooks stay off until you turn them on in **Plugins**. When a plugin can't be installed, for example because a plugin it needs can't be, the agent says so instead of showing the card.
### Plugins from ChatGPT
Plugins in the [ChatGPT plugin directory](https://chatgpt.com/plugins) can't be installed in Enconvo. Most of them are ChatGPT apps, which run only inside ChatGPT, and OpenAI gives the rest of them only to ChatGPT and Codex. If you've signed in to Codex on your Mac, the agent knows the directory from the copy Codex keeps. When you name one of its plugins or paste its chatgpt.com link, the agent tells you why it can't install it and offers something that does the same: a Connector, an MCP server, a skill, or a plugin with the same name in one of your marketplaces. Many of the directory's plugins that come with files also have a plugin of the same name in OpenAI Curated, the marketplace that comes with Codex (OpenAI's public `openai/plugins` repository). The agent offers that plugin, and installing it adds OpenAI Curated to Enconvo. Enconvo doesn't load the ChatGPT apps those plugins include, only their skills and MCP servers.
A chatgpt.com link doesn't work in **Add from GitHub** either; the dialog says the same thing.
## From the command line
`plugin install` takes a plugin from GitHub, git, npm, a zip on the web, a folder or a marketplace. Enconvo 2.5.6 or later has to be running.
```sh theme={null}
npx -p @enconvo/api enconvo plugin install
```
| Source | Example |
| - | - |
| A GitHub repository, optionally a folder in it and a branch, tag or commit | `acme/notes`, `acme/plugins/notes@v1.2.0` |
| A GitHub address | `https://github.com/acme/plugins/tree/main/notes` |
| Any other git repository over https (needs git); an ssh address works only for GitHub | `https://git.example.com/notes.git`, `git@github.com:acme/notes.git` |
| An npm package | `npm:@acme/notes-plugin`, `npm:@acme/notes-plugin@1.2.0` |
| A plugin zip on the web (public https only) | `https://downloads.acme.com/notes-1.2.0.zip` |
| A folder on your Mac | `./notes`, `~/code/notes`, `/Users/ada/notes` |
| A plugin in an added marketplace | `notes@acme-plugins` |
`plugin install` and `plugin marketplace` need an `@enconvo/api` release newer than 0.1.174. Inside a project that depends on `@enconvo/api`, `npx enconvo …` is enough. `marketplace import` also needs Enconvo 2.5.7 or later.
Add `--preview` to see what would be installed, and from where, without installing it.
When the source is a plugin marketplace rather than a plugin, `plugin install` lists its plugins. A marketplace with more than 200 lists the first 200 and says how many more there are; `plugin marketplace add` lists them all. Pick one with `--plugin`, which also adds the marketplace:
```sh theme={null}
npx -p @enconvo/api enconvo plugin install acme/plugins --plugin notes
```
### What happens on install
* **Settings**: a plugin with required settings, such as an API key, installs and then asks for them. `plugin install` names them; fill them in on the plugin's page.
* **Enconvo plugins from source**: when a GitHub repository or folder holds an Enconvo plugin that hasn't been built, `plugin install` builds it first. A folder is built in place, after `npm install`.
* **Onboarding**: when a plugin names an onboarding skill, Enconvo offers to run it after the first install.
* **Signing in**: when a plugin's MCP servers need you to sign in, as Notion's or Figma's do, the Plugins page shows **Sign in** as soon as it installs. Enconvo opens the server's sign-in page in your browser and offers the next server once that one connects. `plugin install` names the servers instead. A sign-in you skip waits in **Settings > MCP**.
* **Hooks**: a plugin's [hooks](/extensions/plugin-formats#hooks) install turned off, because they run commands. `--preview` lists them; allow them with the **Allow hooks** switch on the plugin's page. Hooks you allowed stay on through updates that don't change them.
* **Dependencies**: when a Claude Code plugin from a marketplace needs other plugins, Enconvo installs them with it (see [Plugin marketplaces](#plugin-marketplaces)). `--preview` lists them and says which are already installed, which would install, and which can't. A dependency the marketplace entry declares from a marketplace that isn't allowed stops the install; one the plugin's own `plugin.json` declares is left out and the install goes on. Their hooks stay off, and uninstalling the plugin keeps them until you prune them (see [Uninstalling](#uninstalling)).
* **Using it**: as in Codex, type `@` in a chat and pick the plugin, or click one of the prompts under **Try asking** on its page. Either way the chat gets the plugin attached. Every installed plugin is in the `@` menu, including a Codex or Claude Code plugin that names no category.
* **Same name**: installing again from the same source updates the plugin. If a plugin with the same name is already installed from somewhere else, such as the store, Enconvo leaves it alone and asks you to uninstall it first.
When Enconvo isn't running, `plugin install` can still install an Enconvo plugin from GitHub by building it. For anything else, open Enconvo and try again.
### Uninstalling
Uninstall a plugin from its menu or its page on the Plugins page, which asks you to confirm first, or from Terminal:
```bash theme={null}
npx -p @enconvo/api enconvo plugin uninstall notes # also: remove, rm
npx -p @enconvo/api enconvo plugin uninstall notes --prune # and the dependencies nothing needs any more
npx -p @enconvo/api enconvo plugin prune --dry-run # list them without removing anything
npx -p @enconvo/api enconvo plugin prune # remove them (also: autoremove)
```
Pruning removes only plugins that were installed because another plugin needed them, once no installed plugin needs them, as `claude plugin prune` does in Claude Code. A plugin you installed yourself is never pruned, and installing a dependency again yourself makes it yours. In Terminal, Enconvo lists what it will remove and asks first; add `-y` to skip the question, which `--prune` needs when it can't ask. The Plugins page's uninstall doesn't prune yet.
## Plugin marketplaces
A marketplace is a catalog of plugins in a repository or folder. Enconvo reads both kinds: Codex's `.agents/plugins/marketplace.json` and Claude Code's `.claude-plugin/marketplace.json`.
```sh theme={null}
npx -p @enconvo/api enconvo plugin marketplace add acme/plugins # GitHub, a git address or a folder
npx -p @enconvo/api enconvo plugin marketplace add acme/plugins --ref v2 # at a branch, tag or commit
npx -p @enconvo/api enconvo plugin marketplace list # added marketplaces and their plugins
npx -p @enconvo/api enconvo plugin install notes@acme-plugins # install one of them
npx -p @enconvo/api enconvo plugin marketplace refresh # fetch them again for new plugins
npx -p @enconvo/api enconvo plugin marketplace remove acme-plugins
```
`refresh` also answers to `upgrade` (Codex's name) and `update` (Claude Code's), and `--ref v2` is the same as `acme/plugins@v2`.
### Marketplaces you added in Codex or Claude Code
If you've added marketplaces in Codex or Claude Code on this Mac, or Codex has fetched its OpenAI Curated marketplace, `marketplace list` shows the ones Enconvo doesn't have yet, and `import` adds them, so you don't type their addresses again:
```sh theme={null}
npx -p @enconvo/api enconvo plugin marketplace import # all of them
npx -p @enconvo/api enconvo plugin marketplace import claude-plugins-official # only these
```
Enconvo finds them in Codex's `~/.codex/config.toml`, its copy of OpenAI Curated, and its personal `~/.agents/plugins/marketplace.json`, and in Claude Code's list of known marketplaces. It only reads those files and changes nothing in either app. OpenAI Curated is added from `openai/plugins` on GitHub. It leaves out the other marketplaces that come with Codex, which hold plugins for Codex's own tools, and Claude Code marketplaces added from the web address of a `marketplace.json` file, which Enconvo doesn't add. When both apps have a marketplace of the same name, it offers Codex's.
A marketplace's plugins can come from a folder in the marketplace, another GitHub repository, a git address, a folder in a git repository, npm, or a zip on the web (Claude Code's `archive` source). A plugin a Codex marketplace marks `NOT_AVAILABLE` can't be installed.
Codex marketplaces such as OpenAI Curated list only each plugin's name and where it comes from. For a plugin in the marketplace's own folder, Enconvo shows the title, description, category and developer from the plugin's manifest, as Codex does, and the agent finds it by what it does as well as by name. What a marketplace entry says itself comes first.
Some of OpenAI Curated's plugins, such as Gmail, Google Drive, Outlook and Teams, work only when you sign in to Codex with ChatGPT, so Codex doesn't offer them to people who sign in with an API key. Enconvo doesn't sign in to ChatGPT either, so it shows them as needing a ChatGPT sign-in, doesn't install them, and the agent doesn't offer them. For those services, add the provider's own MCP server or a Connector instead.
A folder source written as `./plugins/notes` is read from the top of the marketplace. A bare name such as `notes` is read from the folder `metadata.pluginRoot` names, as in Claude Code, and needs that field.
A download from GitHub, npm or the web can take up to three minutes; if it takes longer, Enconvo stops it and asks you to check your connection.
A zip, whether you paste its link or a marketplace lists it, downloads only from a public https address, through at most five redirects. When the marketplace gives its `sha256`, a download that doesn't match is refused. The plugin can sit at the top of the zip or inside one folder.
Claude Code marketplace entries work with a plugin's own `plugin.json` the way Claude Code reads them:
* An entry can add `commands`, `agents`, `skills`, `outputStyles` and `themes` to the plugin's own, and its `hooks` replace the plugin's hooks for the same events.
* An entry with `"strict": false` that also lists any of these, over a plugin that has a `plugin.json`, is refused as conflicting manifests. Keep them in one place.
* When the plugin has no `plugin.json`, the entry is its manifest.
* The entry's name, description, author and other listing details are shown; the version is the plugin's.
* A marketplace's `renames` are followed. A plugin installed under its old name keeps updating under the new one, and installing by the old name finds it. A name renamed to `null` was removed from the marketplace, and Enconvo says so. If the plugin's own manifest changed its name too, Enconvo asks you to uninstall the old plugin and install the new one, because Enconvo names a plugin after its manifest.
* A plugin's `dependencies`, in its entry or its `plugin.json`, install with it. Each is a name (`"formatter"`), a name and marketplace (`"formatter@acme-tools"`), either followed by a `^` range (`"formatter@acme-tools@^2.1"`), or `{ "name", "marketplace", "version" }` with a semver range. A dependency comes from the plugin's own marketplace unless it names another one, and another marketplace has to be listed in `allowCrossMarketplaceDependenciesOn` by the marketplace you installed from. A dependency with a `version` range installs at the highest release tag (`--v`) in that range, and in the ranges other installed plugins put on it, from the plugin's own repository or, for a plugin inside the marketplace, the marketplace's (a marketplace folder counts when it's in a git repository). With no such tag, a plugin inside the marketplace installs as the marketplace has it, and one in its own repository is refused. Ranges no single version satisfies refuse the install, and updates stay inside the ranges. A dependency that's already installed is left as it is, and one outside its `version` range gets a warning.
On the Plugins page, open **Add → Add from GitHub…** and paste the marketplace's address, or pick one you've added under **Your marketplaces**.
Enconvo keeps a copy of a marketplace from GitHub or git, and reads a folder marketplace where it is. Removing a marketplace keeps the plugins you installed from it.
Before you share a marketplace, check it and every plugin in it. The rules are the ones `claude plugin validate` applies, plus Codex's for an `.agents/plugins/marketplace.json`; see [Validation Codes](/extensions/validation-codes#marketplaces). An error means Claude Code can't add the marketplace or install the plugin, even though it may still list it: a field of the wrong type in an entry, `renames` that don't lead to a plugin, `relevance` signals it refuses, or a marketplace name that looks like one of Anthropic's own, such as `claude-plugins-hub`. A warning covers what Claude Code ignores, such as a misspelled field, and names Claude Desktop rejects.
```sh theme={null}
npx -p @enconvo/api enconvo plugin validate path/to/marketplace
```
## Updates
Enconvo's plugin update check also covers plugins installed from GitHub, git, npm, folders and marketplaces, and lists their updates with the store's. It reads a repository's latest commit without downloading it, asks npm for the latest version, notices when an installed folder has changed, and, for a zip a marketplace pins by `sha256`, notices when the pin changes. Updating installs the plugin again from the same source.
To check one plugin, open its page and choose **Check for updates** in the **⋯** menu. When a newer version is there, click **Update** in the message that appears.
Or update one from Terminal, as `claude plugin update` does in Claude Code:
```bash theme={null}
npx -p @enconvo/api enconvo plugin update notes # from wherever it came from, or the store
npx -p @enconvo/api enconvo plugin update notes@acme-plugins # only if it came from that marketplace
```
It checks first. When nothing is newer, it says the plugin is already at its latest version and changes nothing; otherwise it updates the plugin the way the Updates list does.
## Publish your own
To list a plugin in the Enconvo store, see [Plugin Store Guidelines](/extensions/publishing-guidelines). To share it without the store, push it to GitHub or a marketplace, and people can install it with **Add from GitHub…** or the commands above.
### Tag a release
`plugin tag` marks the commit you're releasing with a git tag named `--v`, as `claude plugin tag` does. Claude Code and Enconvo pick among these tags when another plugin's dependency asks for a version range, and anyone can install that release with Enconvo, for example `acme/plugins/notes@notes--v1.2.0`.
```sh theme={null}
npx -p @enconvo/api enconvo plugin tag plugins/notes --dry-run # check, and print the git commands
npx -p @enconvo/api enconvo plugin tag plugins/notes --push # tag HEAD and push the tag to origin
```
The version comes from the plugin's manifest, or from its marketplace entry when the manifest has none, and has to be semver (`1.2.0`). Before tagging, `plugin tag` checks the plugin as `plugin validate` does, and stops when the marketplace entry names a different version, when files in the plugin's folder aren't committed, or when the tag exists. Bump the version for a new release; `--force` moves an existing tag instead. It tags Codex, Claude Code, portable and Enconvo plugins alike, so every manifest the package carries has to name the same version. `-m` sets the tag's message (`%s` is the version), and `--remote` the remote `--push` pushes to. Like `plugin install`, it needs an `@enconvo/api` release newer than 0.1.174.
# Plugins Overview
Source: https://docs.enconvo.ai/extensions/overview
Find, install, configure, and use Enconvo plugins.
Plugins add commands, providers, tools, and API routes to Enconvo. Open **Settings → Plugins → Plugins** to search the catalog and inspect installed plugins.
## Find and configure a plugin
1. Search by the task or plugin name.
2. Open its detail page and review its description, commands, and requirements.
3. Install it if it is not already installed.
4. Configure any required provider credentials or command settings.
5. Run a command from SmartBar, or enable its tools for the Agent that should use it.
The **Installed** strip provides quick access to installed plugins. A plugin's detail page lists commands and their settings. Opening a command's settings from another surface takes you back to that command within its plugin.
## Find the right capability
| Task | Guide |
| - | - |
| Improve or translate text | [Writing Toolkit](/features/writing-tools), [Translation](/ai/translate) |
| Search and read the web | [Web Search](/ai/web-search), [Read Web Pages](/ai/web-fetch) |
| Work with files or a terminal | [File Tools](/ai/file-tools), [Code Runner](/ai/code-runner) |
| Generate images, video, or speech | [Provider Catalog](/providers/catalog) |
| Work with Mail, Calendar, Notes, or Reminders | [Apple Ecosystem](/integrations/apple-ecosystem) |
| Connect external tools | [MCP Servers](/features/mcp) |
| Add reusable Agent instructions | [Skills](/configuration/skills) |
The [Built-in Command Catalog](/extensions/built-in-extensions) lists the currently documented command families. Available store entries and installed plugins can differ between builds.
## Commands, providers, and tools
A command is an executable action. A provider supplies a capability such as a model or voice. A tool is an action an Agent can call. Installing a plugin does not necessarily choose its provider globally or enable every tool for every Agent.
In SmartBar, use its configured command picker (normally `@`) or search a command's title. The `/` action menu serves a different purpose; it is not a universal plugin-name prefix.
## Update or remove
Use the plugin's available update or uninstall controls and review the confirmation. Check Agents, workflows, and custom commands that depend on it before removal. Resetting a command restores its settings; resetting a shared provider can also affect credentials used by other capabilities. See [Credentials](/configuration/credentials).
## Develop a plugin
Use the TypeScript SDK and CLI described in [Developing Extensions](/extensions/developing). The current CLI groups build, install, schema generation, and publish under `enconvo plugin`. Publishing makes a plugin available outside your local development environment. Enconvo also installs Codex, Claude Code and portable plugins; see [Plugin Formats](/extensions/plugin-formats) and [Installing Plugins](/extensions/installing-plugins).
# Plugin Formats
Source: https://docs.enconvo.ai/extensions/plugin-formats
The plugin packages Enconvo installs, including Codex, Claude Code and portable plugins, and the files and fields it reads from each.
Enconvo installs its own plugins and the plugins other AI apps use. A Codex or Claude Code plugin installs as it is, without changes, and one folder can be a plugin for Enconvo, Codex and Claude Code at the same time.
## Formats
| Format | Enconvo recognizes it by | What Enconvo loads |
| - | - | - |
| Enconvo plugin | `package.json` with Enconvo's `$schema` or a `commands` list | Commands, Local API routes, AI model and voice providers, settings, skills and MCP servers |
| Claude Code plugin | `.claude-plugin/plugin.json` | Skills, MCP servers, and settings from `userConfig` and `channels` |
| Codex plugin | `.codex-plugin/plugin.json` | Skills, MCP servers, and the listing in `interface` |
| Portable plugin ([Agent Plugins](https://agent-plugins.org)) | `plugin.json` at the root, with a `name` | Skills, MCP servers, and the listing in `extensions["com.openai"]` |
| Desktop extension (MCPB, formerly DXT) | `manifest.json` | Its MCP server, and `user_config` as settings |
Enconvo checks these in order and uses the first that matches. An Enconvo `package.json` always wins, so an Enconvo plugin can also carry a `plugin.json` for other apps. A `package.json` without Enconvo's schema or commands, such as the one an MCP server's Node.js project has, doesn't hide a `plugin.json` next to it.
Codex and OpenAI's portal read a root `plugin.json` as a portable plugin only when it gives `"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json"`, the one Agent Plugins schema Codex supports. Without it, Codex reads `.codex-plugin/plugin.json` or `.claude-plugin/plugin.json` instead, and installs nothing when neither is there. Enconvo installs the plugin either way, and `plugin validate` reports `plugin_schema_missing`. A portable plugin's `name` has up to 64 lowercase letters, digits and single dots or hyphens, and starts and ends with a letter or digit, such as `acme-tools` or `acme.tools`. OpenAI's portal refuses the dot, so name a plugin you mean to submit there `acme-tools`. Leave out a field you don't fill in rather than setting it to `null`: Codex and Claude Code refuse a `plugin.json` with a `null` `version`, `description`, `author`, `homepage`, `repository` or `license`, and both want `repository` and `license` as text and `keywords` as a list of text.
## One package for Enconvo, Codex and Claude Code
`plugin create` sets up a package that installs in all three apps:
```sh theme={null}
npx -p @enconvo/api enconvo plugin create notes --template skills # a skill
npx -p @enconvo/api enconvo plugin create notes --template mcp # an MCP server
```
`--template command`, the default, makes an Enconvo plugin with a TypeScript command; see [Developing Extensions](/extensions/developing).
```text theme={null}
notes/
├── plugin.json # portable manifest: name, version, description
├── .codex-plugin/plugin.json # the Codex listing (interface)
├── .claude-plugin/plugin.json # the Claude Code manifest
├── skills/hello/
│ ├── SKILL.md
│ └── agents/openai.yaml # the skill's name and example prompt
├── mcp.json # MCP servers for Codex and Enconvo (mcp template)
├── .mcp.json # the same servers for Claude Code (mcp template)
├── mcp/server.mjs # a dependency-free MCP server (mcp template)
└── assets/icon.png
```
Keep `name`, `version` and `description` the same in the three manifests, and raise `version` for every release. `plugin validate` warns when they differ, and `plugin publish` refuses.
The commands on this page need an `@enconvo/api` release newer than 0.1.174, and installing needs Enconvo 2.5.6 or later. Inside a project that depends on `@enconvo/api`, `npx enconvo …` is enough.
## How Enconvo reads the manifests
When a folder has more than one `plugin.json`, Enconvo reads all of them. For each field, the first manifest that sets it wins, in this order: `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, then the root `plugin.json`. The others fill in what it leaves out, so a Codex manifest can add the listing to a portable one. `extensions` are merged per vendor, and `extensions["com.openai"].interface` fills in the `interface` fields the Codex manifest doesn't set. Codex itself reads the listing from only one of them, so keep it in one place: `.codex-plugin/plugin.json`, or `extensions["com.openai"]` in `plugin.json`.
A portable plugin's skills are the folders in `skills/` and its MCP servers are the ones in `mcp.json`, in Codex, OpenAI's portal and Enconvo alike. `skills` and `mcpServers` in its `plugin.json`, in `extensions["com.openai"]` or in `.codex-plugin/plugin.json` are ignored, and `plugin validate` warns `component_declaration_ignored`. Only `.claude-plugin/plugin.json` still declares its own, since Claude Code reads it.
### Name, title and description
| Enconvo shows | From |
| - | - |
| Name (the plugin's id) | `name` |
| Title | `displayName` (Claude Code), then `interface.displayName`, then `name` |
| Description | `description`, then `interface.shortDescription`, then `interface.longDescription` |
| Version | `version` (`0.0.1` when missing) |
| Category | `category`, then `interface.category` |
### Listing (`interface`)
Enconvo reads the same `interface` fields as Codex and OpenAI's plugin portal, from `.codex-plugin/plugin.json` or from `extensions["com.openai"].interface` in a portable `plugin.json`.
| Field | Shown in Enconvo as |
| - | - |
| `shortDescription`, `longDescription` | The plugin's summary and details |
| `defaultPrompt` | Example prompts under **Try asking** (up to 4). A prompt that names the plugin as `@` or `@`, as Codex's do, shows the plugin there and opens the chat with it attached; any other prompt gets the plugin in front |
| `capabilities` | What the plugin can do (up to 8) |
| `developerName` | The developer; `author.name` when missing |
| `websiteURL` | The website; `homepage`, then `repository` when missing |
| `supportURL`, `privacyPolicyURL`, `termsOfServiceURL` | Links on the plugin's page |
| `brandColor`, `brandColorDark` | Accent colors, as hex such as `#0A84FF` |
| `logo`, `composerIcon`, `logoDark`, `composerIconDark` | The icon: the first of these that is an image inside the package. In dark mode, the Plugins page shows `logoDark` (else `composerIconDark`) instead |
| `screenshots` | Screenshots under the plugin's description (up to 8), each an image inside the package; click one to see it larger |
Paths start at the plugin's root, such as `./assets/logo.png`. A link has to start with `http://` or `https://` to be shown.
A Claude Code plugin can give its icon and links as top-level fields in `.claude-plugin/plugin.json`, the way Anthropic's plugin directory reads them. Enconvo uses each one when `interface` doesn't set it, both for the installed plugin and for the plugin store:
| Claude Code field | Used as |
| - | - |
| `icon` | The icon, after the `interface` logos. A path inside the plugin, such as `./logo.png` |
| `documentationUrl` | The website, after `homepage` |
| `supportUrl`, `privacyPolicyUrl`, `termsOfServiceUrl` | `supportURL`, `privacyPolicyURL`, `termsOfServiceURL` |
```json theme={null}
{
"name": "deploy-tools",
"version": "1.0.0",
"icon": "./logo.png",
"documentationUrl": "https://example.com/docs",
"supportUrl": "https://example.com/support",
"privacyPolicyUrl": "https://example.com/privacy",
"termsOfServiceUrl": "https://example.com/terms"
}
```
Claude Code ignores these fields when it loads the plugin, so `plugin validate` only warns about a bad one. Keep them in `plugin.json`, not in a marketplace entry, where `claude plugin validate` reports them as unknown.
OpenAI's portal takes one of its own categories (Productivity, Creativity, Developer Tools, Business & Operations, Data & Analytics, Communication, Education & Research, Security, Finance, Healthcare, Travel, Entertainment or Other), example prompts that don't @mention an MCP server, and screenshots only for a plugin with an MCP server. `plugin validate --openai` checks all three.
The plugin store sends the website, support, privacy policy and terms of service links with each version, so its page shows them before anyone installs the plugin. It sends only `https://` links; `plugin review` flags the others. An Enconvo `package.json` can hold the same `interface` block for these links.
```json theme={null}
{
"name": "notes",
"version": "1.2.0",
"description": "Search and summarize your notes.",
"author": { "name": "Ada Lovelace" },
"interface": {
"displayName": "Notes",
"shortDescription": "Search your notes",
"developerName": "Ada Lovelace",
"category": "Productivity",
"defaultPrompt": ["Find my notes about the Q3 launch"],
"websiteURL": "https://example.com/notes",
"privacyPolicyURL": "https://example.com/privacy",
"brandColor": "#0A84FF",
"logo": "./assets/icon.png"
}
}
```
Write the listing in English. For other languages, add `translations` to `extensions["com.openai"].publication`, the text OpenAI's portal imports for each locale. Enconvo shows the one for its interface language in place of `shortDescription` and `longDescription`: `fr-FR` or `fr` for French, `zh-CN` for Simplified Chinese and `zh-TW` or `zh-HK` for Traditional Chinese. Without a match, the English listing stays.
```json theme={null}
"extensions": {
"com.openai": {
"publication": {
"translations": {
"fr-FR": { "subtitle": "Cherchez vos notes", "description": "Cherchez vos notes depuis le chat." }
}
}
}
}
```
### Onboarding skill
Set `extensions["com.openai"].onboardingSkill` to one of the plugin's skills, and Enconvo offers to run it right after the plugin is installed for the first time. Use it to walk people through signing in or setting up.
Point it at the skill's `SKILL.md`, such as `./skills/get-started/SKILL.md`, which is what OpenAI's portal takes. Enconvo also takes the skill's folder.
## MCP servers
Enconvo takes a plugin's MCP servers from the first of these that has any:
1. `mcpServers` in the manifest: the servers themselves, or a path to a file of them. In a portable plugin, only `.claude-plugin/plugin.json`'s counts.
2. `mcp.json` at the root (the portable format).
3. `.mcp.json` at the root (Claude Code).
4. `mcpServers` in `package.json`.
A file can list the servers under `mcpServers` or `mcp_servers`, or be the list itself.
```json theme={null}
{
"mcpServers": {
"notes": { "type": "stdio", "command": "node", "args": ["./mcp/server.mjs"], "cwd": "./" },
"notes-cloud": { "type": "streamable-http", "url": "https://example.com/mcp" }
}
}
```
* **Transports**: `stdio`, `http` (also written `streamable-http` or `streamable_http`) and `sse`. Servers of other types, such as `ws`, are skipped.
* **Claude Code reads strictly**: it drops a server with a `url` but no `type`, an unknown `type`, or a field of the wrong shape, such as an empty `command` or a `timeout` that isn't a positive whole number. Its `tools` is a list of `{"name", "permission_policy"}`, while Codex's is an object of tool settings by tool name, so a server with either form fails in the other app: give each its own MCP file, or leave `tools` out. `enconvo plugin validate` reports all of these (see [MCP servers and apps](/extensions/validation-codes#mcp-servers-and-apps)).
* **Working folder**: a relative `cwd` starts at the plugin's folder.
* **Remote servers**: use `https://` (or `wss://`) for anything but this computer, and never commit a token or key in `headers`: everyone who installs the plugin can read it. Reference a sensitive setting or an environment variable instead, such as `"Authorization": "Bearer ${user_config.api_token}"`. `enconvo plugin validate` warns about both, as `claude plugin validate` does (see [MCP servers and apps](/extensions/validation-codes#mcp-servers-and-apps)).
* **Variables** in `command`, `args`, `env`, `cwd`, `url` and `headers`:
| Variable | Becomes |
| - | - |
| `${CLAUDE_PLUGIN_ROOT}`, `${CODEX_PLUGIN_ROOT}`, `${PLUGIN_ROOT}` | The plugin's installed folder |
| `${CLAUDE_PLUGIN_DATA}`, `${PLUGIN_DATA}` | A folder for the plugin's own data, kept across updates |
| `${NAME}`, `${NAME:-default}` | An environment variable, or the default when it isn't set |
| `${user_config.KEY}` | The plugin's setting `KEY` (see [Settings](#settings)) |
Claude Code starts a local server from the current project, so its `.mcp.json` names files through `${CLAUDE_PLUGIN_ROOT}`. Codex and Enconvo start it from the plugin's folder. When a plugin has both files, keep them in step.
When the plugin also has `.codex-plugin/plugin.json`, Codex doesn't start the servers it declares (or those in `.mcp.json`) but reads their `env_vars`, and Enconvo does the same: a local server in `mcp.json` gets the variables its namesake there lists, except those with `"source": "remote"`. An `env` entry that only forwards one of them, such as `"API_TOKEN": "${API_TOKEN}"`, is dropped, so the server gets the variable when it's set and doesn't get a literal `${API_TOKEN}` when it isn't. `enconvo plugin scan` starts servers the same way.
### Signing in to a remote server
A remote server that asks for OAuth gets a **Sign in** button, and Enconvo registers itself with the server's authorization server. Limit what it asks for with `scopes` (Codex, a list) or `oauth.scopes` (Claude Code, one space-separated string).
When the authorization server doesn't register clients, ship the OAuth app people sign in through, in either tool's fields:
```json theme={null}
{
"mcpServers": {
"tracker": {
"type": "http",
"url": "https://mcp.example.com/mcp",
"oauth": {
"client_id": "your-app-id",
"callback_port": 3118,
"callback_url": "http://127.0.0.1:3118/callback"
}
}
}
}
```
* Claude Code writes `clientId` and `callbackPort`, and the sign-in comes back to `http://localhost:/callback`.
* Codex writes `client_id`, `callback_port`, `callback_url` and, for a confidential app, `client_secret`.
* Register the app's redirect as written: Enconvo listens on that port while someone signs in, then finishes the sign-in itself. If another app is using the port, the sign-in asks the person to close it and try again.
* The redirect has to be an `http` address on the same computer (`127.0.0.1`, `localhost` or `[::1]`).
* While the app's fields still hold placeholders such as `` or an unset `${VAR}`, Enconvo ignores the app and signs in the usual way.
Two more fields tell the sign-in what the server itself doesn't say:
* `oauth_resource` (Codex, next to `url`) is the resource the token is for. Enconvo sends it to the authorization server exactly as written, in the sign-in and in every renewal, so a server that compares it as a string (`https://mcp.notion.com` without a trailing slash) accepts the token. It has to be on the server's own origin; otherwise Enconvo signs in without it.
* `oauth.authServerMetadataUrl` (Claude Code) is where the authorization server's metadata is, for a server that doesn't publish it. Enconvo reads it instead of looking at the server's well-known addresses, and shows **Sign in** for the server even when they answer nothing. It has to use `https://`; Enconvo also reads `http://` from `localhost` while you test, which Claude Code doesn't. When the address can't be read, Enconvo looks the usual way.
`enconvo plugin validate` warns about an `oauth_resource` on another origin and an `authServerMetadataUrl` that isn't `https://`.
### Which tools run, and when Enconvo asks
Codex's fields for a server's tools work in Enconvo too:
```json theme={null}
{
"mcpServers": {
"tracker": {
"type": "http",
"url": "https://mcp.example.com/mcp",
"disabled_tools": ["delete_project"],
"default_tools_approval_mode": "writes",
"tools": {
"search": { "approval_mode": "auto" },
"send_invoice": { "approval_mode": "prompt" }
}
}
}
}
```
* `enabled_tools` offers only the tools it lists; `disabled_tools` hides the ones it lists.
* `default_tools_approval_mode` sets how all the server's tools are approved, and `tools..approval_mode` sets it for one tool:
| Mode | In Enconvo |
| - | - |
| `prompt` | Asks before every call. |
| `writes` | Asks before every call to a tool that doesn't declare `readOnlyHint: true`. |
| `auto` | Asks as for any tool: by its annotations and the Agent's [Permissions](/ai/agents) setting. |
| `approve` | The same as `auto`. Codex runs the tools without asking; in Enconvo only the person turns questions off, with the Permissions chip. |
Each answer covers one call; Enconvo doesn't offer to remember it for the chat. When the Permissions chip is **Full access**, Enconvo doesn't ask. `enconvo plugin validate` reports a mode it doesn't know as an error, since Codex won't load it, and warns about `approve`.
## Skills
Enconvo loads every `skills//SKILL.md`, the skill folders named by the manifest's `skills` field (not in a portable plugin), and a `SKILL.md` at the plugin's root. A skill's `SKILL.md` starts with its `name` and a `description` of when to use it:
```markdown theme={null}
---
name: summarize-notes
description: Summarizes a set of notes into key points. Use when the user asks for a summary of their notes.
---
Instructions the agent follows when it uses the skill.
```
From Enconvo 2.5.7, Enconvo reads this frontmatter as YAML, the way Claude Code does. A `description` that wraps over several lines, starts on the line below `description:`, uses quotes and escapes, or is folded with `>` reaches the agent as Claude Code shows it. The same goes for a Claude Code command's frontmatter. A list becomes its text, as in Claude Code: `argument-hint: [file]` reads `file`, so quote it (`argument-hint: "[file]"`) to keep the brackets. Frontmatter that isn't valid YAML is still read a line at a time. `enconvo plugin validate` reports it, because Claude Code then loads the file without its description (see [validation codes](/extensions/validation-codes#claude-code-agents-and-commands)). A plugin installed before then picks up the new descriptions when it updates or is installed again.
An `agents/openai.yaml` next to it sets how Codex and Enconvo list the skill:
```yaml theme={null}
interface:
display_name: "Summarize Notes"
short_description: "Key points from your notes"
default_prompt: "Summarize my notes from this week"
policy:
allow_implicit_invocation: false # only when the user picks it
```
`display_name` becomes the skill's title in Enconvo. With `allow_implicit_invocation: false`, or Claude Code's `disable-model-invocation: true` in `SKILL.md`, the agent doesn't pick the skill on its own and uses it only when someone asks for it.
From Enconvo 2.5.7, `short_description` is the line the `/` and `$` menus and the SmartBar's skill search show under the skill's name, and those searches match it. Without it, Enconvo uses `short-description` under `metadata` in the `SKILL.md` frontmatter, as Codex does, and then the `description`:
```markdown theme={null}
---
name: summarize-notes
description: Summarizes the user's notes for a date range, grouped by project, with open questions and decisions listed separately.
metadata:
short-description: Key points from your notes
---
```
Keep it short; Codex ignores a `short_description` longer than 1,024 characters, and so does Enconvo. The agent always reads the full `description` to decide when to use the skill.
From Enconvo 2.5.7, the MCP servers a skill needs, listed under `dependencies.tools` the way Codex lists them, work in Enconvo too:
```yaml theme={null}
dependencies:
tools:
- type: "mcp"
value: "linear"
description: "Linear MCP server"
transport: "streamable_http" # the default; or "stdio" with a command
url: "https://mcp.linear.app/mcp"
```
When the agent loads the skill, Enconvo connects the MCP server you added with that URL (or, for `stdio`, that command), whatever you named it, even if it's switched off, and gives the agent its tools. As in Codex, a server counts by what it runs, not by its name. For a server you haven't added, one that needs you to sign in, or one that can't connect, the agent is told which it is and how to fix it, and asks you before it adds a server or opens a sign-in. Other `transport` values are skipped, as they are in Codex.
From Enconvo 2.5.7, two more Claude Code fields in `SKILL.md` work as they do in Claude Code:
```markdown theme={null}
---
name: triage-crash
description: Reads a crash log and names the likely cause.
when_to_use: Use when the user pastes a stack trace or a crash report.
user-invocable: false
---
```
* `when_to_use` is added to the description the agent sees (`description - when_to_use`), and skill search matches it too.
* `user-invocable: false` keeps the skill out of the `/` and `$` menus and the SmartBar's skill search, for skills that only make sense when the agent picks them. The agent still sees and uses it.
Yes-or-no fields are read as Claude Code reads them: `true`, `yes`, `on` and `1` mean yes, and `false`, `no`, `off` and `0` mean no. Any other `user-invocable` value also hides the skill from the menus.
From Enconvo 2.5.7, the agent reads a skill with Claude Code's variables filled in, so a skill can run its own scripts:
```markdown theme={null}
Run `python3 ${CLAUDE_SKILL_DIR}/scripts/report.py --region ${user_config.region}`.
```
| Variable | Becomes |
| - | - |
| `${CLAUDE_SKILL_DIR}` | The skill's own folder, in any skill |
| `${CLAUDE_PLUGIN_ROOT}` | The plugin's installed folder |
| `${CLAUDE_PLUGIN_DATA}` | The plugin's data folder, kept across updates (created when a skill names it) |
| `${user_config.KEY}` | The plugin's setting `KEY`. A sensitive setting shows as `[hidden: the "" setting]`, and one that's empty as `[not set: the "<title>" setting]` |
Only these names, written with braces, are filled in: `$HOME` and other `${…}` text reaches the agent as written. As in Claude Code, a name is filled in wherever it appears, including in examples.
Skills keep their plain names. When two plugins both ship a skill with the same name, such as `configure`, the agent sees each one as `<plugin>:<name>` (`telegram:configure`, `discord:configure`), the name Claude Code gives it. A skill that names another as `/telegram:access` loads that plugin's copy.
### Claude Code commands
From Enconvo 2.5.7, a Claude Code plugin's commands install as skills, the way Claude Code treats them: every `commands/<name>.md`. The file name is the skill's name (a command in `commands/git/push.md` becomes `git-push`), and a skill with the same name wins. The `description`, or the file's first line, describes it.
As in Claude Code, a `commands` field in the manifest replaces the `commands/` folder: list the folders or `.md` files to install (`[]` installs none), or map each command's name to a `source` file or inline `content`:
```json theme={null}
{
"commands": {
"status": { "source": "./commands/status.md", "description": "Show the deployment status", "argumentHint": "[env]" },
"about": { "content": "Describe what this plugin does.", "description": "Describe this plugin" }
}
}
```
An entry needs exactly one of `source` and `content`; its `description` and `argumentHint` win over the file's frontmatter. `enconvo plugin validate` reports entries Claude Code would reject, and warns when the field leaves out a `commands/` folder the plugin ships. It also reads the frontmatter of every command, agent and skill as Claude Code does and reports YAML Claude Code can't parse, since Claude Code then loads the file without its description and other fields (see [validation codes](/extensions/validation-codes#claude-code-agents-and-commands)).
```markdown theme={null}
---
description: Create a git commit
argument-hint: [message]
---
Current status: !`git status`
Commit the staged changes with the message $ARGUMENTS.
```
* `${CLAUDE_PLUGIN_ROOT}` and `${CLAUDE_PLUGIN_DATA}` become the plugin's installed folder and its data folder, and `${user_config.KEY}` the plugin's setting, as in [skills](#skills).
* `$ARGUMENTS`, `$1` and named `arguments` stand for what the person wrote with the command, and the agent runs `` !`command` `` lines and ` ```! ` blocks with its shell tool before it follows the rest.
* `disable-model-invocation: true` (or the older `hide-from-slash-command-tool: "true"`) makes it a skill only people start.
* `user-invocable: false` keeps it out of the `/` and `$` menus, and `when_to_use` is added to what the agent sees, as in [skills](#skills).
* `allowed-tools` and `model` are ignored: the agent keeps its usual tools, model and approvals.
A plugin installed with an earlier Enconvo gets its commands the next time Enconvo starts.
When another plugin has a command or skill of the same name, the agent sees each one as `<plugin>:<name>`, as Claude Code names them (see [Skills](#skills)). A specific name such as `commit-push-pr` still reads better than `help`.
## Agents
From Enconvo 2.5.7, a Claude Code plugin's agents (every `agents/<name>.md`, or only the `.md` files the manifest's `agents` field lists, which replaces the folder as in Claude Code) become helpers that an agent can hand work to, in any chat running in Agent mode. They also appear in the composer's `@` menu after Explorer and Subagent. Enconvo reads the same frontmatter Claude Code does:
```markdown theme={null}
---
name: code-reviewer
description: Reviews a diff for bugs. Use after editing code.
tools: Read, Grep, Glob
model: sonnet
---
Review the changes for bugs. Read ${CLAUDE_PLUGIN_ROOT}/checklist.md first.
```
* `description` tells the agent when to use the helper. `<example>` blocks are left out of what it sees.
* A `tools` list with only reading tools (`Read`, `Grep`, `Glob`, `WebFetch`, …), or `permissionMode: plan`, makes the helper read-only. Other tool lists limit what it may call.
* `model` is used when the chat's model provider has a matching model, and the helper otherwise runs on the chat's model.
* `${CLAUDE_PLUGIN_ROOT}` and `${CLAUDE_PLUGIN_DATA}` become the plugin's installed folder and its data folder.
A project's own helper (in `.claude/agents/`, `.codex/agents/` or `.enconvo/agents/`) keeps its name. A plugin helper whose name is already taken, by a project helper, another plugin or a built-in role such as `explorer`, gets the plugin's name in front (`pr_review_toolkit_code_reviewer`). An agent is offered at most 20 helpers, the project's first.
## Hooks
A Claude Code or Codex plugin's hooks run commands on the person's Mac when something happens in a chat. Enconvo finds them where Claude Code and Codex do: the manifest's `hooks` field (a path, several paths, or the hooks themselves), `extensions["com.openai"].hooks`, `hooks/hooks.json`, and a `hooks.json` at the plugin's root.
```json theme={null}
{
"hooks": {
"PreToolUse": [
{ "matcher": "Bash", "hooks": [{ "type": "command", "command": "./scripts/guard.sh", "timeout": 10 }] }
],
"SessionStart": [
{ "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/session-start.mjs\"" }] }
]
}
}
```
Because they run commands, a plugin's hooks install turned off. People allow them in the install preview, or later with the **Allow hooks** switch on the plugin's page. Allowing covers the hooks as they are: when an update changes them, they turn off again until the person checks the new commands and allows them.
| Event | When it runs |
| - | - |
| `SessionStart` | A new chat starts |
| `UserPromptSubmit` | A message is sent |
| `PreToolUse` | Before a tool runs; it can block the tool |
| `PermissionRequest` | A tool asks for approval |
| `PostToolUse` | After a tool runs |
| `Stop`, `SubagentStop` | The reply, or a subagent, finishes; it can ask the agent to continue |
* **Matchers**: a tool event's `matcher` is a regular expression tested against the Enconvo tool's name, title and command. A `SessionStart` matcher that doesn't match `startup` never fires, since Enconvo only starts new chats.
* **Commands**: a command that starts with `./` runs the file in your plugin. Each command gets `PLUGIN_ROOT` and `PLUGIN_DATA` (and the `CLAUDE_PLUGIN_ROOT` and `CLAUDE_PLUGIN_DATA` names) in its environment, the plugin's settings as `CLAUDE_PLUGIN_OPTION_<KEY>` (see [Settings](#settings)), and the event as JSON on stdin. A hook that runs in a chat with a working folder starts there and gets it as `CLAUDE_PROJECT_DIR`.
* **Timeouts**: `timeout` is in seconds, 60 by default and at most 600. A hook marked `async` starts and isn't waited for.
* **Skipped**: other events (such as `PostToolBatch` or `PreCompact`), hooks whose `type` isn't `command`, hooks with an `if` permission rule, and shell commands that name `${user_config.KEY}` don't run in Enconvo. The preview and the plugin's page list them.
For hooks that also work in Claude Code and Codex, put them in `hooks/hooks.json`, which both read (Codex only when its manifest's `hooks` names nothing else), and keep to what both take: `command` hooks with the whole command line in `command`, since Codex has no `args`, each `${CLAUDE_PLUGIN_ROOT}` path in double quotes, a whole number of seconds in `timeout`, and only `description` and `hooks` at the top of the file. Hooks written in a manifest differ between the two: Claude Code's `hooks` holds the events themselves, Codex's a whole hooks file, `{"hooks": {…}}`. Claude Code doesn't load a plugin whose hooks file isn't valid JSON, and applies none of a file's hooks when it can't read one under `PreToolUse` or `PermissionRequest`; Codex skips a whole file over a top-level field other than `description` and `hooks`, or a hook type it doesn't know. `plugin validate` reports each of these with what each app does (see [Hooks](/extensions/validation-codes#hooks)).
Enconvo's store takes a plugin with hooks, but OpenAI's portal can't take one yet, and neither can it take app references (`apps` or `.app.json`). `plugin validate --openai` flags both, so leave them out of the package you upload there.
## Settings
Enconvo turns a Claude Code plugin's `userConfig`, and a desktop extension's `user_config`, into the plugin's settings. Until required settings are filled in, the plugin shows **Need configure** on the Plugins page, and `plugin install` says which settings it needs.
```json .claude-plugin/plugin.json theme={null}
{
"name": "my-database",
"userConfig": {
"region": { "type": "string", "title": "Region", "description": "Where your database runs", "options": ["us-east1", "europe-west1"], "default": "us-east1" },
"password": { "type": "string", "title": "Password", "description": "Your database password", "sensitive": true, "required": true }
},
"mcpServers": {
"db": {
"command": "npx",
"args": ["-y", "my-database-mcp", "--region", "${user_config.region}"],
"env": { "DB_PASSWORD": "${user_config.password}" }
}
}
}
```
* **Types**: `string` becomes a text field, or a password field when `sensitive`; a `string` with `options` becomes a dropdown. `number`, `boolean`, `file` and `directory` keep their types, and `required`, `default` and `multiple` carry over.
* **In MCP servers**: `${user_config.KEY}` in a server's `command`, `args`, `env`, `cwd`, `url` or `headers` becomes the setting's value. A setting with several values is joined with commas, or, when it's the whole argument, becomes one argument per value.
* **Sensitive settings** are filled in only as the server starts, so they never appear in Enconvo's saved server settings.
* **Missing settings**: a server that needs a required setting you haven't filled in doesn't start, and says which setting to fill in. An optional setting left empty becomes an empty value.
* **Changes**: saving a setting on the plugin's page restarts the servers that use it, with the new value.
* **Checks**: Claude Code doesn't load a plugin with a setting outside its rules, such as one without a `title` and `description`, or a `${user_config.KEY}` in a server for a key no setting declares. Enconvo is more lenient, so run `enconvo plugin validate` to catch them before you share the plugin (see [Claude Code settings and channels](/extensions/validation-codes#claude-code-settings-and-channels)).
* **In skills and commands**: `${user_config.KEY}` in a skill's or command's text becomes the setting's value when the agent loads it (see [Skills](#skills)). A sensitive setting stays out of the conversation.
* **In hooks**: each setting is in a hook's environment as `CLAUDE_PLUGIN_OPTION_<KEY>`, the key in capitals (`api_token` becomes `CLAUDE_PLUGIN_OPTION_API_TOKEN`), with the saved value or the default. `true`/`false` and numbers are written as text, and several values are joined with commas. `${user_config.KEY}` works in a hook's `args`, but not in a shell `command`, where a value could run as code: as in Claude Code, such a hook doesn't run.
```json hooks/hooks.json theme={null}
{
"hooks": {
"Stop": [
{ "hooks": [{ "type": "command", "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/report.mjs", "--region=${user_config.region}"] }] }
]
}
}
```
A sensitive setting reaches the hooks that can change what the agent does (`PreToolUse`, `Stop` and `SubagentStop`). The other events' hooks run without it, and a hook that names it in `args` doesn't start for those events.
### Channel settings
A Claude Code channel binds a message channel, such as a chat-app bridge, to one of the plugin's MCP servers. Settings a channel asks for in its own `userConfig` appear on the plugin's settings page after the plugin's own, titled with the channel's `displayName` (such as **Telegram: Bot token**), and fill `${user_config.KEY}` only in that server's `env`:
```json .claude-plugin/plugin.json theme={null}
{
"name": "chat-bridge",
"mcpServers": {
"telegram": {
"command": "node",
"args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
"env": { "BOT_TOKEN": "${user_config.bot_token}" }
}
},
"channels": [
{
"server": "telegram",
"displayName": "Telegram",
"userConfig": {
"bot_token": { "type": "string", "title": "Bot token", "description": "Telegram bot token", "sensitive": true, "required": true }
}
}
]
}
```
A channel's setting can share its key with one of the plugin's own settings or another channel's: each is saved apart, and the server's `args`, `url` and headers, like every other server, still use the plugin's own settings. Hooks see a channel setting as `CLAUDE_PLUGIN_OPTION_CHANNEL__<SERVER>__<KEY>`.
## What Enconvo doesn't load
| Part | What happens |
| - | - |
| ChatGPT apps (`.app.json`) | The plugin's page says it needs a ChatGPT app, and Enconvo installs the rest of the plugin. An app counts as needed unless its entry says `"required": false` or `"optional": true`, as OpenAI's own plugins mark the apps they can do without. |
| Claude Code LSP servers, monitors, output styles, workflows, themes and syntax highlighting languages (`lspServers`, `.lsp.json`, `experimental.monitors`, `outputStyles`, `workflows`, `experimental.themes`, `experimental.syntaxHighlighting`) | Not loaded; Enconvo installs the rest of the plugin. `plugin validate` still checks them as Claude Code does, so the plugin keeps loading there, and warns that Enconvo skips them (`plugin_component_not_loaded`). Declare themes and monitors under `experimental`, and keep `${user_config.*}` out of a monitor's command: Claude Code won't start it. |
| Claude Code `binaries` | Not fetched. Claude Code downloads the files `binaries` lists into the plugin's `bin/` when it installs the plugin; Enconvo installs the plugin without them, so hooks and servers that run them work only in Claude Code (`plugin_binaries_not_fetched`). |
## Check a package
```sh theme={null}
npx -p @enconvo/api enconvo plugin validate # Enconvo, Codex and Claude Code rules
npx -p @enconvo/api enconvo plugin validate --openai # also OpenAI's portal rules
npx -p @enconvo/api enconvo plugin scan # starts the MCP servers and checks their tools
```
`plugin validate` reads every format above and names each problem with a code. `plugin scan` starts the MCP servers the package declares, wherever it declares them, the way Enconvo starts them once the plugin is installed, so a server that works only when started from your project folder fails there too. See [Validation Codes](/extensions/validation-codes) for what each one means, and [Installing Plugins](/extensions/installing-plugins) to try the package in Enconvo.
# AI Model and Voice Plugins
Source: https://docs.enconvo.ai/extensions/provider-plugins
Add your own AI model or text-to-speech provider to Enconvo's pickers with a plugin.
A provider plugin adds a service Enconvo already has a picker for. Once it is installed, its AI model shows up in the model picker next to OpenAI, Anthropic and the rest, and its voice shows up in the text-to-speech voice list. Chats, agents, read-aloud and workflows then use it exactly like a built-in provider.
This page builds one plugin, `acme_ai`, with both kinds: a chat model for an OpenAI-compatible API and a text-to-speech voice. It assumes you have read [Developing Extensions](/extensions/developing).
<Note>
Provider plugins need Enconvo 2.5.6 or later. Set `"minAppVersion": "2.5.6"` in `package.json`.
</Note>
## How a provider plugin fits in
```text theme={null}
acme_ai/
├── package.json # two provider commands + the API key preference
├── assets/icon.png
└── src/
├── chat.ts # the AI model provider → commandType "provider", provider_category "llm"
├── say.ts # the voice provider → commandType "provider", provider_category "tts"
└── api/
├── models.ts # the model list the picker shows (route acme_ai/models)
└── voices.ts # the voice list (route acme_ai/voices)
```
Start from the scaffold (`npx -p @enconvo/api enconvo plugin create acme_ai`), then replace its sample command with the files below.
* Each provider is a command with `"commandType": "provider"` and a `provider_category`: `llm` for AI models, `tts` for voices.
* Its source file exports `main(options)`, which returns an instance of the SDK base class (`LLMProvider` or `TTSProvider`). Enconvo creates the instance and calls it; the plugin never runs as a standalone command.
* Enconvo names a plugin's provider by its full command key, `acme_ai|chat`, so it can never clash with a built-in one such as `llm|open_ai`.
* Installing a plugin never makes its provider the default. Users choose it in the picker. If the plugin is uninstalled, anything that had it selected goes back to the default.
## The manifest
```json theme={null}
{
"$schema": "https://enconvo.com/schemas/extension.json",
"name": "acme_ai",
"version": "1.0.0",
"title": "Acme AI",
"description": "Acme AI chat models and voices in Enconvo.",
"icon": "icon.png",
"author": "your-name",
"type": "module",
"minAppVersion": "2.5.6",
"categories": ["Productivity"],
"preferences": [
{
"name": "api_key",
"title": "API Key",
"description": "Your Acme AI API key.",
"type": "password",
"required": true
}
],
"commands": [
{
"name": "chat",
"title": "Acme AI",
"description": "Chat with Acme AI models.",
"icon": "icon.png",
"commandType": "provider",
"provider_category": "llm",
"mode": "no-view",
"private": true,
"preferences": [
{
"name": "modelName",
"title": "Model",
"type": "dropdown",
"dataProxy": "acme_ai/models",
"default": "acme-large"
}
]
},
{
"name": "say",
"title": "Acme AI Voice",
"description": "Read text aloud with Acme AI voices.",
"icon": "icon.png",
"commandType": "provider",
"provider_category": "tts",
"private": true,
"preferences": [
{
"name": "voice",
"title": "Voice",
"type": "dropdown",
"dataProxy": "acme_ai/voices",
"default": "alloy"
}
]
}
]
}
```
Keep the `scripts`, `dependencies` and `devDependencies` that `enconvo plugin create` wrote. What matters here:
* `"private": true` keeps the provider out of the command list; it is only reached through the pickers.
* The preference names are fixed: an AI model provider reads its model from `modelName`, and a voice provider reads its voice from `voice`. The pickers write to those names.
* `dataProxy` points at the plugin's own API route (`acme_ai/models`). The `default` is the `value` of one item in that list. At run time Enconvo hands the provider the whole item, so the code reads `this.options.modelName.value`.
* A preference at the top level of the manifest, like `api_key`, is shared by every command and route in the plugin. Users fill it in on the plugin's page in Settings, and the provider reads it as `this.options.api_key`. Use `"type": "password"` for keys so they are stored encrypted.
* `isDefault` and `sort` are removed when a plugin is installed; a plugin can't put its provider first or make it the default.
* The routes in `src/api/` need no entry in `commands`; the build adds them.
## The model and voice lists
The picker calls the `dataProxy` route whenever it opens, so the route must answer fast. The simplest route returns a fixed list.
`src/api/models.ts`:
```typescript theme={null}
/**
* The models the Acme AI provider offers, for the model picker.
* @private
*/
export default async function main(_req: Request) {
return Response.json([
{ type: "llm_model", title: "Acme Large", value: "acme-large", context: 128000, maxTokens: 8192, toolUse: false, visionEnable: false },
{ type: "llm_model", title: "Acme Small", value: "acme-small", context: 32000, maxTokens: 4096, toolUse: false, visionEnable: false },
])
}
```
Each model item has:
| Field | Meaning |
| - | - |
| `type` | Always `"llm_model"` |
| `title` | The name shown in the picker |
| `value` | The model id sent to your API |
| `context` | The context window, in tokens. Enconvo trims long chats to fit it. |
| `maxTokens` | The most tokens the model may write in one reply |
| `toolUse` | Whether the model can call tools. With `false`, agents chat with it without tools. |
| `visionEnable` | Whether the model accepts images |
To list the models your API offers instead, fetch them inside `ListCache`. It keeps the list until the user refreshes it in the picker, and the plugin's preferences, such as `api_key`, arrive in the options:
```typescript theme={null}
import { ListCache, type RequestOptions } from "@enconvo/api"
async function fetchModels(options: RequestOptions): Promise<ListCache.ListItem[]> {
const resp = await fetch("https://api.acme.ai/v1/models", {
headers: { Authorization: `Bearer ${options.api_key}` },
})
if (!resp.ok) return []
const body = (await resp.json()) as { data: { id: string }[] }
return body.data.map((model) => ({
type: "llm_model",
title: model.id,
value: model.id,
context: 128000,
maxTokens: 8192,
toolUse: false,
visionEnable: false,
}))
}
/** @private */
export default async function main(req: Request) {
const options = (await req.json().catch(() => ({}))) as RequestOptions
return Response.json(await new ListCache(fetchModels).getList(options))
}
```
`src/api/voices.ts`:
```typescript theme={null}
/**
* The voices the Acme AI provider offers, for the voice picker.
* @private
*/
export default async function main(_req: Request) {
return Response.json([
{ title: "Alloy", value: "alloy" },
{ title: "Nova", value: "nova" },
])
}
```
`@private` keeps these routes out of the plugin's generated API docs, since only the pickers call them.
## An AI model provider
Extend `LLMProvider` and implement two methods:
* `_call(params)` returns the whole reply as an `AssistantMessage`.
* `_stream(params)` returns a `Stream` of reply events as they arrive. Chats use this one.
`src/chat.ts`, for an API that follows OpenAI's chat completions format:
```typescript theme={null}
import {
AssistantMessage,
BaseChatMessage,
BaseChatMessageChunk,
BaseChatMessageLike,
LLMProvider,
Stream,
} from "@enconvo/api"
const BASE_URL = "https://api.acme.ai/v1"
export default function main(options: any) {
return new AcmeChat(options)
}
class AcmeChat extends LLMProvider {
protected async _call(params: LLMProvider.ResolvedParams): Promise<BaseChatMessage> {
const resp = await this.complete(params, false)
const data = await resp.json()
return new AssistantMessage(data.choices?.[0]?.message?.content ?? "")
}
protected async _stream(params: LLMProvider.ResolvedParams): Promise<Stream<BaseChatMessageChunk>> {
const controller = new AbortController()
const resp = await this.complete(params, true, controller)
const chunks = Stream.fromSSEResponse<any>(resp, controller)
// Enconvo reads a stream of content blocks: start a text block, send its
// pieces as text deltas, then stop it.
async function* events(): AsyncGenerator<BaseChatMessageChunk> {
let open = false
for await (const chunk of chunks) {
const text = chunk.choices?.[0]?.delta?.content
if (!text) continue
if (!open) {
open = true
yield { type: "content_block_start", content_block: { type: "text", text: "" } }
}
yield { type: "content_block_delta", delta: { type: "text_delta", text } }
}
if (open) yield { type: "content_block_stop" }
}
return new Stream(events, controller)
}
private async complete(params: LLMProvider.ResolvedParams, stream: boolean, controller = new AbortController()) {
params.signal?.addEventListener("abort", () => controller.abort())
const resp = await fetch(`${BASE_URL}/chat/completions`, {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${this.options.api_key}`,
},
body: JSON.stringify({
model: this.options.modelName?.value,
messages: toChatMessages(params.messages),
stream,
}),
signal: controller.signal,
})
if (!resp.ok) {
throw new Error(`Acme AI ${resp.status}: ${await resp.text()}`)
}
return resp
}
}
// Each Enconvo message holds a list of parts (text, images, files, tool steps).
// This provider only sends the text.
function toChatMessages(messages: BaseChatMessageLike[]) {
return messages
.filter((m) => m.role === "system" || m.role === "user" || m.role === "assistant")
.map((m) => ({
role: m.role,
content: m.content.map((part) => (part.type === "text" ? part.text : "")).join(""),
}))
.filter((m) => m.content.length > 0)
}
```
### The stream events
`_stream` does not pass your API's chunks through. It yields Enconvo's content-block events, which follow Anthropic's streaming format:
| Event | When |
| - | - |
| `{ type: "content_block_start", content_block: { type: "text", text: "" } }` | A text block begins |
| `{ type: "content_block_delta", delta: { type: "text_delta", text } }` | More text for the open block |
| `{ type: "content_block_start", content_block: { type: "thinking", thinking: "" } }` | A reasoning block begins |
| `{ type: "content_block_delta", delta: { type: "thinking_delta", thinking } }` | More reasoning text |
| `{ type: "content_block_stop" }` | The open block ends |
Close each block before you start the next one. `Stream.fromSSEResponse` reads a server-sent events response and skips OpenAI's `[DONE]` line; for any other format, parse the response yourself inside the generator. Abort the controller when `params.signal` fires, so that the Stop button ends the request.
### Messages
`params.messages` is the conversation, already trimmed to the model's context window. Each message has a `role` (`system`, `user`, `assistant` or `tool`) and a `content` list of parts: `text`, `image_url`, `file`, and `flow_step` for earlier tool calls. The example keeps only the text, which is enough for a model with `toolUse: false` and `visionEnable: false`.
To offer images, set `visionEnable: true` on the model and send the `image_url` parts in your API's image format.
To offer tools, set `toolUse: true` and send `params.tools` to your API. Stream each call back as a `tool_use` block: `content_block_start` with `{ type: "tool_use", id, name, input: {} }`, then `content_block_delta` events with `{ type: "input_json_delta", partial_json }`. Turn the `flow_step` parts of earlier messages back into your API's tool call and tool result messages. Enconvo runs the tools and calls the model again with the results.
## A text-to-speech provider
Extend `TTSProvider` and implement `_toFile`. It gets the text and the path to write, and returns the path once the audio is there.
`src/say.ts`:
```typescript theme={null}
import fs from "node:fs"
import { TTSProvider } from "@enconvo/api"
const BASE_URL = "https://api.acme.ai/v1"
export default function main(options: any) {
return new AcmeVoice({ options })
}
class AcmeVoice extends TTSProvider {
protected async _toFile({ text, audioFilePath, voice, speed, format }: TTSProvider._ToFileTTSParams): Promise<TTSProvider.TTSItem> {
const resp = await fetch(`${BASE_URL}/audio/speech`, {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${this.options.api_key}`,
},
body: JSON.stringify({ model: "acme-tts", input: text, voice, speed, response_format: format }),
})
if (!resp.ok) {
throw new Error(`Acme AI ${resp.status}: ${await resp.text()}`)
}
await fs.promises.writeFile(audioFilePath, Buffer.from(await resp.arrayBuffer()))
return { path: audioFilePath, text }
}
}
```
The `TTSProvider` constructor takes `{ options }`, while `LLMProvider` takes the options themselves.
* `voice` is the `value` of the voice the user picked.
* `format` is the file type to write, `mp3` unless the caller asks for another. `audioFilePath` already ends in it.
* `speed` is a number, 1 for normal speed. Send it on if your API supports it.
* If your provider returns a path to an empty or missing file, Enconvo reports an error instead of playing silence.
## Try it and publish it
```sh theme={null}
npm install
npm run dev
```
`npm run dev` builds the plugin into Enconvo and rebuilds it whenever you save.
1. Open the plugin's page in Enconvo's Settings and enter the API key.
2. Open the model picker in a chat. Acme AI is listed with the other providers; pick a model and send a message. The reply streams in as your `_stream` yields it.
3. In the text-to-speech settings, pick Acme AI Voice and play a voice preview, or select some text and read it aloud.
If something fails, the error your provider throws is shown in the chat or the preview, so put the API's status and message in it, as the examples do.
When it works, publish it like any other plugin:
```sh theme={null}
npm run validate
npx enconvo plugin publish -m "First release"
```
<Tip>
The **Plugin Development Guide** plugin in Enconvo's plugin store carries this guide as a skill, so an agent in Enconvo can help you build a provider plugin.
</Tip>
# Plugin Store Guidelines
Source: https://docs.enconvo.ai/extensions/publishing-guidelines
What Enconvo's reviewers check before a plugin appears in the store, and the review materials to send with it.
Enconvo reviews every version submitted to the plugin store before anyone else can install it. These guidelines apply to every kind of plugin the store takes: Enconvo, Codex, Claude Code and portable plugins, including plugins made only of skills. They follow [OpenAI's plugin guidelines](https://developers.openai.com/apps-sdk/app-submission-guidelines), so a plugin that meets them is also close to ready for OpenAI's plugin portal.
Before you submit, run:
```sh theme={null}
npx -p @enconvo/api enconvo plugin validate # the store's rules
npx -p @enconvo/api enconvo plugin validate --openai # also OpenAI's portal rules
npx -p @enconvo/api enconvo plugin scan # starts the MCP server and checks its tools
```
`validate` catches what can be checked automatically, and `scan` checks the tools of a plugin with an MCP server; [Validation Codes](/extensions/validation-codes) explains each problem they report. Reviewers check the rest by hand, as described below.
## Purpose and quality
* The plugin does something useful that Enconvo can't already do, and does it completely. Placeholder, demo-only or trial versions are turned down.
* It behaves predictably. When something fails, such as a network error, a missing permission or a bad input, it says what happened instead of failing silently.
* It uses only code, names, icons and content you own or are licensed to use. It doesn't impersonate another product, and doesn't suggest that Enconvo or anyone else endorses it.
## Name, description and listing
* **Name and title**: clear and specific. Avoid a generic single word, and don't add "MCP", "MCP Server" or "Plugin" to a company name.
* **Description**: says what the plugin does, accurately. No comparisons with other products, claims you can't back up, or prices, discounts and free-trial offers.
* **Icon and screenshots**: the icon is a PNG, JPEG, WebP or GIF of up to 5 MB. Up to 8 screenshots go in a `metadata/` folder and are shown in file name order. They show the plugin as it really works.
* **Support**: give people a way to reach you: `interface.websiteURL` and `interface.supportURL`, or `homepage` or `repository` for the website. A Claude Code plugin can use its `supportUrl` and `documentationUrl` instead. The store page shows these links before anyone installs the plugin.
* **Version**: raise it for every update. While an update is in review, the store keeps offering the version before it. `plugin publish` asks the store which version it released before it builds or uploads anything, and stops with the next version to use when yours isn't higher.
## MCP tools
When the plugin brings an MCP server, reviewers read its tools as the AI model will.
* **Names** are plain verbs that say what the tool does, such as `get_order_status`, and are unique within the server. No jargon or unexplained abbreviations.
* **Descriptions** explain what the tool does, what it changes and what it can't do, and match its input schema and real behavior. They don't tell the model to prefer this plugin, to call other plugins, or to call the tool for everything.
* **One operation per tool**, each with its own input schema.
* **Annotations** are set explicitly on every tool:
| Annotation | `true` when the tool | `false` when it |
| - | - | - |
| `readOnlyHint` | only reads, computes or previews | changes anything: writes, saves a file, sends, posts, uploads, queues work or starts a job |
| `destructiveHint` | deletes, overwrites, cancels or sends something that can't be taken back, even if the user could undo it | only adds |
| `openWorldHint` | reaches public or open-ended content, such as a web search, or sends to any address | stays inside a bounded account, workspace or catalog, even one hosted elsewhere |
Enconvo relies on these annotations. A tool marked `readOnlyHint: true` runs without asking the user and alongside other reads. A tool marked `destructiveHint: true` asks the user first unless they have given the agent full access. A tool that changes something but claims to be read-only is turned down.
`enconvo plugin scan` starts the plugin's MCP server, lists its tools with their annotations, and names each tool that leaves one out ([`annotations_required`](/extensions/validation-codes#mcp-server-scan)).
A tool that shows its own interface names its view, a `ui://` resource, in `_meta.ui.resourceUri`, and the view declares the domains it reaches in `_meta.ui.csp` (`connectDomains`, `resourceDomains`, `frameDomains`). These are the MCP Apps keys every host reads. Enconvo also reads ChatGPT's `_meta["openai/outputTemplate"]` and `_meta["openai/widgetCSP"]`, and gives a view written for ChatGPT (`text/html+skybridge`, or a tool named only by `openai/outputTemplate`) the `window.openai` API it calls, so a plugin built for ChatGPT shows its interface in Enconvo unchanged. Set the MCP Apps keys as well, so other hosts show it too. `scan` reads each view as Enconvo does and says when one is set only the OpenAI way.
## Data and privacy
* **Ask only for what the task needs.** Tool inputs are specific to the task. Don't ask for the whole conversation, earlier messages or broad profile data "just in case".
* **Return only what answers the request.** Leave internal ids, trace data and debugging output out of tool results.
* **Never collect** payment card data, health records, government ids such as social security numbers, or passwords, API keys and one-time codes through tool inputs. Credentials go in the plugin's preferences, where Enconvo keeps them.
* **Privacy policy.** A plugin that sends data to a server needs a published privacy policy saying what it collects, why, who receives it, how long it is kept and how people can delete it. Put its address in `interface.privacyPolicyURL`, and the terms of service, if you have them, in `interface.termsOfServiceURL`. The store page links both.
* **No tracking** of people, their queries or their usage beyond what the plugin needs to work and what its privacy policy discloses.
* **Keep secrets out of the package.** Anyone can download it. `.env` files are left out automatically, but check that no other keys or private files end up in it.
## Sign-in and test accounts
If the plugin needs an account, sign-in is explicit and asks only for the permissions it needs. Reviewers need to try it without creating an account or receiving a two-factor code, so give them a demo account that has sample data:
```sh theme={null}
npx -p @enconvo/api enconvo plugin publish --review-notes "Sign in as review@example.com with the password …"
```
Reviewer notes go only to Enconvo's reviewers. They aren't part of the package or the store listing.
## Commerce
A plugin may work with an account people already pay for, and may say when a feature needs a different plan. If it sells something or takes payments, say so in the review materials (`commerce` and `commerce_description`, below): what is sold and where people pay. People pay on your own site; the plugin doesn't hide charges or charge Enconvo users more than everyone else.
OpenAI's portal is stricter. It takes plugins that sell physical goods only, and no subscriptions, credits or other digital products. Check its [commerce rules](https://developers.openai.com/apps-sdk/app-submission-guidelines) before you submit there.
## Safety
* The plugin is suitable for a general audience, including teenagers, and doesn't target children under 13.
* It does what the user asked and nothing else: no unrelated content, redirects or ads.
* Its descriptions, prompts and skills never ask for secrets, move money or data without the user's say, try to override Enconvo's safeguards, or hide what the plugin does, including through encoded instructions.
* It doesn't scrape websites or wrap other services against their terms, or get around their rate limits and access controls.
* It doesn't sell or enable anything in OpenAI's list of [prohibited goods and services](https://developers.openai.com/apps-sdk/app-submission-guidelines), such as weapons, drugs, gambling, adult content, malware or financial fraud.
## Review materials
Review materials tell reviewers what to try: prompts the plugin should handle, prompts it should leave alone, and a short demo video. They are stored with each version and shown only to reviewers.
In a Codex, Claude Code or portable plugin, they go where OpenAI's portal reads them, under `extensions["com.openai"]` of one `plugin.json`. OpenAI imports them from `.codex-plugin/plugin.json` when the plugin has one, as `enconvo plugin create` makes it; from the root `plugin.json` when that one has `extensions["com.openai"]` of its own or there is no Codex manifest; and from `.claude-plugin/plugin.json` in a plugin made only for Claude Code. Don't add `extensions["com.openai"]` to the root `plugin.json` just for them: Codex then ignores the listing in `.codex-plugin/plugin.json`. `enconvo plugin validate --openai` names the manifest they belong in.
```json theme={null}
{
"name": "notes",
"version": "1.2.0",
"extensions": {
"com.openai": {
"review": {
"test_cases": {
"positive": [
{
"description": "Finds a note by topic",
"prompt": "Find my notes about the Q3 launch",
"tools_triggered": "search_notes, read_note",
"expected_behavior": "Lists the matching notes and quotes the most relevant one"
}
],
"negative": [
{ "description": "Unrelated question", "prompt": "What's the weather in Paris?" }
]
},
"demo_recording_url": "https://example.com/notes-demo.mp4",
"commerce": false
},
"publication": {
"release_notes": "Search now matches note titles."
}
}
}
}
```
In an Enconvo plugin, the same `review` object goes at the top level of `package.json`.
| Field | What it holds |
| - | - |
| `test_cases.positive` | Prompts the plugin should handle, each with a `description`, the `prompt`, `expected_behavior`, and the `tools_triggered`. Optional: `file_attachment_urls` and `expected_output_url`. |
| `test_cases.negative` | Prompts the plugin should leave to something else, each with a `description` and the `prompt`. |
| `demo_recording_url` | A video of the main prompts and tools. |
| `commerce`, `commerce_description` | Whether the plugin sells something, and what and where. |
| `publication.release_notes` | What changed. `plugin publish` uses them as the store's changelog unless you pass `-m`. |
Each list holds up to 20 cases. Text fields hold up to 4,000 characters, and every address is an `https://` address reviewers can open. `validate` and `publish` refuse materials that break these limits.
Sign-in details never go in the package, because anyone can download it. `validate` and `publish` refuse a `review` that has `test_credentials` or `reviewer_instructions`; pass them with `--review-notes` instead, or in the Review details form of OpenAI's dashboard.
In `plugin.json`, `publication` can also hold what OpenAI's portal imports for the listing, and `validate --openai` checks them as the portal does. Enconvo shows `translations` in its interface language for an installed plugin and before installing one from a source; the Enconvo store's pages don't use them yet:
| Field | What it holds |
| - | - |
| `countries` | Where the plugin is available, as uppercase country codes such as `["US", "GB"]`. `[]` makes it available everywhere. |
| `translations` | Listing text by locale, such as `{"fr-FR": {"subtitle": "…", "description": "…"}}`. A subtitle is one line of up to 30 characters, a description up to 4,000. |
A field set to `null` keeps the value already saved in OpenAI's dashboard. Plugin-level test cases are for a plugin with exactly one MCP server.
OpenAI's final submission of a plugin with an MCP server or app takes exactly 5 positive and 3 negative cases, a demo recording and release notes; a plugin with only skills needs just the release notes. `validate --openai` lists what is missing as warnings, because the portal's upload accepts a plugin without them and asks for them only at final submission.
## Submission checklist
Before you run `plugin publish`:
* `plugin validate` reports no errors, and you have read its warnings.
* `version` is higher than the last version you published, and every manifest in the package gives the same name and version.
* For an update, `plugin validate --previous` with the zip of the release before it reports nothing you didn't mean: an update replaces the whole plugin, so a skill or MCP server it leaves out is removed (`plugin_components_removed`).
* The title, description and icon say what the plugin does, and the screenshots show it working.
* A homepage or support address is set, and a privacy policy is linked if the plugin sends data anywhere.
* Every MCP tool has a clear name and description and sets `readOnlyHint`, `destructiveHint` and `openWorldHint`, and `plugin scan` lists them without problems.
* Skills say in their `description` when to use them.
* Required settings, such as an API key, are declared as settings, not asked for in chat.
* No keys, tokens or private files are in the folder.
* Review materials list prompts to try and prompts to leave alone, and a demo account is ready for `--review-notes` if sign-in is needed.
* You installed the package from its folder (`plugin install .`) and tried the test cases in Enconvo.
## What happens after you submit
1. `plugin publish` checks the plugin and that its version is higher than the one the store released, then uploads it and submits the version for review. Until a new plugin is approved, only you can see it.
2. A reviewer reads the listing, the package's files (with what changed since the released version), the review materials and your notes, and tries the test cases.
3. An approved version appears in the store, and installed copies are offered the update. If a version is turned down, you get an email with the reason. Fix it, raise the version and publish again.
Enconvo also looks into reports about published plugins. A plugin found to break these guidelines, including one approved before, can be removed from the store, and its developer is emailed the reason.
## Submitting to OpenAI as well
The same folder can go to OpenAI's plugin portal:
```sh theme={null}
npx -p @enconvo/api enconvo plugin validate --openai
npx -p @enconvo/api enconvo plugin scan --openai
npx -p @enconvo/api enconvo plugin pack --openai
```
`pack --openai` writes the zip the portal takes. Credentials for OpenAI's reviewers go in the portal's submission form, never in the package. Keep your own keys out of it too: `pack` and `publish` leave out `.env` files, and `validate` warns about a file that looks like a private key or a login (`archive_member_secret`).
The portal takes only letters, digits, `-` and `_` in the plugin's `name`, and OpenAI suggests lowercase letters, digits and single hyphens. Codex, Claude Code and Enconvo also install a dotted name such as `acme.tools`, but `validate --openai` and `pack --openai` refuse it (`plugin_name_format`), so name a plugin you mean to submit `acme-tools`.
After the upload, the portal connects to the plugin's MCP server and scans its tools; when the server changes, rescan it there. It reaches the server only at a public `https://` URL, so a server that runs on the user's computer has to be deployed first; `scan --openai` warns about one (`mcp_server_not_remote`). At final submission the portal asks for all three annotations on every tool. It no longer asks you to justify them; if its automated review flags one, you can appeal with an explanation. A plugin whose views embed pages still needs a justification for each embedded page: what it does, why the plugin embeds it, and who controls its domain. Pages from the MCP server's own registrable domain are allowed, and separate tenants on a shared host count as different domains. `scan --openai` lists the domains your views embed (`frame_domain_explanation_required`).
Before you can submit the plugin, the portal verifies that you control the MCP server's domain: it gives you a token to serve as plain text at `/.well-known/openai-apps-challenge` on the server's host or a parent domain. `scan --openai` says what those URLs answer, and `scan --challenge-token <token>` checks that one serves exactly the token before you select **Verify Domain**; see [Domain verification](/extensions/validation-codes#domain-verification).
To update a plugin you published there, upload a complete ZIP with a higher version and everything you mean to keep. If you didn't keep the zip of the published version, the portal gives it to you with **Download release ZIP** in that version's **…** menu; check the new version against it with `validate --openai --previous <zip>`. The portal can't add an MCP server to a published plugin that had none, or change a published server's URL (ask OpenAI's support for that), and `--previous` reports both; see [Updates](/extensions/validation-codes#updates).
OpenAI's portal connects only one MCP server per plugin to scan and review it, so `validate --openai` warns about a plugin with more. The same server declared for Codex in `mcp.json` and for Claude Code in `.mcp.json` counts once.
OpenAI's final submission asks more of the listing than its upload does, and `validate --openai` warns about each gap:
* `interface.longDescription`, and an `interface.category`; without one, the directory lists the plugin under Other.
* For a plugin with an MCP server, `websiteURL`, `supportURL`, `privacyPolicyURL` and `termsOfServiceURL`, each an `https://` address of up to 1,024 characters.
* A listing of your own. A Claude Code plugin with only `.claude-plugin/plugin.json` gets one the portal fills in with defaults (`claude_format_normalized`), so add a `.codex-plugin/plugin.json` with an `interface` to write it yourself.
* Screenshots only when the MCP server has its own interface: one PNG or JPEG for each starter prompt, exactly 706 pixels wide and 400 to 860 pixels tall. The portal decides from its scan, so `scan --openai` refuses screenshots when no tool shows an interface (`screenshots_not_allowed`). OpenAI's directory no longer shows screenshots and introduces a plugin by its starter prompts, so write those with care.
The directory shows the developer name of your verified OpenAI identity, whatever `interface.developerName` says. See [OpenAI's final submission](/extensions/validation-codes#openais-final-submission) for the codes.
# Validation Codes
Source: https://docs.enconvo.ai/extensions/validation-codes
What each problem `enconvo plugin validate`, `scan`, `pack` and `publish` report means, how severe it is, and how to fix it.
`plugin validate` checks a plugin folder or `.zip`, or a [marketplace](#marketplaces) and the plugins in it, without uploading anything. `plugin pack` and `plugin publish` run the same checks first. Each problem has a code; OpenAI's plugin portal uses the same codes for the rules it shares with Enconvo.
```sh theme={null}
npx -p @enconvo/api enconvo plugin validate [path] # the folder, a .zip or a marketplace
npx -p @enconvo/api enconvo plugin validate [path] --openai # OpenAI's portal rules become errors
npx -p @enconvo/api enconvo plugin validate [path] --json # the result as JSON
npx -p @enconvo/api enconvo plugin validate [path] --previous <release> # check an update against the release before it
```
Each problem is one line: its severity, its code, the file it is in, and what is wrong.
```text theme={null}
warning[plugin_short_description_too_long] .codex-plugin/plugin.json: interface.shortDescription is 42 characters; the limit is 30. (OpenAI's plugin portal)
error[skill_description_missing] skills/notes/SKILL.md: skills/notes/SKILL.md description is required.
```
`validate` exits with status 1 when there is an error, so you can run it in CI.
## Severity
| Severity | Meaning |
| - | - |
| `error` | Enconvo, Codex or Claude Code can't use the plugin as it is. `pack` and `publish` stop. |
| `warning` | The plugin works, but something is ignored or may not work in another app. |
| `warning … (OpenAI's plugin portal)` | Only OpenAI's portal applies the rule. With `--openai`, and in `pack --openai`, it is an error. |
The review rules OpenAI checks at final submission, such as the number of test cases, stay warnings even with `--openai`, because the portal's upload accepts a plugin without them. So does `mcp_servers_multiple`: the upload takes a plugin with several MCP servers. So do `undeclared_mcp_manifest_ignored` and `undeclared_app_manifest_ignored`: the upload leaves the file out, but Codex still loads it. The [final submission's listing rules](#openais-final-submission) are reported only with `--openai`, as warnings.
## Text fields
Most text fields are checked the same way, and their codes start with the field's stem, such as `plugin_display_name`:
| Code | Severity | Meaning |
| - | - | - |
| `<stem>_missing` | error when the field is required, otherwise portal | The field isn't set. |
| `<stem>_wrong_type` | error | The value isn't text. In a portable or Claude Code `plugin.json`, a `null` `version`, `description`, `author.name`, `author.email`, `author.url` or `homepage` is this error too, because Codex and Claude Code refuse the file. Leave the field out instead. |
| `<stem>_empty` | error | The value is empty or only spaces. |
| `<stem>_character_unsupported` | portal | The value has control characters, or line breaks in a one-line field. |
| `<stem>_too_long` | portal | The value is longer than the portal's limit below. |
| Stem | Field | Limit |
| - | - | - |
| `plugin_name` | `name` (required) | 64 |
| `plugin_id` | `id` in `.codex-plugin/plugin.json`, or `extensions["com.openai"].id` | |
| `plugin_version` | `version` | 64 |
| `plugin_description` | `description` | 1,024 |
| `plugin_author_name`, `plugin_author_email` | `author.name`, `author.email` | 120, 320 |
| `plugin_display_name` | `interface.displayName` (missing: `plugin_display_name_empty`) | 30 |
| `plugin_short_description` | `interface.shortDescription` | 30 |
| `plugin_long_description` | `interface.longDescription` | 4,000 |
| `plugin_developer_name` | `interface.developerName` | 120 |
| `plugin_category` | `interface.category` | |
| `plugin_capability` | each of `interface.capabilities` | 120 |
| `plugin_default_prompt` | each of `interface.defaultPrompt` | 128 |
| `skill_name` | `name` in `SKILL.md` (required) | |
| `skill_description` | `description` in `SKILL.md` (required) | 1,024 |
| `skill_agent_display_name`, `skill_agent_short_description`, `skill_agent_default_prompt`, `skill_agent_brand_color`, `skill_agent_icon_small`, `skill_agent_icon_large` | `interface` fields in `agents/openai.yaml` | |
## Addresses and colors
Addresses have to be `https://` addresses without a user name or password. The stems are `plugin_homepage`, `plugin_author_url`, `plugin_website_url`, `plugin_privacy_policy_url`, `plugin_terms_of_service_url` and `plugin_support_url`.
| Code | Severity | Meaning |
| - | - | - |
| `<stem>_format` (`plugin_author_url_not_https`) | portal | Not an `https://` address. |
| `<stem>_has_credentials` | portal | The address holds a user name or password. |
| `plugin_brand_color_format`, `plugin_brand_color_dark_format`, `skill_agent_brand_color_format` | portal | Not a six-digit hex color such as `#1A73E8`. |
| `plugin_brand_color_contrast`, `plugin_brand_color_dark_contrast` | portal | Less than 2:1 contrast against the light (`#FFFFFF`) or dark (`#212121`) background. |
The listing's four addresses (`websiteURL`, `supportURL`, `privacyPolicyURL`, `termsOfServiceURL`) take up to 2,048 characters in the upload, so a longer one is `<stem>_too_long` (portal). Final submission takes up to 1,024, so one between the two limits is a `<stem>_too_long` warning, only with `--openai`.
## Manifests
| Code | Severity | Meaning |
| - | - | - |
| `plugin_manifest_missing` | error | The folder has no `package.json`, `plugin.json`, `.codex-plugin/plugin.json`, `.claude-plugin/plugin.json`, `manifest.json` or `SKILL.md`. |
| `plugin_manifest_not_file`, `plugin_manifest_unreadable`, `plugin_manifest_json_malformed`, `plugin_manifest_root_not_object` | error | The manifest isn't a readable UTF-8 file holding a JSON object. |
| `codex_manifest_parent_not_directory`, `codex_manifest_path_not_file` | error | `.codex-plugin` isn't a folder, or `.codex-plugin/plugin.json` in it isn't a file. |
| `plugin_name_format` | error | `name` has to start with a letter or digit and use only letters, digits, `-` and `_`, with single dots between them, as Codex and Claude Code take it, so `acme.tools` works and `acme.` or `acme..tools` doesn't. A portable `plugin.json`'s `name` follows Codex's rule instead: up to 64 lowercase letters, digits and single dots or hyphens, starting and ending with a letter or digit, so `acme.tools` works and `Acme_Tools` or `acme--tools` doesn't. OpenAI's portal takes no dots, so a dotted name in the manifest it reads is also an OpenAI portal finding (a warning, an error with `--openai`) that names the hyphenated name to submit, such as `acme-tools`. |
| `plugin_schema_missing` | error, or warning | The root `plugin.json` doesn't give `"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json"`, so Codex and OpenAI's portal don't read it as a portable plugin. A warning when `.codex-plugin/plugin.json` or `.claude-plugin/plugin.json` is there for them to read instead, an error otherwise. |
| `plugin_schema_unsupported` | error | `$schema` names another version of the Agent Plugins schema. Codex supports only 1.0.0 and refuses the plugin. |
| `plugin_version_not_semver` | error | `version` isn't a version number like `1.2.0`. |
| `plugin_author_wrong_type` | error | `author` in `plugin.json` has to be an object like `{"name": "…"}`. |
| `plugin_author_field_unsupported` | error | A portable `plugin.json`'s `author` has a field other than `name`, `email` and `url`, and Codex refuses it. |
| `plugin_repository_wrong_type`, `plugin_license_wrong_type` | error | `repository` or `license` in a portable or Claude Code `plugin.json` isn't text, such as `"https://github.com/acme/tools"` or `"MIT"`. Codex and Claude Code refuse an object or a `null`. |
| `plugin_keywords_wrong_type` | error | `keywords` in a `plugin.json` isn't a list of text. Codex and Claude Code refuse the file. |
| `plugin_schema_wrong_type`, `plugin_display_name_wrong_type`, `plugin_default_enabled_wrong_type`, `plugin_settings_wrong_type`, `plugin_dependencies_wrong_type` | error | In a Claude Code `plugin.json`, `$schema` or `displayName` isn't text, `defaultEnabled` isn't `true` or `false`, `settings` isn't an object, or `dependencies` isn't a list, `null` included. Claude Code doesn't load the plugin. |
| `plugin_dependency_invalid` | error | A Claude Code dependency isn't a plugin name (`"formatter"`), a name and marketplace (`"vault@acme"`), either followed by a version range (`"vault@acme@^1.2"`), or `{"name": "vault", "marketplace": "acme"}`. Names and marketplaces start with a letter or digit and use letters, digits, `.`, `_` and `-`. |
| `plugin_homepage_invalid` | error | A Claude Code `plugin.json`'s `homepage` isn't a web address, so Claude Code doesn't load the plugin. An `http://` address loads, with the `plugin_homepage_format` warning the listing gives it. |
| `plugin_metadata_wrong_type`, `plugin_binaries_wrong_type` | warning | `metadata` or `binaries` in a Claude Code `plugin.json` isn't an object, so Claude Code ignores it. |
| `plugin_binary_invalid` | warning | A binary's name isn't a lowercase file name like `rg`, or its `sha256` isn't the file's SHA-256 as 64 lowercase hex digits, so Claude Code doesn't fetch it. |
| `plugin_binaries_too_many` | warning | `binaries` lists more than 16 files. Claude Code fetches the first 16 (of the first 64) and ignores the rest. |
| `plugin_binaries_not_fetched` | warning | The plugin lists `binaries`. Claude Code fetches them into `bin/` when it installs the plugin; Enconvo doesn't, so hooks and servers that run them work only in Claude Code. |
| `plugin_extensions_wrong_type` | warning | `extensions` or `extensions["com.openai"]` isn't an object, so Codex and Enconvo ignore it and take the listing from `.codex-plugin/plugin.json`, if there is one. |
| `plugin_manifest_field_unsupported` | warning | A portable `plugin.json` has a field the Agent Plugins schema doesn't define. Put app data under `extensions`. In a Claude Code `plugin.json`, a field Claude Code doesn't read, as `claude plugin validate` reports it: the message names the field you likely meant (`descripton` → `description`), the marketplace entry it belongs in (`category`, `tags`, `source`, `strict`), `experimental` for `evals` and `syntaxHighlighting`, `userConfig` for `user_config`, or the manifest it comes from, such as npm's `type` or VS Code's `engines`. Listing fields such as `icon`, `screenshots` and `privacyPolicyUrl`, `extensions`, and `interface` and `apps` when Codex reads this file aren't reported. |
| `component_declaration_ignored` | warning | A portable plugin declares `skills` or `mcpServers` in `plugin.json`, in `extensions["com.openai"]`, or in `.codex-plugin/plugin.json` (a `skills` other than `./skills/`, or servers written out there). Codex, OpenAI's portal and Enconvo take its skills from `skills/` and its MCP servers from `mcp.json`; servers in `.codex-plugin/plugin.json` only pass their `env_vars` to the `mcp.json` servers of the same name. |
| `codex_overlay_ignored` | warning | `plugin.json` has `extensions["com.openai"]`, so Codex ignores `.codex-plugin/plugin.json`. Keep the listing in one of them. |
| `plugin_manifest_name_mismatch`, `plugin_manifest_version_mismatch` | warning (error in `publish`) | The manifests for different apps give different names or versions. |
| `plugin_interface_missing` | portal | There is no listing (`interface`). |
| `plugin_developer_missing` | portal | Neither `author.name` nor `interface.developerName` says who made the plugin. |
| `plugin_interface_wrong_type` | error | `interface` isn't an object. |
| `plugin_capabilities_wrong_type`, `plugin_capabilities_too_many` | error, portal | `interface.capabilities` isn't a list of text, or has more than 20 entries. |
| `plugin_default_prompt_wrong_type`, `plugin_default_prompt_entry_wrong_type` | error | `interface.defaultPrompt` isn't text or a list of text. |
| `plugin_default_prompt_too_many`, `plugin_default_prompt_duplicate` | portal | More than 3 example prompts, or the same prompt twice, ignoring letter case, spacing and Unicode form. |
| `plugin_default_prompt_mention` | portal | An example prompt @mentions an MCP server, which OpenAI's starter prompts can't. |
| `plugin_category_unknown` | portal | `interface.category` isn't one of OpenAI's categories: Productivity, Creativity, Developer Tools, Business & Operations, Data & Analytics, Communication, Education & Research, Security, Finance, Healthcare, Travel, Entertainment or Other. Without a category, OpenAI lists the plugin under Other. |
| `plugin_onboarding_skill_wrong_type` | error | `extensions["com.openai"].onboardingSkill` isn't a path. |
| `plugin_onboarding_skill_missing`, `plugin_onboarding_skill_not_skill_file`, `plugin_onboarding_skill_not_included` | portal | `onboardingSkill` has to point at the `SKILL.md` of one of the plugin's skills, like `./skills/get-started/SKILL.md`. Enconvo also takes the skill's folder. |
| `plugin_logo_path_missing`, `plugin_composer_icon_path_missing` | portal | `interface.logo` or `interface.composerIcon` isn't set. |
| `plugin_runtime_surface_missing` | error | The plugin has nothing to run: no skill, MCP server or app. |
| `dxt_version_missing` | warning | A desktop extension's `manifest_version` isn't set. |
| `dxt_server_missing` | error | A desktop extension's `server` doesn't say how to start its MCP server. |
### Paths to skills, MCP servers and apps
The stems are `plugin_skills` (`skills`), `plugin_mcp` (`mcpServers`) and `plugin_apps` (`apps`).
| Code | Severity | Meaning |
| - | - | - |
| `plugin_skills_directory_missing`, `plugin_mcp_file_missing`, `plugin_apps_file_missing` | error | The path points at nothing. |
| `<stem>_path_wrong_type`, `<stem>_path_empty` | error | The value isn't a path, or is empty. |
| `<stem>_path_not_directory`, `<stem>_path_not_file` | error | The path points at a file where a folder belongs, or the other way round. |
| `<stem>_path_unsupported` | portal | Codex takes only `./skills/`, `./.mcp.json` and `./.app.json`. |
| `undeclared_mcp_manifest_ignored` | warning | A Codex plugin has `.mcp.json` but `mcpServers` doesn't point at it. Codex and Enconvo load it anyway, but OpenAI's portal leaves it out of the upload. |
| `undeclared_app_manifest_ignored` | warning | A Codex plugin has `.app.json` but `apps` doesn't point at it. Codex loads it anyway, but OpenAI's portal leaves it out. Point at it if the plugin uses the app, or remove the file. |
## Images and other files
These apply to the listing's images (`logo`, `composerIcon`, `logoDark`, `composerIconDark`, `screenshots`), the skill icons in `agents/openai.yaml` (`icon_small`, `icon_large`) and an Enconvo plugin's `icon`.
| Code | Severity | Meaning |
| - | - | - |
| `declared_asset_path_wrong_type`, `declared_asset_path_empty`, `declared_asset_path_has_outer_whitespace`, `declared_asset_path_has_control_character` | error | The path isn't usable text. |
| `declared_asset_path_unsafe`, `declared_asset_path_outside_package` | error | The path is absolute or leaves the plugin's folder. |
| `declared_asset_file_missing`, `declared_asset_not_regular_file` | error (warning for an Enconvo icon) | The file doesn't exist or isn't a regular file. |
| `branding_asset_path_missing_root_prefix` | portal | The path has to start with `./`. |
| `image_file_format_unsupported`, `image_file_too_large` | portal (error for an Enconvo icon) | Not a PNG, JPEG, WebP or SVG (an Enconvo icon may also be a GIF), or larger than 5 MB. |
| `image_file_unreadable` | portal | The image can't be read. |
| `svg_xml_malformed` | portal | The SVG isn't UTF-8 text or well-formed XML: every tag has to close, inside one root element. |
| `svg_root_element_invalid` | portal | The file isn't an SVG image. |
| `svg_dimensions_missing`, `svg_dimensions_not_numeric`, `svg_dimensions_not_positive` | portal | The SVG needs a `viewBox` or a `width` and `height`. |
| `svg_dimensions_not_square`, `svg_dimensions_too_small` | portal | The SVG has to be square and at least 48 pixels. |
| `raster_image_decode_failed`, `raster_image_extension_content_mismatch` | portal | The image can't be read, or its contents don't match its extension. |
| `raster_image_not_square`, `raster_image_dimensions_too_small`, `raster_image_dimensions_too_large` | portal | The image has to be square, from 48 to 4,096 pixels. |
## Skills
| Code | Severity | Meaning |
| - | - | - |
| `skill_manifest_not_regular_file`, `skill_manifest_unreadable`, `skill_manifest_invalid_utf8` | error | `SKILL.md` isn't a readable UTF-8 text file. |
| `skills_path_unreadable` | error | You don't have permission to open the skills folder or a skill's folder (Enconvo's code). |
| `skill_frontmatter_missing`, `skill_frontmatter_unclosed`, `skill_frontmatter_yaml_malformed`, `skill_frontmatter_wrong_type` | error | `SKILL.md` has to start with front matter: a `---` line, `name` and `description` as YAML, and another `---` line. |
| `skill_identity_duplicate` | error | Two skills have the same `name`. |
| `skill_identity_too_long` | portal | `<plugin>:<skill>` is longer than 64 characters. |
| `skill_body_empty` | portal | `SKILL.md` has no instructions after its front matter. |
| `skill_directory_hidden` | portal | A skill's folder name starts with a dot. |
| `skill_manifest_nested`, `skill_manifest_missing` | portal | Each skill has to be a folder right inside `skills/`, with a `SKILL.md`. |
| `skill_file_ignored`, `skill_symlink_ignored` | warning | A file outside a skill folder, or a symbolic link, is left out. |
| `skill_metadata_ignored` | warning | `SKILL.md` sets its listing in `metadata`; put it in `agents/openai.yaml`. |
| `skill_agent_not_regular_file`, `skill_agent_unreadable`, `skill_agent_invalid_utf8`, `skill_agent_yaml_malformed`, `skill_agent_top_level_wrong_type` | portal | `agents/openai.yaml` isn't a readable UTF-8 YAML object. |
| `skill_agent_interface_missing`, `skill_agent_interface_wrong_type` | portal | `agents/openai.yaml` needs an `interface` section. |
| `skill_agent_policy_wrong_type`, `skill_agent_allow_implicit_invocation_wrong_type` | portal | `policy` isn't an object, or `allow_implicit_invocation` isn't `true` or `false`. |
| `skill_agent_dependencies_wrong_type`, `skill_agent_dependency_unsupported` | portal | `dependencies` takes only `tools`. |
## Claude Code agents and commands
A Claude Code plugin's `agents` and `commands` fields are checked as Claude Code loads them. Either field replaces its default folder.
| Code | Severity | Meaning |
| - | - | - |
| `plugin_agents_path_wrong_type`, `plugin_commands_path_wrong_type` | error | The field isn't a path or a list of paths (for `commands`, or a map of command names). |
| `plugin_agents_path_missing`, `plugin_commands_path_missing` | error | A listed path doesn't exist. |
| `plugin_agents_path_not_file` | error | `agents` lists a folder. Claude Code takes agent `.md` files only, so list each one. |
| `plugin_agents_file_not_markdown`, `plugin_commands_file_not_markdown` | error | A listed file, or a command's `source`, isn't a `.md` file. |
| `plugin_command_entry_wrong_type` | error | An entry in the `commands` map isn't an object. |
| `plugin_command_entry_source_or_content` | error | A `commands` map entry needs exactly one of `source` and `content`. |
| `plugin_command_entry_content_empty` | error | A command's `content` is empty. |
| `default_agents_folder_ignored`, `default_commands_folder_ignored` | warning | The plugin has an `agents/` or `commands/` folder, but the field doesn't list it, so nothing in it is installed. |
The frontmatter of each command, agent and skill (the `---` block at the top of the file) is read as Claude Code reads it. Claude Code parses it as YAML, and when that fails it tries once more after putting top-level values that hold `: ` or a YAML symbol such as `@`, `*` or `#` in quotes. Frontmatter that still fails loads with no metadata: a command or skill loses its description and every other field, and an agent keeps only the name its file gives it. Quote a value that holds `: ` or starts with a symbol, at any level, to be safe.
| Code | Severity | Meaning |
| - | - | - |
| `plugin_component_frontmatter_invalid` | error | Claude Code can't parse the frontmatter. The message gives the line and what to change, such as a quote that isn't closed, a nested value with `: ` in it, or a line indented more than the keys around it. |
| `plugin_component_frontmatter_wrong_type` | error | The frontmatter is a list or a single value instead of `key: value` lines. |
| `plugin_component_frontmatter_missing` | warning | A command or agent has no frontmatter, so Claude Code shows it without a description. |
| `plugin_component_description_missing` | warning | A command or agent has no `description`, which tells people and Claude when to use it. A skill gets `skill_description_missing`. |
| `plugin_component_field_wrong_type` | error | `description` or `name` isn't text, `allowed-tools` isn't text or a list of tool names, or `shell` isn't text. YAML reads `name: 5` as a number and `name: true` as a boolean, so put such values in quotes. |
| `plugin_component_shell_invalid` | error | A command's or skill's `shell` isn't `bash` or `powershell`. |
| `plugin_component_metadata_ignored` | warning | A command's or skill's `metadata` isn't `key: value` pairs, so Claude Code drops it. |
| `plugin_component_unreadable` | error | A command or agent file can't be read. |
| `plugin_root_context_ignored` | warning | The plugin has a `CLAUDE.md` or `CLAUDE.local.md` at its root. Neither Claude Code nor Enconvo loads it as context; put that context in a skill (`skills/<name>/SKILL.md`). |
Every `.md` file under `commands/`, `agents/` and the paths the manifest lists is checked, including hidden folders. A skill whose frontmatter, name or description already has a `skill_*` finding isn't checked again. Only a plugin with a `.claude-plugin/plugin.json` is read this way.
Claude Code's directory listing fields are checked as warnings, because Claude Code ignores them when it loads the plugin. Enconvo and the plugin store leave out a bad one.
| Code | Severity | Meaning |
| - | - | - |
| `plugin_icon_wrong_type` | warning | `icon` isn't a path. |
| `plugin_icon_path_invalid` | warning | `icon` doesn't start with `./`, leaves the plugin with `..`, or links to a file outside it. |
| `plugin_icon_file_missing` | warning | `icon` isn't a file in the plugin. |
| `plugin_icon_format_unsupported` | warning | `icon` isn't a `.png`, `.jpg`, `.jpeg`, `.webp`, `.svg` or `.gif` image. |
| `plugin_listing_url_invalid` | warning | `documentationUrl`, `supportUrl`, `privacyPolicyUrl` or `termsOfServiceUrl` isn't an `https://` address, or holds a user name or password. |
## Claude Code settings and channels
Claude Code doesn't load a plugin whose `userConfig` or `channels` breaks its rules, so these are errors, matching `claude plugin validate`. Enconvo turns the settings into the plugin's preferences. A `.codex-plugin` manifest isn't checked for them.
| Code | Severity | Meaning |
| - | - | - |
| `user_config_wrong_type` | error | `userConfig` (at the top level or in a channel) isn't an object of settings by key. |
| `user_config_key_invalid` | error | A setting key isn't letters, digits and `_`, or starts with a digit. |
| `user_config_setting_wrong_type` | error | A setting isn't an object. |
| `user_config_field_unsupported` | error | A setting has a field other than `type`, `title`, `description`, `required`, `default`, `options`, `multiple`, `sensitive`, `min` and `max`. |
| `user_config_type_invalid` | error | `type` isn't `string`, `number`, `boolean`, `directory` or `file`. |
| `user_config_field_wrong_type` | error | `title` or `description` is missing or isn't text, `required`, `multiple` or `sensitive` isn't `true` or `false`, `min` or `max` isn't a number, or `default` isn't text, a number, `true` or `false`, or a list of text. |
| `user_config_options_invalid` | error | `options` is on a setting that isn't a plain `string` one (or is `multiple` or `sensitive`), or isn't a non-empty list of text up to 64 characters that differs in more than letter case, with no control, invisible or non-plain space character and no space at either end. Its `default` has to be one of them; without a `default`, set `"required": true`. |
| `channels_wrong_type` | error | `channels` isn't a list. |
| `channel_wrong_type` | error | A channel isn't an object. |
| `channel_field_unsupported` | error | A channel has a field other than `server`, `displayName` and `userConfig`. |
| `channel_server_missing` | error | A channel doesn't name its MCP server in `server`. |
| `channel_display_name_wrong_type` | error | A channel's `displayName` isn't text. |
| `user_config_reference_undeclared` | error | An MCP server's `command`, `args`, `env`, `url` or `headers` names `${user_config.KEY}` for a key that isn't a top-level setting or a setting of that server's channel. Claude Code drops the server or passes the text through, and Enconvo fills in an empty value. |
| `user_config_reference_in_headers_helper` | error | An MCP server's `headersHelper` names `${user_config.KEY}`. Claude Code never fills settings into this shell command, so read the value in the helper script. |
## MCP servers and apps
These apply to every MCP file the plugin has, and to the servers a Claude Code plugin declares inline in `.claude-plugin/plugin.json`.
| Code | Severity | Meaning |
| - | - | - |
| `mcp_manifest_unreadable`, `mcp_manifest_json_malformed`, `mcp_manifest_wrong_type`, `plugin_mcp_path_not_file` | error | The MCP file isn't a readable UTF-8 JSON object. |
| `mcp_servers_wrong_type` | error | The server list isn't an object keyed by server name. |
| `mcp_server_name_empty`, `mcp_server_wrong_type` | error | A server has an empty name, or isn't an object. |
| `mcp_server_transport_missing` | error | A server needs a `command` to run or a `url` to connect to. |
| `mcp_servers_missing` | warning | The servers aren't under `mcpServers`. Servers listed at the top work in Enconvo, Codex and Claude Code, but the Agent Plugins schema puts them under `mcpServers`. Servers under `mcp_servers` work only in Enconvo. |
| `mcp_server_type_missing` | warning | A server in a portable `mcp.json` needs `"type"`: `stdio`, `streamable-http` or `sse`. |
| `mcp_server_type_unsupported` | warning | A server's `type` (or Enconvo's older `transport`) is one Enconvo doesn't connect to, such as `ws`, so it skips the server. Enconvo runs `stdio`, `http` (or `streamable-http`) and `sse` servers. |
| `mcp_server_url_type_missing` | error | A server Claude Code reads has a `url` but no `type`, so Claude Code takes it for a local server without a `command` and drops it. Add `"type": "http"` (or `"sse"`). |
| `mcp_server_type_unknown` | error | A server Claude Code reads has a `type` it doesn't know, so it drops the server. Use `stdio` (or no type) for a command, and `http`, `sse` or `ws` for a url. |
| `mcp_server_type_reserved` | error | A server Claude Code reads uses a type only Claude Code itself registers (`sdk`, `sse-ide`, `ws-ide`) or only claude.ai connectors use (`claudeai-proxy`), so it drops a plugin's. |
| `mcp_server_field_wrong_type` | error | A field of a server Claude Code reads has the wrong shape, as `claude plugin validate` reports it: an empty or missing `command`, `args` that aren't a list of text, `env` or `headers` values that aren't text, a `url` that isn't text, a malformed `oauth`, `tools` or `toolPermissions`, a `timeout` that isn't a positive whole number, or an `alwaysLoad` that isn't true or false. Claude Code drops the whole server. Fields it doesn't know pass. |
| `mcp_server_cwd_outside` | warning | A portable server's `cwd` has to start with `./`, `${PLUGIN_ROOT}` or `${PLUGIN_DATA}`. |
| `mcp_server_url_invalid` | error | A remote server's `url` isn't an absolute address such as `https://host/path`, and holds no `${VAR}`, so it never connects. An empty `url` isn't checked. |
| `mcp_server_url_insecure` | warning | A remote server's `url` uses `http://` or `ws://` to a host other than `localhost`, a `.localhost` name, `127.0.0.1` or `[::1]`, so its requests, headers and any credentials travel in cleartext. Use `https://` or `wss://`. A url whose host is a variable isn't checked. |
| `mcp_server_header_credential` | warning | A value in a remote server's `headers` (or Codex `http_headers`) looks like a real credential: a known token shape such as `sk-…`, `ghp_…`, `AKIA…` or a JWT, or a long, varied value under an authorization, API key, token, secret, password or credential header. Everyone who installs the plugin can read it, so reference a sensitive setting (`${user_config.KEY}`) or an environment variable (`${VAR}`) instead. Values with a variable or placeholder text such as `your-api-key` pass. |
| `mcp_server_oauth_resource_ignored` | warning | A remote server's `oauth_resource` isn't on the server's own origin, or has a fragment, so Enconvo signs in without it. |
| `mcp_server_auth_metadata_insecure` | warning | A remote server's `oauth.authServerMetadataUrl` doesn't use `https://`. Claude Code refuses it; Enconvo reads `http://` only from `localhost`, for testing. |
| `mcp_server_approval_mode_invalid` | error | A server's `default_tools_approval_mode` or a tool's `approval_mode` isn't `auto`, `prompt`, `writes` or `approve`. Codex won't load the file. |
| `mcp_server_tools_wrong_type` | error | A server's `tools` isn't an object of tool settings by tool name, or a tool's settings aren't an object. Codex can't load a server whose `tools` is a list, the form Claude Code takes, and Claude Code drops an `http` or `sse` server whose `tools` is Codex's object (`mcp_server_field_wrong_type`), so give each its own MCP file or remove `tools`. |
| `mcp_server_approval_approve_ignored` | warning | A server or tool asks for `approve`. Codex runs those tools without asking, but Enconvo asks as it would for any tool; only the person turns questions off, with the Agent's Permissions chip. |
| `mcp_servers_multiple` | warning | The plugin has more than one MCP server. OpenAI's portal connects only one of them per plugin to scan and review it. A server declared in both `mcp.json` and `.mcp.json` under the same name counts once. |
| `app_manifest_unreadable`, `app_manifest_json_malformed`, `app_manifest_wrong_type`, `plugin_apps_path_not_file` | error | `.app.json` isn't a readable UTF-8 JSON object. |
| `app_entries_missing`, `app_entries_wrong_type`, `app_entry_wrong_type` | error | `.app.json` needs an `apps` object of app entries. |
| `app_id_missing`, `app_id_wrong_type` | error | An app entry needs an `id`. |
| `app_id_format` | portal | An app's `id` has to be the ID OpenAI gave it, starting with `asdk_app_`, `connector_` or `templated_apps_`. |
| `app_entry_required_wrong_type`, `app_entry_optional_wrong_type` | portal | An app's `required` or `optional` has to be `true` or `false`. An app is needed unless it says `"required": false` or `"optional": true`. |
| `duplicate_app_reference` | warning | Two app entries have the same `id`. Codex and OpenAI's portal keep only the first. |
| `app_configuration_excluded` | portal | OpenAI's portal can't take a plugin with app references (`apps` or `.app.json`) yet. Put the MCP server's address in `.mcp.json` and finish the app's setup in OpenAI's dashboard. Enconvo, Codex and Claude Code still install the plugin. |
| `hooks_configuration_excluded` | portal | OpenAI's portal can't take a plugin with lifecycle hooks (the manifest's `hooks`, `hooks/hooks.json` or `hooks.json`) yet. Leave them out of the package you upload there; Enconvo's store takes them. |
| `screenshot_configuration_excluded` | portal | `interface.screenshots` is for a plugin with an MCP server and its own interface; OpenAI's portal refuses it in a plugin that has only skills. |
## Hooks
These apply to `hooks/hooks.json`, the files the manifest's `hooks` names, and hooks written in the manifest itself, checked as `claude plugin validate` checks them and as Codex reads them. Each message says what Claude Code and Codex do about the problem. Claude Code reads a Claude Code plugin's hooks; Codex reads the hooks of the manifest it loads (`.codex-plugin/plugin.json`, a portable plugin's `extensions["com.openai"].hooks`, or a Claude Code plugin's when it has no other manifest).
| Code | Severity | Meaning |
| - | - | - |
| `hooks_unreadable`, `hooks_json_malformed` | error | A hooks file isn't readable UTF-8 JSON. Claude Code doesn't load the plugin at all, and Codex skips the file. |
| `hooks_wrong_type` | error | A hooks file, or its `hooks`, isn't an object. Claude Code and Codex skip every hook in it. |
| `hooks_events_outside` | error or warning | Events such as `PreToolUse` are at the top of the file, beside `hooks`, instead of inside it: `{"hooks": {"PreToolUse": […]}}`. Codex skips the file, and so does Claude Code when one of them is `PreToolUse` or `PermissionRequest`, or the file has no `hooks`; it ignores other stray events. |
| `hooks_events_missing` | error | A hooks file has no `hooks` object of events, so Claude Code applies none of it. |
| `hooks_field_unsupported` | error or warning | A hooks file has `surface`, which Claude Code no longer takes, or another field than `description` and `hooks`, which Codex refuses: it skips every hook in the file. |
| `hooks_field_wrong_type` | error | A hooks file's `description` isn't text, or its `modules` isn't a list of one hooks module. |
| `hook_event_unknown` | warning | Claude Code or Codex doesn't send the event, so it ignores those hooks. Codex sends 12 events: 11 of Claude Code's, such as `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart` and `Stop`, and its own `Interrupt`. |
| `hook_matchers_wrong_type`, `hook_matcher_invalid`, `hook_entry_invalid` | error or warning | An event isn't a list of matchers, a matcher isn't `{"matcher": "…", "hooks": […]}` with text in `matcher`, or a hook isn't an object with a `type`. |
| `hook_type_unknown` | error or warning | A hook's `type` isn't one Claude Code (`command`, `prompt`, `agent`, `http`, `mcp_tool`) or Codex (`command`, `prompt`, `agent`, `mcp_tool`) knows. Codex skips the whole file over a type it doesn't know, such as `http`. |
| `hook_field_wrong_type` | error or warning | A hook misses a field its type needs (`command`, `prompt`, `url`, or `server` and `tool`) or has one of the wrong kind, such as a `timeout` that isn't a number above 0 (Codex needs a whole number), a `url` that isn't absolute, or `headers` values that aren't text. |
| `hook_type_unsupported` | warning | A `prompt` or `agent` hook in a Codex plugin: Codex reads it but doesn't run it yet. |
| `hook_args_ignored` | warning | A `command` hook Codex reads has `args`. Codex has none, so it runs the `command` alone: write the whole command line there, with each path in double quotes. |
| `hook_command_placeholder_unquoted` | warning | A shell command uses `${CLAUDE_PLUGIN_ROOT}`, `${CLAUDE_PLUGIN_DATA}` or `${CLAUDE_PROJECT_DIR}` outside quotes, so it breaks when the path has a space. Write `"${CLAUDE_PLUGIN_ROOT}/scripts/run.sh"`. |
| `plugin_hooks_wrong_type` | error or warning | The manifest's `hooks` isn't a path to a hooks file, the hooks themselves, or a list of them, or the list mixes paths and hooks, which Codex ignores. |
| `plugin_hooks_path_invalid`, `plugin_hooks_path_missing`, `plugin_hooks_path_not_file` | error | A path in `hooks` doesn't start with `./`, points at nothing, or points at a folder. |
| `hooks_inline_format_conflict` | warning | Hooks written in a manifest have the other app's shape: Claude Code's `hooks` holds the events themselves, Codex's a whole hooks file, `{"hooks": {…}}`, and each ignores the other's. Put them in `hooks/hooks.json`, which both read. |
| `hooks_file_ignored` | warning | `hooks/hooks.json` isn't loaded by Codex because its manifest names other hooks (Claude Code always adds the file), or the plugin has a `hooks.json` at its root, which neither app loads unless the manifest names it. Name the file in `hooks`, or move it to `hooks/hooks.json`. |
An error here means the plugin's own app loses hooks: Claude Code applies none of a file's hooks when it can't read one under `PreToolUse` or `PermissionRequest`, since that hook may be what guards the plugin, and Codex skips a whole file it can't parse. When only the other app is affected, such as Codex reading a Claude Code plugin, or Claude Code ignoring one entry under another event, it is a warning.
## Claude Code components
These apply to the LSP servers, monitors, output styles, workflows, themes, syntax highlighting languages and TypeScript declarations (`types`) in a Claude Code plugin's `.claude-plugin/plugin.json`, checked as `claude plugin validate` checks them. Enconvo doesn't load any of them, so they matter only for the plugin in Claude Code, but an error here means Claude Code doesn't load the plugin at all. Like `claude plugin validate`, `validate` doesn't open `.lsp.json` or a monitors file the manifest names.
| Code | Severity | Meaning |
| - | - | - |
| `plugin_component_not_loaded` | warning | The plugin has LSP servers, monitors, output styles, workflows, themes or syntax highlighting languages, which only Claude Code runs. Enconvo installs the rest of the plugin. |
| `plugin_component_path_invalid` | error | A path in `lspServers`, `outputStyles`, `workflows`, `types`, `experimental.themes`, `experimental.monitors` or `experimental.outputStyles` doesn't start with `./`, or, for LSP servers and monitors, doesn't end in `.json`, or, for `types`, in `.d.ts`. |
| `plugin_component_path_missing` | error | A path points at nothing, which Claude Code reports as a load failure. A path with `..` or `\` is `declared_asset_path_unsafe`. |
| `plugin_component_wrong_type` | error | A component isn't a path, inline LSP servers or monitors, or a list of them, `types` isn't a path, or `experimental.evals` or `experimental.outputStyles` isn't a path or a list of paths. |
| `plugin_component_not_experimental` | warning | `themes` or `monitors` is at the top of the manifest. Claude Code still loads it there for now, but asks for `experimental.themes` and `experimental.monitors`. |
| `plugin_experimental_wrong_type`, `plugin_experimental_field_unsupported` | warning | `experimental` isn't an object, or holds a key other than `themes`, `monitors`, `outputStyles`, `evals` and `syntaxHighlighting`; the message names the key you likely meant. Claude Code ignores it. |
| `plugin_experimental_field_not_loaded` | warning | `experimental.outputStyles` is set. Claude Code accepts it, but loads output styles only from `outputStyles` and `output-styles/`. |
| `plugin_syntax_highlighting_invalid` | error | `experimental.syntaxHighlighting` isn't `{"hljsLanguages": [{"id": "hcl"}]}` with up to 16 highlight.js languages and no other keys. Each language takes an `id` of up to 64 lowercase letters, digits, `_` and `-`, starting with a letter, an optional `remote` of up to 256 characters (`npm:<package>[@<version>]` or `github:<owner>/<repo>@<ref>#<path>.js`), and an optional `integrity` (a `sha256-`, `sha384-` or `sha512-` hash in base64). |
| `lsp_server_wrong_type`, `lsp_server_field_unsupported` | error | An inline LSP server isn't an object, or has a key Claude Code doesn't take. It takes `command`, `extensionToLanguage`, `args`, `transport`, `env`, `initializationOptions`, `settings`, `workspaceFolder`, `startupTimeout`, `shutdownTimeout`, `requestTimeout`, `restartOnCrash`, `maxRestarts` and `diagnostics`. |
| `lsp_server_command_missing`, `lsp_server_command_has_spaces` | error | An LSP server has no `command`, or its `command` has a space and isn't an absolute path. Put arguments in `args`: `{"command": "gopls", "args": ["serve"]}`. |
| `lsp_server_extensions_invalid` | error | `extensionToLanguage` is missing or empty, has a key without a leading `.`, or maps one to something other than a language name: `{".go": "go"}`. |
| `lsp_server_field_wrong_type` | error | `args` isn't a list of text, `env` an object of text, `transport` `stdio` or `socket`, a timeout a whole number above 0, `maxRestarts` a whole number of 0 or more, or `restartOnCrash` or `diagnostics` true or false. |
| `monitor_wrong_type`, `monitor_field_unsupported`, `monitor_field_missing` | error | A monitor isn't an object, has a key other than `name`, `command`, `description` and `when`, or lacks `name`, `command` or `description` as text. |
| `monitor_when_invalid` | error | `when` isn't `always` or `on-skill-invoke:` followed by a skill name. |
| `monitor_name_duplicate` | error | Two monitors share a `name`. |
| `user_config_reference_in_monitor_command` | error | A monitor's `command` names `${user_config.*}`. `claude plugin validate` passes it, but Claude Code refuses to start the monitor, because the command runs through a shell. Have the script read the value itself. |
| `default_output_styles_folder_ignored`, `default_workflows_folder_ignored`, `default_themes_folder_ignored`, `default_monitors_file_ignored` | warning | The manifest names output styles, workflows, themes or monitors, so Claude Code ignores the default `output-styles/`, `workflows/`, `themes/` or `monitors/monitors.json` unless the manifest lists it too. LSP servers in the manifest add to `.lsp.json` instead. |
## Archives
When you validate a `.zip`, these are errors. When you validate a folder, `validate` checks the archive `plugin pack` would make from it, and reports the file rules as portal rules; the `plugin_root_*` rules apply only to a `.zip`. A file or folder in it that you don't have permission to read is an `archive_member_unreadable` error for a folder too, because `pack` and `publish` can't zip it: run `chmod u+r` on it (`u+rx` for a folder), or move it out of the plugin.
| Code | Meaning |
| - | - |
| `archive_format_not_zip`, `archive_empty`, `archive_member_unreadable` | The file isn't a readable, non-empty zip. |
| `archive_too_large`, `archive_uncompressed_too_large`, `archive_too_many_entries` | Over 100 MB, over 512 MB unpacked, or over 5,000 entries. |
| `archive_member_too_large` | One file is over 100 MB. |
| `archive_member_type_unsupported` | A link or special file; an archive holds only files and folders. |
| `archive_member_path_empty`, `archive_member_path_has_outer_whitespace`, `archive_member_path_has_backslash`, `archive_member_path_absolute`, `archive_member_path_has_empty_segment`, `archive_member_path_has_parent_segment` | A file's path is empty, absolute, uses `\` or `..`, or has stray spaces or empty parts. |
| `archive_member_path_too_deep` | A path is more than 20 folders deep. |
| `archive_member_path_duplicate`, `archive_member_path_normalization_collision`, `archive_member_path_type_conflict` | Two paths are the same, differ only in letter case or Unicode form, or one is both a file and a folder. |
| `plugin_root_missing`, `plugin_root_ambiguous`, `plugin_root_has_siblings` | The archive has to hold one plugin, at its top or in one folder there, with nothing next to it. |
| `archive_metadata_ignored` (warning) | macOS Finder data (`__MACOSX`, `.DS_Store`) is left out. Make the archive with `plugin pack`. |
| `archive_member_secret` (warning) | A file looks like a private key or a login: an SSH key (`id_rsa`, `id_ed25519`), a `.p12` or `.pfx` file, a `.pem` or `.key` file with a private key in it, or a `.netrc`, `.npmrc` or `.pypirc` with a password or token. Everyone who installs the plugin gets a copy, so move it out of the plugin folder and have the plugin ask for it in a setting or an environment variable. `pack` and `publish` always leave out `.env` files. |
## Marketplaces
`validate` checks a folder with a Claude Code `.claude-plugin/marketplace.json` or a Codex `.agents/plugins/marketplace.json`, or the catalog file itself. A Claude Code catalog gets the rules `claude plugin validate` applies. Each plugin in the marketplace's folders is then checked as a plugin, and its problems start with `plugins[N] (name):`, with file paths from the top of the marketplace. A plugin that is also its own marketplace is checked once.
| Code | Meaning |
| - | - |
| `marketplace_json_invalid` | The catalog isn't a JSON object. |
| `marketplace_name_missing`, `marketplace_name_invalid` | The marketplace needs a name of letters, digits, `.`, `_` and `-`, starting with a letter or digit, with no spaces, `..` or non-ASCII letters. Codex takes no dots in a marketplace name, so a dotted name is an error in a Codex catalog, and a warning in a Claude Code catalog when the folder has no `.agents/plugins/marketplace.json`, because Codex then reads the Claude Code one. Use `acme-tools` rather than `acme.tools`. |
| `marketplace_name_reserved` | Claude Code keeps names such as `inline`, `npm` and `github`, and names that start with `claudeai-` (error). The official Anthropic names are a warning, because Claude Code takes them only from Anthropic's repositories. `org`, `org-provisioned` and `unknown` are a warning too: Claude Code takes them, but Claude Desktop's managed marketplace sync rejects the whole marketplace. |
| `marketplace_name_impersonates` | A Claude Code marketplace named like one of Anthropic's own: `anthropic` or `claude` followed by `marketplace`, `plugins`, `official` or `directory` (`claude-plugins-hub`), or `official` next to either (`acme-claude-official`), also when the words are split with separators (`cl-aude-marketplaces`). Claude Code refuses to add the marketplace, so lead with your own name, such as `acme-claude-plugins`. Codex takes the name, and Enconvo still installs the marketplace. |
| `marketplace_name_too_long` (warning) | The name is longer than 128 characters. Claude Code takes it, but Claude Desktop's managed marketplace sync rejects the marketplace. |
| `marketplace_owner_missing` | A Claude Code catalog needs `owner.name`. |
| `marketplace_description_missing`, `marketplace_display_name_missing` (warning) | Claude Code shows the description; Codex shows `interface.displayName`. |
| `marketplace_field_unknown` (warning) | Claude Code ignores this top-level or `metadata` field. The message names the field you likely meant, such as `plugins` for `plugin`. |
| `marketplace_field_wrong_type` | A top-level field Claude Code can't read, so it can't add the marketplace: a `$schema`, `version` or `description` that isn't text, an `owner.email` or `owner.url` that isn't text, a `forceRemoveDeletedPlugins` that isn't `true` or `false`, an `allowCrossMarketplaceDependenciesOn` that isn't a list of marketplace names, or a `metadata` that isn't an object or whose `version` or `description` isn't text. `renames` that isn't an object of old plugin names to a new name or `null` is this error too; Claude Code then ignores the renames. |
| `marketplace_rename_unresolved` | An old name in `renames` doesn't lead to a plugin in the catalog or to `null`: the chain loops, ends at a name that isn't in `plugins`, or takes more than 16 steps. |
| `marketplace_plugins_missing`, `marketplace_plugins_empty` | `plugins` isn't a list, or it is empty (a warning). |
| `marketplace_plugin_root_invalid` | `metadata.pluginRoot` has to be a relative path inside the marketplace. |
| `marketplace_plugin_invalid`, `marketplace_plugin_name_missing`, `marketplace_plugin_name_invalid`, `marketplace_plugin_duplicate` | An entry isn't an object, has no usable name, or repeats another's. An entry's name follows the plugin `name` rule: letters, digits, `-` and `_`, with single dots between them. |
| `marketplace_plugin_name_too_long` (warning) | The entry's name is longer than 128 characters. Claude Code takes it, but Claude Desktop's managed marketplace sync drops the entry. |
| `marketplace_plugin_field_wrong_type` | Claude Code lists the plugin but can't install it, because an entry field has the wrong type: a text field such as `version`, `description`, `license`, `repository` or `category` that isn't text, a `homepage` that isn't a URL, `keywords` or `tags` that aren't lists of text, a `strict` or `defaultEnabled` that isn't `true` or `false`, an `author` without a `name`, a `dependencies` entry Claude Code can't read, `headers` values that aren't text, or a component field of the wrong shape, such as a `skills` path without `./`, an `agents` file that isn't `.md`, or an `mcpServers` file that isn't `.json` or `.mcpb`. The same checks apply inside `experimental`. An entry's `userConfig` and `channels` get the `user_config_*` and `channel*` checks a `plugin.json` gets. |
| `marketplace_plugin_field_unknown` (warning) | Claude Code ignores this field in the entry, its `experimental`, its `relevance` or `relevance.signals`. The message names the field you likely meant, or the manifest the field comes from. |
| `marketplace_plugin_field_ignored` (warning) | The entry's `experimental`, `metadata` or `relevance` isn't an object, so Claude Code ignores it. |
| `marketplace_plugin_relevance_invalid` | `relevance` needs `signals` naming at least one of `cli` (up to 10 command names), `hosts` (up to 20 lowercase host names, like `registry.terraform.io`), `filesRead` and `cwd` (up to 10 patterns with forward slashes), or `manifestDeps` (1 to 10 `{"file", "pattern"}` regular expressions), and an optional `topic` of 1 to 64 characters. The message says whether Claude Code can't install the plugin or only `claude plugin validate` refuses it. |
| `marketplace_plugin_source_missing`, `marketplace_plugin_source_invalid` | The source is missing or can't be fetched: a path with `..` or outside the marketplace, a bare name without `metadata.pluginRoot`, a `sha` that isn't a full commit, an `archive` that isn't a public https zip or has a `sha256` that isn't 64 hex digits, or a git address Enconvo can't clone. |
| `marketplace_plugin_source_unsupported` (warning) | Enconvo can't install a `command` source. |
| `marketplace_plugin_folder_missing`, `marketplace_plugin_empty` | The plugin's folder isn't there, or it has no `plugin.json` and the entry gives it nothing to load. |
| `marketplace_plugin_manifest_conflict` | `"strict": false` with components, over a plugin that has its own `plugin.json`. Claude Code doesn't load it and Enconvo refuses to install it. |
| `marketplace_plugin_name_mismatch`, `marketplace_plugin_version_mismatch` (warning) | The entry's name or version differs from the plugin's `plugin.json`. |
| `marketplace_plugin_hooks_not_inline` (warning) | Only hooks written in the entry are applied. |
| `marketplace_plugin_headers_helper_not_strict` | An `archive` source with a `headersHelper` needs `"strict": false`, so the plugin's whole manifest is in the entry where people can review it. Claude Code refuses to run the helper otherwise. |
| `marketplace_plugin_headers_ignored` (warning) | `headers` and `headersHelper` apply only to an `archive` source, so on any other source Claude Code and Enconvo ignore them. On an archive, Enconvo doesn't send `headers` or run `headersHelper`, so a download that needs them fails in Enconvo. |
| `marketplace_plugin_archive_unpinned` (warning) | An `archive` source with a `headersHelper` has no `source.sha256`. Pin the digest so people install the archive you reviewed. |
| `marketplace_plugin_header_dropped` (warning) | A routing or identity header, such as `Host`, `Cookie`, `X-Forwarded-For` or `Proxy-Authorization`, which Claude Code drops when it downloads the archive. |
| `marketplace_plugin_listing_field_misplaced` (warning) | The entry has `icon`, `documentationUrl`, `supportUrl`, `privacyPolicyUrl` or `termsOfServiceUrl`, which belong in the plugin's `.claude-plugin/plugin.json`. `claude plugin validate` reports them as unknown in an entry. |
| `marketplace_plugin_manifest_missing` (warning) | A Codex marketplace plugin without `.codex-plugin/plugin.json`. |
| `marketplace_policy_missing`, `marketplace_policy_invalid`, `marketplace_category_missing` | A Codex entry needs `policy.installation` (`AVAILABLE`, `INSTALLED_BY_DEFAULT` or `NOT_AVAILABLE`), `policy.authentication` (`ON_INSTALL` or `ON_USE`) and a `category`. A missing one is a warning; a wrong value is an error. |
## Enconvo `package.json`
| Code | Severity | Meaning |
| - | - | - |
| `plugin_name_format` | error | `name` uses only letters, digits, dots, dashes and underscores. |
| `plugin_version_not_semver`, `plugin_min_app_version_not_semver` | error | `version` or `minAppVersion` isn't a version number like `1.2.0`. |
| `plugin_title_missing` | error | `title` isn't set. |
| `plugin_description_missing` | warning | `description` isn't set. |
| `screenshots_too_many` | error | More than 8 images in `metadata/`. |
| `screenshot_file_ignored` | warning | A file in `metadata/` isn't an image and is left out. |
| `image_file_unreadable` | error | You don't have permission to read `metadata/` or an image in it. |
| `store_link_not_https` | warning | A link in `interface` (`websiteURL`, `supportURL`, `privacyPolicyURL`, `termsOfServiceURL`) isn't an `https://` address without a user name or password, of up to 2,048 characters, so the store page leaves it out. |
## Review materials
These check the `review` object (in `package.json`, or `extensions["com.openai"].review` in the `plugin.json` OpenAI's portal imports; see [where they go](/extensions/publishing-guidelines#review-materials)) and, in that `plugin.json`, `extensions["com.openai"].publication`. See [Review materials](/extensions/publishing-guidelines#review-materials). A field set to `null` counts as left out, as it does in OpenAI's import, which keeps the value saved there.
| Code | Severity | Meaning |
| - | - | - |
| `review_wrong_type`, `review_test_cases_wrong_type`, `review_test_case_wrong_type` | error | `review`, `test_cases` or a case isn't an object. |
| `review_test_cases_too_many` | error | A list has more than 20 cases. |
| `review_test_case_description_missing`, `review_test_case_prompt_missing`, `review_test_case_expected_behavior_missing` | error | A case needs a `description` and `prompt`; a positive case also needs `expected_behavior`. |
| `review_test_case_text_wrong_type`, `review_test_case_text_empty`, `review_test_case_text_too_long` | error | A case's text isn't text, is empty, or is over 4,000 characters. |
| `review_test_case_file_attachment_urls_wrong_type`, `review_test_case_file_attachments_too_many` | error | `file_attachment_urls` isn't a list of addresses, or has more than 10. |
| `review_test_case_url_format`, `review_demo_recording_url_format` | error | An address isn't `https://`. |
| `review_commerce_wrong_type` | error | `commerce` isn't `true` or `false`. |
| `review_commerce_description_wrong_type`, `review_commerce_description_empty`, `review_commerce_description_too_long` | error | `commerce_description` isn't usable text of up to 4,000 characters. |
| `publication_release_notes_wrong_type` | error | `publication.release_notes` isn't text. |
| `review_test_credentials_in_package`, `review_reviewer_instructions_in_package` | error | Sign-in details would ship inside the package, which anyone can download. Pass them with `plugin publish --review-notes`, or in the Review details form of OpenAI's dashboard. |
| `review_test_cases_server_count` | portal | `review.test_cases` in `plugin.json` are for a plugin with exactly one MCP server. A server declared in both `mcp.json` and `.mcp.json` under the same name counts once. |
| `publication_wrong_type`, `publication_countries_wrong_type`, `publication_translations_wrong_type`, `publication_translation_wrong_type` | portal | `publication`, `countries`, `translations` or a translation isn't the right shape: `countries` is a list, `translations` an object keyed by locale such as `fr-FR`. |
| `publication_country_format` | portal | A country isn't a two-letter uppercase code like `US`. `[]` makes the plugin available everywhere. |
| `publication_translation_locale_empty` | portal | A translation's locale is empty. |
| `publication_translation_subtitle_*`, `publication_translation_description_*` (`_wrong_type`, `_empty`, `_character_unsupported`, `_too_long`) | portal | A translated subtitle is one line of up to 30 characters; a description is up to 4,000 characters and may have line breaks. Neither may be only spaces or hold tabs or other control characters. The limits count spaces at either end. |
| `review_test_cases_missing` | warning, only with `--openai` | A plugin with an MCP server or app has no review materials. The warning names the manifest they go in. |
| `review_manifest_ignored` | warning, only with `--openai` | The review materials are in a manifest OpenAI's portal doesn't import, such as `.claude-plugin/plugin.json` beside a `.codex-plugin/plugin.json`. The Enconvo store still takes them from there. |
| `review_positive_test_cases_count`, `review_negative_test_cases_count` | warning | OpenAI's final submission takes exactly 5 positive and 3 negative cases. Checked in `plugin.json` only. |
| `review_demo_recording_missing`, `publication_release_notes_missing` | warning | OpenAI's final submission needs a demo video and release notes. Checked in `plugin.json` only; a plugin with only skills needs no demo. |
| `publication_country_unknown` | warning | A country isn't an ISO 3166 code. The United Kingdom is `GB`, not `UK`. |
| `review_test_case_tools_triggered_missing` | warning | A positive case doesn't name the tools it should call. |
| `review_commerce_description_missing` | warning | `commerce` is `true` but nothing says what is sold. |
## OpenAI's final submission
OpenAI's portal takes the uploaded plugin without these, then asks for them when you submit it to the directory. `validate --openai` and `pack --openai` report them as warnings, and plain `validate` leaves them out. They check the listing in `.codex-plugin/plugin.json`, `plugin.json` or `.claude-plugin/plugin.json`.
| Code | Severity | Meaning |
| - | - | - |
| `claude_format_normalized` | warning, only with `--openai` | The plugin has only `.claude-plugin/plugin.json`. The portal converts it to `.codex-plugin/plugin.json` and fills in the listing, such as the display name and short description, with its own defaults. To write the listing yourself, add a `.codex-plugin/plugin.json` with an `interface`. |
| `submission_description_required` | warning, only with `--openai` | `interface.longDescription` isn't set. The directory shows it on the plugin's page; it takes up to 4,000 characters and may have line breaks. |
| `plugin_category_defaulted` | warning, only with `--openai` | `interface.category` isn't set, so the directory lists the plugin under Other. |
| `plugin_listing_urls_missing` | warning, only with `--openai` | A plugin with an MCP server needs `websiteURL`, `supportURL`, `privacyPolicyURL` and `termsOfServiceURL` in `interface`. A plugin with only skills doesn't. |
| `screenshot_count_mismatch` | warning, only with `--openai` | A plugin with an MCP server takes one screenshot for each starter prompt (`interface.defaultPrompt`). |
| `screenshot_format_unsupported` | warning, only with `--openai` | A screenshot isn't a PNG or JPEG image. |
| `screenshot_dimensions_unsupported` | warning, only with `--openai` | A screenshot isn't exactly 706 pixels wide and 400 to 860 pixels tall. |
The directory shows the developer name of your verified OpenAI identity, whatever `interface.developerName` says. Screenshots are only for an MCP server with its own interface; see `screenshot_configuration_excluded` and, from `plugin scan --openai`, `screenshots_not_allowed`.
## Updates
An update replaces the whole plugin, on OpenAI's portal as in Enconvo and Codex. To check a new version as an update, give `validate` or `pack` the release before it, as a `.zip` or a folder: the zip `plugin pack` made, or the one OpenAI's portal gives you with **Download release ZIP** in the published version's **…** menu.
```sh theme={null}
npx -p @enconvo/api enconvo plugin validate --openai --previous my-plugin-1.0.0.zip
npx -p @enconvo/api enconvo plugin pack --openai --previous my-plugin-1.0.0.zip
```
Only what changed counts; the previous release's own problems aren't reported. `validate --json` lists the skills and MCP servers it compares under `components`.
| Code | Severity | Meaning |
| - | - | - |
| `plugin_previous_unreadable` | error | The previous release isn't there, or it isn't a plugin; the message gives its first error. |
| `plugin_name_mismatch` | portal | The plugin's `name` changed. OpenAI's portal takes an update only under the published plugin's name, and Enconvo and Codex install a renamed plugin as another plugin. |
| `plugin_version_unchanged` | warning, also with `--openai` | The `version` is the previous release's. OpenAI's portal asks you to confirm before it reuses a published version, and Enconvo's store doesn't take one. |
| `plugin_id_changed` | warning | The previous release has an `id` (`extensions["com.openai"].id`, or `id` in `.codex-plugin/plugin.json`) and this version has another one or none. Managed plugin catalogs know the plugin by the id they gave it, so keep it. OpenAI's portal keeps its own identity for an uploaded ZIP. |
| `plugin_version_not_higher` | warning | The version is lower than the previous release's, or differs from it only in build metadata (`1.0.0+2`). Enconvo's store takes only a higher version. Checked when both are version numbers like `1.2.0`. |
| `mcp_server_added_to_skills_plugin` | portal | The previous release has no MCP server and this version adds one. OpenAI's portal takes an MCP server only in a plugin's first ZIP. Checked for a plugin with a `plugin.json`; Enconvo's store takes the change. |
| `mcp_server_url_changed` | portal | A remote MCP server's URL changed. OpenAI's update flow can't move a published server: ask OpenAI's support to change it, or keep the old URL. A URL with a variable, such as `${MCP_URL}`, isn't compared. Checked for a plugin with a `plugin.json`. |
| `plugin_components_removed` | warning | This version leaves out skills or MCP servers the previous release has, so the update removes them for everyone who installed it. |
## Codes only OpenAI's portal reports
OpenAI's portal has a few codes that `validate` doesn't report, because they repeat a rule `validate` already checks under another code, or because only OpenAI can check them.
| Code | Meaning |
| - | - |
| `submission_display_name_*`, `submission_subtitle_*`, `submission_description_too_long`, `submission_description_character_unsupported`, `plugin_capability_invalid` | The listing you edit at final submission breaks the same limits as `interface.displayName`, `interface.shortDescription`, `interface.longDescription` and `interface.capabilities`; see [Text fields](#text-fields). |
| `submission_developer_name_*`, `developer_name_defaulted` | The developer name comes from your verified OpenAI identity. |
| `manifest_normalized` | The portal saves the manifest it read as `.codex-plugin/plugin.json`, and asks you to confirm any field it changed. |
| `skill_frontmatter_adjusted` | The portal trimmed the spaces around a skill's `name` and `description` and collapsed the spaces inside them. Nothing to fix. |
| `mcp_configuration_excluded` | The portal took an MCP configuration out of a skills-only upload. |
| `archive_member_path_too_long`, `skill_bundle_too_large` | A path, or a skill's compressed files, are over a limit OpenAI doesn't publish; the portal's message gives the limit. |
| `archive_plugin_files_missing` | A skills-only ZIP has no plugin manifest or no valid skill. `validate` reports these as `plugin_manifest_missing` and the `skill_*` codes. |
| `scan_required` | The portal needs a successful, current scan of the production MCP server; rescan after the server changes. `plugin scan --openai` checks the tools beforehand. |
| `domain_verification_required` | Host the token the portal gives you at `/.well-known/openai-apps-challenge` on the MCP server's host or an allowed parent host, then select **Verify Domain**. `plugin scan --openai` says what those URLs answer, and `--challenge-token <token>` checks for the exact token first; see [Domain verification](#domain-verification). |
| `app_not_eligible` | A local or workspace package refers to an MCP server that isn't eligible or available. To list the plugin in the directory, submit it **With MCP** and give the MCP server directly. |
| `justification_required` | A tool annotation has no justification of its read-only, open-world or destructive behavior. The portal's error list still has this code, though its submission page no longer asks for one; if the portal reports it, give the justification there. |
## MCP server scan
`validate` reads the plugin's files; `plugin scan` starts its MCP servers. It connects to each server the plugin declares, lists the server's tools and checks them, as OpenAI's portal does when you connect the plugin's server. Scanning runs the plugin's code, so scan only plugins you trust.
```sh theme={null}
npx -p @enconvo/api enconvo plugin scan [path] # the plugin's folder
npx -p @enconvo/api enconvo plugin scan [path] --openai # also what OpenAI's portal needs
npx -p @enconvo/api enconvo plugin scan [path] --timeout 60 # seconds to wait for each server; the default is 30
npx -p @enconvo/api enconvo plugin scan [path] --json # the result as JSON
npx -p @enconvo/api enconvo plugin scan [path] --challenge-token <token> # checks the token OpenAI's portal gave you
```
```text theme={null}
notes (mcp.json, stdio: node ./mcp/server.mjs): 2 tools
search_notes readOnlyHint=true destructiveHint=false openWorldHint=false
delete_note readOnlyHint=false destructiveHint=? openWorldHint=?
warning[annotations_required] mcp.json: MCP server "notes": 1 of 2 tools doesn't set every annotation: delete_note (destructiveHint, openWorldHint). OpenAI's final submission asks for readOnlyHint, destructiveHint and openWorldHint as true or false on every tool, and Enconvo uses them to decide which tools run without asking. (OpenAI's plugin portal)
notes@1.2.0: 1 MCP server, 2 tools, 1 warning.
```
With `--openai`, `annotations_required` is an error. `scan` finds servers where Enconvo does, in the manifests' `mcpServers`, `mcp.json` and `.mcp.json`, and starts them as Enconvo, Codex and Claude Code do: a command starts in no particular folder unless it sets `cwd`, and gets only basic variables from your shell (`HOME`, `PATH`, `SHELL`, `USER` and a few more) plus the ones it names in `env_vars` and its own `env`. A server at a URL is reached over Streamable HTTP, with the headers it declares and the token in `bearer_token_env_var`. For a tool that shows its own interface, `scan` reads its view with `resources/read`, as Enconvo does, for the domains the view declares; the listing shows each view that embeds pages. `scan` exits with status 1 when there is an error, and doesn't take a `.zip`: unzip it and scan the folder.
| Code | Severity | Meaning |
| - | - | - |
| `annotations_required` | portal | A tool doesn't set `readOnlyHint`, `destructiveHint` and `openWorldHint` to `true` or `false`. OpenAI's final submission asks for all three on every tool, and Enconvo uses them to decide which tools run without asking. See [MCP tools](/extensions/publishing-guidelines#mcp-tools) for which value fits. |
| `annotations_conflicting` | warning | A tool is marked both `readOnlyHint: true` and `destructiveHint: true`. A read-only tool changes nothing, so one of them is wrong. |
| `tool_description_missing` | warning | A tool has no description. The model picks tools by what their descriptions say. |
| `tool_name_duplicate` | warning | The server lists two tools with the same name. |
| `tools_missing` | warning, only with `--openai` | The server lists no tools, so OpenAI's portal has nothing to scan or review. |
| `domain_challenge_missing` | warning, only with `--openai` | No URL where OpenAI's portal verifies the server's domain serves a token yet. Expected until the portal gives you one after the upload; see [Domain verification](#domain-verification). |
| `domain_challenge_format` | warning | The server's own challenge URL answers with a web page, JSON, several tokens or a redirect instead of the token alone, or the token has spaces or a line break around it. The portal asks for the exact token as plain text. |
| `domain_challenge_mismatch` | error, only with `--challenge-token` | No challenge URL serves the token you gave. The message lists what each one answers. |
| `domain_challenge_unchecked` | warning | You gave `--challenge-token`, but the plugin has no MCP server at a public `https://` URL, so there's no domain to verify. |
| `mcp_server_not_remote` | warning, only with `--openai` | The server runs on the user's computer, or its URL isn't a public `https://` address. OpenAI's portal connects to a server at a public `https://` URL to scan and review it, so deploy the server and declare its URL before you submit there. Enconvo, Codex and Claude Code run a local server as it is. |
| `scan_server_failed` | error | The server couldn't start, exited, or didn't answer in time. The message quotes the end of what it printed on stderr. When a command uses paths like `./server.js`, start it from the plugin's folder: `${CLAUDE_PLUGIN_ROOT}/server.js` in `.mcp.json`, or `"cwd": "./"` in `mcp.json`. |
| `scan_sign_in_required` | warning | The server asked for sign-in (HTTP 401 or 403), so its tools weren't listed. Enconvo signs in when the plugin is installed. To scan it here, give the server a token through `bearer_token_env_var` or its `headers`. |
| `scan_stdout_not_jsonrpc` | warning | A command server printed something on stdout that isn't an MCP message. Enconvo, Codex and Claude Code read only JSON-RPC there, so log to stderr. |
| `scan_variable_unset` | warning | The server's settings use a variable, such as `${API_KEY}`, that isn't set in your shell. Set it to scan the server as it will run. |
| `scan_transport_unsupported` | warning | The server uses the older `sse` transport, or another one the scan doesn't speak, so it wasn't scanned. Enconvo still runs an `sse` server. |
| `ui_template_openai_only` | warning | A tool names its view only in `_meta["openai/outputTemplate"]`. Enconvo and ChatGPT read that key, but other MCP Apps hosts read only `_meta.ui.resourceUri`, so set that to the same `ui://` URI as well. |
| `ui_resource_unreadable` | warning | A tool points at a view the server doesn't give: the server doesn't offer resources, or `resources/read` fails for that URI. Enconvo and other hosts then show the tool's result without its interface. |
| `widget_csp_openai_only` | warning | A view declares domains only in `_meta["openai/widgetCSP"]` (`connect_domains`, `resource_domains`, `frame_domains`). Enconvo and ChatGPT read that key, but other MCP Apps hosts read only `_meta.ui.csp` (`connectDomains`, `resourceDomains`, `frameDomains`), so the view can't reach those domains there. Declare them in both. |
| `frame_domain_explanation_required` | warning, only with `--openai` | A view embeds pages from other domains (`frameDomains`). OpenAI's final submission asks you to explain each one: what the page does, why the plugin embeds it, and who controls its domain. Pages from the MCP server's own registrable domain are allowed; separate tenants on a shared host count as different domains. |
| `screenshots_not_allowed` | error, only with `--openai` | `interface.screenshots` lists images, but no tool shows an interface of its own (`_meta.ui.resourceUri` or `_meta["openai/outputTemplate"]`). OpenAI's portal takes screenshots only from a plugin whose scan finds one, and its directory shows starter prompts instead. Reported only when every server was scanned. |
| `scan_servers_missing` | error | The plugin declares no MCP server. |
| `scan_archive_unsupported` | error | `scan` was given a `.zip`. |
OpenAI's portal no longer asks you to justify each tool's annotations; if its automated review flags one, you can appeal with an explanation. It does ask for a justification of each page your views embed (`frame_domain_explanation_required`). A server you have to sign in to is scanned there with the reviewer account you give in the Review details form.
### Domain verification
When you connect a plugin's MCP server in OpenAI's portal, after the upload, the portal verifies that you control the server's domain before you can submit the plugin. It gives you a token, and you serve that token at `/.well-known/openai-apps-challenge` on the MCP server's host or on a parent domain: for `https://mcp.example.com/mcp`, at `https://mcp.example.com/.well-known/openai-apps-challenge` or `https://example.com/.well-known/openai-apps-challenge`. The URL answers with the token alone, as plain text: not a web page, JSON or a list of tokens. The path of the server's URL doesn't matter. If another plugin's token is already at that URL, use a parent domain or a hostname of your plugin's own rather than replacing it.
For each server at a public `https://` URL, `scan --openai` reads those URLs and lists what each answers. Once the portal gives you the token, check it before you select **Verify Domain**:
```sh theme={null}
npx -p @enconvo/api enconvo plugin scan --challenge-token tok_123
```
```text theme={null}
domain verification:
https://mcp.example.com/.well-known/openai-apps-challenge: HTTP 404
https://example.com/.well-known/openai-apps-challenge: the token you gave
```
One URL that serves the token is enough. `scan` exits with status 1 when none does (`domain_challenge_mismatch`).
## Packing and publishing
| Code | Severity | Meaning |
| - | - | - |
| `plugin_path_missing` | error | The folder doesn't exist. |
| `plugin_build_missing` | error | Build the Enconvo plugin first (`npm run build`). |
| `plugin_format_not_packable` | error | A desktop extension is packed with `npx @anthropic-ai/mcpb pack`. |
| `plugin_format_not_publishable` | error | The store takes Enconvo, Codex, Claude Code and portable plugins; share a desktop extension's `.mcpb` file instead. |
| `plugin_version_missing` | error | The store needs a version. |
| `plugin_package_too_large` | error | The package is over 50 MB. |
| `plugin_readme_too_large` | warning | The README is over 64 KB, so the store page leaves it out. |
| `store_icon_missing` | warning | The plugin has no icon the store can show (PNG, JPEG, WebP or GIF up to 5 MB) in `interface.logo` or the other `interface` logos, or in a Claude Code plugin's `icon`, so it shows a default icon. |
# Frequently Asked Questions
Source: https://docs.enconvo.ai/faq
Find the right feature and resolve common setup questions.
## Which macOS version do I need?
Current builds target macOS 14 or later. MLX local processing requires Apple Silicon. See [Installation](/installation).
## Do I need an API key?
You can use Enconvo Cloud, your own provider API key, supported account connections, or local models. Configure the capability you need under [Providers](/providers/overview).
## Does a local model keep every task offline?
Only the operations performed by local providers stay local. Web search, remote MCP servers, cloud speech, or cloud embeddings can still send data outside the Mac. See [Privacy and Security](/configuration/privacy-security).
## What is the difference between Dictation, Voice Trigger, and Live Voice?
Dictation inserts recognized speech as text. Voice Trigger sends speech to an Agent. Live Voice is a two-way spoken conversation. See [Dictation](/features/dictation) and [Live Voice](/features/live-voice).
## What is the difference between Appshots and Quick Capture?
[Appshots](/features/appshots) attaches the current app window as conversation context. [Quick Capture](/features/quick-capture) saves current app content into a knowledge base for later retrieval.
## What is the difference between Memory and Knowledge Base?
[Memory](/ai/memory) holds reusable facts. [Knowledge Base](/ai/knowledge-base) stores reference material and retrieves relevant content.
## Why did changing the default model not change an existing chat?
Current chats can keep their own model and reasoning selection. Project defaults and Agent defaults also have different scopes. See [Model Selection](/ai/model-selection-guide).
## Can Enconvo use tools from other services?
Yes, through installed plugins, Skills, and configured [MCP Servers](/features/mcp). To let an external local AI client read Enconvo's knowledge bases, use [Knowledge Base MCP](/advanced/knowledge-base-mcp).
## Can tasks run while I am away?
[Scheduled Tasks](/workflows/scheduled-jobs) can run locally while Enconvo and the Mac are available. Configure IM delivery if you want the results sent to a connected chat.
## Where are missing features?
Check your app version, installed extensions, permissions, and [update channel](/configuration/updates). Beta and Dev features can appear before Production. Use the [Feature Directory](/reference/feature-directory) to find the guide and settings entry.
## Where should I report a problem?
Use the [Enconvo community](https://discord.gg/jYsdVRRK2k) with the app version, feature, expected result, actual error, and a small reproduction. Remove private content and credentials from screenshots and logs. See [Troubleshooting](/getting-started/troubleshooting).
# AI Commands
Source: https://docs.enconvo.ai/features/ai-commands
Save a prompt as a reusable command.
An AI Command packages a repeated prompt with its model and settings. Use one for a focused operation such as rewriting a support reply; use an [Agent](/ai/agents) for broader work with tools, or a [Workflow](/workflows/introduction) for a sequence of steps.
<Frame>
<img alt="Unsaved Friendly Support Reply AI Command example" />
</Frame>
## Create a command
1. Open **Settings → AI Commands**, or run **Create AI Command** from SmartBar.
2. Give it a recognizable title and an instruction describing the input and desired output.
3. Choose the AI model and other options shown in the editor. Use the global model when you want the command to follow your general model preference.
4. Save it, then find the command by name in SmartBar.
5. Test with a short sample and refine the prompt based on the result.
Example instruction:
```text theme={null}
Rewrite the input as a short, friendly support reply.
Preserve names, dates, product names, and technical details.
Return only the rewritten reply.
```
## Use changing context
Where a field supports variables, use the variable picker to include input text, selected text, the active app, or other context. See [Variables](/workflows/variables). Inspect the expanded context before using a command with private documents.
## Maintain commands
Revisit the command's settings when changing its model, prompt, or shortcut. **More → Reset configuration**, where available, restores defaults after confirmation; read the prompt before resetting a customized command.
If a command is missing, check that it was saved and search its title. If output ignores selected text, review the input/context settings and Accessibility permission.
# App Sidebar
Source: https://docs.enconvo.ai/features/app-sidebar
Work with an assistant alongside the application or website you are using.
App Sidebar places an Enconvo conversation alongside an app window. It uses the available app context to help you read, write, or work without repeatedly copying information into a separate chat.
## Open and configure
1. Focus the app you want help with.
2. Run **Show App Sidebar** from Enconvo, or use its assigned shortcut.
3. Where enabled, click the side hint on the app window to open the sidebar.
4. Ask a specific question and review the attached context before submitting.
Open **Settings → App Sidebar** for sidebar behavior. **Applications** and **Websites** configure app- and site-specific destinations. Check [Shortcut settings](/configuration/keyboard-shortcuts) for your installed hotkey rather than relying on an older video's defaults.
## What context is available
Browser integrations can provide a page title, URL, and content. Finder context can include selected files. Other apps may expose selected text, accessible window content, or a screenshot, depending on permissions and the app itself. A code editor does not necessarily expose a full project or every open file.
Try: “Explain the selected paragraph,” “Help me rewrite this draft more concisely,” or “Describe what is visible in this window.” Add [Appshots](/features/appshots) or explicit files when the available context is incomplete.
## Chat and actions
Continue a conversation, start another one, or use the available window controls to keep the assistant nearby. App context supplies information; interacting with app controls requires the appropriate [Computer Use](/features/computer-use) or [Browser Control](/features/browser-control) tools on the Agent.
## Troubleshooting
If the sidebar does not attach, bring the intended app window forward and reopen it. If text is missing, check Accessibility permission, app exclusions, and the attached context. Use the [Chat Window](/ai/chat) when you need more room for history or files.
# Appshots
Source: https://docs.enconvo.ai/features/appshots
Attach the frontmost app window to an AI conversation.
Appshots captures the frontmost external app window as context for your next request. Use it when you want to ask about something visible without saving it to a knowledge base.
## Capture an app
1. Open **Settings → Context → Appshots** and enable **Appshots**.
2. Check the configured **Hotkey**. The settings page explains how to press it; modifier-key gestures and ordinary shortcuts are configurable.
3. Bring the app you want to discuss to the front and press that hotkey.
4. Review the attached context in Enconvo, then ask a specific question such as “Explain the error in this window.”
<Frame>
<img alt="Appshots settings with enable, capture sound, and hotkey controls" />
</Frame>
## Choose the right capture tool
| Goal | Use |
| - | - |
| Ask about the current app window | Appshots |
| Draw attention to a region before asking | [Screen Doodle](/features/screen-doodle) |
| Save the current app's content for later search | [Quick Capture](/features/quick-capture) |
| Extract text from an image | [OCR](/ai/ocr) |
**Capture sound** controls the shutter feedback. A sound alone is not a substitute for checking the attachment before submitting.
## If no context appears
Check **Settings → Permissions**, especially Screen Recording and Accessibility. Bring the target app forward again; Appshots is intended to capture an external app, not Enconvo's own settings. If a shortcut conflicts with another app, change it in Appshots settings.
Captured content can be sent to the model you use for the request. See [Context Awareness](/features/context-awareness) for choosing context sources.
# Avatars
Source: https://docs.enconvo.ai/features/avatar
Give an Agent a desktop character and voice.
An Avatar is a desktop character connected to an Agent. It presents voice conversations with speech-synchronized animation while the Agent uses its normal instructions and tools.
<Frame>
<img alt="Avatar gallery showing Agent assignment, rendering quality, voice, and optional downloads" />
</Frame>
## Set up a character
1. Open **Settings → Agents → Avatar**.
2. Choose a character in the gallery and download its base package.
3. Assign an Agent when prompted. Each Agent has one Avatar assignment, and each character is assigned to one Agent.
4. Choose the character's **Quality** and **Voice**. Voice changes apply to the next voice conversation.
5. Click **Open** to show the assigned Agent's Avatar.
**Optional downloads** lists additional packages for that character, such as higher-resolution textures or motions when available. Start with the base package and choose a quality appropriate for your Mac.
## Talk and interact
Set up [Realtime Voice](/features/live-voice), then use the Avatar's conversation controls to start talking. Right-click the character for available voice, history, settings, and character controls. The chat bubble shows conversation text and voice activity.
You can move the character, use scroll to rotate it, and use Control-scroll or a pinch gesture to zoom. Transparent margins allow clicks to pass through to the desktop.
## Character selection and Agent identity
The desktop **Character** menu does not reassign Agents. Selecting a character assigned to another Agent opens that Agent's Avatar. An unassigned character is shown through the main Agent. Change permanent assignments in Settings.
The Avatar switch in the menu bar or Dynamic Island opens the main Agent with its assigned character.
## Troubleshooting
| Problem | Check |
| - | - |
| Voice or quality controls are unavailable | Download the character and assign an Agent first |
| Download fails | Read the gallery error, check connectivity and free disk space, and retry |
| Character is blurry when enlarged | Review rendering quality and available optional textures |
| Call will not start | Review Realtime Voice access and microphone permissions |
| The wrong Agent answers | Review the character's Agent assignment |
A [Pet](/features/pet) is a separate desktop companion with different controls.
## Watch the steps
<video aria-label="Browse the Avatar gallery">
<source type="video/mp4" />
[Download the walkthrough](/videos/guides/avatar-gallery.mp4).
</video>
Switch to Downloaded, search for Tia, inspect Optional downloads, then return to Gallery. No package is downloaded and no assignment is changed. This silent walkthrough uses real interface captures with pauses added for reading. The written steps above provide the same instructions.
# Browser Control
Source: https://docs.enconvo.ai/features/browser-control
Read and operate real browser tabs through the Enconvo Companion extension.
Browser Control lets an Agent work with browser tabs that have the Enconvo Companion extension connected. It can read a page, click controls, fill fields, inspect results, and manage tabs using the browser's existing sign-in state.
## Set up
1. Install [Enconvo Companion from the Chrome Web Store](https://chromewebstore.google.com/detail/enconvo-companion/afaklbihknigbnjdkegbnenkheogejkd) in a supported Chromium browser, or use the appropriate extension package for your browser.
2. Keep Enconvo and the browser running.
3. Open the extension popup and confirm its **Connected** status.
4. Check the Agent's browser tool access and any website approval requested by the extension.
5. Start with a read-only task, such as “Read this page and summarize the main points.”
See [Browser Extension](/features/browser-extension) for connected-browser status, targeting, and approval behavior. Safari does not use the Chromium companion extension; use the supported route for your browser rather than assuming every browser has identical capabilities.
## Manual Chromium installation
If your build provides the unpacked extension, open `chrome://extensions` (or your browser's equivalent), enable Developer mode, choose **Load unpacked**, and select `~/.enconvo/chrome_extension/`. Restart Enconvo if its bundled extension folder has not yet been prepared.
## Work with a specific tab
Name the browser and intended page in your request. For example:
> In Edge, read the current documentation tab and list the three setup steps. Keep the page open.
The Agent inspects page state, chooses an element, acts, and checks the resulting state. Page references can change after navigation or dynamic updates; a fresh snapshot helps recover when an element is no longer available.
## Available operations
| Area | Examples |
| - | - |
| Navigation | Open a URL, go back or forward, reload, wait for a condition |
| Reading | Page state, visible text, attributes, screenshots, selected content |
| Interaction | Click, type, fill, select, press keys, scroll, drag |
| Browser organization | Inspect and manage tabs, windows, and connected sessions |
| Advanced tools | Page evaluation, cookies, storage, history, and browser-specific inspection |
Capabilities and website access vary by browser, page, extension version, and enabled tools. Browser-internal pages and restricted content may not be accessible. Browser control can act on your real account; specify whether a task should only prepare a draft or also submit it.
## Configuration and diagnostics
Choose the default browser in Computer Use preferences, or name a browser in the task. The `browser-use/status` Local API route reports connection state. Developers can inspect the installed route schemas under **Settings → Developer → APIs** rather than relying on a fixed list of action names.
## Troubleshooting
* **Not connected:** verify that the extension is enabled and Enconvo is running; inspect the popup status. The companion connects locally on port 11225.
* **Wrong browser or tab:** explicitly name the target and request a fresh page state.
* **Click or fill fails:** inspect the updated page; a dialog, navigation, or embedded frame may have changed the target.
* **Blank screenshot:** make the target tab visible and wait for page content to load.
* **Website asks to sign in:** complete the site's normal login flow; an existing browser profile does not guarantee a valid session for every site.
Use [Computer Use](/features/computer-use) for native macOS apps, file dialogs, and desktop controls.
# Enconvo Browser Extension
Source: https://docs.enconvo.ai/features/browser-extension
Use Enconvo with your real browser session for signed-in websites, website approvals, and browser automation
## Overview
The Enconvo Browser Extension lets Enconvo control your real browser when a task needs your signed-in browser state. Use it for sites such as LinkedIn, Gmail, Salesforce, dashboards, or internal tools where your cookies and browser extensions matter.
For public pages, local previews, or workflows that should not touch your personal browser profile, use isolated browser automation instead.
## Set Up The Extension
<Steps>
<Step title="Install the extension">
Install the Enconvo browser extension in Chrome, Edge, Brave, Arc, Vivaldi, Opera, or Firefox.
</Step>
<Step title="Open your browser">
Keep the browser running. The extension connects to Enconvo automatically over `ws://localhost:11225`.
</Step>
<Step title="Check the toolbar popup">
Click the extension icon. The popup should show **Connected Chrome**, **Connected Edge**, **Connected Firefox**, or the current browser name.
</Step>
<Step title="Start a browser task">
Ask Enconvo to read, click, type, take a screenshot, or manage tabs in the browser.
</Step>
</Steps>
## Popup Status
The extension popup shows:
* **Connection status**: whether the current browser extension instance is connected to Enconvo.
* **Current browser**: the browser this extension instance is connected as, such as Chrome, Edge, Brave, or Firefox.
* **Connected browsers**: other browser extension instances currently connected to Enconvo.
* **Version**: the installed browser extension version.
* **Learn more**: a link back to this documentation page.
If the popup says disconnected, restart Enconvo and refresh the browser. If it still does not connect, disable and re-enable the extension.
## Multiple Browsers
Enconvo can connect to more than one browser at the same time. Browser actions use this priority order when no browser is specified:
1. The default browser selected in Computer Use settings.
2. Your macOS system default browser.
3. The most recently focused connected browser.
You can also target a browser explicitly in automation APIs:
```json theme={null}
{
"browser": "edge"
}
```
Common values include `chrome`, `google_chrome`, `edge`, `brave_browser`, `arc`, `vivaldi`, `opera`, and `firefox`.
## Current Tab Targeting
When a browser task starts, Enconvo records the browser and tab it is working
with. Follow-up actions stay attached to that tab whenever possible, even if a
page opens a popup, reloads, or switches focus.
For best results:
* Keep the target tab open until the task finishes.
* Mention the browser name if several browsers are connected.
* Ask Enconvo to "use the current tab" when you want it to act on the visible
page.
* Ask for a fresh snapshot after a page navigation or form submission.
## Website Access And Safety
Browser pages can contain untrusted instructions. Review the site and the requested action before allowing Enconvo to continue on sensitive pages.
The extension uses browser permissions to read page content, click, type, capture screenshots, inspect tabs, and access cookies when a browser task requires it. Treat authenticated pages, browser history, and internal tools as sensitive data.
## Troubleshooting
<AccordionGroup>
<Accordion title="The popup says disconnected">
1. Make sure Enconvo is running.
2. Restart the browser.
3. Disable and re-enable the extension.
4. Confirm nothing is blocking `localhost:11225`.
</Accordion>
<Accordion title="The wrong browser is controlled">
Open Computer Use settings and set the default browser, or pass a browser value such as `edge`, `chrome`, or `firefox` in the browser action.
</Accordion>
<Accordion title="The extension is connected but a page cannot be controlled">
Browser internal pages such as `chrome://` cannot be controlled. Strict CSP pages, closed Shadow DOM, and browser permission prompts may also limit automation.
</Accordion>
<Accordion title="File upload does not work">
In the browser extension details page, enable file URL access if the task needs local file uploads or file-backed pages.
</Accordion>
</AccordionGroup>
# Companion Orb and Desktop Pet
Source: https://docs.enconvo.ai/features/companion-bar
Find the current replacement for the legacy Companion Orb.
The **Companion Orb** is a legacy interface. Current builds replace it with the **Desktop Pet**. If you used an older version, look under **Settings → Primary Function Area → Pet**; the old Orb toggle is no longer the current setup path.
| What you want | Current feature |
| - | - |
| A small character that shows Agent activity | [Desktop Pet](/features/pet) |
| A character assigned to an Agent, with voice chat | [Avatar](/features/avatar) |
| A compact conversation at the top of the screen | [Dynamic Island](/features/dynamic-island) |
| An assistant alongside another app | [App Sidebar](/features/app-sidebar) |
| A full conversation workspace | [Chat Window](/ai/chat) |
On migration, users with the old Orb enabled receive the Pet instead. Review **When tapped, open** and **Session cards** in Pet settings to choose how it behaves. Older Orb screenshots and hotkeys do not describe the current Pet or Avatar controls.
# Computer Use
Source: https://docs.enconvo.ai/features/computer-use
Let EnConvo interact with macOS apps by clicking, typing, scrolling, dragging, and reading app state
## Overview
Computer Use lets EnConvo operate native macOS apps when a task needs more than
text generation. It can inspect the active app, find visible controls, click or
type into fields, scroll lists, drag items, choose files, use app menus, and
wait for the app state to change before continuing.
Use Computer Use for desktop workflows such as:
* Filling a form in a native app
* Selecting a file in a macOS file picker
* Navigating a settings window
* Clicking a toolbar button or menu item
* Moving through a multi-step app workflow
* Reading what is visible in the current window
<Note>
For websites and browser tabs, use [Browser Control](/features/browser-control)
or the [Enconvo Browser Extension](/features/browser-extension). Computer Use is
best for native macOS apps and system windows.
</Note>
## Permissions
Computer Use relies on macOS Accessibility and, for visual screenshots, Screen
Recording permission.
<Steps>
<Step title="Open macOS Privacy settings">
Open **System Settings → Privacy & Security**.
</Step>
<Step title="Enable Accessibility">
Add and enable EnConvo under **Accessibility**. This allows EnConvo to read
app controls and perform clicks, typing, and keyboard shortcuts.
</Step>
<Step title="Enable Screen Recording when needed">
Add and enable EnConvo under **Screen Recording** if a workflow needs
screenshots or visual state.
</Step>
<Step title="Restart EnConvo">
Quit and reopen EnConvo after changing macOS permissions.
</Step>
</Steps>
## What Computer Use Can Do
| Action | Examples |
| - | - |
| **Inspect app state** | Read the current window, controls, menu items, selected text, and visible fields |
| **Click and double-click** | Click buttons, sidebar rows, toolbar items, menu commands, and coordinates |
| **Type and press keys** | Fill inputs, submit forms, use shortcuts like `Cmd + S` |
| **Scroll** | Move through lists, tables, settings panes, or long documents |
| **Drag** | Drag files, rows, sliders, or selection handles when the app supports it |
| **Use file pickers** | Select files and folders in native open/save dialogs |
| **Wait after actions** | Re-check app state after a click, navigation, or loading step |
## Running A Computer Use Task
Ask EnConvo for the outcome you want, not the low-level action list.
<Steps>
<Step title="Open the target app">
Bring the app or window you want EnConvo to control to the foreground.
</Step>
<Step title="Describe the task">
For example: "Open the settings panel and turn off launch at login" or
"Choose the latest PDF from Downloads in this file picker."
</Step>
<Step title="Review sensitive actions">
For destructive, financial, account, or permission-changing actions,
confirm the step before EnConvo continues.
</Step>
<Step title="Let EnConvo continue">
EnConvo will inspect the app, act, wait for the result, and continue until
the workflow is complete or needs your confirmation.
</Step>
</Steps>
## Examples
### Choose A File In A Native File Picker
> "In this file picker, select the newest screenshot from my Desktop."
EnConvo can inspect the native file picker, navigate folders, select the file,
and confirm the dialog.
### Change A Setting In Another App
> "Open this app's preferences and disable notifications."
EnConvo can use app menus, search visible settings, toggle controls, and verify
the result.
### Work Across Multiple Windows
> "Copy the confirmation code from Mail and paste it into the login window."
EnConvo can read visible windows, switch focus, copy text, and paste into the
target field.
## Safety Guidance
<Warning>
Computer Use can interact with real apps and real data. Review the screen before
allowing EnConvo to submit forms, change account settings, delete files, make
purchases, or send messages.
</Warning>
Best practices:
* Keep the target window visible when possible.
* Give specific goals and constraints.
* Avoid asking EnConvo to act on private or financial pages without review.
* Stop the task if the visible app state no longer matches your intent.
## Troubleshooting
<AccordionGroup>
<Accordion title="EnConvo cannot see app controls">
Confirm EnConvo has Accessibility permission, then restart EnConvo and the
target app. Some apps expose fewer controls than others; screenshots and
coordinate actions may still help.
</Accordion>
<Accordion title="Clicks go to the wrong app">
Bring the target app to the foreground before starting. If multiple windows
are open, mention the app or window name in your request.
</Accordion>
<Accordion title="File picker selection fails">
Make sure the file exists and the picker allows that file type. If the file
is in iCloud or a network location, wait for it to finish downloading first.
</Accordion>
<Accordion title="A workflow continues too quickly">
Ask EnConvo to wait for a specific visible result, such as "wait until the
Save button is enabled" or "continue after the table reloads."
</Accordion>
</AccordionGroup>
## Related Features
<CardGroup>
<Card title="Browser Control" icon="window-restore" href="/features/browser-control">
Control real browser tabs and signed-in websites.
</Card>
<Card title="Context Awareness" icon="eye" href="/features/context-awareness">
Learn how EnConvo understands your current screen and app context.
</Card>
</CardGroup>
# Context Awareness
Source: https://docs.enconvo.ai/features/context-awareness
How EnConvo understands your screen and provides relevant assistance
## Overview
Context Awareness is EnConvo's core technology that enables it to understand what you're working on and provide relevant, intelligent assistance. Instead of asking you to explain your context, EnConvo sees and understands your screen, active applications, and current tasks.
<YouTubePlayer title="Context Awareness Overview & Demo" />
## How It Works
EnConvo uses advanced screen analysis to understand:
### 1. Active Application Detection
EnConvo knows which application you're using and adapts its responses accordingly:
| Application | Context Provided |
| - | - |
| Web Browser | Current URL, page title, visible content |
| Code Editor | Programming language, file path, code content |
| Finder | Selected files, current directory |
| Other Apps | Current window content & Screenshot |
### 2. More Contextual responses
Based on context, EnConvo can provide more contextual responses:
* Coding? Offers debugging help, documentation lookup, etc.
* Writing? Suggests grammar fixes, tone improvements, etc.
* Browsing? Provides summaries, translations, etc.
## Manual Context Control
<Tip>
Use `#` prefix to add context to your queries.
</Tip>
### Context Modifiers
Use these prefixes for specific context types:
```
#screen - Include current screen content
#finder - Include current Finder selection
#clipboard - Include clipboard content
#browser - Include current browser tab
#... (and more)
```
## Privacy & Security
<Warning>
Context attached to a request may be sent to the chosen model or processing provider. Automatic capture and background features have their own controls; review the active sources and provider settings before working with sensitive content.
</Warning>
### Exclusions
Configure apps or content to exclude from context:
1. Go to Settings → Context Awareness
2. Add applications to the exclusion list
### App-Specific Actions
<AccordionGroup>
<Accordion title="Web Browsers (Safari, Chrome, Arc)">
* Summarize current page
* Translate page content
* Extract key information
* Save to knowledge base
</Accordion>
<Accordion title="Finder">
* Describe selected files
* Organize suggestions
* Batch rename help
* Content analysis
</Accordion>
</AccordionGroup>
## Related Features
<CardGroup>
<Card title="SmartBar" icon="magnifying-glass" href="/features/smartbar">
Use context in SmartBar queries
</Card>
<Card title="OCR Features" icon="text" href="/ai/ocr">
Extract text from images
</Card>
</CardGroup>
# Dictation and Voice Trigger
Source: https://docs.enconvo.ai/features/dictation
Insert speech as text or send it to an Agent.
Dictation turns speech into text in the app you are using. **Voice Trigger / Voice Command** sends a spoken request to an Agent. [Live Voice](/features/live-voice) is a separate two-way conversation feature.
## Dictate into an app
1. Open **Settings → Dictation → Dictation Models** and configure a provider.
2. Open **Dictation** settings and check the hotkey and gesture mode.
3. Place the cursor in a text field in another app.
4. Use the configured gesture to start recording, speak, and stop according to that gesture's mode.
5. Review the inserted text, especially names, dates, and numbers.
Microphone permission is needed to capture audio. Inserting text into another app can require Accessibility permission.
## Post-actions
Dictation can run configured commands after recognition, such as **Dictation Polish** or **Dictation Translate** from Writing Toolkit. Review the post-action selection when the inserted text differs from the raw transcript. A post-action using a cloud model can send recognized text to that provider even if recognition itself was local.
## Send speech to an Agent
1. Open **Settings → Agents → Voice Trigger**.
2. Configure **Triggered Agent**, its hotkey, and **Session Timeout**.
3. Invoke the gesture and speak a complete instruction.
4. End recording and review the Agent's progress and result.
Voice Command can reuse the latest triggered Agent session within the configured timeout. It does not work by matching only a fixed set of phrases; the selected Agent interprets the request with its available tools.
## History and vocabulary
Open **Dictation History** to revisit past recognized text. Use [Dictionary](/configuration/speech-assets) for custom vocabulary and provider language/hot-word settings when supported.
## Choose recognition separately
Dictation, recording, file transcription, and live captions have separate model settings. A provider suited to batch files may not be the best choice for streaming input. The [Speech Recognition](/ai/speech-recognition) guide and [provider catalog](/providers/catalog#speech-recognition) explain those categories.
## Troubleshooting
| Symptom | Check |
| - | - |
| No microphone input | Microphone permission and selected input device |
| Text appears but is not inserted | Accessibility, focused field, and whether the app accepts paste |
| Wrong text after recognition | Post-actions, language hints, and vocabulary |
| Slow result after stopping | Streaming versus batch model behavior |
| Agent receives the wrong conversation | Triggered Agent and Session Timeout |
| Another feature owns the microphone | Finish Live Voice or microphone recording first |
Use [Voice Notes](/features/voice-notes) to save speech directly into a knowledge base.
# Dynamic Island
Source: https://docs.enconvo.ai/features/dynamic-island
Use a compact assistant at the top of your screen.
The Dynamic Island keeps quick Agent requests and activity near the top of your display. You can type, use voice, attach context, and return to an in-progress conversation.
<Frame>
<img alt="Dynamic Island behavior, display, and default Agent settings" />
</Frame>
## Start a request
1. Open **Settings → Primary Function Area → Dynamic Island** and enable it.
2. Move to the top-center wake area or use the configured **Shortcut** to expand it.
3. Type a request, or select one of the **Home Shortcuts**.
4. Review any attached context before submitting. [Appshots](/features/appshots) and [Screen Doodle](/features/screen-doodle) help you ask about other apps.
5. Follow progress and open the result when the task finishes.
## Make it fit your desktop
| Setting | What it changes |
| - | - |
| Hide when collapsed | Keep the compact island hidden until hover or shortcut activation |
| Exclude notch area | Avoid hover activation inside the physical notch |
| Hover expand delay | How long to hover before expanding |
| Auto dismiss delay | How long the expanded panel stays open after interaction |
| Display | Select a display or follow the mouse |
| Hide on fullscreen | Hide on a display occupied by a fullscreen app |
| Show in screen recordings | Include the island in screenshots and recordings |
| Default Agent | The Agent used for a new request from the island |
| Home Shortcuts | Commands shown on its home screen |
## Voice and completion
[Live Voice](/features/live-voice) offers a spoken conversation; ordinary voice input transcribes a prompt. Starting Live Talk from SmartBar hands the call to the Dynamic Island in current builds.
Choose whether a completed island session expands automatically under [Notifications](/configuration/notifications). That setting is separate from macOS notifications.
## Troubleshooting
If it appears on another display, check the Display setting. If it disappears in fullscreen or does not appear in a screen recording, check the corresponding visibility setting before changing permissions. Use the shortcut to distinguish a hover-activation issue from a disabled panel.
# Live Captioning
Source: https://docs.enconvo.ai/features/live-captioning
Read realtime subtitles and revisit captioning sessions.
Live Captioning produces subtitles while audio is playing or being captured. Its saved sessions appear separately from imported transcription files and meeting recordings.
## Start captioning
1. Open **Settings → Captioning → Captioning Model** and select a model suitable for realtime recognition.
2. Open **Live Captioning** and choose **Start Captioning**, or invoke the corresponding command.
3. Select the audio source and controls offered by the captioning panel. Grant microphone or system-audio capture access as required.
4. Start the audio you want to follow and check that subtitles appear.
5. Stop captioning when finished, then open the saved session from the Live Captioning list.
## Translation
Some speech providers expose live translation, source/target language, or spoken-translation options. Configure those in the selected captioning provider. Not every speech model supports realtime translation; file-transcription support alone does not imply live-captioning support.
## Review a session
Open a saved session to review its transcript and available processing results. Check names, numbers, and speaker labels against the audio when accuracy matters. Use [Speech Assets](/configuration/speech-assets) to maintain vocabulary and speaker names.
## Troubleshooting
| Symptom | Check |
| - | - |
| No subtitles | Audio source, input level, capture permissions, and selected provider |
| Text appears only after stopping | Whether the selected model supports streaming |
| Wrong language | Recognition language or language hints |
| Translation is absent | Provider translation support and target language |
| Session has a processing error | Error details in the saved item; do not assume missing speech |
For a completed file, use [Transcription](/features/transcription). For recording a meeting, use [Meeting Recording](/features/meeting-recording).
# Live Voice
Source: https://docs.enconvo.ai/features/live-voice
Have a spoken conversation with an Agent and its tools.
Live Voice is a two-way voice conversation. Your Agent can answer aloud, perform tasks with its enabled tools, and keep transcripts in the conversation history. Ordinary [Dictation](/features/dictation) instead turns speech into text input.
<Frame>
<img alt="Realtime Voice access and automatic hang-up settings" />
</Frame>
## Set up voice access
1. Open **Settings → Agents → Realtime Voice**.
2. Choose **Enconvo Cloud** or your own provider under **GPT Live → Voice Access**, according to the options in your build. For access with your own key, select the OpenAI provider profile whose API key should be used.
3. Confirm that Enconvo has Microphone access in macOS and select working microphone and speaker devices.
4. Check the idle timeout, which controls when an unused call hangs up.
<Note>
Realtime Voice access is configured separately from an Agent's ordinary text model. A text-model subscription connection does not by itself establish GPT Live API access.
</Note>
## Start and end a call
1. Open the Agent and conversation you want to use.
2. Click the voice waveform / Live Talk control. Wait until the connection indicator shows that the microphone is ready.
3. Speak a complete request. For a tool task, name the desired result and provide enough context for the Agent.
4. Expand the working details to inspect tool progress or results.
5. Use the microphone control to mute, or the hang-up control to end the call.
Spoken turns are saved in regular chat history. Reopening that conversation lets you review the dialogue and work details. You can also use an [Avatar](/features/avatar) as the visible speaker.
## If a call does not work
* **It cannot connect:** check the selected voice access method and OpenAI provider profile, then read the connection error.
* **The microphone is unavailable:** finish an active Dictation or microphone recording session first, and check macOS Microphone access.
* **The Agent cannot perform an action:** review that Agent's tools and permissions. Voice does not add tools the Agent lacks.
* **The call ends while idle:** review the idle timeout in Realtime Voice settings.
See [Agents](/ai/agents) for tool configuration and [Speech Recognition](/ai/speech-recognition) for transcription providers.
# MCP (Model Context Protocol)
Source: https://docs.enconvo.ai/features/mcp
Connect AI to external tools, data sources, and services with MCP servers
## What is MCP?
[Model Context Protocol (MCP)](https://modelcontextprotocol.io) is an open standard that lets AI models use external tools and data sources. Each MCP server exposes tools the AI can call -- read files, query databases, send messages, and more.
EnConvo has built-in MCP support. Add an MCP server and the AI can use its tools automatically.
## Setting Up MCP Servers
### From Settings UI
The MCP Servers pane lives in the **Plugins** section of the Settings sidebar.
1. Open **Settings** — click the EnConvo icon in the macOS menu bar and choose **Settings...**, or press `Cmd + ,`
2. In the left sidebar, scroll down to the **Plugins** section and click **MCP Servers**
3. Click **Add server**
4. Choose a transport type (stdio, HTTP, or SSE) and fill in the configuration
5. Toggle the switch to enable/disable
<Tip>
The Settings sidebar is long — press `Cmd + F` inside Settings and type "MCP" to filter the sidebar and jump straight to the pane. You can also open it directly with the deeplink `enconvo://preference?pane=mcp_management`.
</Tip>
### Via CLI
```bash theme={null}
# Add a stdio server
enconvo mcp add github --command npx --args "-y @modelcontextprotocol/server-github"
# Add an HTTP server
enconvo mcp add notion --transport http --url "https://mcp.notion.com/mcp"
# List servers
enconvo mcp servers list
# List tools
enconvo mcp tools list
```
### Import from Other Tools
If you have MCP configs from Claude Desktop, Cursor, or other tools:
1. In **Settings** → **Plugins** → **MCP Servers**, click **Import**
2. Paste your JSON configuration
3. Click **Import** to add all servers
### Install Links
MCP servers can be installed with EnConvo deeplinks. It uses the same format as `mcp.json` with a name and transport configuration.
Install links:
```
https://enconvo.com/mcp/install?name=$NAME&config=$BASE64_ENCODED_CONFIG
```
| Component | Description |
| - | - |
| `https://enconvo.com` | Web install page |
| `/mcp/install` | Path |
| `name` | Query parameter for server name |
| `config` | Query parameter for base64 encoded JSON configuration |
The web page auto-launches the `enconvo://` deeplink and shows the server configuration as fallback.
#### Generate install link
1. Get name and JSON configuration of server
2. `JSON.stringify` the configuration then base64 encode it
3. Replace `$NAME` and `$BASE64_ENCODED_CONFIG` with the name and encoded config
#### Example
Try this JSON in the MCP install link generator:
```json Single MCP server config theme={null}
{
"exa": {
"url": "https://mcp.exa.ai/mcp"
}
}
```
Result:
| Format | Example |
| - | - |
| Text link | `https://enconvo.com/mcp/install?name=exa&config=eyJ1cmwiOiJodHRwczovL21jcC5leGEuYWkvbWNwIn0=` |
| Dark button | <img alt="Add to Enconvo" /> |
| Light button | <img alt="Add to Enconvo" /> |
Badge code for your README:
<CodeGroup>
```markdown Markdown theme={null}
[](https://enconvo.com/mcp/install?name=your-server&config=BASE64_CONFIG)
```
```html HTML theme={null}
<a href="https://enconvo.com/mcp/install?name=your-server&config=BASE64_CONFIG">
<img src="https://file.enconvo.com/badges/mcp-install-dark.svg?v=20260628-adaptive-logo" alt="Add to Enconvo" height="44" />
</a>
```
```jsx JSX theme={null}
<a href="https://enconvo.com/mcp/install?name=your-server&config=BASE64_CONFIG">
<img src="https://file.enconvo.com/badges/mcp-install-dark.svg?v=20260628-adaptive-logo" alt="Add to Enconvo" height={44} />
</a>
```
</CodeGroup>
#### Install server
1. Click the link or paste into browser
2. EnConvo opens the MCP Servers settings pane
3. The server is added and starts connecting automatically
4. Once connected, its tools are available to the AI
## Troubleshooting
<AccordionGroup>
<Accordion title="Server fails to start">
* Verify the command and arguments in your configuration
* For stdio servers, ensure the binary is installed and in your PATH
* For Node.js servers, ensure `npx` or `node` is available
</Accordion>
<Accordion title="Tools not appearing">
* Confirm the server is in **Connected** status
* Some servers require API keys before exposing tools
* Try disconnecting and reconnecting the server
</Accordion>
<Accordion title="Authentication errors">
* Verify API keys are correct and not expired
* Check that required environment variables are set
</Accordion>
</AccordionGroup>
<Info>
For the full MCP specification, visit [modelcontextprotocol.io](https://modelcontextprotocol.io).
</Info>
# Media Utilities
Source: https://docs.enconvo.ai/features/media-tools
Compress images, video, and audio, or extract a soundtrack.
Enconvo includes local utility commands alongside its AI generation tools. Find them in SmartBar or under **Settings → Plugins**.
| Command | Use |
| - | - |
| Image Compress | Compress one or more images with adjustable quality |
| Video Compress | Reduce a video's file size |
| Audio Compress | Reduce an audio file's size |
| Extract Audio | Save audio from a video |
| Online Video Downloader | Download supported online video or audio from a URL |
## Compress or convert a file
1. Find the command in SmartBar.
2. Supply the file or files as input, using the command's file controls or supported context.
3. Review output quality, destination, and overwrite options in the command's settings.
4. Run the command and open the output to check it.
Keep the original when experimenting with compression. Image Compress supports batch input and either overwrite or a custom output folder; choose the destination deliberately.
## Download media
Give **Online Video Downloader** the supported page URL and review the available audio/video options. Availability depends on the source site and access requirements. Download only content you are authorized to save.
## Troubleshooting
For a failed conversion, check the input format, writable output location, and available disk space. If an online download stops working, inspect the error and update the utility before trying again; websites can change their formats and access rules.
Related: [Image Generation](/ai/image-generation), [Video Generation](/ai/video-generation), [Transcription](/features/transcription).
# Meeting Recording
Source: https://docs.enconvo.ai/features/meeting-recording
Record a meeting, review its transcript, and extract follow-ups.
Meeting recording captures a session for transcription and later review. Choose the recording model separately from your dictation or file-transcription model.
## Record a session
1. Open **Settings → Recording → Recording Models** and configure a provider.
2. Open **Recordings** and choose **Start Recording**, or run **Start to Record (Meeting/Lecture)**.
3. Review the recording panel's audio sources and controls. Grant microphone or system-audio access as required.
4. Start recording and confirm that the intended audio is being captured.
5. Stop when finished, then open the saved item under Recordings.
Make sure participants know about recording and follow the requirements applicable to your meeting.
## Review the result
Inspect the transcript and any available summary or chat view. Check who said what, especially when voices overlap. Use speaker naming controls to improve labels and [Dictionary](/configuration/speech-assets) for recurring terms.
Ask the Agent to separate decisions, open questions, and action items. Require an explicit owner and deadline only when they were actually stated in the meeting.
## Failure recovery
Read the saved item's processing status. Transcription, title generation, and search indexing are separate stages; a later-stage error does not necessarily mean the audio or transcript is lost. Use copyable diagnostic details when reporting an error, after checking for private information.
If audio is missing, check the selected source and macOS capture permissions. If the microphone is busy, finish Dictation or Live Voice before starting microphone capture.
## Related modes
Use [Transcription](/features/transcription) for an existing file, [Live Captioning](/features/live-captioning) for realtime subtitles, and [Voice Notes](/features/voice-notes) for a short spoken note saved into a knowledge base.
# Desktop Pets
Source: https://docs.enconvo.ai/features/pet
Keep an animated companion and session cards on your desktop.
The desktop Pet provides a small animated entry point to Enconvo. It is separate from a voice-enabled [Avatar](/features/avatar).
<Frame>
<img alt="Desktop Pet controls for tap destination and session cards" />
</Frame>
## Choose a Pet
1. Open **Settings → Primary Function Area → Pet**.
2. Choose a character in **My Pets** or **Gallery**, then select **Wake Pet** to show it.
3. Set **When tapped, open** to the destination you prefer.
4. Review **Session cards** and the Pet size controls.
5. Return to the desktop and tap the Pet to open the configured destination.
## Custom Pets
The Pet settings page also provides **Custom pets** controls. Use **Open folder** to locate custom Pet packages and follow the supported format shown in your build; a character image alone is not necessarily an installable animated Pet package. After adding a supported package, select the Pet in **My Pets**.
Before removing a custom Pet, read the confirmation so you know which local asset is being removed.
## If the Pet is missing
Check **Wake Pet**, the selected installed character, and the Pet size. If tapping opens an unexpected surface, review **When tapped, open**. For voice conversations and Agent-specific characters, use the Avatar gallery instead.
# PopBar
Source: https://docs.enconvo.ai/features/popbar
Run configurable commands and PopBar extensions on selected text from a compact toolbar.
PopBar appears near selected text when enabled. Its commands can explain, translate, edit, search, copy, or read the selection aloud, and [PopBar extensions](#popbar-extensions) add more buttons, such as a web search, a text converter, or sending the selection to another app.
## Use PopBar
1. Open **Settings → Primary Function Area → PopBar** and enable it.
2. Select a short passage in a supported app.
3. Choose an action in the toolbar.
4. Review the result before using the command's copy, paste, or replacement action.
You can also run **Show PopBar** with an assigned shortcut. Selection detection depends on the app and Accessibility permission; secure fields and some custom editors may not expose selectable text.
## Choose the buttons
The **Buttons** tab of PopBar settings shows the bar's buttons in one strip. Drag a button to reorder it, point to it and click **×** to take it off, or click it for more options. **Reset to Default** brings back the default buttons.
Buttons that don't fit on the bar are under **⌄** at its end. Click **⌄** to open the **More** panel: it lists those buttons, with a search field for every button and setting. Once you've changed the buttons, **Reset to Default** also appears there, under **Turn Off PopBar**, and brings back the default buttons and their order, with **Undo**.
Click **Add Buttons** to open the Button Gallery. It has Ask AI, Ask in Sidebar, Open Link, Search, Copy, Translate, Explain, Fix Spelling, AI Edit, Read Aloud, and more, the actions of your [PopBar extensions](#popbar-extensions), and a way to make your own [AI Command](/features/ai-commands). You can also add a [Writing Toolkit](/features/writing-tools) command for your own editing workflow. The toolbar reflects the buttons you added.
## Control where it appears
The **When It Shows** tab sets whether PopBar shows only with its hotkey or everywhere, and the places where it stays away. Exclude apps where automatic selection actions would interrupt your work. Escape dismisses the current toolbar.
## PopBar extensions
PopBar extensions are small add-ons whose actions become PopBar buttons. They use the extension format of [PopClip](https://www.popclip.app), so extensions written for PopClip install in Enconvo too. PopBar extensions need Enconvo for Mac.
<Note>
Enconvo isn't affiliated with Pilotmoon Software, the maker of PopClip.
</Note>
### Install from Enconvo's catalog
1. Open **Plugins** and choose the **PopBar Extensions** tab.
2. Browse the catalog by category, or type in the search field to find one.
3. Click **+** next to an extension, then **Install**.
4. The card that follows lists the extension's buttons, when each one shows, and where it is. Choose **On Bar**, **In ⌄ More**, or **Off** for each, then click **Done**. **Settings…** opens the extension's options.
New buttons go to the front of the PopBar's **⌄ More** panel, or onto the bar while it has room. **⌄** shows a dot until you open the panel, where the new buttons are marked **NEW**.
Enconvo reviews every extension in its catalog before listing it, and installs exactly the version it reviewed. Installed extensions are listed at the top of the tab. When Enconvo has reviewed a newer version of one, its row in the catalog shows **Update**. In the Button Gallery, **Get more…** opens the same tab.
You can also browse the catalog on the web at [app.enconvo.com/popbar-extensions](https://app.enconvo.com/popbar-extensions). On your Mac, an extension's **Install** button opens Enconvo, which shows what the extension can do before anything installs.
### Add an extension from elsewhere
Click **Add PopBar extension…** on the **PopBar Extensions** tab, or in the **Add** menu of the Plugins page. Then do one of these:
* Paste a link to a `.popclipextz` package.
* Paste a snippet, the short text form of an extension that starts with `#popclip`.
* Click **Choose file…** to pick a `.popclipextz` package or a `.popclipext` folder on your Mac.
Click **Preview**. Enconvo reads the extension without running it and lists what it can do beyond the PopBar, such as running scripts, connecting to the internet, opening apps, or pressing keys. Nothing installs until you click **Allow and install**, which ends on the same card of buttons as an install from the catalog. An extension that doesn't come from Enconvo's catalog isn't reviewed by Enconvo, so install it only from a source you trust.
When you select a snippet in any app, the PopBar shows an **Install Extension** button first. Clicking it opens the same preview.
### Import from PopClip
If you use PopClip, click **Import from PopClip…** on the **PopBar Extensions** tab. Enconvo copies your PopClip extensions and their settings, in PopClip's order, and adds their actions to the PopBar. PopClip itself isn't changed.
* An extension that is turned off in PopClip installs, but isn't added to the PopBar.
* API keys and passwords aren't copied. Enconvo lists the extensions that need them, so enter them again in each extension's settings.
* An extension that matches a version in Enconvo's catalog counts as reviewed and updates from the catalog.
### Settings, updates, and removal
Open an extension from the **PopBar Extensions** tab to see its page. Its **PopBar buttons** section lists each button and when it shows, and lets you put it on the bar, in **⌄ More**, or off the PopBar. **Arrange all buttons in PopBar Settings** opens the Buttons tab. An extension with options shows **Settings** at the top of its page, and **Settings…** on its card in the Button Gallery. An extension installed from a link updates from the same link. When an update can do more than the version you allowed, Enconvo shows only what's new and asks again before updating.
To remove an extension, open it from the **PopBar Extensions** tab and uninstall it. Its buttons leave the PopBar.
### What isn't supported yet
* Extensions that sign in to an account.
* Extensions that build their actions each time the bar appears.
Enconvo tells you during the preview when an extension uses one of these.
### Suggest an extension
Enconvo's catalog lives in [github.com/Enconvo/popbar-extensions](https://github.com/Enconvo/popbar-extensions). Open an issue or pull request there to suggest an extension for review.
## Troubleshooting
* **No toolbar:** check Enable, Accessibility permission, and app exclusions.
* **Wrong text:** make a fresh selection and invoke PopBar again.
* **Missing command:** check the Buttons tab and verify that the command's plugin is installed.
* **Result does not replace text:** the destination app may not allow replacement; copy the result and paste it into an editable field.
* **Extension buttons don't appear:** click **⌄** at the end of the PopBar, where new buttons go, or check the extension's page in Plugins: an **Off** button isn't on the PopBar. Some buttons show only for text they can work on: **Base64 Decode**, for example, shows only for text that looks like Base64, so selecting plain text shows only **Base64 Encode**.
* **An extension button replaced the selected text:** many extensions paste their result over the selection, as they do in PopClip. Where the text can't be edited, the result is copied instead.
* **Catalog doesn't load:** check your connection, then click **Try again** on the **PopBar Extensions** tab.
## Change the result's model or settings
For commands with an AI model setting, the result toolbar offers a model picker. Changing it updates the command's default for later runs too. The result window's Settings button opens the command that produced that result, such as **Plugins → Writing Toolkit → Explain**.
# Quick Capture
Source: https://docs.enconvo.ai/features/quick-capture
Save the current app content to a knowledge base.
Quick Capture saves the current app's content for later retrieval. Appshots attaches an app window to the current request; Quick Capture creates a knowledge-base item.
<Frame>
<img alt="Quick Capture destination, sound, automatic summary, and hotkey controls" />
</Frame>
## Capture something worth keeping
1. Open **Settings → Memory → Quick Capture** and enable it.
2. Choose **Save to**, then review the **Hotkey**.
3. Bring the app containing the content to the front.
4. Invoke the hotkey.
5. Open the destination knowledge base and check the saved item.
## Options
| Setting | Use |
| - | - |
| Save to | Destination knowledge base |
| Capture sound | Audible confirmation of capture |
| Auto summary | Create an AI summary for the item's preview and search |
| Hotkey | Keyboard gesture that captures the current app |
Auto summary uses AI processing; review your model/provider configuration if you want to control where captured content is processed.
## Troubleshooting
For missing or incomplete content, check [Permissions](/configuration/permissions), return to the intended app, and try a small, clearly visible example. Check the destination before assuming a capture was lost. Indexing and summary generation can finish after the initial capture.
Related: [Knowledge Base](/ai/knowledge-base), [Appshots](/features/appshots), [Voice Notes](/features/voice-notes).
# Quick Links
Source: https://docs.enconvo.ai/features/quick-links
Open a website or browser search with a command.
Quick Links turns a search query or configured URL into a browser action. Built-in commands include **Google Search in Browser**, **YouTube Search in Browser**, and **Twitter/X Search in Browser**.
## Search from SmartBar
1. Open SmartBar and find the browser-search command you want.
2. Enter the search text as the command's input.
3. Run the command and check the result in your default browser.
Quick Links opens a destination. [Web Search](/ai/web-search) instead supplies search results to an AI response, and [Browser Control](/features/browser-control) lets an Agent interact with pages.
## Configure a link
Open **Settings → Plugins → Quick Links** and select **Quick Link** or a search command. Review its URL template and supported input variables before saving your own configuration. Test with ordinary text first, including spaces or punctuation.
If the destination is wrong, check the command's template and input. If the browser does not open, check your default browser and whether the command is installed.
# Screen Doodle
Source: https://docs.enconvo.ai/features/screen-doodle
Mark up a screen region and attach it to the Dynamic Island.
Screen Doodle lets you point out a part of the screen before asking your Agent about it. The confirmed annotation becomes an image attachment in the Dynamic Island.
<Frame>
<img alt="Screen Doodle activation and completion settings" />
</Frame>
## Mark up your screen
1. Open **Settings → Context → Screen Doodle** and check the **Hotkey**.
2. Bring the content you want to discuss to the front, then invoke Screen Doodle.
3. If **Capture Region First** is enabled, select the region to capture. Otherwise, draw directly over the live screen.
4. Use the overlay's drawing controls to mark the relevant area.
5. Click the checkmark or press **Command + Return** to confirm.
6. In the Dynamic Island, review the attached image and type a request, such as “What does the highlighted warning mean?”
## Activation settings
| Setting | Behavior |
| - | - |
| Capture Region First | Select a region before drawing |
| Hotkey | Open or toggle the overlay from the keyboard |
| Double Right-Click | Toggle Screen Doodle with a quick right-click gesture |
If the overlay does not open, check the configured shortcut and [macOS permissions](/configuration/permissions). If you only need the whole app window, use [Appshots](/features/appshots).
See [Dynamic Island](/features/dynamic-island) for the conversation that receives your annotation.
# SmartBar
Source: https://docs.enconvo.ai/features/smartbar
Ask, launch commands, and attach context from anywhere on your Mac.
SmartBar is a compact launcher for conversations and commands. Open it with your configured shortcut, commonly **Shift + Command + D**.
## Make a request
1. Open SmartBar and type a question.
2. Select an Agent or model when needed.
3. Attach the relevant context rather than assuming the Agent sees every open app.
4. Submit and follow the response or tool progress.
5. Copy the result or continue the conversation.
## Commands, context, and recent tasks
The trigger characters are configurable under **Settings → Primary Function Area → SmartBar**. The default fields are:
| Input | Purpose |
| - | - |
| `@` | Search commands |
| `#` | Pick context sources |
| `>` | Find recent tasks |
| `/` | Open actions such as model and reasoning selection |
Choose from the picker rather than typing an assumed tool identifier. Installed commands and available contexts can vary. See [Writing Toolkit](/features/writing-tools), [Quick Links](/features/quick-links), and [Context Awareness](/features/context-awareness).
## Choose a layout
<Frame>
<img alt="Input Only, Input and Toolbar, and Full Panel SmartBar layout choices" />
</Frame>
| Layout | Initial appearance |
| - | - |
| Input Only | Just the input field |
| Input and Toolbar | Input, quick actions, model picker, and voice controls |
| Full Panel | Also show the command list when opened |
These settings control how SmartBar opens. Command lists and results still appear when you type or run a command.
## Useful settings
Choose the **Default Agent**, initial state, context behavior, navigation bindings, and conversation-clearing behavior on the SmartBar settings page. **Shake to Dynamic Island** lets you hand off the floating interaction using the supported gesture when enabled.
Per-chat model and reasoning behavior is described in [Model Selection](/ai/model-selection-guide). Changing a default is not the same as changing every existing chat.
## Voice and calculations
Use the microphone for [Dictation](/features/dictation). Use Live Talk for [Live Voice](/features/live-voice); current builds hand SmartBar calls to the Dynamic Island.
Type a simple arithmetic expression such as `2+3*4` to use the calculator result. Check the displayed result and action before copying it.
## Troubleshooting
If SmartBar does not open, check its hotkey and competing shortcuts. If an app or selected text is missing from context, check [Permissions](/configuration/permissions). If results fail, inspect the selected provider and the reported error. See [Updates](/configuration/updates) when a documented control is missing from your build.
# Transcription
Source: https://docs.enconvo.ai/features/transcription
Turn an existing audio or video file into a searchable transcript.
Use Transcription for media you already have. **Recordings** stores captured meetings; **Live Captioning** stores captioning sessions. These views share the same recording-detail experience but show different sources.
## Import a file
1. Open **Settings → Transcription → Transcription Models** and select a provider.
2. Open **Transcription** and choose **Import File**, or the audio/video import action.
3. Select a supported file and wait for extraction and transcription to finish.
4. Open the item and review the transcript and processing status.
5. Correct important speaker names, terms, and figures before using the result.
You can also run the **Transcribe** command. Its settings include output format, speaker diarization, and transcription provider.
## Outputs and follow-up
Open a saved item's transcript and available summary/chat views. Ask questions about the transcript rather than assuming every detail was recognized correctly. The selected provider and command determine timestamp, structured-output, and diarization support.
For vocabulary and speaker naming, see [Speech Assets](/configuration/speech-assets). For later retrieval with other documents, see [Knowledge Base](/ai/knowledge-base).
## Processing failures
Current builds distinguish transcription failures from “no speech.” Read the error and available diagnostic details. A problem can come from audio extraction, provider file limits, account access, or the service itself; title generation and search indexing can fail separately from transcription.
If the transcript is already saved, check whether the failed stage is only a title or indexing step before importing the same file again. Keep the original media until you have verified the transcript.
See [Speech Recognition](/ai/speech-recognition) for choosing a file-capable provider.
# Visual Answers
Source: https://docs.enconvo.ai/features/visual-answers
Ask for diagrams, visual explanations, and interactive widgets in chat.
Enconvo can display visual content directly inside a conversation, including SVG diagrams, HTML previews, and interactive widgets when the Agent has the relevant tools.
## Ask for a useful visual
Be explicit about the question the visual should answer:
```text theme={null}
Show how this request moves from the browser to the API and database.
Use a small diagram and explain the failure points.
```
```text theme={null}
Create an interactive comparison of these three plans.
Let me change the monthly usage and see the estimated total.
```
Include the underlying data and units for charts or calculators. A polished visual does not establish that its facts or calculations are correct.
## Use and save the result
Wait for the visual to finish generating, then interact with any controls it provides. Some widgets can send a follow-up prompt back to the conversation.
Hover over a completed visual to reveal its menu. **Copy to clipboard** and **Download file** provide the available export actions; confirm the filename in the download dialog. An exported image captures a state of the visual and may not preserve its interactive behavior.
## Troubleshooting
If you receive code instead of a visual, check the Agent's enabled tools and ask it to render the result in the conversation. If a widget is incomplete, wait for generation to finish and ask for a simpler revision. For an actual image asset rather than a chat widget, use [Image Generation](/ai/image-generation).
# Voice Notes
Source: https://docs.enconvo.ai/features/voice-notes
Save a spoken note into a knowledge base.
Voice Note records an idea into a knowledge base so you can find it later. Use [Dictation](/features/dictation) when you want text inserted into another app instead.
<Frame>
<img alt="Voice Note hotkey and destination knowledge base" />
</Frame>
## Save a note
1. Create or choose a [Knowledge Base](/ai/knowledge-base).
2. Open **Settings → Memory → Voice Note**.
3. Set **Save to** to the destination knowledge base and review **Voice Note Hotkey**.
4. Invoke the hotkey and record a short note. End the recording using the recording controls.
5. Open the destination knowledge base and review the saved item and transcription.
## Make notes easier to find
Include the subject and useful names in the recording: “Project Atlas: ask the designer for the updated onboarding icons.” Review important names, numbers, and dates in the transcript before relying on them.
## Troubleshooting
If there is no audio, check Microphone permission and the selected input device. If the note is not where expected, check **Save to**. If transcription fails, inspect the error and the configured speech provider rather than recording the same note repeatedly.
See [Speech Assets](/configuration/speech-assets) for vocabulary and speaker management, and [Quick Capture](/features/quick-capture) for saving visible app content.
# Window Management
Source: https://docs.enconvo.ai/features/window-management
Choose the Enconvo surface that fits the task and configure its activation.
Enconvo offers several surfaces for the same everyday work. Choose one based on how much space and context you need.
| Surface | Best use | Guide |
| - | - | - |
| SmartBar | Launch a command or ask a quick question | [SmartBar](/features/smartbar) |
| Chat Window | Ongoing conversations, history, and files | [Chat](/ai/chat) |
| App Sidebar | Work alongside another application | [App Sidebar](/features/app-sidebar) |
| PopBar | Act on selected text | [PopBar](/features/popbar) |
| Dynamic Island | Compact top-screen input and session status | [Dynamic Island](/features/dynamic-island) |
| Pet | Desktop access and Agent activity | [Desktop Pet](/features/pet) |
| Avatar | An Agent character and voice interaction | [Avatar](/features/avatar) |
## Set activation shortcuts
Open **Settings → General → Shortcut** or the feature's own settings. Review the assigned combination and activation mode. Global shortcuts can conflict with macOS, input methods, and other apps; choose an unused combination if an entry does not open.
## Keep the right result visible
Use the pin or window controls exposed by the active surface. **Pin SmartBar** is also available as a native command. A pinned surface can remain visible while you return to another app. Press Escape or use the surface's close control when finished; closing a window is different from deleting a conversation.
## Multiple displays
Review display-related options in each surface's settings, especially Dynamic Island. After changing display arrangements, reopen the intended surface and confirm that it is on the screen you expect. App Sidebar follows the target app window; permissions and app-specific window behavior can affect attachment.
## Result destinations
Some command settings include a **Window Mode** or output destination. Use the options offered for that command to decide where the result appears. Voice input can also paste into the focused application, so check the input target before dictating.
If a window is missing, check its assigned shortcut, the active display, and whether it is behind another app. See [Troubleshooting](/getting-started/troubleshooting) for permission and launch issues.
# Writing Toolkit
Source: https://docs.enconvo.ai/features/writing-tools
Rewrite, explain, summarize, and transform selected text.
Writing Toolkit turns common editing tasks into commands available from SmartBar and PopBar. It uses the global AI model unless you choose a command-specific override.
<Frame>
<img alt="Writing Toolkit commands and the Explain prompt settings" />
</Frame>
## Improve a paragraph
1. Select text in the app where you are writing.
2. Open [PopBar](/features/popbar) and choose an editing command, or search for the command in [SmartBar](/features/smartbar).
3. Review the result before copying or inserting it into your document.
4. To adjust that command, open its settings under **Settings → Plugins → Writing Toolkit**. The result window's Settings action opens the command that produced it.
## Choose a command
| Goal | Commands |
| - | - |
| Correct errors | Fix Spelling & Grammar, Proofread |
| Improve wording | Improve Writing, Polish, Rewrite, AI Edit |
| Change length | Make Longer, Make Shorter, Make Concise |
| Change tone | Friendly, Confident, Casual, Professional |
| Understand content | Explain, Summarize, Extract Key Points |
| Reformat | Convert to List, Convert to Table |
| Email | Polish Email |
| Speech cleanup | Dictation Polish, Dictation Translate |
| Visual context | Screenshot Explain |
| Short expression | Emoji |
Polish Email can apply its configured email signature. Check that signature before using the result in a real message.
## Make results more reliable
Supply the audience and intent when a rewrite is ambiguous. Preserve names, dates, figures, and quoted wording explicitly. Compare the edited text against the original; fluent output can still change meaning.
For a repeated custom instruction, create an [AI Command](/features/ai-commands). For language conversion, see [Translation](/ai/translate).
# Troubleshooting
Source: https://docs.enconvo.ai/getting-started/troubleshooting
Solutions to common issues and how to get help
## Overview
This guide covers the most common issues users encounter with EnConvo and how to resolve them. If your issue is not listed here, reach out on our [Discord community](https://discord.gg/jYsdVRRK2k).
## Node.js Process Issues
EnConvo uses a Node.js process for extension execution. If extensions fail to load or respond, the Node.js service may need attention.
### Symptoms
* Extensions do not respond
* Chat messages hang with no response
* "Connection failed" errors
* SmartBar opens but commands do not execute
### Solutions
<AccordionGroup>
<Accordion title="Restart the Node.js service">
1. Click the EnConvo menu bar icon
2. Select "Restart Node.js Service"
3. Wait 5-10 seconds for the service to reinitialize
This resolves most connection issues.
</Accordion>
<Accordion title="Check the socket connection">
The Unix Domain Socket file should exist at:
```
~/.config/Enconvo/.macopilot.socket
```
If this file is missing, restart EnConvo completely (Quit → Relaunch).
</Accordion>
<Accordion title="Kill orphaned Node.js processes">
If the Node.js process is stuck, terminate it manually:
```bash theme={null}
# Find EnConvo-related Node.js processes
ps aux | grep -i enconvo | grep node
# Kill the process (replace PID with the actual process ID)
kill -9 <PID>
```
Then restart EnConvo.
</Accordion>
<Accordion title="Check Node.js version">
EnConvo requires Node.js 18+. Check your version:
```bash theme={null}
node --version
```
If you have an older version, update via [nodejs.org](https://nodejs.org) or:
```bash theme={null}
brew install node
```
</Accordion>
</AccordionGroup>
## Extension Loading Failures
### Symptoms
* "Extension not found" error
* Extension appears in list but does not work
* "Failed to load command" message
### Solutions
<AccordionGroup>
<Accordion title="Reinstall the extension">
1. Settings → Plugins → Find the plugin
2. Uninstall it
3. Reinstall from the Extension Store
</Accordion>
<Accordion title="Check extension path">
Extensions are installed to:
```
~/.config/enconvo/extension/{extensionName}/
```
Verify the extension directory exists and contains a `package.json`:
```bash theme={null}
ls ~/.config/enconvo/extension/{extensionName}/
```
</Accordion>
<Accordion title="Clear extension cache">
Remove the extension's cached build artifacts:
```bash theme={null}
rm -rf ~/.config/enconvo/extension/{extensionName}/node_modules
```
Then restart EnConvo to trigger a rebuild.
</Accordion>
<Accordion title="Check for version incompatibility">
Some extensions require a minimum EnConvo version. Check the extension's `package.json`:
```json theme={null}
"minAppVersion": "1.8.8"
```
Update EnConvo if your version is older.
</Accordion>
</AccordionGroup>
## AI Model Issues
### No Response from AI
<AccordionGroup>
<Accordion title="Verify API key">
1. Settings → Key Management
2. Find your provider (OpenAI, Anthropic, etc.)
3. Click "Validate" to test the key
4. If validation fails, re-enter your API key
</Accordion>
<Accordion title="Check network connection">
Cloud AI providers require internet access:
```bash theme={null}
# Test connectivity to OpenAI
curl -s https://api.openai.com/v1/models -H "Authorization: Bearer YOUR_KEY" | head -20
# Test connectivity to Anthropic
curl -s https://api.anthropic.com/v1/messages -H "x-api-key: YOUR_KEY" | head -20
```
</Accordion>
<Accordion title="Check proxy settings">
If you use a proxy, configure it in Settings → Network → HTTP Proxy. Some corporate networks block AI API endpoints.
</Accordion>
<Accordion title="Check API quota">
You may have exhausted your API quota or hit rate limits. Check your provider's dashboard:
* OpenAI: [platform.openai.com/usage](https://platform.openai.com/usage)
* Anthropic: [console.anthropic.com](https://console.anthropic.com)
* Google: [aistudio.google.com](https://aistudio.google.com)
</Accordion>
<Accordion title="Try a different model">
Switch to a different model or provider temporarily to isolate the issue. If other models work, the problem is specific to the original model or provider.
</Accordion>
</AccordionGroup>
### Slow Responses
* **Large context**: Reduce the amount of context being sent (fewer tools, smaller knowledge base results)
* **Model selection**: Smaller models (e.g., GPT-4o-mini, Claude 3.5 Haiku) respond faster
* **Local models**: Local models on Apple Silicon may be slow with large contexts. Consider using cloud providers for long conversations
### Ollama/Local Model Issues
<AccordionGroup>
<Accordion title="Ollama not connecting">
1. Verify Ollama is running:
```bash theme={null}
ollama list
```
2. Check the server URL in Settings matches Ollama's address (default: `http://localhost:11434`)
3. Restart Ollama:
```bash theme={null}
ollama serve
```
</Accordion>
<Accordion title="Model not found">
Pull the model first:
```bash theme={null}
ollama pull llama3.2
```
Then refresh the model list in EnConvo: Settings → AI Models → Ollama → Refresh
</Accordion>
</AccordionGroup>
## Audio & Microphone Issues
### Dictation Not Working
<AccordionGroup>
<Accordion title="Check microphone permission">
1. System Settings → Privacy & Security → Microphone
2. Ensure EnConvo is listed and enabled
3. If not listed, trigger dictation once -- macOS will prompt for permission
</Accordion>
<Accordion title="Check input device">
1. Settings → Voice → Input Device
2. Select the correct microphone
3. Test with macOS Sound preferences to verify the mic works
</Accordion>
<Accordion title="Check dictation provider">
1. Settings → Voice → Dictation Provider
2. Try the "Microsoft (Enconvo Cloud Plan) Free" provider -- it requires no API key
3. If using a custom provider, verify the API key
</Accordion>
</AccordionGroup>
### TTS (Read Aloud) Not Working
<AccordionGroup>
<Accordion title="Check TTS provider">
Settings → Voice → TTS Provider. Try "macOS System TTS" as a fallback -- it requires no API key and works offline.
</Accordion>
<Accordion title="Check audio output">
Verify your Mac's audio output is not muted and the volume is up. Try playing audio in another app to confirm.
</Accordion>
</AccordionGroup>
## Keyboard Shortcut Issues
### Shortcut Does Not Work
<AccordionGroup>
<Accordion title="Check for conflicts">
Another app may have claimed the same shortcut. Common conflicts:
* **Spotlight** (`Cmd + Space`)
* **Alfred/Raycast** (various shortcuts)
* **macOS Screenshots** (`Cmd + Shift + 3/4/5`)
* **Other productivity tools**
Change EnConvo's shortcut in Settings, or disable the conflicting shortcut in the other app.
</Accordion>
<Accordion title="Grant Accessibility permission">
Global shortcuts require Accessibility permission:
1. System Settings → Privacy & Security → Accessibility
2. Find EnConvo in the list and enable it
3. If already enabled, try toggling it off and on
4. Restart EnConvo
</Accordion>
<Accordion title="Restart EnConvo">
Shortcut registration can sometimes fail. Quit and relaunch EnConvo.
</Accordion>
</AccordionGroup>
## Accessibility Permission Issues
### Selected Text Not Detected
EnConvo needs Accessibility permission to read selected text for PopBar and context awareness.
<Steps>
<Step title="Open System Settings">
System Settings → Privacy & Security → Accessibility
</Step>
<Step title="Enable EnConvo">
Toggle EnConvo on. If it is already on, toggle it off, wait 2 seconds, then toggle it back on.
</Step>
<Step title="Restart EnConvo">
Quit and relaunch EnConvo for the permission change to take effect.
</Step>
<Step title="Verify">
Select text in any app and check if PopBar appears or if SmartBar context detection works.
</Step>
</Steps>
### Screen Recording Permission
Screenshot OCR and screen context require Screen Recording permission:
1. System Settings → Privacy & Security → Screen & System Audio Recording (or Screen Recording)
2. Enable EnConvo
3. Restart EnConvo
<Warning>
On macOS Ventura (13) and later, you may need to remove and re-add EnConvo from the Accessibility and Screen Recording lists if permissions are not taking effect after an app update.
</Warning>
## Knowledge Base Issues
<AccordionGroup>
<Accordion title="Documents not being indexed">
* Check the embedding provider is configured and working (Settings → Knowledge Base → Embedding Model)
* Verify the document format is supported (PDF, TXT, MD, DOCX, HTML, etc.)
* Check the console logs for indexing errors
</Accordion>
<Accordion title="Search returns no results">
* Ensure the knowledge base is selected in the chat context
* Try lowering the Score Threshold in Knowledge Base settings
* Increase the Top K Results count
* Re-index the knowledge base if documents were recently added
</Accordion>
<Accordion title="Knowledge base is large and slow">
* Consider splitting into multiple smaller, topic-focused knowledge bases
* Enable a Reranker provider to improve result quality without increasing Top K
* Use smaller embedding models for faster indexing
</Accordion>
</AccordionGroup>
## Browser Control Issues
<AccordionGroup>
<Accordion title="Cannot connect to browser">
1. Install the [Enconvo Companion extension](https://chrome.google.com/webstore/detail/enconvo-companion) in your browser
2. Ensure the browser supports the Companion extension (Chrome, Edge, Brave, Arc, Vivaldi, Opera, Firefox)
3. Restart the browser after installing the extension
</Accordion>
<Accordion title="Firefox support">
Firefox is supported through the Companion extension. If it does not connect, confirm the extension is enabled, restart Firefox, and check that localhost access is not blocked.
</Accordion>
</AccordionGroup>
## Viewing Logs
Logs are essential for diagnosing issues that are not covered above.
### Extension Logs
View logs from individual extensions:
1. Enable Developer Mode: Settings → Advanced → Developer Mode → On
2. Open the log viewer in the debug panel
3. Logs show real-time extension output, errors, and JSON-RPC messages
### System Logs
View EnConvo's system-level logs in macOS Console:
```bash theme={null}
# View recent EnConvo logs
log show --predicate 'subsystem == "com.frostyeve.enconvo"' --last 1h
# Stream live logs
log stream --predicate 'subsystem == "com.frostyeve.enconvo"'
```
### Node.js Server Logs
The Node.js server logs to stdout. When running in development:
```bash theme={null}
# Check if the Node.js server is running
ps aux | grep enconvo | grep node
```
## Submitting a Bug Report
If you cannot resolve an issue, submit a bug report:
<Steps>
<Step title="Gather information">
Collect:
* EnConvo version (Settings → About)
* macOS version
* Steps to reproduce the issue
* Error messages (screenshots or text)
* Relevant logs
</Step>
<Step title="Report on Discord">
Join [discord.gg/jYsdVRRK2k](https://discord.gg/jYsdVRRK2k) and post in the #bug-reports channel with:
* Description of the issue
* Steps to reproduce
* Expected vs actual behavior
* Your collected information
</Step>
<Step title="Report on GitHub">
For extension-specific bugs, open an issue on the relevant [GitHub repository](https://github.com/enconvo):
* Include the extension name and version
* Attach relevant log snippets
* Describe your configuration
</Step>
</Steps>
<Tip>
The more detail you provide in bug reports, the faster the issue can be diagnosed. Screenshots, log snippets, and exact reproduction steps are extremely helpful.
</Tip>
## Common Quick Fixes
For reference, here is a summary of the most effective quick fixes:
| Issue | Quick Fix |
| - | - |
| Extensions not responding | Menu Bar → Restart Node.js Service |
| AI not responding | Settings → Key Management → Validate key |
| Shortcuts not working | System Settings → Accessibility → Toggle EnConvo |
| PopBar not appearing | System Settings → Accessibility → Enable EnConvo |
| OCR not working | System Settings → Screen Recording → Enable EnConvo |
| Dictation failing | Settings → Voice → Try "Microsoft Free" provider |
| Ollama not connecting | Run `ollama serve` in Terminal |
| Extension missing | Reinstall from Extension Store |
| Everything broken | Quit EnConvo → Relaunch |
## Next Steps
<CardGroup>
<Card title="Settings Reference" icon="gear" href="/configuration/settings-reference">
Review all configurable settings
</Card>
<Card title="Privacy & Security" icon="shield" href="/configuration/privacy-security">
Understand data handling
</Card>
<Card title="Discord Community" icon="discord" href="https://discord.gg/jYsdVRRK2k">
Get help from the community
</Card>
<Card title="FAQ" icon="circle-question" href="/faq">
Frequently asked questions
</Card>
</CardGroup>
# Enconvo Documentation
Source: https://docs.enconvo.ai/index
Use AI across your Mac: chat, voice, context, knowledge, and automation.
Enconvo brings AI chat, voice input, tools, and automation into your Mac. Start with one task, then add the models, context, and integrations you need.
<CardGroup>
<Card title="Get started" icon="bolt" href="/quickstart">Install Enconvo, connect a model, and complete your first request.</Card>
<Card title="Find a feature" icon="list" href="/reference/feature-directory">Browse the complete guide directory by what you want to do.</Card>
<Card title="Work with your voice" icon="microphone" href="/features/dictation">Dictate into apps, talk to an Agent, and transcribe recordings.</Card>
<Card title="Automate a task" icon="clock" href="/workflows/scheduled-jobs">Build a workflow or schedule an Agent to run later.</Card>
</CardGroup>
## Choose how to work
| You want to… | Start here |
| - | - |
| Ask a quick question from any app | [SmartBar](/features/smartbar) |
| Keep an ongoing conversation | [Chat](/ai/chat) |
| Keep the assistant near the top of the screen | [Dynamic Island](/features/dynamic-island) |
| Improve selected text | [PopBar](/features/popbar) and [Writing Toolkit](/features/writing-tools) |
| Ask about something on screen | [Appshots](/features/appshots) or [Screen Doodle](/features/screen-doodle) |
| Search personal documents | [Knowledge Base](/ai/knowledge-base) |
| Speak naturally and hear answers | [Live Voice](/features/live-voice) |
| Create images, video, or audio | [Image Generation](/ai/image-generation), [Video Generation](/ai/video-generation), [Text-to-Speech](/ai/text-to-speech) |
| Connect an external AI client | [Knowledge Base MCP](/advanced/knowledge-base-mcp) |
| Configure a model or API key | [Providers](/providers/overview) and [Credentials](/configuration/credentials) |
## Find the right instructions for your build
These guides cover current Enconvo features, including features available first in Beta or Dev. If an entry is missing from your app, check its version and [update channel](/configuration/updates). Screenshots show an example configuration; your models, shortcuts, and installed tools may differ.
Use [Settings Reference](/configuration/settings-reference) to find a setting and [Troubleshooting](/getting-started/troubleshooting) when a task fails.
# Installation
Source: https://docs.enconvo.ai/installation
Install Enconvo and prepare your Mac.
## Requirements
Current Enconvo builds target **macOS 14 or later**. Download the build appropriate for Apple Silicon or Intel from [enconvo.com](https://www.enconvo.com). On-device MLX features require Apple Silicon; individual local models also need sufficient memory and disk space.
## Install
1. Download the DMG from the official website.
2. Open it and drag **Enconvo** into **Applications**.
3. Launch the copy in Applications.
4. Complete the app's onboarding and connect a model using the [Quick Start](/quickstart).
5. Grant feature permissions when prompted. See [macOS Permissions](/configuration/permissions) for what each permission enables.
Keep the app in Applications so launch shortcuts, permissions, and updates refer to a consistent copy.
## Update
Use **Check for Updates** from the Enconvo menu bar item. Choose **Production**, **Beta**, or **Dev** under **Settings → General → Updates**. See [Updates](/configuration/updates) for channel behavior.
App and extension versions are separate. If a feature is absent or an integration behaves differently, check both the app and installed extension updates.
## Common installation problems
| Problem | Next step |
| - | - |
| The app does not launch | Confirm macOS compatibility and that the download finished |
| Permissions appear enabled but do not work | Quit and reopen the running copy; avoid launching a different old copy |
| Local model fails to download | Check disk space, connectivity, and that the selected runtime supports your Mac |
| You cannot find the app window | Use the menu bar item or configured SmartBar shortcut |
If macOS reports that the download is damaged or untrusted, obtain a fresh installer from the official website instead of disabling system security controls.
# Apple Ecosystem Integration
Source: https://docs.enconvo.ai/integrations/apple-ecosystem
Seamlessly integrate with Apple Mail, Reminders, Calendar, Contacts, Messages, Notes, Maps, and Shortcuts
## Overview
EnConvo deeply integrates with macOS native applications, letting you manage email, reminders, calendar events, contacts, messages, notes, and shortcuts through natural language. Because these integrations use native macOS APIs and AppleScript, they work offline, respect your system preferences, and feel like a natural extension of your Mac.
<CardGroup>
<Card title="Apple Mail" icon="envelope">
Read, compose, and manage emails
</Card>
<Card title="Apple Reminders" icon="check-circle">
Create, update, and complete reminders
</Card>
<Card title="Apple Calendar" icon="calendar">
View, create, and manage events
</Card>
<Card title="Apple Contacts" icon="user">
Search and read contact details
</Card>
<Card title="Apple Messages" icon="message">
Send iMessages to contacts
</Card>
<Card title="Apple Notes" icon="note-sticky">
Create, read, and update notes
</Card>
<Card title="Apple Maps" icon="map">
Look up addresses and directions
</Card>
<Card title="Apple Shortcuts" icon="bolt">
Run any shortcut from your system
</Card>
</CardGroup>
## Apple Mail
The Apple Mail integration provides full email management through the native Mail app on your Mac.
### Available Tools
| Tool | Description |
| - | - |
| **Compose New Message** | Create and send a new email with To, CC, BCC, subject, body, and attachments |
| **See Recent Mail** | View recent messages (optionally unread-only) |
| **See Mail Accounts** | List all configured email accounts |
| **Get Message Content** | Read the full content of a specific email |
| **Open Message in Mail** | Open a specific email in the Mail app |
| **Toggle Message Read** | Mark a message as read or unread |
| **Move to Archive** | Archive a specific email |
| **Move to Trash** | Move an email to the trash |
| **Delete Message** | Permanently delete an email |
| **Move to Mailbox** | Move an email to a specific mailbox |
| **Mark All as Read** | Mark all emails as read |
### Example Usage
```
"Show me my unread emails"
"Send an email to alice@example.com about the project deadline"
"Archive all emails from notifications@github.com"
"What did Bob say in his last email?"
```
### Configuration
| Setting | Description | Default |
| - | - | - |
| **Unread-Only** | Only show unread messages in recent mail | On |
<Note>
Apple Mail integration works with all email accounts configured in the macOS Mail app, including iCloud, Gmail, Outlook, and Exchange accounts.
</Note>
## Apple Reminders
Create, manage, and track reminders with full support for due dates, priorities, recurrence rules, and location-based triggers.
### Available Tools
| Tool | Description |
| - | - |
| **Add to Apple Reminders** | Create a new reminder with title, notes, due date, priority, recurrence, and location |
| **Get Reminders Events** | List all reminders across all lists |
| **Get Reminders Lists** | List all reminder lists |
| **Toggle Completion Status** | Mark a reminder as complete or incomplete |
| **Delete Reminder** | Remove a reminder |
| **Update Reminder** | Modify an existing reminder's title, notes, date, priority, recurrence, or location |
### Reminder Features
**Due dates and times:**
```
"Remind me to call the dentist tomorrow at 2pm"
"Add a reminder for the team standup every weekday at 9am"
```
**Priorities:**
```
"Create a high-priority reminder to submit the report by Friday"
```
**Recurrence rules:**
* Daily, weekly, monthly, or yearly frequency
* Custom intervals (e.g., every 2 weeks)
* End date or occurrence count
```
"Set a recurring reminder to review expenses on the first of every month"
```
**Location-based triggers:**
```
"Remind me to buy groceries when I arrive at the store"
```
### Recurrence Configuration
| Property | Description | Example |
| - | - | - |
| `frequency` | Recurrence type | `daily`, `weekly`, `monthly`, `yearly` |
| `interval` | Repeat every N periods | `2` (every 2 weeks) |
| `endDate` | When recurrence stops | `2025-12-31` |
| `occurrenceCount` | Number of occurrences | `10` |
## Apple Shortcuts
Run any Apple Shortcut installed on your system directly from EnConvo. The Shortcuts integration dynamically discovers all shortcuts available on your Mac.
### How It Works
<Steps>
<Step title="Automatic Discovery">
EnConvo scans your system for all installed Apple Shortcuts and makes them available as tools
</Step>
<Step title="Natural Language Trigger">
Ask the AI to run any shortcut by name -- no need to remember exact names
</Step>
<Step title="Input and Output">
Pass text input to shortcuts and receive their output (both text and binary data are supported)
</Step>
</Steps>
### Available Tools
| Tool | Description |
| - | - |
| **List Shortcuts** | See all Apple Shortcuts available on your system |
| **Run Shortcut** | Execute a shortcut by name with optional text input |
### Example Usage
```
"Run my 'Morning Routine' shortcut"
"List all my shortcuts"
"Execute the 'Resize Image' shortcut with the file on my desktop"
```
### Siri Integration
Since Shortcuts work with Siri, you can create powerful automation chains:
1. Create a Shortcut in the Shortcuts app that calls EnConvo
2. Trigger it via Siri voice command
3. EnConvo processes the request using AI
4. Results flow back through the Shortcut
<Tip>
Combine Apple Shortcuts with EnConvo workflows for advanced automation. For example, a Shortcut can trigger an EnConvo workflow that uses AI to process data and then passes the result to another Shortcut.
</Tip>
## Apple Calendar
Full calendar management with support for creating, updating, deleting, and querying events, including recurrence rules, alarms, and all-day events.
### Available Tools
| Tool | Description |
| - | - |
| **Add to Calendar** | Create a new calendar event with title, dates, location, notes, alarms, and recurrence |
| **Update Calendar Event** | Modify an existing event |
| **Get Calendar Events** | Retrieve events for a specified number of days |
| **Delete Calendar Event** | Remove an event (optionally all recurrences) |
| **Get Calendar List** | List all available calendars |
### Event Features
**Basic events:**
```
"Schedule a team meeting tomorrow at 3pm for one hour"
"Add a dentist appointment on March 25th from 10am to 11am at 123 Main St"
```
**All-day events:**
```
"Block off next Friday as a personal day"
```
**Recurring events:**
```
"Create a weekly team standup every Monday at 9am"
"Schedule a monthly review on the first of each month"
```
**Alarms and reminders:**
```
"Schedule a meeting at 2pm with a 15-minute reminder"
"Add a 1-hour warning alarm to my flight tomorrow"
```
**Multiple calendars:**
```
"Add this event to my Work calendar"
"Show me events from all calendars for the next week"
```
### Event Properties
| Property | Description | Example |
| - | - | - |
| `title` | Event title | `"Team Standup"` |
| `startDate` / `endDate` | Date range | `yyyy-MM-dd HH:mm:ss` format |
| `location` | Event location | `"Conference Room B"` |
| `notes` | Additional details | `"Bring Q4 report"` |
| `isAllDay` | All-day event flag | `true` / `false` |
| `url` | Associated URL | Meeting link |
| `alarms` | Alert offsets in seconds | `-3600` (1 hour before) |
| `recurrence` | Repeat rule | `{frequency: "weekly", interval: 1}` |
| `availability` | Busy/free status | `0` (free), `1` (busy) |
## Apple Contacts
Search and read entries from the macOS Contacts app.
### Available Tools
| Tool | Description |
| - | - |
| **Search Contacts** | Look up a contact by name, phone, or email |
| **Get Contact Details** | Read full details (emails, phones, addresses, notes) |
### Example Usage
```
"What is Alice's phone number?"
"Find all contacts at Acme Corp"
"Get Bob's email address"
```
## Apple Messages
Send iMessage or SMS messages to anyone in your Contacts.
### Available Tools
| Tool | Description |
| - | - |
| **Send Message** | Send an iMessage or SMS to a contact, phone number, or email |
### Example Usage
```
"Send a text to Alice saying I'll be 10 minutes late"
"Message Bob 'meeting pushed to 3pm'"
```
<Note>
Apple Messages sending is limited by iMessage/SMS configuration on your Mac. The Messages app must be signed in to your Apple ID for iMessage delivery.
</Note>
## Apple Notes
Full Notes integration including reading, writing, and observing the currently selected note.
### Available Tools
| Tool | Description |
| - | - |
| **Create Note** | Add a new note in a specified folder |
| **Get Notes** | List notes in a folder or across all folders |
| **Read Note** | Fetch a note's content by ID or title |
| **Update Note** | Modify an existing note |
| **Get Selected Note** | Return whatever note the user has selected in Notes.app |
### Example Usage
```
"Create a note titled 'Trip Checklist' with my packing list"
"Add today's meeting notes to my 'Work' folder"
"Summarize the note I have open"
```
<Tip>
The **Get Selected Note** tool lets the AI react to the note you are currently viewing — ideal for "summarize this" or "translate this" flows.
</Tip>
## Apple Maps
Query addresses, coordinates, and directions via the native Maps app.
### Available Tools
| Tool | Description |
| - | - |
| **Search Address** | Look up a location by free-text query |
| **Get Directions** | Compute a route between two locations |
### Example Usage
```
"Where is 1 Infinite Loop?"
"Directions from my office to SFO by car"
```
## Required Permissions
These integrations use native macOS APIs and require appropriate system permissions.
<Steps>
<Step title="Accessibility Permission">
Go to **System Settings** -> **Privacy & Security** -> **Accessibility** and enable EnConvo. This is required for reading screen content and interacting with apps.
</Step>
<Step title="Automation Permission">
When EnConvo first tries to control Mail, Reminders, Calendar, Contacts, Messages, Notes, or Shortcuts, macOS will prompt you to grant Automation permission for each app. Click **Allow**.
</Step>
<Step title="Calendar Access">
Grant EnConvo access to your calendars when prompted. Go to **System Settings** -> **Privacy & Security** -> **Calendars** if you need to change this later.
</Step>
<Step title="Reminders Access">
Grant EnConvo access to your reminders when prompted. Go to **System Settings** -> **Privacy & Security** -> **Reminders** if needed.
</Step>
<Step title="Contacts Access">
Grant EnConvo access to your contacts when prompted. Go to **System Settings** -> **Privacy & Security** -> **Contacts** if needed.
</Step>
</Steps>
<Warning>
If you deny a permission prompt, the corresponding integration will not function. You can always re-enable permissions in **System Settings** -> **Privacy & Security**.
</Warning>
## Privacy
* All Apple ecosystem integrations operate entirely on your Mac using native macOS APIs
* No data is sent to external servers unless you explicitly ask the AI to process content (e.g., "summarize this email")
* Email content, reminders, and calendar events are accessed on demand -- nothing is cached or stored by EnConvo
* You can revoke permissions at any time through macOS System Settings
## Troubleshooting
<AccordionGroup>
<Accordion title="Mail tools not working">
Verify that the Mail app is configured with at least one email account. Check that EnConvo has Automation permission for Mail in **System Settings** -> **Privacy & Security** -> **Automation**.
</Accordion>
<Accordion title="Calendar access denied">
Go to **System Settings** -> **Privacy & Security** -> **Calendars** and ensure EnConvo is listed and enabled. Restart EnConvo after granting permission.
</Accordion>
<Accordion title="Reminders not appearing">
Ensure EnConvo has Reminders access in **System Settings** -> **Privacy & Security** -> **Reminders**. Also verify that your reminders are synced and visible in the native Reminders app.
</Accordion>
<Accordion title="Shortcuts not discovered">
The Shortcuts integration dynamically scans your system. If a newly created shortcut does not appear, try restarting EnConvo. Shortcuts must be saved in the Shortcuts app (not just in iCloud).
</Accordion>
</AccordionGroup>
## Related Features
<CardGroup>
<Card title="Gmail Integration" icon="google" href="/integrations/gmail">
Google Gmail integration via API
</Card>
<Card title="Messaging Channels" icon="comments" href="/integrations/messaging">
Telegram and Discord
</Card>
<Card title="Agents" icon="robot" href="/ai/agents">
AI agents that use Apple tools automatically
</Card>
<Card title="Workflows" icon="diagram-project" href="/workflows/introduction">
Automate Apple app tasks in workflows
</Card>
</CardGroup>
# Gmail Integration
Source: https://docs.enconvo.ai/integrations/gmail
Read, search, and manage Gmail directly from Enconvo
## Overview
The Gmail integration brings your email directly into EnConvo's AI workspace. With 13 built-in tools, you can search, read, send, draft, organize, and manage emails entirely through natural language -- no need to switch to your browser or the Gmail app.
Ask your AI assistant to find important emails, draft replies, clean up your inbox, or manage labels, and it handles everything behind the scenes using the Gmail API.
## Available Tools
EnConvo's Gmail extension exposes the following tools that the AI can use automatically during conversations:
### Email Operations
| Tool | Description |
| - | - |
| **Search Emails** | Search your inbox using Gmail search syntax (e.g., `from:john@example.com`, `subject:invoice`, `after:2024/01/01`) |
| **Read Email** | Retrieve the full content of a specific email by its message ID |
| **Send Email** | Send a new email with recipients, subject, body, CC/BCC, and attachments |
| **Draft Email** | Create a draft email without sending it |
| **Modify Email** | Change email labels (move between folders, mark as read/unread) |
| **Delete Email** | Permanently delete a specific email |
### Batch Operations
| Tool | Description |
| - | - |
| **Batch Modify Emails** | Apply label changes to multiple emails at once (configurable batch size, default 50) |
| **Batch Delete Emails** | Permanently delete multiple emails in batches |
### Label Management
| Tool | Description |
| - | - |
| **List Email Labels** | Retrieve all available Gmail labels |
| **Create Label** | Create a new Gmail label with visibility settings |
| **Update Label** | Rename or change visibility of an existing label |
| **Delete Label** | Remove a Gmail label |
| **Get or Create Label** | Find an existing label by name, or create it if it does not exist |
## Setting Up Gmail
### Authentication
EnConvo uses Google OAuth to securely connect to your Gmail account. Sign-in uses Google authorization; review the requested access before granting it.
<Steps>
<Step title="Open Gmail Extension Settings">
Go to **Settings** and find the **Gmail** extension
</Step>
<Step title="Choose Credential Provider">
Select either **Gmail (Enconvo Cloud)** (recommended, pre-configured OAuth) or your own **Gmail** credentials
</Step>
<Step title="Authorize Access">
Click **Sign In** and follow the Google OAuth flow to grant EnConvo access to your Gmail
</Step>
<Step title="Start Using Gmail Tools">
Enable the Gmail tools for the Agent you intend to use, then test a read-only request in that Agent's conversation
</Step>
</Steps>
<Tip>
The **Gmail (Enconvo Cloud)** credential option provides a pre-configured OAuth setup so you can get started without creating your own Google API project.
</Tip>
### Using Your Own Google API Credentials
If you prefer to use your own Google Cloud project:
1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select an existing one
3. Enable the **Gmail API**
4. Create OAuth 2.0 credentials (Desktop application type)
5. In EnConvo, select the **Gmail** credential provider and enter your Client ID and Client Secret
## Using Gmail in Conversations
Once connected, simply talk to your AI assistant about email tasks. The AI automatically selects and uses the appropriate Gmail tools.
### Example Conversations
**Search and summarize:**
```
"Find all emails from John in the last week and summarize them"
```
**Draft a reply:**
```
"Draft a reply to the latest email from marketing@company.com thanking them for the report"
```
**Inbox cleanup:**
```
"Archive all newsletters from the past month"
```
**Label management:**
```
"Create a label called 'Q1 Reports' and move all emails with 'quarterly report' in the subject there"
```
**Batch operations:**
```
"Delete all promotional emails older than 6 months"
```
### Email Composition Features
When sending or drafting emails, the AI can:
* Set recipients (To, CC, BCC)
* Compose both plain text and HTML email bodies
* Attach files from your Mac
* Reply to existing email threads (preserving thread context)
* Use `multipart/alternative` for emails with both plain text and HTML versions
## Workflows
Gmail tools integrate with EnConvo's workflow system. Common workflow patterns:
| Workflow | Description |
| - | - |
| **Daily Email Digest** | Search for unread emails, summarize them, and present a morning briefing |
| **Auto-Categorize** | Search for new emails and automatically apply labels based on content |
| **Follow-Up Reminder** | Find emails awaiting replies and create reminders |
| **Report Generation** | Search for emails matching criteria and compile a summary report |
## Privacy and Security
<Warning>
EnConvo accesses your Gmail only when you explicitly ask the AI to perform email-related tasks. No emails are read, cached, or processed in the background.
</Warning>
* **OAuth 2.0**: Industry-standard authentication -- EnConvo never sees your Google password
* **On-demand access**: Gmail API calls are made only when the AI uses a Gmail tool during your conversation
* **No background syncing**: EnConvo does not maintain a local copy of your emails
* **Revocable access**: You can revoke EnConvo's access at any time from your [Google Account permissions](https://myaccount.google.com/permissions)
* **Scoped permissions**: Only the minimum required Gmail scopes are requested
## Troubleshooting
<AccordionGroup>
<Accordion title="Authentication fails or token expired">
Go to **Settings** -> **Gmail** and re-authenticate by signing in again. OAuth tokens expire periodically and need to be refreshed.
</Accordion>
<Accordion title="AI does not use Gmail tools">
Make sure the Gmail extension is installed and the credential provider is configured. Gmail tools are automatically available to agent-mode conversations -- verify that agent mode is enabled.
</Accordion>
<Accordion title="Search returns no results">
Gmail search uses the same query syntax as the Gmail web interface. Try simpler queries first (e.g., `from:john`) and ensure the emails exist in the authenticated account.
</Accordion>
<Accordion title="Cannot send attachments">
Verify that the file paths are correct and accessible. The AI needs valid absolute file paths on your Mac to attach files.
</Accordion>
</AccordionGroup>
## Related Features
<CardGroup>
<Card title="Apple Mail" icon="envelope" href="/integrations/apple-ecosystem">
Native macOS Mail integration
</Card>
<Card title="Agents" icon="robot" href="/ai/agents">
AI agents that use Gmail tools automatically
</Card>
<Card title="Workflows" icon="diagram-project" href="/workflows/introduction">
Automate email tasks with workflows
</Card>
<Card title="Context Awareness" icon="eye" href="/features/context-awareness">
AI understands your current context
</Card>
</CardGroup>
# iPhone App
Source: https://docs.enconvo.ai/integrations/iphone-app
A narrated video tutorial: pair the Enconvo iPhone app with your Mac and reach your chats from your phone.
The Enconvo iPhone app pairs with your Mac, so your Mac's projects and chats are on your phone. Every chat you open from the phone keeps running on your Mac, with its files, apps, and agents. This tutorial pairs a phone from start to finish: sign in, show the pairing code on the Mac, and scan it with the iPhone.
<YouTubePlayer title="How to Pair Your iPhone with Your Mac in Enconvo | Step-by-Step Tutorial" />
The video is 1 minute 12 seconds long. The written steps below follow the same order, with the matching timestamp for each step.
<Note>
The iPhone app is in beta. Install it from [TestFlight](https://testflight.apple.com/join/MJQuEN28), or scan the TestFlight code in **Settings → Agents → Connections** on your Mac. Pairing needs Enconvo 2.5.6 beta or later on the Mac.
</Note>
## Steps
<Steps>
<Step title="Sign in on your iPhone (0:07)">
Install the iPhone app and sign in with the same Enconvo account as your Mac. Only phones signed in to your account can pair with it.
</Step>
<Step title="Show the pairing code (0:16)">
On the Mac, open **Settings → Agents → Connections** and select **Show pairing code**. The QR code is good for five minutes; if it runs out, select **Show a new code**.
</Step>
<Step title="Scan it with your iPhone (0:22)">
On the phone, open **Remote** and tap **Pair a Mac**, then point the camera at the code on your Mac. The two are paired in a moment. Your phone reaches the Mac through the Enconvo relay, and messages are end-to-end encrypted.
</Step>
<Step title="Your Mac, on your phone (0:34)">
Once the Mac shows as **Online** in Remote, its projects and chats are right there on your phone.
</Step>
<Step title="Open any chat (0:40)">
Open any chat and pick up where you left off. The chat still runs on your Mac, so it can use that Mac's files, apps, and agents.
</Step>
<Step title="Keep it reachable (0:47)">
In **Connections** (or **Settings → Keep Awake**), turn on **Keep this Mac awake**. It keeps the Mac from sleeping, on battery too, so your phone can always reach it. You can also keep the screen on, have it turn off after a set time, or keep the Mac awake with the lid closed (this asks for an administrator password once).
</Step>
<Step title="Remove a phone (0:52)">
Lost a phone? In **Connections → Paired phones**, select **Remove** next to it. That phone can no longer reach your Mac; to use it again, pair it with a new code.
</Step>
</Steps>
## What you can do from your phone
Once paired, you can:
* Browse your Mac's projects and chats, and continue any chat.
* Answer questions an Agent asks while it works on your Mac.
* Get notified when a chat finishes.
* Chat with AI models on the phone itself, using Enconvo Cloud points or your own API key.
## Manage paired phones
**Settings → Agents → Connections** lists every paired phone and shows whether phones can reach this Mac right now.
| Task | How |
| - | - |
| Pair another phone | Select **Pair another phone** and scan the new code. A Mac can have up to 10 paired phones. |
| Remove a phone | Select **Remove** next to it in **Paired phones**. |
| Start over | Select **Reset connection**. Enconvo creates a new connection key and removes every paired phone; each phone then scans a new code. |
<Tip>
If the phone can't reach your Mac, check that the Mac is awake, signed in, and online, and that **Connections** shows it as **Online**.
</Tip>
## Next steps
<CardGroup>
<Card title="Chat" icon="comments" href="/ai/chat">Chats, models, and the Chat Window you continue from the phone.</Card>
<Card title="Agents" icon="robot" href="/ai/agents">The Agents your phone can hand work to on the Mac.</Card>
<Card title="Messaging Channels" icon="paper-plane" href="/integrations/messaging">Reach an Agent from Telegram or Discord instead.</Card>
<Card title="Account" icon="user" href="/configuration/account">Sign in and manage the account both devices share.</Card>
</CardGroup>
# Messaging Channels
Source: https://docs.enconvo.ai/integrations/messaging
Connect an Enconvo Agent to Telegram or Discord and control incoming access.
Current built-in IM Channel providers are **Telegram** and **Discord**. Configure them in **Settings → Agents → IM Channels**. Each channel provider binds to at most one Agent; one Agent can serve multiple channel providers.
## Add a channel
1. Open **IM Channels** and add a provider for Telegram or Discord.
2. Give the connection an identifiable name.
3. Enter the platform's **Bot Token** in its password field.
4. Choose **bind agent** to select the Agent that should handle incoming messages.
5. Review access controls, then enable the channel.
6. Confirm that its connection status is **Connected** and send a test message from an allowed account.
Keep Enconvo running and the Mac online while the bot is listening. The Agent's model and tool configuration determine the replies it can produce.
## Telegram
Create a bot with Telegram's **BotFather** and copy its bot token. Open the channel's **Access Control** before enabling it. The default pairing policy requires a new user to share a pairing code for approval; review pending requests and approve only the intended users.
If the bot works in a direct chat but not a group, review Telegram's bot privacy and group permissions as well as the channel's access policy. A token alone does not grant permission to every conversation.
## Discord
Create an application and bot in the Discord Developer Portal, invite it to the intended server, and grant the permissions and intents required for the messages it should receive and send. Paste its bot token into the Discord provider and bind an Agent.
If it connects but does not reply, check the target channel's permissions and whether the bot receives that type of message. Keep access limited to the intended server and channels.
## Sessions and replies
Incoming conversations are routed to chat sessions for the bound Agent. Reply context follows that conversation; it is not one shared transcript for every connected user. Changing the bound Agent reconnects the channel so subsequent messages go to the selected Agent.
Use a dedicated Agent with appropriate instructions and tools for a public or team bot. Review which tools it can invoke before making it available to other people.
## Scheduled delivery
[Scheduled Tasks](/workflows/scheduled-jobs) can deliver results to a configured IM chat. Select the destination explicitly and use the task's run history to distinguish a generation failure from a delivery failure.
## Troubleshooting
| Symptom | Check |
| - | - |
| Disconnected | Bot token, network, enabled state, and Enconvo running |
| Connected but silent | Agent binding, provider access, platform permissions, and pairing policy |
| Wrong assistant behavior | The bound Agent's instructions, tools, and model |
| Telegram user cannot connect | Pending pairing request and allowed users |
| Replies stop after quitting Enconvo | The local listener needs the app and runtime to remain running |
This built-in channel page does not provide Slack or Feishu setup. If you use those services through another plugin or MCP server, follow that integration's own guide.
# Plans and Usage
Source: https://docs.enconvo.ai/pricing
Understand app licensing, Cloud points, and provider billing.
Enconvo supports several ways to access AI. Check your **Settings → Account** page and the official website for the plans, entitlements, and prices currently available to your account.
| Access | Where usage is accounted for |
| - | - |
| Enconvo app license | App feature access shown in Account |
| Enconvo Cloud Plan | Cloud usage and points shown in Points Usage |
| Your own API key | The selected model provider's API account |
| Supported provider subscription | The connected provider account's supported capabilities and limits |
| Local models | Your Mac's compute, memory, storage, and any required model downloads |
Buying an app license does not itself create paid API credit with every provider. A provider's chat subscription also does not imply access to all of that provider's APIs.
## Current plan information
* [Enconvo website](https://www.enconvo.com)
* [Enconvo Cloud Plan](https://www.enconvo.com/cloud-plan)
* [Cloud model pricing](https://www.enconvo.com/cloud-pricing)
Use the model and access method actually selected in the feature when checking cost. Text, images, video, transcription, embeddings, and realtime voice can have different accounting.
## Check unexpected usage
Open **Points Usage** for Enconvo Cloud, or the provider's own usage page for BYOK. Review scheduled tasks, long-running tasks, retrieval, and generation requests that may have used the same provider profile.
Related: [Account](/configuration/account), [Credentials](/configuration/credentials), [Providers](/providers/overview).
# 1min AI
Source: https://docs.enconvo.ai/providers/1minai
Connect 1min AI and choose an AI model in Enconvo.
Use **1min AI** as an AI Model provider in Enconvo. The available model list comes from the installed provider and your account access; select a model in the app rather than relying on a fixed list in this guide.
## Connect
1. Open **Settings → Global Providers Settings → AI Model**.
2. Select **1min AI**, or use **Add New Provider** to create another profile.
3. Configure the provider’s **Authentication** using your own account or API key, following the available method on that page.
4. Validate the credential if a validation action is offered.
5. Choose the model or deployment, then select this provider in your Agent or conversation and send a short text request.
## Provider options
The provider definition includes: **Model Name**, **Temperature**, **Max Tokens**. Some controls appear only for models or authentication methods that support them.
## Use it in a conversation
Select the model from the conversation’s model menu. Review reasoning and tool support for the selected model before running an Agent task. A text-only request is a useful connection check before adding images, documents, or tools.
Provider profiles share credentials across their supported categories. See [Credentials and Provider Profiles](/configuration/credentials) before renaming, deleting, or changing a shared key.
## Troubleshooting
| Symptom | Check |
| - | - |
| Authentication failure | Correct profile, authentication method, and account access |
| Model unavailable | Current model picker and access granted to your account |
| Tool or image request fails | Selected model capabilities and enabled Agent tools |
| Rate or usage limit | Provider account usage, or Cloud usage if using an Enconvo Cloud provider |
| Slow response | Input size, selected model, reasoning setting, and provider availability |
See the [provider capability catalog](/providers/catalog) for other categories and [Model Selection](/ai/model-selection-guide) for choosing a model by task.
# AIMagicX
Source: https://docs.enconvo.ai/providers/aimagicx
Connect AIMagicX and choose an AI model in Enconvo.
Use **AIMagicX** as an AI Model provider in Enconvo. The available model list comes from the installed provider and your account access; select a model in the app rather than relying on a fixed list in this guide.
## Connect
1. Open **Settings → Global Providers Settings → AI Model**.
2. Select **AIMagicX**, or use **Add New Provider** to create another profile.
3. Configure the provider’s **Authentication** using your own account or API key, following the available method on that page.
4. Validate the credential if a validation action is offered.
5. Choose the model or deployment, then select this provider in your Agent or conversation and send a short text request.
## Provider options
The provider definition includes: **Model Name**, **Temperature**, **Max Tokens**. Some controls appear only for models or authentication methods that support them.
## Use it in a conversation
Select the model from the conversation’s model menu. Review reasoning and tool support for the selected model before running an Agent task. A text-only request is a useful connection check before adding images, documents, or tools.
Provider profiles share credentials across their supported categories. See [Credentials and Provider Profiles](/configuration/credentials) before renaming, deleting, or changing a shared key.
## Troubleshooting
| Symptom | Check |
| - | - |
| Authentication failure | Correct profile, authentication method, and account access |
| Model unavailable | Current model picker and access granted to your account |
| Tool or image request fails | Selected model capabilities and enabled Agent tools |
| Rate or usage limit | Provider account usage, or Cloud usage if using an Enconvo Cloud provider |
| Slow response | Input size, selected model, reasoning setting, and provider availability |
See the [provider capability catalog](/providers/catalog) for other categories and [Model Selection](/ai/model-selection-guide) for choosing a model by task.
# Anthropic
Source: https://docs.enconvo.ai/providers/anthropic
Connect Anthropic and choose an AI model in Enconvo.
Use **Anthropic** as an AI Model provider in Enconvo. The available model list comes from the installed provider and your account access; select a model in the app rather than relying on a fixed list in this guide.
## Connect
1. Open **Settings → Global Providers Settings → AI Model**.
2. Select **Anthropic**, or use **Add New Provider** to create another profile.
3. Configure the provider’s **Authentication** using your own account or API key, following the available method on that page.
4. Validate the credential if a validation action is offered.
5. Choose the model or deployment, then select this provider in your Agent or conversation and send a short text request.
## Provider options
Choose **API Key** or **Claude Subscription** in Authentication. See [Claude Subscription](/providers/anthropic_subscription) for connecting an account. Reasoning controls depend on the selected model.
The provider definition includes: **Model Name**, **Temperature**. Some controls appear only for models or authentication methods that support them.
## Use it in a conversation
Select the model from the conversation’s model menu. Review reasoning and tool support for the selected model before running an Agent task. A text-only request is a useful connection check before adding images, documents, or tools.
Provider profiles share credentials across their supported categories. See [Credentials and Provider Profiles](/configuration/credentials) before renaming, deleting, or changing a shared key.
## Troubleshooting
| Symptom | Check |
| - | - |
| Authentication failure | Correct profile, authentication method, and account access |
| Model unavailable | Current model picker and access granted to your account |
| Tool or image request fails | Selected model capabilities and enabled Agent tools |
| Rate or usage limit | Provider account usage, or Cloud usage if using an Enconvo Cloud provider |
| Slow response | Input size, selected model, reasoning setting, and provider availability |
See the [provider capability catalog](/providers/catalog) for other categories and [Model Selection](/ai/model-selection-guide) for choosing a model by task.
# Claude Subscription
Source: https://docs.enconvo.ai/providers/anthropic_subscription
Connect a supported Anthropic account through provider Authentication.
Connect your supported Anthropic account through Enconvo’s provider Authentication controls. Available capabilities and limits depend on your account and the service’s current access rules.
## Connect
1. Open **Settings → AI Model → Anthropic**.
2. In **Authentication**, select **Claude Subscription**.
3. Click **Connect** and complete the account’s sign-in and authorization flow.
4. Return to Enconvo and check that the intended account is connected.
5. Select an available model and try a short request.
## Account status and usage
Use the account card’s menu to **Reconnect** or **Refresh usage** when those actions are available. **% left** describes remaining allowance; a reset countdown indicates when the reported window resets. Unavailable usage data is not a promise of unlimited access.
The account card can show the remaining five-hour and weekly allowances, including per-model allowances when returned by the service.
## Troubleshooting
If sign-in fails, follow the provider’s error and check that you connected the intended account. If a model or capability is unavailable, confirm it appears for that account in the current picker. If a usage window is exhausted, wait for its reported reset or choose another access method you have configured.
A subscription connection is distinct from an API key. Switching Authentication changes the access method used by that provider. See [Credentials](/configuration/credentials) for shared profiles and [Pricing](/pricing) for the difference between app licensing, Cloud usage, and provider billing.
# Arli AI
Source: https://docs.enconvo.ai/providers/arli
Connect Arli AI and choose an AI model in Enconvo.
Use **Arli AI** as an AI Model provider in Enconvo. The available model list comes from the installed provider and your account access; select a model in the app rather than relying on a fixed list in this guide.
## Connect
1. Open **Settings → Global Providers Settings → AI Model**.
2. Select **Arli AI**, or use **Add New Provider** to create another profile.
3. Configure the provider’s **Authentication** using your own account or API key, following the available method on that page.
4. Validate the credential if a validation action is offered.
5. Choose the model or deployment, then select this provider in your Agent or conversation and send a short text request.
## Provider options
The provider definition includes: **Model Name**, **Temperature**. Some controls appear only for models or authentication methods that support them.
## Use it in a conversation
Select the model from the conversation’s model menu. Review reasoning and tool support for the selected model before running an Agent task. A text-only request is a useful connection check before adding images, documents, or tools.
Provider profiles share credentials across their supported categories. See [Credentials and Provider Profiles](/configuration/credentials) before renaming, deleting, or changing a shared key.
## Troubleshooting
| Symptom | Check |
| - | - |
| Authentication failure | Correct profile, authentication method, and account access |
| Model unavailable | Current model picker and access granted to your account |
| Tool or image request fails | Selected model capabilities and enabled Agent tools |
| Rate or usage limit | Provider account usage, or Cloud usage if using an Enconvo Cloud provider |
| Slow response | Input size, selected model, reasoning setting, and provider availability |
See the [provider capability catalog](/providers/catalog) for other categories and [Model Selection](/ai/model-selection-guide) for choosing a model by task.
# Azure OpenAI
Source: https://docs.enconvo.ai/providers/azure-openai
Connect Azure OpenAI and choose an AI model in Enconvo.
Use **Azure OpenAI** as an AI Model provider in Enconvo. The available model list comes from the installed provider and your account access; select a model in the app rather than relying on a fixed list in this guide.
## Connect
1. Open **Settings → Global Providers Settings → AI Model**.
2. Select **Azure OpenAI**, or use **Add New Provider** to create another profile.
3. Configure the provider’s **Authentication** using your own account or API key, following the available method on that page.
4. Validate the credential if a validation action is offered.
5. Choose the model or deployment, then select this provider in your Agent or conversation and send a short text request.
## Provider options
Configure the credential’s **API Key**, **Endpoint**, and **API Version**, then set **Azure OpenAI Api Deployment Name** in the model provider. A deployment name is the name configured in your Azure resource, not necessarily the model family name. Streaming is a separate provider setting.
The provider definition includes: **Azure OpenAI Api Deployment Name**, **Temperature**. Some controls appear only for models or authentication methods that support them.
## Use it in a conversation
Select the model from the conversation’s model menu. Review reasoning and tool support for the selected model before running an Agent task. A text-only request is a useful connection check before adding images, documents, or tools.
Provider profiles share credentials across their supported categories. See [Credentials and Provider Profiles](/configuration/credentials) before renaming, deleting, or changing a shared key.
## Troubleshooting
| Symptom | Check |
| - | - |
| Authentication failure | Correct profile, authentication method, and account access |
| Model unavailable | Current model picker and access granted to your account |
| Tool or image request fails | Selected model capabilities and enabled Agent tools |
| Rate or usage limit | Provider account usage, or Cloud usage if using an Enconvo Cloud provider |
| Slow response | Input size, selected model, reasoning setting, and provider availability |
See the [provider capability catalog](/providers/catalog) for other categories and [Model Selection](/ai/model-selection-guide) for choosing a model by task.
# Provider Capability Catalog
Source: https://docs.enconvo.ai/providers/catalog
Browse every declared provider by the feature it powers.
This catalog groups the providers declared by the current Enconvo extensions by capability. Installed builds and account access can differ. Model names, voices, prices, and quotas are intentionally left to the live pickers and provider accounts.
Configure shared access through [Credentials](/configuration/credentials); select a provider separately for each capability.
## AI models
Open **AI Model**. See the [task guide](/ai/chat).
| Provider | Configuration |
| - | - |
| Enconvo Cloud Plan | Model Name, Temperature |
| OpenAI | Model Name, Temperature |
| OpenClaw | Model Name, Gateway Transport, Temperature |
| Hermes Agent | Model Name, Temperature |
| Anthropic | Model Name, Temperature |
| Minimax AI | Model Name, Temperature |
| Google Gemini AI | Model Name, Temperature, Google Search Tool, URL Context Tool, Show thoughts |
| Ollama | Model Name, Temperature |
| Deep Seek | Model Name, Temperature |
| Groq AI | Model Name, Temperature |
| Azure OpenAI | Azure OpenAI Api Deployment Name, Temperature |
| X.AI-GROK | Model Name, Temperature |
| Z.AI | Model Name, Temperature |
| Xiaomi MiMo | Model Name, Temperature |
| Mistral AI | Model Name, Temperature |
| Qwen | Model Name, Temperature |
| Cohere AI | Model Name, Temperature |
| Perplexity | Model Name, Temperature |
| SiliconFlow | Model Name, Temperature |
| LM Studio | Model Name, Temperature |
| MLX (mlx) | Model, Temperature, Reasoning Effort |
| OpenRouter | Model Name, Temperature, Google Search Tool, URL Context Tool |
| Fireworks | Model Name, Temperature |
| Together AI | Model Name, Temperature |
| Poe | Model Name, Temperature |
| kimi.ai | Model Name, Temperature |
| DashScope | Model Name, Temperature |
| Sambanova AI | Model Name, Temperature |
| DeepInfra | Model Name, Temperature |
| Phala | Model Name, Temperature |
| Cerebras AI | Model Name, Temperature |
| Arli AI | Model Name, Temperature |
| AIMagicX | Model Name, Temperature, Max Tokens |
| 1min AI | Model Name, Temperature, Max Tokens |
| Vercel AI Gateway | Model Name, Temperature, Google Search Tool, URL Context Tool |
## Speech recognition
Open **Dictation / Recording / Transcription / Captioning Models**. See the [task guide](/ai/speech-recognition).
| Provider | Configuration |
| - | - |
| Soniox (Enconvo Cloud) | Model, Language Hints, Live Translation, Translate From, Translate To |
| OpenAI (Enconvo Cloud) | ModelName |
| xAI Speech-to-Text (Enconvo Cloud) | Model, Language |
| Voxtral (Enconvo Cloud) | ModelName |
| Voxtral | ModelName |
| OpenAI | Model Name, Prompt |
| xAI Speech-to-Text | Model, Language |
| Groq (Enconvo Cloud) | Prompt, Language, ModelName |
| Google Gemini (Enconvo Cloud) | ModelName |
| Microsoft (Enconvo Cloud) | Language, Model Name |
| Parakeet MLX | Model Name |
| Parakeet CoreML | Model Name |
| SenseVoice CoreML | Model Name |
| Paraformer CoreML | Model Name |
| Nemotron CoreML | Model Name |
| Qwen3 MLX | Model, Language |
| Microsoft | Language, Model Name |
| AssemblyAI (Enconvo Cloud) | Model |
| Assembly AI | Language, Model Name |
| Soniox | Model, Language Hints, Live Translation, Translate From, Translate To |
| Volcengine (Enconvo Cloud) | Model, Language Hints, Hot Words |
| Volcengine (ByteDance BigASR) | Model, Language Hints, Hot Words |
| Groq | Language, Prompt, ModelName |
| ElevenLabs (Scribe) | Language, ModelName |
| ElevenLabs (Enconvo Cloud) | Model, Language |
| Whisper MLX | ModelName, Language |
| Google Gemini | Model Name |
## Text-to-speech
Open **Text-to-Speech**. See the [task guide](/ai/text-to-speech).
| Provider | Configuration |
| - | - |
| xAI TTS ( Enconvo Cloud Plan ) | Voice, Language |
| Gemini TTS ( Enconvo Cloud Plan ) | Model Name, Voice |
| Edge TTS | Voice, Output Format |
| xAI TTS | Voice, Language |
| Gemini TTS | Model Name, Voice |
| OpenAI TTS | Model Name, Voice, Speech Speed |
| Microsoft TTS ( Enconvo Cloud Plan ) | Speech Voice, Speech Speed |
| Microsoft TTS | Speech Voice, Speech Speed |
| Eleven Labs TTS | Model Name, Voice, Speech Speed |
| Kokoro (mlx) | Model, Speech Speed |
| Qwen3 (mlx) | Model |
| System TTS | Voice, Speech Speed |
| Speechify TTS | Model Name, Voice, Speech Speed |
| MiniMax TTS ( Enconvo Cloud Plan ) | Model Name, Voice, Speech Speed |
| MiniMax TTS | Model Name, Voice, Speech Speed |
| Xiaomi MiMo TTS | Model Name, Speech Speed |
| Xiaomi MiMo TTS ( Enconvo Cloud Plan ) | Model Name, Speech Speed |
| Soniox TTS | Voice, Language |
| Soniox TTS ( Enconvo Cloud Plan ) | Voice, Language |
## Image generation
Open **Image Generation**. See the [task guide](/ai/image-generation).
| Provider | Configuration |
| - | - |
| OpenAI (Enconvo Cloud) | Model Name |
| Google Gemini (Enconvo Cloud) | Model Name |
| Google Gemini | Model Name |
| OpenAI | Model Name |
| xAI | Model Name |
| OpenRouter | Model Name |
| Kie.ai | Model Name |
| Topview | Model Name |
| Azure AI | Model Name, Size, Number |
| Together | Model Name, Size, Number, Steps |
## Video generation
Open **Video Generation**. See the [task guide](/ai/video-generation).
| Provider | Configuration |
| - | - |
| xAI (Enconvo Cloud) | Model Name |
| xAI | Model Name |
| OpenRouter | Model Name |
| Kie.ai | Model Name |
| Topview | Model Name |
| Google Gemini (Enconvo Cloud) | Model Name |
| Google Gemini | Model Name |
## Web search
Open **Web Search**. See the [task guide](/ai/web-search).
| Provider | Configuration |
| - | - |
| Tavily (Enconvo Cloud) | Model Name |
| Gemini | Provider, Model Name |
| Tavily | Provider-specific settings |
| Bing | Provider-specific settings |
| Brave | Provider-specific settings |
| Google Custom | Provider-specific settings |
| Exa | Provider-specific settings |
| xAI X Search (Enconvo Cloud) | Model Name |
| xAI X Search | Model Name |
## Web fetch
Open **Web Fetch**. See the [task guide](/ai/web-fetch).
| Provider | Configuration |
| - | - |
| Local Fetch (locally , free) | Browser-Assisted Fetching, Enconvo Companion Extension |
| Jina AI Link Reader | Provider-specific settings |
| Firecrawl Link Reader | Provider-specific settings |
| Enconvo Cloud Plan | Provider-specific settings |
## OCR
Open **OCR**. See the [task guide](/ai/ocr).
| Provider | Configuration |
| - | - |
| PP-OCRv6 (MLX) | Model |
| AI Model OCR | Instruction, AI Model Provider |
| Apple Native OCR | Provider-specific settings |
| Mistral OCR (Enconvo Cloud Plan) | Model |
| Mistral OCR | Model |
## Embeddings
Open **Knowledge Base settings**. See the [task guide](/advanced/knowledge-base-advanced).
| Provider | Configuration |
| - | - |
| Gemma (mlx) | Model |
| EnConvo Cloud Plan | Model Name |
| OpenAI | Model Name |
| Ollama | Model Name |
| Voyage AI | Model Name |
| Qwen3 (mlx) | Model |
| Jina (mlx) | Model |
| MiniLM (mlx) | Model |
| SiliconFlow | Model Name |
## Reranking
Open **Knowledge Base settings**. See the [task guide](/advanced/knowledge-base-advanced).
| Provider | Configuration |
| - | - |
| EnConvo Cloud Plan | Model Name |
| Voyage AI | Model Name |
| Qwen3 (mlx) | Model |
| Jina (mlx) | Model |
| SiliconFlow | Model Name |
# Cerebras AI
Source: https://docs.enconvo.ai/providers/cerebras
Connect Cerebras AI and choose an AI model in Enconvo.
Use **Cerebras AI** as an AI Model provider in Enconvo. The available model list comes from the installed provider and your account access; select a model in the app rather than relying on a fixed list in this guide.
## Connect
1. Open **Settings → Global Providers Settings → AI Model**.
2. Select **Cerebras AI**, or use **Add New Provider** to create another profile.
3. Configure the provider’s **Authentication** using your own account or API key, following the available method on that page.
4. Validate the credential if a validation action is offered.
5. Choose the model or deployment, then select this provider in your Agent or conversation and send a short text request.
## Provider options
The provider definition includes: **Model Name**, **Temperature**. Some controls appear only for models or authentication methods that support them.
## Use it in a conversation
Select the model from the conversation’s model menu. Review reasoning and tool support for the selected model before running an Agent task. A text-only request is a useful connection check before adding images, documents, or tools.
Provider profiles share credentials across their supported categories. See [Credentials and Provider Profiles](/configuration/credentials) before renaming, deleting, or changing a shared key.
## Troubleshooting
| Symptom | Check |
| - | - |
| Authentication failure | Correct profile, authentication method, and account access |
| Model unavailable | Current model picker and access granted to your account |
| Tool or image request fails | Selected model capabilities and enabled Agent tools |
| Rate or usage limit | Provider account usage, or Cloud usage if using an Enconvo Cloud provider |
| Slow response | Input size, selected model, reasoning setting, and provider availability |
See the [provider capability catalog](/providers/catalog) for other categories and [Model Selection](/ai/model-selection-guide) for choosing a model by task.
# Cohere AI
Source: https://docs.enconvo.ai/providers/cohere
Connect Cohere AI and choose an AI model in Enconvo.
Use **Cohere AI** as an AI Model provider in Enconvo. The available model list comes from the installed provider and your account access; select a model in the app rather than relying on a fixed list in this guide.
## Connect
1. Open **Settings → Global Providers Settings → AI Model**.
2. Select **Cohere AI**, or use **Add New Provider** to create another profile.
3. Configure the provider’s **Authentication** using your own account or API key, following the available method on that page.
4. Validate the credential if a validation action is offered.
5. Choose the model or deployment, then select this provider in your Agent or conversation and send a short text request.
## Provider options
The provider definition includes: **Model Name**, **Temperature**. Some controls appear only for models or authentication methods that support them.
## Use it in a conversation
Select the model from the conversation’s model menu. Review reasoning and tool support for the selected model before running an Agent task. A text-only request is a useful connection check before adding images, documents, or tools.
Provider profiles share credentials across their supported categories. See [Credentials and Provider Profiles](/configuration/credentials) before renaming, deleting, or changing a shared key.
## Troubleshooting
| Symptom | Check |
| - | - |
| Authentication failure | Correct profile, authentication method, and account access |
| Model unavailable | Current model picker and access granted to your account |
| Tool or image request fails | Selected model capabilities and enabled Agent tools |
| Rate or usage limit | Provider account usage, or Cloud usage if using an Enconvo Cloud provider |
| Slow response | Input size, selected model, reasoning setting, and provider availability |
See the [provider capability catalog](/providers/catalog) for other categories and [Model Selection](/ai/model-selection-guide) for choosing a model by task.
# DashScope
Source: https://docs.enconvo.ai/providers/dashscope
Connect DashScope and choose an AI model in Enconvo.
Use **DashScope** as an AI Model provider in Enconvo. The available model list comes from the installed provider and your account access; select a model in the app rather than relying on a fixed list in this guide.
## Connect
1. Open **Settings → Global Providers Settings → AI Model**.
2. Select **DashScope**, or use **Add New Provider** to create another profile.
3. Configure the provider’s **Authentication** using your own account or API key, following the available method on that page.
4. Validate the credential if a validation action is offered.
5. Choose the model or deployment, then select this provider in your Agent or conversation and send a short text request.
## Provider options
The provider definition includes: **Model Name**, **Temperature**. Some controls appear only for models or authentication methods that support them.
## Use it in a conversation
Select the model from the conversation’s model menu. Review reasoning and tool support for the selected model before running an Agent task. A text-only request is a useful connection check before adding images, documents, or tools.
Provider profiles share credentials across their supported categories. See [Credentials and Provider Profiles](/configuration/credentials) before renaming, deleting, or changing a shared key.
## Troubleshooting
| Symptom | Check |
| - | - |
| Authentication failure | Correct profile, authentication method, and account access |
| Model unavailable | Current model picker and access granted to your account |
| Tool or image request fails | Selected model capabilities and enabled Agent tools |
| Rate or usage limit | Provider account usage, or Cloud usage if using an Enconvo Cloud provider |
| Slow response | Input size, selected model, reasoning setting, and provider availability |
See the [provider capability catalog](/providers/catalog) for other categories and [Model Selection](/ai/model-selection-guide) for choosing a model by task.
# DeepInfra
Source: https://docs.enconvo.ai/providers/deepinfra
Connect DeepInfra and choose an AI model in Enconvo.
Use **DeepInfra** as an AI Model provider in Enconvo. The available model list comes from the installed provider and your account access; select a model in the app rather than relying on a fixed list in this guide.
## Connect
1. Open **Settings → Global Providers Settings → AI Model**.
2. Select **DeepInfra**, or use **Add New Provider** to create another profile.
3. Configure the provider’s **Authentication** using your own account or API key, following the available method on that page.
4. Validate the credential if a validation action is offered.
5. Choose the model or deployment, then select this provider in your Agent or conversation and send a short text request.
## Provider options
Use a DeepInfra API key. The built-in endpoint is managed by the provider preset; its base-URL field is hidden in the current credential settings. Tool and image support depend on the model.
The provider definition includes: **Model Name**, **Temperature**. Some controls appear only for models or authentication methods that support them.
## Use it in a conversation
Select the model from the conversation’s model menu. Review reasoning and tool support for the selected model before running an Agent task. A text-only request is a useful connection check before adding images, documents, or tools.
Provider profiles share credentials across their supported categories. See [Credentials and Provider Profiles](/configuration/credentials) before renaming, deleting, or changing a shared key.
## Troubleshooting
| Symptom | Check |
| - | - |
| Authentication failure | Correct profile, authentication method, and account access |
| Model unavailable | Current model picker and access granted to your account |
| Tool or image request fails | Selected model capabilities and enabled Agent tools |
| Rate or usage limit | Provider account usage, or Cloud usage if using an Enconvo Cloud provider |
| Slow response | Input size, selected model, reasoning setting, and provider availability |
See the [provider capability catalog](/providers/catalog) for other categories and [Model Selection](/ai/model-selection-guide) for choosing a model by task.
# Deep Seek
Source: https://docs.enconvo.ai/providers/deepseek
Connect Deep Seek and choose an AI model in Enconvo.
Use **Deep Seek** as an AI Model provider in Enconvo. The available model list comes from the installed provider and your account access; select a model in the app rather than relying on a fixed list in this guide.
## Connect
1. Open **Settings → Global Providers Settings → AI Model**.
2. Select **Deep Seek**, or use **Add New Provider** to create another profile.
3. Configure the provider’s **Authentication** using your own account or API key, following the available method on that page.
4. Validate the credential if a validation action is offered.
5. Choose the model or deployment, then select this provider in your Agent or conversation and send a short text request.
## Provider options
The provider definition includes: **Model Name**, **Temperature**. Some controls appear only for models or authentication methods that support them.
## Use it in a conversation
Select the model from the conversation’s model menu. Review reasoning and tool support for the selected model before running an Agent task. A text-only request is a useful connection check before adding images, documents, or tools.
Provider profiles share credentials across their supported categories. See [Credentials and Provider Profiles](/configuration/credentials) before renaming, deleting, or changing a shared key.
## Troubleshooting
| Symptom | Check |
| - | - |
| Authentication failure | Correct profile, authentication method, and account access |
| Model unavailable | Current model picker and access granted to your account |
| Tool or image request fails | Selected model capabilities and enabled Agent tools |
| Rate or usage limit | Provider account usage, or Cloud usage if using an Enconvo Cloud provider |
| Slow response | Input size, selected model, reasoning setting, and provider availability |
See the [provider capability catalog](/providers/catalog) for other categories and [Model Selection](/ai/model-selection-guide) for choosing a model by task.
# Enconvo Cloud Plan
Source: https://docs.enconvo.ai/providers/enconvo
Use supported AI services through your Enconvo account.
Enconvo Cloud Plan provides model and media services through your Enconvo account. Choose a provider labeled **Enconvo Cloud** or **Enconvo Cloud Plan** in the capability you want to use.
## Set up
1. Sign in to your Enconvo account.
2. Open a category such as **AI Model**, **Image Generation**, **Text-to-Speech**, or the relevant speech-model settings.
3. Select the Cloud provider and choose a model or voice.
4. Run a short request and check the output.
5. Review **Settings → Account → Points Usage** for Cloud consumption.
AI chat, speech, images, video, embeddings, reranking, and web tools use different provider configurations. Choosing Cloud for chat does not automatically select it for every other category.
## Models and usage
The current model picker and your account determine availability. Review the [Cloud Plan](https://www.enconvo.com/cloud-plan) and [Cloud pricing](https://www.enconvo.com/cloud-pricing) pages for current terms instead of assuming all model requests use the same number of points.
If a request fails, check account access, available balance or allowance, the selected model, and the reported error. BYOK and supported subscription connections are alternatives configured through [Credentials](/configuration/credentials).
# Fireworks
Source: https://docs.enconvo.ai/providers/fireworks
Connect Fireworks and choose an AI model in Enconvo.
Use **Fireworks** as an AI Model provider in Enconvo. The available model list comes from the installed provider and your account access; select a model in the app rather than relying on a fixed list in this guide.
## Connect
1. Open **Settings → Global Providers Settings → AI Model**.
2. Select **Fireworks**, or use **Add New Provider** to create another profile.
3. Configure the provider’s **Authentication** using your own account or API key, following the available method on that page.
4. Validate the credential if a validation action is offered.
5. Choose the model or deployment, then select this provider in your Agent or conversation and send a short text request.
## Provider options
The provider definition includes: **Model Name**, **Temperature**. Some controls appear only for models or authentication methods that support them.
## Use it in a conversation
Select the model from the conversation’s model menu. Review reasoning and tool support for the selected model before running an Agent task. A text-only request is a useful connection check before adding images, documents, or tools.
Provider profiles share credentials across their supported categories. See [Credentials and Provider Profiles](/configuration/credentials) before renaming, deleting, or changing a shared key.
## Troubleshooting
| Symptom | Check |
| - | - |
| Authentication failure | Correct profile, authentication method, and account access |
| Model unavailable | Current model picker and access granted to your account |
| Tool or image request fails | Selected model capabilities and enabled Agent tools |
| Rate or usage limit | Provider account usage, or Cloud usage if using an Enconvo Cloud provider |
| Slow response | Input size, selected model, reasoning setting, and provider availability |
See the [provider capability catalog](/providers/catalog) for other categories and [Model Selection](/ai/model-selection-guide) for choosing a model by task.
# Google Gemini AI
Source: https://docs.enconvo.ai/providers/google
Connect Google Gemini AI and choose an AI model in Enconvo.
Use **Google Gemini AI** as an AI Model provider in Enconvo. The available model list comes from the installed provider and your account access; select a model in the app rather than relying on a fixed list in this guide.
## Connect
1. Open **Settings → Global Providers Settings → AI Model**.
2. Select **Google Gemini AI**, or use **Add New Provider** to create another profile.
3. Configure the provider’s **Authentication** using your own account or API key, following the available method on that page.
4. Validate the credential if a validation action is offered.
5. Choose the model or deployment, then select this provider in your Agent or conversation and send a short text request.
## Provider options
The AI Model page offers **API Key** and **Google Account** authentication. Other Gemini capabilities share the profile’s API key. **Google Search Tool**, **URL Context Tool**, and **Show thoughts** appear where supported. See [Google Account](/providers/google_subscription).
The provider definition includes: **Model Name**, **Temperature**, **Google Search Tool**, **URL Context Tool**, **Show thoughts**. Some controls appear only for models or authentication methods that support them.
## Use it in a conversation
Select the model from the conversation’s model menu. Review reasoning and tool support for the selected model before running an Agent task. A text-only request is a useful connection check before adding images, documents, or tools.
Provider profiles share credentials across their supported categories. See [Credentials and Provider Profiles](/configuration/credentials) before renaming, deleting, or changing a shared key.
## Troubleshooting
| Symptom | Check |
| - | - |
| Authentication failure | Correct profile, authentication method, and account access |
| Model unavailable | Current model picker and access granted to your account |
| Tool or image request fails | Selected model capabilities and enabled Agent tools |
| Rate or usage limit | Provider account usage, or Cloud usage if using an Enconvo Cloud provider |
| Slow response | Input size, selected model, reasoning setting, and provider availability |
See the [provider capability catalog](/providers/catalog) for other categories and [Model Selection](/ai/model-selection-guide) for choosing a model by task.
# Google Account
Source: https://docs.enconvo.ai/providers/google_subscription
Connect a supported Google Gemini AI account through provider Authentication.
Connect your supported Google Gemini AI account through Enconvo’s provider Authentication controls. Available capabilities and limits depend on your account and the service’s current access rules.
## Connect
1. Open **Settings → AI Model → Google Gemini AI**.
2. In **Authentication**, select **Google Account**.
3. Click **Connect** and complete the account’s sign-in and authorization flow.
4. Return to Enconvo and check that the intended account is connected.
5. Select an available model and try a short request.
## Account status and usage
Use the account card’s menu to **Reconnect** or **Refresh usage** when those actions are available. **% left** describes remaining allowance; a reset countdown indicates when the reported window resets. Unavailable usage data is not a promise of unlimited access.
Google Account authentication applies to the Gemini AI Model connection. Other Gemini capabilities use the API key shared by the provider profile.
## Troubleshooting
If sign-in fails, follow the provider’s error and check that you connected the intended account. If a model or capability is unavailable, confirm it appears for that account in the current picker. If a usage window is exhausted, wait for its reported reset or choose another access method you have configured.
A subscription connection is distinct from an API key. Switching Authentication changes the access method used by that provider. See [Credentials](/configuration/credentials) for shared profiles and [Pricing](/pricing) for the difference between app licensing, Cloud usage, and provider billing.
# Groq AI
Source: https://docs.enconvo.ai/providers/groq
Connect Groq AI and choose an AI model in Enconvo.
Use **Groq AI** as an AI Model provider in Enconvo. The available model list comes from the installed provider and your account access; select a model in the app rather than relying on a fixed list in this guide.
## Connect
1. Open **Settings → Global Providers Settings → AI Model**.
2. Select **Groq AI**, or use **Add New Provider** to create another profile.
3. Configure the provider’s **Authentication** using your own account or API key, following the available method on that page.
4. Validate the credential if a validation action is offered.
5. Choose the model or deployment, then select this provider in your Agent or conversation and send a short text request.
## Provider options
The provider definition includes: **Model Name**, **Temperature**. Some controls appear only for models or authentication methods that support them.
## Use it in a conversation
Select the model from the conversation’s model menu. Review reasoning and tool support for the selected model before running an Agent task. A text-only request is a useful connection check before adding images, documents, or tools.
Provider profiles share credentials across their supported categories. See [Credentials and Provider Profiles](/configuration/credentials) before renaming, deleting, or changing a shared key.
## Troubleshooting
| Symptom | Check |
| - | - |
| Authentication failure | Correct profile, authentication method, and account access |
| Model unavailable | Current model picker and access granted to your account |
| Tool or image request fails | Selected model capabilities and enabled Agent tools |
| Rate or usage limit | Provider account usage, or Cloud usage if using an Enconvo Cloud provider |
| Slow response | Input size, selected model, reasoning setting, and provider availability |
See the [provider capability catalog](/providers/catalog) for other categories and [Model Selection](/ai/model-selection-guide) for choosing a model by task.
# Hermes Agent
Source: https://docs.enconvo.ai/providers/hermes
Use Hermes Agent as an OpenAI-compatible model in EnConvo
## Overview
Hermes Agent is an open-source AI agent from Nous Research. It runs as a local or server-hosted agent runtime with tools, memory, skills, terminal access, and messaging integrations.
In EnConvo, Hermes Agent is used through its OpenAI-compatible API server. After the Hermes gateway is running, EnConvo can use Hermes like any other AI model in chat, EnConvo agents, and model-powered features.
<Tip>
New to Hermes? Start with the [Hermes Agent Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart), then return here to connect it to EnConvo.
</Tip>
<Tip>
API reference: [Hermes Agent API server docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server). Source: [Hermes Agent GitHub repo](https://github.com/NousResearch/hermes-agent).
</Tip>
## What You Need
* Hermes Agent already installed and configured
* Hermes gateway running with the API server enabled
* The API server token from `API_SERVER_KEY` in `~/.hermes/.env`
* EnConvo with the Hermes Agent AI model provider enabled
Hermes exposes OpenAI-compatible endpoints such as `/v1/models`, `/v1/chat/completions`, and `/v1/responses`. EnConvo's Hermes provider uses the Chat Completions API (`/v1/chat/completions`).
<Note>
EnConvo does not use the Hermes Responses API for this provider. Configure Hermes as an OpenAI-compatible Chat Completions provider.
</Note>
## Automatic Setup in EnConvo
Open EnConvo **Settings** -> **AI Model** -> **Hermes Agent**. The setup card can start, stop, and configure the local Hermes API server for you.
Use **Auto Setup** when Hermes is installed on the same Mac as EnConvo. EnConvo will:
<Steps>
<Step title="Find Hermes">
Check that the `hermes` CLI exists on this Mac.
</Step>
<Step title="Enable the API server">
Update `~/.hermes/.env` with `API_SERVER_ENABLED=true` and an `API_SERVER_KEY` if one is missing.
</Step>
<Step title="Start the gateway">
Start the Hermes gateway service.
</Step>
<Step title="Verify the API">
Probe the local API server with `/v1/health` and `/v1/models`.
</Step>
<Step title="Save credentials">
Save the base URL and API server key into EnConvo's Hermes credentials.
</Step>
</Steps>
The setup card shows a runtime badge such as **Running** or **Stopped**. While the card is visible, EnConvo refreshes this status periodically and stops refreshing when the card is no longer visible.
## Get Base URL and API Key
Use this base URL when EnConvo runs on the same Mac as Hermes:
```text theme={null}
http://127.0.0.1:8642/v1
```
Read the API server token from `~/.hermes/.env`:
```bash theme={null}
awk -F= '/^API_SERVER_KEY=/{print $2}' ~/.hermes/.env
```
EnConvo sends this value as:
```http theme={null}
Authorization: Bearer <API_SERVER_KEY>
```
To test the OpenAI-compatible endpoint directly:
```bash theme={null}
curl http://127.0.0.1:8642/v1/chat/completions \
-H "Authorization: Bearer <API_SERVER_KEY>" \
-H "Content-Type: application/json" \
-d '{
"model": "hermes-agent",
"messages": [
{ "role": "user", "content": "Hello!" }
]
}'
```
<Warning>
Use the base URL ending in `/v1`, not the full `/v1/chat/completions` endpoint.
</Warning>
## Configure Hermes in EnConvo
Open EnConvo **Settings** -> **AI Model** -> **Hermes Agent**, then configure the credential provider.
<img alt="Hermes Agent credential settings in EnConvo" />
| Setting | Value |
| - | - |
| **Hermes Base URL** | `http://127.0.0.1:8642/v1` |
| **API Server Key** | `API_SERVER_KEY` from `~/.hermes/.env` |
Click **Validate** after entering the base URL and token.
## API Behavior and Attachments
EnConvo sends Hermes requests through OpenAI-compatible Chat Completions:
```http theme={null}
POST /v1/chat/completions
```
Use `hermes-agent` or the model name advertised by the Hermes `/v1/models` endpoint.
<Warning>
Image attachments are not sent to Hermes by EnConvo. Treat the Hermes provider as a text/chat provider in EnConvo, even if your upstream Hermes API server advertises image input support. For image workflows, use a vision-capable model provider or run OCR/image analysis before sending text to Hermes.
</Warning>
## Use Hermes as an AI Model
Once configured, Hermes appears in the model selector. Choose **Hermes Agent** and select the advertised model, usually `hermes-agent`.
<img alt="Hermes Agent selected as the chat model" />
Use this mode when you want an EnConvo conversation, command, or feature to run through Hermes Agent while keeping the normal EnConvo interface.
<Steps>
<Step title="Open the model picker">
In chat or another model-powered EnConvo feature, click the current model name.
</Step>
<Step title="Choose Hermes Agent">
Select **Hermes Agent** in the provider list.
</Step>
<Step title="Select the Hermes model">
Choose `hermes-agent` or the model name advertised by your Hermes API server.
</Step>
<Step title="Run the feature normally">
Ask your question or run the EnConvo feature. Hermes handles the model call behind the scenes.
</Step>
</Steps>
<Note>
EnConvo loads Hermes models from the Hermes `/v1/models` endpoint. If Hermes is not running or the endpoint is unavailable, EnConvo falls back to `hermes-agent`.
</Note>
## Create an EnConvo Agent for Hermes
You can also create an EnConvo agent that coordinates Hermes Agent. This is useful when you want an EnConvo-facing workflow, tool set, or prompt around Hermes' agent runtime.
<Steps>
<Step title="Open Create Agent">
Open SmartBar and search for **Create Agent**.
</Step>
<Step title="Name the agent">
Create a clear title, such as `Hermes Agent`.
</Step>
<Step title="Write coordinator instructions">
Give the EnConvo agent instructions that explain how it should work with Hermes.
```markdown theme={null}
You coordinate Hermes Agent for the user.
Use Hermes for agentic work, automation, terminal-backed tasks, and requests that should run through the user's Hermes setup.
Summarize what Hermes did, surface any blockers, and ask before destructive or irreversible actions.
```
</Step>
<Step title="Choose the Hermes model">
In the agent's model settings, select **Hermes Agent** and choose `hermes-agent`.
</Step>
<Step title="Save and use the agent">
Start a conversation with the new EnConvo agent. It will use Hermes while retaining the EnConvo agent interface and tools you configured.
</Step>
</Steps>
## LAN Access
If Hermes is running on another machine, use the host machine's LAN IP in EnConvo:
```text theme={null}
http://<hermes-host-lan-ip>:8642/v1
```
<Warning>
LAN access should use a strong `API_SERVER_KEY`. Only expose the Hermes API server on networks you trust.
</Warning>
## Troubleshooting
<AccordionGroup>
<Accordion title="Hermes Agent does not appear in the model picker">
Make sure the Hermes provider is enabled in **Settings** -> **AI Model**. If the model list is empty, confirm the gateway is running with `hermes gateway status`.
</Accordion>
<Accordion title="Validation fails with unauthorized">
Recheck `API_SERVER_KEY` in `~/.hermes/.env`. EnConvo expects this value and sends it as a Bearer token.
</Accordion>
<Accordion title="Connection fails">
Confirm the API server is healthy with `curl http://127.0.0.1:8642/v1/health`. If EnConvo runs on another device, use the host's LAN IP and make sure Hermes is bound for network access.
</Accordion>
<Accordion title="Start succeeds but the status takes a moment to update">
Service managers can return before the API server is ready. Wait a few seconds and check the setup card's runtime badge again, or run `hermes gateway status` and test `curl http://127.0.0.1:8642/v1/health`.
</Accordion>
<Accordion title="Image attachments are ignored">
The Hermes provider in EnConvo is currently text-only. EnConvo will not send image attachments to Hermes; choose a vision-capable provider for direct image input.
</Accordion>
<Accordion title="Wrong base URL">
Enter `http://<gateway-host>:8642/v1`. Do not include `/chat/completions` in the EnConvo base URL field.
</Accordion>
<Accordion title="Need gateway logs">
Read Hermes gateway logs with `tail -f ~/.hermes/logs/gateway.log` and errors with `tail -f ~/.hermes/logs/gateway.error.log`.
</Accordion>
</AccordionGroup>
# kimi.ai
Source: https://docs.enconvo.ai/providers/kimi
Connect kimi.ai and choose an AI model in Enconvo.
Use **kimi.ai** as an AI Model provider in Enconvo. The available model list comes from the installed provider and your account access; select a model in the app rather than relying on a fixed list in this guide.
## Connect
1. Open **Settings → Global Providers Settings → AI Model**.
2. Select **kimi.ai**, or use **Add New Provider** to create another profile.
3. Configure the provider’s **Authentication** using your own account or API key, following the available method on that page.
4. Validate the credential if a validation action is offered.
5. Choose the model or deployment, then select this provider in your Agent or conversation and send a short text request.
## Provider options
The provider definition includes: **Model Name**, **Temperature**. Some controls appear only for models or authentication methods that support them.
## Use it in a conversation
Select the model from the conversation’s model menu. Review reasoning and tool support for the selected model before running an Agent task. A text-only request is a useful connection check before adding images, documents, or tools.
Provider profiles share credentials across their supported categories. See [Credentials and Provider Profiles](/configuration/credentials) before renaming, deleting, or changing a shared key.
## Troubleshooting
| Symptom | Check |
| - | - |
| Authentication failure | Correct profile, authentication method, and account access |
| Model unavailable | Current model picker and access granted to your account |
| Tool or image request fails | Selected model capabilities and enabled Agent tools |
| Rate or usage limit | Provider account usage, or Cloud usage if using an Enconvo Cloud provider |
| Slow response | Input size, selected model, reasoning setting, and provider availability |
See the [provider capability catalog](/providers/catalog) for other categories and [Model Selection](/ai/model-selection-guide) for choosing a model by task.
# LM Studio
Source: https://docs.enconvo.ai/providers/lm-studio
Connect Enconvo to LM Studio on your Mac or local network.
Use LM Studio to serve models locally or from another computer on your network. The model server must be running and have a compatible model available.
## Connect on the same Mac
1. Load a model in LM Studio and start its local API server.
2. Open **Settings → AI Model → LM Studio**.
3. Configure its credential/server URL. The default preset uses `http://127.0.0.1:1234/v1`.
4. Select a model from the available list and try a short text-only request.
5. Select that model in an Agent or conversation when you want to use it.
## Connect to another computer
Use the server computer’s LAN address instead of `127.0.0.1` or `localhost`; those names always refer to the computer running Enconvo. Configure the model server to accept connections on its local-network interface, and enable Enconvo under **System Settings → Privacy & Security → Local Network** if macOS blocks access.
Keep the port and API path appropriate to your server. Allow access only on networks and interfaces you intend to use.
## Troubleshooting
| Error | Check |
| - | - |
| Connection refused | Server is running, address/port are correct, and LAN listening is enabled if remote |
| Host/network unreachable | Network reachability and macOS Local Network permission |
| Empty model list | Model is downloaded/loaded and server endpoint is compatible |
| Tool calls or images fail | The selected model supports those capabilities |
| Out of memory | Choose a smaller model or reduce context and concurrent workloads |
Local model inference does not make remote tools offline. See [Local Models](/ai/local-llm) for the full processing chain.
# Minimax AI
Source: https://docs.enconvo.ai/providers/minimax
Connect Minimax AI and choose an AI model in Enconvo.
Use **Minimax AI** as an AI Model provider in Enconvo. The available model list comes from the installed provider and your account access; select a model in the app rather than relying on a fixed list in this guide.
## Connect
1. Open **Settings → Global Providers Settings → AI Model**.
2. Select **Minimax AI**, or use **Add New Provider** to create another profile.
3. Configure the provider’s **Authentication** using your own account or API key, following the available method on that page.
4. Validate the credential if a validation action is offered.
5. Choose the model or deployment, then select this provider in your Agent or conversation and send a short text request.
## Provider options
The provider definition includes: **Model Name**, **Temperature**. Some controls appear only for models or authentication methods that support them.
## Use it in a conversation
Select the model from the conversation’s model menu. Review reasoning and tool support for the selected model before running an Agent task. A text-only request is a useful connection check before adding images, documents, or tools.
Provider profiles share credentials across their supported categories. See [Credentials and Provider Profiles](/configuration/credentials) before renaming, deleting, or changing a shared key.
## Troubleshooting
| Symptom | Check |
| - | - |
| Authentication failure | Correct profile, authentication method, and account access |
| Model unavailable | Current model picker and access granted to your account |
| Tool or image request fails | Selected model capabilities and enabled Agent tools |
| Rate or usage limit | Provider account usage, or Cloud usage if using an Enconvo Cloud provider |
| Slow response | Input size, selected model, reasoning setting, and provider availability |
See the [provider capability catalog](/providers/catalog) for other categories and [Model Selection](/ai/model-selection-guide) for choosing a model by task.
# Mistral AI
Source: https://docs.enconvo.ai/providers/mistral
Connect Mistral AI and choose an AI model in Enconvo.
Use **Mistral AI** as an AI Model provider in Enconvo. The available model list comes from the installed provider and your account access; select a model in the app rather than relying on a fixed list in this guide.
## Connect
1. Open **Settings → Global Providers Settings → AI Model**.
2. Select **Mistral AI**, or use **Add New Provider** to create another profile.
3. Configure the provider’s **Authentication** using your own account or API key, following the available method on that page.
4. Validate the credential if a validation action is offered.
5. Choose the model or deployment, then select this provider in your Agent or conversation and send a short text request.
## Provider options
The provider definition includes: **Model Name**, **Temperature**. Some controls appear only for models or authentication methods that support them.
## Use it in a conversation
Select the model from the conversation’s model menu. Review reasoning and tool support for the selected model before running an Agent task. A text-only request is a useful connection check before adding images, documents, or tools.
Provider profiles share credentials across their supported categories. See [Credentials and Provider Profiles](/configuration/credentials) before renaming, deleting, or changing a shared key.
## Troubleshooting
| Symptom | Check |
| - | - |
| Authentication failure | Correct profile, authentication method, and account access |
| Model unavailable | Current model picker and access granted to your account |
| Tool or image request fails | Selected model capabilities and enabled Agent tools |
| Rate or usage limit | Provider account usage, or Cloud usage if using an Enconvo Cloud provider |
| Slow response | Input size, selected model, reasoning setting, and provider availability |
See the [provider capability catalog](/providers/catalog) for other categories and [Model Selection](/ai/model-selection-guide) for choosing a model by task.
# MLX Local Models
Source: https://docs.enconvo.ai/providers/mlx
Use on-device language models on Apple Silicon.
The **MLX (mlx)** AI Model provider runs supported models on Apple Silicon through Enconvo’s local model runtime.
## Use a local model
1. Open **Settings → AI Model → MLX (mlx)**.
2. Open the model picker and select a supported model.
3. Download the required resources when prompted, allowing enough disk space and memory for the selected model.
4. Wait for setup to complete, then test a short text request.
5. Review **Temperature** and **Reasoning Effort** when supported by the selected model.
Model files need an initial download; subsequent inference uses the local runtime. Model availability and hardware support depend on your build.
## Other local capabilities
Enconvo also includes MLX providers for speech recognition, text-to-speech, embeddings, reranking, and OCR. Each capability has its own model selection. See the [provider catalog](/providers/catalog).
If loading fails, inspect the error, available memory and disk space, and the model’s hardware requirements. Start with a smaller model before increasing context or concurrency.
# Ollama
Source: https://docs.enconvo.ai/providers/ollama
Connect Enconvo to Ollama on your Mac or local network.
Use Ollama to serve models locally or from another computer on your network. The model server must be running and have a compatible model available.
## Connect on the same Mac
1. Start Ollama and download a model using its own model-management tools.
2. Open **Settings → AI Model → Ollama**.
3. Configure its credential/server URL. The default preset uses `http://127.0.0.1:11434`.
4. Select a model from the available list and try a short text-only request.
5. Select that model in an Agent or conversation when you want to use it.
## Connect to another computer
Use the server computer’s LAN address instead of `127.0.0.1` or `localhost`; those names always refer to the computer running Enconvo. Configure the model server to accept connections on its local-network interface, and enable Enconvo under **System Settings → Privacy & Security → Local Network** if macOS blocks access.
Keep the port and API path appropriate to your server. Allow access only on networks and interfaces you intend to use.
## Troubleshooting
| Error | Check |
| - | - |
| Connection refused | Server is running, address/port are correct, and LAN listening is enabled if remote |
| Host/network unreachable | Network reachability and macOS Local Network permission |
| Empty model list | Model is downloaded/loaded and server endpoint is compatible |
| Tool calls or images fail | The selected model supports those capabilities |
| Out of memory | Choose a smaller model or reduce context and concurrent workloads |
Local model inference does not make remote tools offline. See [Local Models](/ai/local-llm) for the full processing chain.
# OpenAI
Source: https://docs.enconvo.ai/providers/openai
Connect OpenAI and choose an AI model in Enconvo.
Use **OpenAI** as an AI Model provider in Enconvo. The available model list comes from the installed provider and your account access; select a model in the app rather than relying on a fixed list in this guide.
## Connect
1. Open **Settings → Global Providers Settings → AI Model**.
2. Select **OpenAI**, or use **Add New Provider** to create another profile.
3. Configure the provider’s **Authentication** using your own account or API key, following the available method on that page.
4. Validate the credential if a validation action is offered.
5. Choose the model or deployment, then select this provider in your Agent or conversation and send a short text request.
## Provider options
Choose **API Key** or **ChatGPT Subscription** in Authentication. With an API key, **API Type** chooses Responses API or Completions API. Keep the default endpoint unless you intentionally use a compatible service. For account access, see [ChatGPT Subscription](/providers/openai_subscription).
The provider definition includes: **Model Name**, **Temperature**. Some controls appear only for models or authentication methods that support them.
## Use it in a conversation
Select the model from the conversation’s model menu. Review reasoning and tool support for the selected model before running an Agent task. A text-only request is a useful connection check before adding images, documents, or tools.
Provider profiles share credentials across their supported categories. See [Credentials and Provider Profiles](/configuration/credentials) before renaming, deleting, or changing a shared key.
## Troubleshooting
| Symptom | Check |
| - | - |
| Authentication failure | Correct profile, authentication method, and account access |
| Model unavailable | Current model picker and access granted to your account |
| Tool or image request fails | Selected model capabilities and enabled Agent tools |
| Rate or usage limit | Provider account usage, or Cloud usage if using an Enconvo Cloud provider |
| Slow response | Input size, selected model, reasoning setting, and provider availability |
See the [provider capability catalog](/providers/catalog) for other categories and [Model Selection](/ai/model-selection-guide) for choosing a model by task.
# ChatGPT Subscription
Source: https://docs.enconvo.ai/providers/openai_subscription
Connect a supported OpenAI account through provider Authentication.
Connect your supported OpenAI account through Enconvo’s provider Authentication controls. Available capabilities and limits depend on your account and the service’s current access rules.
## Connect
1. Open **Settings → AI Model → OpenAI**.
2. In **Authentication**, select **ChatGPT Subscription**.
3. Click **Connect** and complete the account’s sign-in and authorization flow.
4. Return to Enconvo and check that the intended account is connected.
5. Select an available model and try a short request.
## Account status and usage
Use the account card’s menu to **Reconnect** or **Refresh usage** when those actions are available. **% left** describes remaining allowance; a reset countdown indicates when the reported window resets. Unavailable usage data is not a promise of unlimited access.
OpenAI also offers subscription authentication in supported image-generation and transcription providers. Check the Authentication section in that feature; realtime voice access is configured separately.
## Troubleshooting
If sign-in fails, follow the provider’s error and check that you connected the intended account. If a model or capability is unavailable, confirm it appears for that account in the current picker. If a usage window is exhausted, wait for its reported reset or choose another access method you have configured.
A subscription connection is distinct from an API key. Switching Authentication changes the access method used by that provider. See [Credentials](/configuration/credentials) for shared profiles and [Pricing](/pricing) for the difference between app licensing, Cloud usage, and provider billing.
# OpenClaw
Source: https://docs.enconvo.ai/providers/openclaw
Use OpenClaw agents as OpenAI-compatible models in EnConvo
## Overview
OpenClaw is a self-hosted AI agent platform for running assistants across chat, messaging channels, tools, skills, and automations.
OpenClaw can expose its agents through an OpenAI-compatible Gateway. After you enable the Gateway, EnConvo can use an OpenClaw agent like any other AI model, including inside chat, EnConvo agents, and model-powered features.
OpenClaw's Gateway exposes OpenAI-compatible endpoints such as `/v1/models`, `/v1/chat/completions`, and `/v1/responses`. EnConvo's OpenClaw provider uses the Chat Completions API (`/v1/chat/completions`).
<Note>
EnConvo does not use the OpenClaw Responses API for this provider. Configure OpenClaw through its OpenAI-compatible Chat Completions Gateway.
</Note>
<Tip>
New to OpenClaw? Start with the [OpenClaw Getting Started guide](https://docs.openclaw.ai/start/getting-started), then return here to connect it to EnConvo.
</Tip>
<Tip>
See the [OpenClaw Gateway docs](https://docs.openclaw.ai/gateway#openai-compatible-endpoints) for the full Gateway endpoint reference.
</Tip>
## What You Need
* OpenClaw installed on the machine that will run the Gateway
* The OpenClaw Gateway running on a reachable host and port
* The Chat Completions Gateway endpoint enabled
* The Gateway token from `~/.openclaw/openclaw.json`
* EnConvo with the OpenClaw AI model provider enabled
## Automatic Setup in EnConvo
Open EnConvo **Settings** -> **AI Model** -> **OpenClaw**. The setup card can start, stop, and configure the local OpenClaw Gateway for you.
Use **Auto Setup** when OpenClaw is installed on the same Mac as EnConvo. EnConvo will:
<Steps>
<Step title="Find OpenClaw">
Check that the `openclaw` CLI exists on this Mac.
</Step>
<Step title="Enable Chat Completions">
Run `openclaw config set gateway.http.endpoints.chatCompletions.enabled true`.
</Step>
<Step title="Prepare the Gateway token">
Read `gateway.auth.token` from `~/.openclaw/openclaw.json`, or create one if it is missing.
</Step>
<Step title="Start the Gateway">
Start or restart the OpenClaw Gateway service.
</Step>
<Step title="Verify the API">
Probe the Gateway with `/health` and `/v1/models`.
</Step>
<Step title="Save credentials">
Save the base URL and Gateway token into EnConvo's OpenClaw credentials.
</Step>
</Steps>
The setup card shows a runtime badge such as **Running** or **Stopped**. While the card is visible, EnConvo refreshes this status periodically and stops refreshing when the card is no longer visible.
## Enable OpenClaw Gateway
You can ask OpenClaw to prepare the Gateway details for you:
```text theme={null}
enable openai-compatible api and give me the token and baseurl
```
Use the returned base URL and token in EnConvo's OpenClaw credential settings.
<Steps>
<Step title="Enable Chat Completions">
Enable the OpenAI-compatible chat completions endpoint once:
```bash theme={null}
openclaw config set gateway.http.endpoints.chatCompletions.enabled true
```
</Step>
<Step title="Choose the bind mode">
For local-only access, keep the default loopback bind. For another device on your LAN to reach the Gateway, bind to LAN:
```bash theme={null}
openclaw config set gateway.bind lan
```
</Step>
<Step title="Restart the Gateway">
Apply the configuration change:
```bash theme={null}
openclaw gateway restart
```
</Step>
<Step title="Check Gateway status">
Confirm the Gateway is running:
```bash theme={null}
openclaw gateway status
```
</Step>
</Steps>
## Configure OpenClaw in EnConvo
Open EnConvo **Settings** -> **AI Model** -> **OpenClaw**, then configure the credential provider.
<img alt="OpenClaw credential settings in EnConvo" />
| Setting | Value |
| - | - |
| **OpenClaw Base URL** | `http://<gateway-host>:<port>/v1` |
| **Gateway Token** | `gateway.auth.token` from `~/.openclaw/openclaw.json` |
EnConvo uses the Chat Completions API for OpenClaw automatically.
<Warning>
Use the base URL ending in `/v1`, not the full `/v1/chat/completions` endpoint. For example, if your endpoint is `http://192.168.1.18:18789/v1/chat/completions`, enter `http://192.168.1.18:18789/v1`.
</Warning>
To read the Gateway token from the default OpenClaw config file:
```bash theme={null}
jq -r '.gateway.auth.token' ~/.openclaw/openclaw.json
```
EnConvo sends this value as:
```http theme={null}
Authorization: Bearer <gateway-token>
```
Click **Validate** after entering the base URL and token.
## API Behavior and Attachments
EnConvo sends OpenClaw requests through OpenAI-compatible Chat Completions:
```http theme={null}
POST /v1/chat/completions
```
Use `openclaw:main` or another model name advertised by your OpenClaw agent list.
<Warning>
Image attachments are not sent to OpenClaw by EnConvo. Treat the OpenClaw provider as a text/chat provider in EnConvo. For image workflows, use a vision-capable model provider or run OCR/image analysis before sending text to OpenClaw.
</Warning>
## Use OpenClaw as an AI Model
Once configured, OpenClaw appears in the model selector. Choose **OpenClaw** and select the agent-backed model, such as `openclaw:main`.
<img alt="OpenClaw selected as the chat model" />
Use this mode when you want an EnConvo conversation, command, or feature to run through an OpenClaw agent while keeping the normal EnConvo interface.
<Steps>
<Step title="Open the model picker">
In chat or another model-powered EnConvo feature, click the current model name.
</Step>
<Step title="Choose OpenClaw">
Select **OpenClaw** in the provider list.
<img alt="OpenClaw in the model selector" />
</Step>
<Step title="Select an OpenClaw agent model">
Choose `openclaw:main` or another OpenClaw agent from the model list.
</Step>
<Step title="Run the feature normally">
Ask your question or run the EnConvo feature. The selected OpenClaw agent handles the model call behind the scenes.
</Step>
</Steps>
<Note>
EnConvo loads OpenClaw models from `openclaw agents list`. If the OpenClaw CLI is not available locally, EnConvo falls back to `openclaw:main`.
</Note>
## Create an EnConvo Agent for OpenClaw
You can also create an EnConvo agent that coordinates an OpenClaw agent. This is useful when you want an EnConvo-facing workflow, tool set, or prompt around a specific OpenClaw agent.
<Steps>
<Step title="Open Create Agent">
Open SmartBar and search for **Create Agent**.
<img alt="Create Agent command in EnConvo" />
</Step>
<Step title="Name the agent">
Create a clear title, such as `OpenClaw Main`.
<img alt="Create New Agent form for OpenClaw" />
</Step>
<Step title="Write coordinator instructions">
Give the EnConvo agent instructions that explain how it should work with OpenClaw.
```markdown theme={null}
You coordinate the OpenClaw Main agent for the user.
Use OpenClaw for agentic work, automation, and tasks that should run through the user's OpenClaw setup.
Summarize what OpenClaw did, surface any blockers, and ask before destructive or irreversible actions.
```
</Step>
<Step title="Choose the OpenClaw model">
In the agent's model settings, select **OpenClaw** and choose `openclaw:main`.
</Step>
<Step title="Save and use the agent">
Start a conversation with the new EnConvo agent. It will use the selected OpenClaw agent model while retaining the EnConvo agent interface and tools you configured.
</Step>
</Steps>
## Troubleshooting
<AccordionGroup>
<Accordion title="OpenClaw does not appear in the model picker">
Make sure the OpenClaw provider is enabled in **Settings** -> **AI Model**. If the model list is empty, verify that `openclaw agents list` works locally or use the default `openclaw:main`.
</Accordion>
<Accordion title="Validation fails with unauthorized">
Recheck the Gateway token. EnConvo expects the value from `gateway.auth.token` and sends it as a Bearer token.
</Accordion>
<Accordion title="Connection fails">
Confirm the Gateway is running with `openclaw gateway status`. If EnConvo is on another device, set `gateway.bind` to `lan`, restart the Gateway, and use the host's LAN IP in the base URL.
</Accordion>
<Accordion title="Start succeeds but EnConvo briefly says it needs attention">
OpenClaw can report that the LaunchAgent restarted before the HTTP Gateway is ready. Wait a few seconds and check the setup card's runtime badge again. You can also verify directly with `openclaw gateway status` and `curl http://127.0.0.1:18789/health`.
</Accordion>
<Accordion title="The Gateway is running but `/v1/models` fails">
Make sure EnConvo is using the same token as `gateway.auth.token` in `~/.openclaw/openclaw.json`. The setup status can still detect a running Gateway through `/health`, but model validation requires the bearer token.
</Accordion>
<Accordion title="Image attachments are ignored">
The OpenClaw provider in EnConvo is currently text-only. EnConvo will not send image attachments to OpenClaw; choose a vision-capable provider for direct image input.
</Accordion>
<Accordion title="Wrong base URL">
Enter `http://<gateway-host>:<port>/v1`. Do not include `/chat/completions` in the EnConvo base URL field.
</Accordion>
</AccordionGroup>
# OpenRouter
Source: https://docs.enconvo.ai/providers/openrouter
Connect OpenRouter and choose an AI model in Enconvo.
Use **OpenRouter** as an AI Model provider in Enconvo. The available model list comes from the installed provider and your account access; select a model in the app rather than relying on a fixed list in this guide.
## Connect
1. Open **Settings → Global Providers Settings → AI Model**.
2. Select **OpenRouter**, or use **Add New Provider** to create another profile.
3. Configure the provider’s **Authentication** using your own account or API key, following the available method on that page.
4. Validate the credential if a validation action is offered.
5. Choose the model or deployment, then select this provider in your Agent or conversation and send a short text request.
## Provider options
The model picker lists models available through OpenRouter. Image and video generation have their own OpenRouter providers in their respective settings categories. Features such as tool use and image input depend on the selected model.
The provider definition includes: **Model Name**, **Temperature**, **Google Search Tool**, **URL Context Tool**. Some controls appear only for models or authentication methods that support them.
## Use it in a conversation
Select the model from the conversation’s model menu. Review reasoning and tool support for the selected model before running an Agent task. A text-only request is a useful connection check before adding images, documents, or tools.
Provider profiles share credentials across their supported categories. See [Credentials and Provider Profiles](/configuration/credentials) before renaming, deleting, or changing a shared key.
## Troubleshooting
| Symptom | Check |
| - | - |
| Authentication failure | Correct profile, authentication method, and account access |
| Model unavailable | Current model picker and access granted to your account |
| Tool or image request fails | Selected model capabilities and enabled Agent tools |
| Rate or usage limit | Provider account usage, or Cloud usage if using an Enconvo Cloud provider |
| Slow response | Input size, selected model, reasoning setting, and provider availability |
See the [provider capability catalog](/providers/catalog) for other categories and [Model Selection](/ai/model-selection-guide) for choosing a model by task.
# Providers
Source: https://docs.enconvo.ai/providers/overview
Choose access and configure each AI capability.
A provider connects an Enconvo feature to a model, voice, search service, or local runtime. Start with the capability you need, then choose its access method.
## Choose access
| Access | Guide |
| - | - |
| Enconvo account and Cloud usage | [Enconvo Cloud Plan](/providers/enconvo) |
| Your own provider API key | [Credentials and Provider Profiles](/configuration/credentials) |
| Supported subscription/account sign-in | [ChatGPT](/providers/openai_subscription), [Claude](/providers/anthropic_subscription), [Google Account](/providers/google_subscription) |
| Local inference | [MLX](/providers/mlx), [Ollama](/providers/ollama), [LM Studio](/providers/lm-studio) |
| External Agent gateway | [OpenClaw](/providers/openclaw), [Hermes](/providers/hermes) |
## Configure the feature you use
Open **Settings → Global Providers Settings** for AI Model, Text-to-Speech, Web Search, Image Generation, Video Generation, Web Fetch, and OCR. Speech recognition has separate provider settings for Dictation, Recording, Transcription, and Captioning. Embedding and reranking choices belong to knowledge-base configuration.
The [Provider Capability Catalog](/providers/catalog) lists every declared provider in these categories. Selecting a chat model does not automatically configure your speech, image, or retrieval provider.
## Profiles and defaults
Create additional profiles when you need separate keys or accounts for the same provider. A profile shares credentials across supported feature categories, so changing it can affect more than one feature. Model choices remain specific to the capability and conversation.
See [Model Selection](/ai/model-selection-guide) for Agent, project, and per-chat defaults. Test a short request after setup before moving to a large document or generation task.
# Perplexity
Source: https://docs.enconvo.ai/providers/perplexity
Connect Perplexity and choose an AI model in Enconvo.
Use **Perplexity** as an AI Model provider in Enconvo. The available model list comes from the installed provider and your account access; select a model in the app rather than relying on a fixed list in this guide.
## Connect
1. Open **Settings → Global Providers Settings → AI Model**.
2. Select **Perplexity**, or use **Add New Provider** to create another profile.
3. Configure the provider’s **Authentication** using your own account or API key, following the available method on that page.
4. Validate the credential if a validation action is offered.
5. Choose the model or deployment, then select this provider in your Agent or conversation and send a short text request.
## Provider options
Select the model in the Perplexity AI Model provider. This is separate from the general Web Search provider setting. Inspect returned sources when relying on an answer about current information.
The provider definition includes: **Model Name**, **Temperature**. Some controls appear only for models or authentication methods that support them.
## Use it in a conversation
Select the model from the conversation’s model menu. Review reasoning and tool support for the selected model before running an Agent task. A text-only request is a useful connection check before adding images, documents, or tools.
Provider profiles share credentials across their supported categories. See [Credentials and Provider Profiles](/configuration/credentials) before renaming, deleting, or changing a shared key.
## Troubleshooting
| Symptom | Check |
| - | - |
| Authentication failure | Correct profile, authentication method, and account access |
| Model unavailable | Current model picker and access granted to your account |
| Tool or image request fails | Selected model capabilities and enabled Agent tools |
| Rate or usage limit | Provider account usage, or Cloud usage if using an Enconvo Cloud provider |
| Slow response | Input size, selected model, reasoning setting, and provider availability |
See the [provider capability catalog](/providers/catalog) for other categories and [Model Selection](/ai/model-selection-guide) for choosing a model by task.
# Phala
Source: https://docs.enconvo.ai/providers/phala
Connect Phala and choose an AI model in Enconvo.
Use **Phala** as an AI Model provider in Enconvo. The available model list comes from the installed provider and your account access; select a model in the app rather than relying on a fixed list in this guide.
## Connect
1. Open **Settings → Global Providers Settings → AI Model**.
2. Select **Phala**, or use **Add New Provider** to create another profile.
3. Configure the provider’s **Authentication** using your own account or API key, following the available method on that page.
4. Validate the credential if a validation action is offered.
5. Choose the model or deployment, then select this provider in your Agent or conversation and send a short text request.
## Provider options
Use a Phala Confidential AI API key. Credential validation can send a minimal model request. The preset manages its endpoint; do not assume a model supports vision or tools just because another model in the provider does.
The provider definition includes: **Model Name**, **Temperature**. Some controls appear only for models or authentication methods that support them.
## Use it in a conversation
Select the model from the conversation’s model menu. Review reasoning and tool support for the selected model before running an Agent task. A text-only request is a useful connection check before adding images, documents, or tools.
Provider profiles share credentials across their supported categories. See [Credentials and Provider Profiles](/configuration/credentials) before renaming, deleting, or changing a shared key.
## Troubleshooting
| Symptom | Check |
| - | - |
| Authentication failure | Correct profile, authentication method, and account access |
| Model unavailable | Current model picker and access granted to your account |
| Tool or image request fails | Selected model capabilities and enabled Agent tools |
| Rate or usage limit | Provider account usage, or Cloud usage if using an Enconvo Cloud provider |
| Slow response | Input size, selected model, reasoning setting, and provider availability |
See the [provider capability catalog](/providers/catalog) for other categories and [Model Selection](/ai/model-selection-guide) for choosing a model by task.
# Poe
Source: https://docs.enconvo.ai/providers/poe
Connect Poe and choose an AI model in Enconvo.
Use **Poe** as an AI Model provider in Enconvo. The available model list comes from the installed provider and your account access; select a model in the app rather than relying on a fixed list in this guide.
## Connect
1. Open **Settings → Global Providers Settings → AI Model**.
2. Select **Poe**, or use **Add New Provider** to create another profile.
3. Configure the provider’s **Authentication** using your own account or API key, following the available method on that page.
4. Validate the credential if a validation action is offered.
5. Choose the model or deployment, then select this provider in your Agent or conversation and send a short text request.
## Provider options
The provider definition includes: **Model Name**, **Temperature**. Some controls appear only for models or authentication methods that support them.
## Use it in a conversation
Select the model from the conversation’s model menu. Review reasoning and tool support for the selected model before running an Agent task. A text-only request is a useful connection check before adding images, documents, or tools.
Provider profiles share credentials across their supported categories. See [Credentials and Provider Profiles](/configuration/credentials) before renaming, deleting, or changing a shared key.
## Troubleshooting
| Symptom | Check |
| - | - |
| Authentication failure | Correct profile, authentication method, and account access |
| Model unavailable | Current model picker and access granted to your account |
| Tool or image request fails | Selected model capabilities and enabled Agent tools |
| Rate or usage limit | Provider account usage, or Cloud usage if using an Enconvo Cloud provider |
| Slow response | Input size, selected model, reasoning setting, and provider availability |
See the [provider capability catalog](/providers/catalog) for other categories and [Model Selection](/ai/model-selection-guide) for choosing a model by task.
# Qwen
Source: https://docs.enconvo.ai/providers/qwen
Connect Qwen and choose an AI model in Enconvo.
Use **Qwen** as an AI Model provider in Enconvo. The available model list comes from the installed provider and your account access; select a model in the app rather than relying on a fixed list in this guide.
## Connect
1. Open **Settings → Global Providers Settings → AI Model**.
2. Select **Qwen**, or use **Add New Provider** to create another profile.
3. Configure the provider’s **Authentication** using your own account or API key, following the available method on that page.
4. Validate the credential if a validation action is offered.
5. Choose the model or deployment, then select this provider in your Agent or conversation and send a short text request.
## Provider options
The current Qwen AI Model provider uses API-key authentication. Qwen OAuth sign-in is temporarily unavailable. Choose the endpoint and account appropriate to the service you use.
The provider definition includes: **Model Name**, **Temperature**. Some controls appear only for models or authentication methods that support them.
## Use it in a conversation
Select the model from the conversation’s model menu. Review reasoning and tool support for the selected model before running an Agent task. A text-only request is a useful connection check before adding images, documents, or tools.
Provider profiles share credentials across their supported categories. See [Credentials and Provider Profiles](/configuration/credentials) before renaming, deleting, or changing a shared key.
## Troubleshooting
| Symptom | Check |
| - | - |
| Authentication failure | Correct profile, authentication method, and account access |
| Model unavailable | Current model picker and access granted to your account |
| Tool or image request fails | Selected model capabilities and enabled Agent tools |
| Rate or usage limit | Provider account usage, or Cloud usage if using an Enconvo Cloud provider |
| Slow response | Input size, selected model, reasoning setting, and provider availability |
See the [provider capability catalog](/providers/catalog) for other categories and [Model Selection](/ai/model-selection-guide) for choosing a model by task.
# Sambanova AI
Source: https://docs.enconvo.ai/providers/sambanova
Connect Sambanova AI and choose an AI model in Enconvo.
Use **Sambanova AI** as an AI Model provider in Enconvo. The available model list comes from the installed provider and your account access; select a model in the app rather than relying on a fixed list in this guide.
## Connect
1. Open **Settings → Global Providers Settings → AI Model**.
2. Select **Sambanova AI**, or use **Add New Provider** to create another profile.
3. Configure the provider’s **Authentication** using your own account or API key, following the available method on that page.
4. Validate the credential if a validation action is offered.
5. Choose the model or deployment, then select this provider in your Agent or conversation and send a short text request.
## Provider options
The provider definition includes: **Model Name**, **Temperature**. Some controls appear only for models or authentication methods that support them.
## Use it in a conversation
Select the model from the conversation’s model menu. Review reasoning and tool support for the selected model before running an Agent task. A text-only request is a useful connection check before adding images, documents, or tools.
Provider profiles share credentials across their supported categories. See [Credentials and Provider Profiles](/configuration/credentials) before renaming, deleting, or changing a shared key.
## Troubleshooting
| Symptom | Check |
| - | - |
| Authentication failure | Correct profile, authentication method, and account access |
| Model unavailable | Current model picker and access granted to your account |
| Tool or image request fails | Selected model capabilities and enabled Agent tools |
| Rate or usage limit | Provider account usage, or Cloud usage if using an Enconvo Cloud provider |
| Slow response | Input size, selected model, reasoning setting, and provider availability |
See the [provider capability catalog](/providers/catalog) for other categories and [Model Selection](/ai/model-selection-guide) for choosing a model by task.
# SiliconFlow
Source: https://docs.enconvo.ai/providers/siliconflow
Connect SiliconFlow and choose an AI model in Enconvo.
Use **SiliconFlow** as an AI Model provider in Enconvo. The available model list comes from the installed provider and your account access; select a model in the app rather than relying on a fixed list in this guide.
## Connect
1. Open **Settings → Global Providers Settings → AI Model**.
2. Select **SiliconFlow**, or use **Add New Provider** to create another profile.
3. Configure the provider’s **Authentication** using your own account or API key, following the available method on that page.
4. Validate the credential if a validation action is offered.
5. Choose the model or deployment, then select this provider in your Agent or conversation and send a short text request.
## Provider options
The provider definition includes: **Model Name**, **Temperature**. Some controls appear only for models or authentication methods that support them.
## Use it in a conversation
Select the model from the conversation’s model menu. Review reasoning and tool support for the selected model before running an Agent task. A text-only request is a useful connection check before adding images, documents, or tools.
Provider profiles share credentials across their supported categories. See [Credentials and Provider Profiles](/configuration/credentials) before renaming, deleting, or changing a shared key.
## Troubleshooting
| Symptom | Check |
| - | - |
| Authentication failure | Correct profile, authentication method, and account access |
| Model unavailable | Current model picker and access granted to your account |
| Tool or image request fails | Selected model capabilities and enabled Agent tools |
| Rate or usage limit | Provider account usage, or Cloud usage if using an Enconvo Cloud provider |
| Slow response | Input size, selected model, reasoning setting, and provider availability |
See the [provider capability catalog](/providers/catalog) for other categories and [Model Selection](/ai/model-selection-guide) for choosing a model by task.
# Soniox
Source: https://docs.enconvo.ai/providers/soniox
Configure Soniox speech-to-text in EnConvo
## Overview
Soniox is a cloud speech platform for speech-to-text, speech translation, and text-to-speech. In EnConvo, Soniox is available as a speech recognition provider for dictation and audio/video transcription.
Soniox is useful when you need high-accuracy multilingual transcription, real-time dictation, speaker diarization, and automatic language detection through your own Soniox API key.
## Supported Models
| Model | Mode | Best For |
| - | - | - |
| **Soniox STT Realtime v5** | Real-time | Low-latency dictation and live speech input |
| **Soniox STT Async v5** | File-based | Audio/video file transcription and longer recordings |
<Note>
Real-time dictation uses EnConvo's macOS realtime client with Soniox's WebSocket STT API. File transcription uses Soniox's async transcription API.
</Note>
## Setup
<Steps>
<Step title="Create a Soniox API key">
1. Go to the [Soniox Console](https://console.soniox.com)
2. Sign in or create a Soniox account
3. Open your project
4. Create an API key
</Step>
<Step title="Configure credentials in EnConvo">
1. Open **Settings** -> **Credentials**
2. Select **Soniox**
3. Paste your Soniox API key
4. Validate and save the credential
</Step>
<Step title="Select Soniox for dictation">
1. Open **Settings** -> **Dictation**
2. Set the dictation provider to **Soniox**
3. Choose **Soniox STT Realtime v5** for real-time voice input
4. Set **Language** to **Auto** or pick a specific language
</Step>
<Step title="Use Soniox for file transcription">
In the **Transcribe Audio/Video files** command, select **Soniox** and use **Soniox STT Async v5** for file-based transcription.
</Step>
</Steps>
## Configuration
| Setting | Description | Default |
| - | - | - |
| **Credential Provider** | Soniox API key stored in EnConvo Credentials | Soniox |
| **Model** | Realtime or async STT model | Soniox STT Realtime v5 |
| **Language** | Auto detection or a language hint | Auto |
| **Speaker Diarization** | Separate speakers when the workflow supports diarization | Available |
| **Punctuation** | Automatic punctuation in recognized text | Enabled |
## Validate and Use
<Steps>
<Step title="Validate the API key">
Click **Validate** in the Soniox credential settings. If validation fails, confirm the key belongs to the correct Soniox project and has not been revoked.
</Step>
<Step title="Test dictation">
For live speech input, run a short dictation test with **Soniox STT Realtime v5** before using it in longer sessions.
</Step>
<Step title="Test file transcription">
For audio or video files, test a short clear recording with **Soniox STT Async v5** before processing long recordings.
</Step>
</Steps>
## Choosing a Model
<AccordionGroup>
<Accordion title="Use Realtime v4 for dictation">
Choose **Soniox STT Realtime v5** when you want text to appear during live voice input. This is the best fit for Dictation, SmartBar voice input, Chat Window voice input, and short spoken commands.
</Accordion>
<Accordion title="Use Async v4 for files">
Choose **Soniox STT Async v5** for recorded audio/video files, longer clips, and workflows where EnConvo transcribes after the recording is complete.
</Accordion>
<Accordion title="Use Auto language detection for multilingual speech">
Set **Language** to **Auto** if you switch languages or do not know the source language. Pick a specific language when the recording is mostly one language and you want more predictable recognition.
</Accordion>
</AccordionGroup>
## Privacy
Soniox is a cloud provider. Audio sent through the Soniox provider is processed by Soniox over the network using your Soniox account and API key.
For fully offline transcription, use a local provider such as Parakeet MLX, Qwen MLX, or Whisper MLX instead.
## Troubleshooting
<AccordionGroup>
<Accordion title="Invalid API key">
* Verify the key was copied from the Soniox Console without extra spaces
* Check that the key belongs to the project you want to use
* Regenerate the key in Soniox and update the EnConvo credential
</Accordion>
<Accordion title="Dictation is not real-time">
* Confirm the selected model is **Soniox STT Realtime v5**
* Confirm the provider is **Soniox**, not another batch transcription provider
* Restart dictation after changing provider or model settings
* If you still see v4 model names, update EnConvo and reopen the provider settings
</Accordion>
<Accordion title="Transcription language is wrong">
* Set **Language** to a specific language instead of **Auto**
* Check that the selected language is supported by Soniox
* For mixed-language audio, switch back to **Auto**
</Accordion>
<Accordion title="No transcript from an audio file">
* Try a common format such as MP3, WAV, FLAC, or M4A
* Confirm the recording contains clear speech
* Check your Soniox account usage, quota, and billing status
</Accordion>
</AccordionGroup>
## Related
<CardGroup>
<Card title="Speech Recognition" icon="microphone" href="/ai/speech-recognition">
Compare Soniox with other speech-to-text providers.
</Card>
<Card title="Dictation" icon="keyboard" href="/features/dictation">
Use Soniox for voice-to-text input.
</Card>
</CardGroup>
# Together AI
Source: https://docs.enconvo.ai/providers/together-ai
Connect Together AI and choose an AI model in Enconvo.
Use **Together AI** as an AI Model provider in Enconvo. The available model list comes from the installed provider and your account access; select a model in the app rather than relying on a fixed list in this guide.
## Connect
1. Open **Settings → Global Providers Settings → AI Model**.
2. Select **Together AI**, or use **Add New Provider** to create another profile.
3. Configure the provider’s **Authentication** using your own account or API key, following the available method on that page.
4. Validate the credential if a validation action is offered.
5. Choose the model or deployment, then select this provider in your Agent or conversation and send a short text request.
## Provider options
The provider definition includes: **Model Name**, **Temperature**. Some controls appear only for models or authentication methods that support them.
## Use it in a conversation
Select the model from the conversation’s model menu. Review reasoning and tool support for the selected model before running an Agent task. A text-only request is a useful connection check before adding images, documents, or tools.
Provider profiles share credentials across their supported categories. See [Credentials and Provider Profiles](/configuration/credentials) before renaming, deleting, or changing a shared key.
## Troubleshooting
| Symptom | Check |
| - | - |
| Authentication failure | Correct profile, authentication method, and account access |
| Model unavailable | Current model picker and access granted to your account |
| Tool or image request fails | Selected model capabilities and enabled Agent tools |
| Rate or usage limit | Provider account usage, or Cloud usage if using an Enconvo Cloud provider |
| Slow response | Input size, selected model, reasoning setting, and provider availability |
See the [provider capability catalog](/providers/catalog) for other categories and [Model Selection](/ai/model-selection-guide) for choosing a model by task.
# Vercel AI Gateway
Source: https://docs.enconvo.ai/providers/vercel-ai-gateway
Connect Vercel AI Gateway and choose an AI model in Enconvo.
Use **Vercel AI Gateway** as an AI Model provider in Enconvo. The available model list comes from the installed provider and your account access; select a model in the app rather than relying on a fixed list in this guide.
## Connect
1. Open **Settings → Global Providers Settings → AI Model**.
2. Select **Vercel AI Gateway**, or use **Add New Provider** to create another profile.
3. Configure the provider’s **Authentication** using your own account or API key, following the available method on that page.
4. Validate the credential if a validation action is offered.
5. Choose the model or deployment, then select this provider in your Agent or conversation and send a short text request.
## Provider options
Use the gateway’s credential and select the routed model. Model capabilities, account access, and billing follow the selected route. Google Search Tool and URL Context Tool are available only on compatible models.
The provider definition includes: **Model Name**, **Temperature**, **Google Search Tool**, **URL Context Tool**. Some controls appear only for models or authentication methods that support them.
## Use it in a conversation
Select the model from the conversation’s model menu. Review reasoning and tool support for the selected model before running an Agent task. A text-only request is a useful connection check before adding images, documents, or tools.
Provider profiles share credentials across their supported categories. See [Credentials and Provider Profiles](/configuration/credentials) before renaming, deleting, or changing a shared key.
## Troubleshooting
| Symptom | Check |
| - | - |
| Authentication failure | Correct profile, authentication method, and account access |
| Model unavailable | Current model picker and access granted to your account |
| Tool or image request fails | Selected model capabilities and enabled Agent tools |
| Rate or usage limit | Provider account usage, or Cloud usage if using an Enconvo Cloud provider |
| Slow response | Input size, selected model, reasoning setting, and provider availability |
See the [provider capability catalog](/providers/catalog) for other categories and [Model Selection](/ai/model-selection-guide) for choosing a model by task.
# X.AI-GROK
Source: https://docs.enconvo.ai/providers/xai
Connect X.AI-GROK and choose an AI model in Enconvo.
Use **X.AI-GROK** as an AI Model provider in Enconvo. The available model list comes from the installed provider and your account access; select a model in the app rather than relying on a fixed list in this guide.
## Connect
1. Open **Settings → Global Providers Settings → AI Model**.
2. Select **X.AI-GROK**, or use **Add New Provider** to create another profile.
3. Configure the provider’s **Authentication** using your own account or API key, following the available method on that page.
4. Validate the credential if a validation action is offered.
5. Choose the model or deployment, then select this provider in your Agent or conversation and send a short text request.
## Provider options
The provider offers **API Key** and **Grok Subscription** authentication in supported categories. xAI also has separate providers for image, video, speech, and X Search; configure each capability in its own category.
The provider definition includes: **Model Name**, **Temperature**. Some controls appear only for models or authentication methods that support them.
## Use it in a conversation
Select the model from the conversation’s model menu. Review reasoning and tool support for the selected model before running an Agent task. A text-only request is a useful connection check before adding images, documents, or tools.
Provider profiles share credentials across their supported categories. See [Credentials and Provider Profiles](/configuration/credentials) before renaming, deleting, or changing a shared key.
## Troubleshooting
| Symptom | Check |
| - | - |
| Authentication failure | Correct profile, authentication method, and account access |
| Model unavailable | Current model picker and access granted to your account |
| Tool or image request fails | Selected model capabilities and enabled Agent tools |
| Rate or usage limit | Provider account usage, or Cloud usage if using an Enconvo Cloud provider |
| Slow response | Input size, selected model, reasoning setting, and provider availability |
See the [provider capability catalog](/providers/catalog) for other categories and [Model Selection](/ai/model-selection-guide) for choosing a model by task.
# Xiaomi MiMo
Source: https://docs.enconvo.ai/providers/xiaomi-mimo
Connect Xiaomi MiMo and choose an AI model in Enconvo.
Use **Xiaomi MiMo** as an AI Model provider in Enconvo. The available model list comes from the installed provider and your account access; select a model in the app rather than relying on a fixed list in this guide.
## Connect
1. Open **Settings → Global Providers Settings → AI Model**.
2. Select **Xiaomi MiMo**, or use **Add New Provider** to create another profile.
3. Configure the provider’s **Authentication** using your own account or API key, following the available method on that page.
4. Validate the credential if a validation action is offered.
5. Choose the model or deployment, then select this provider in your Agent or conversation and send a short text request.
## Provider options
The provider definition includes: **Model Name**, **Temperature**. Some controls appear only for models or authentication methods that support them.
## Use it in a conversation
Select the model from the conversation’s model menu. Review reasoning and tool support for the selected model before running an Agent task. A text-only request is a useful connection check before adding images, documents, or tools.
Provider profiles share credentials across their supported categories. See [Credentials and Provider Profiles](/configuration/credentials) before renaming, deleting, or changing a shared key.
## Troubleshooting
| Symptom | Check |
| - | - |
| Authentication failure | Correct profile, authentication method, and account access |
| Model unavailable | Current model picker and access granted to your account |
| Tool or image request fails | Selected model capabilities and enabled Agent tools |
| Rate or usage limit | Provider account usage, or Cloud usage if using an Enconvo Cloud provider |
| Slow response | Input size, selected model, reasoning setting, and provider availability |
See the [provider capability catalog](/providers/catalog) for other categories and [Model Selection](/ai/model-selection-guide) for choosing a model by task.
# Z.AI
Source: https://docs.enconvo.ai/providers/z-ai
Connect Z.AI and choose an AI model in Enconvo.
Use **Z.AI** as an AI Model provider in Enconvo. The available model list comes from the installed provider and your account access; select a model in the app rather than relying on a fixed list in this guide.
## Connect
1. Open **Settings → Global Providers Settings → AI Model**.
2. Select **Z.AI**, or use **Add New Provider** to create another profile.
3. Configure the provider’s **Authentication** using your own account or API key, following the available method on that page.
4. Validate the credential if a validation action is offered.
5. Choose the model or deployment, then select this provider in your Agent or conversation and send a short text request.
## Provider options
The provider definition includes: **Model Name**, **Temperature**. Some controls appear only for models or authentication methods that support them.
## Use it in a conversation
Select the model from the conversation’s model menu. Review reasoning and tool support for the selected model before running an Agent task. A text-only request is a useful connection check before adding images, documents, or tools.
Provider profiles share credentials across their supported categories. See [Credentials and Provider Profiles](/configuration/credentials) before renaming, deleting, or changing a shared key.
## Troubleshooting
| Symptom | Check |
| - | - |
| Authentication failure | Correct profile, authentication method, and account access |
| Model unavailable | Current model picker and access granted to your account |
| Tool or image request fails | Selected model capabilities and enabled Agent tools |
| Rate or usage limit | Provider account usage, or Cloud usage if using an Enconvo Cloud provider |
| Slow response | Input size, selected model, reasoning setting, and provider availability |
See the [provider capability catalog](/providers/catalog) for other categories and [Model Selection](/ai/model-selection-guide) for choosing a model by task.
# Quick Start
Source: https://docs.enconvo.ai/quickstart
Complete your first Enconvo request and choose your next feature.
## 1. Install and launch
Download Enconvo from [enconvo.com](https://www.enconvo.com), open the DMG, and drag the app into **Applications**. Current builds target **macOS 14 or later**; choose the download for your Mac's processor.
Open the app and grant the [permissions](/configuration/permissions) needed for the features you will use. You can configure screen and microphone access when you first need them.
## 2. Choose AI access
| Option | Setup |
| - | - |
| Enconvo Cloud Plan | Sign in to your Enconvo account and choose a Cloud provider |
| Your own API key | Open **Settings → AI Model**, select a provider, and configure Authentication |
| Supported subscription connection | Choose the subscription/account tab offered by the provider and connect |
| Local models | Configure [Ollama](/providers/ollama), [LM Studio](/providers/lm-studio), or [MLX](/ai/local-llm) |
See your account and the [pricing page](/pricing) for current entitlements and usage. Your model provider's API billing is separate from buying an Enconvo app license.
## 3. Ask a small question
1. Open **SmartBar** using its shortcut, normally **Shift + Command + D**.
2. Type: “Give me a three-item checklist for a productive morning.”
3. Submit and wait for the reply.
4. Review the result and use the response's copy action if you want to keep it.
If nothing happens, check **Settings → Shortcut** and confirm your provider is configured. Shortcuts are customizable.
## 4. Try your own context
Select a short paragraph in another app and try **Summarize** or **Explain** through [PopBar](/features/popbar). For a visible app window, use [Appshots](/features/appshots). Check the captured context before sending it to your model.
## 5. Choose a next step
<CardGroup>
<Card title="Dictation" icon="microphone" href="/features/dictation">Insert spoken text into the app you are using.</Card>
<Card title="Knowledge Base" icon="database" href="/ai/knowledge-base">Add documents and search them in conversation.</Card>
<Card title="Agents" icon="robot" href="/ai/agents">Give an assistant instructions and tools.</Card>
<Card title="All features" icon="list" href="/reference/feature-directory">Find guides, settings, and related capabilities.</Card>
</CardGroup>
# Feature Directory
Source: https://docs.enconvo.ai/reference/feature-directory
Find every user-facing capability by task.
Find a guide by the task you want to complete. Every guide below is also available from the navigation. For individual built-in commands, see the [Command Catalog](/extensions/built-in-extensions); for model, voice, search, and retrieval services, see the [Provider Catalog](/providers/catalog).
New Beta/Dev features may not be available on Production yet. [Check your channel](/configuration/updates) if a documented entry is missing.
## Everyday workspace
| Guide | What you can do |
| - | - |
| [SmartBar](/features/smartbar) | Ask, launch commands, and attach context from anywhere on your Mac. |
| [Chat](/ai/chat) | Manage conversations, projects, context, and model choices. |
| [Dynamic Island](/features/dynamic-island) | Use a compact assistant at the top of your screen. |
| [PopBar](/features/popbar) | Run configurable commands on selected text from a compact toolbar. |
| [App Sidebar](/features/app-sidebar) | Work with an assistant alongside the application or website you are using. |
| [Companion Orb and Desktop Pet](/features/companion-bar) | Find the current replacement for the legacy Companion Orb. |
| [Window Management](/features/window-management) | Choose the Enconvo surface that fits the task and configure its activation. |
| [Desktop Pets](/features/pet) | Keep an animated companion and session cards on your desktop. |
## Voice and recordings
| Guide | What you can do |
| - | - |
| [Dictation and Voice Trigger](/features/dictation) | Insert speech as text or send it to an Agent. |
| [Live Voice](/features/live-voice) | Have a spoken conversation with an Agent and its tools. |
| [Avatars](/features/avatar) | Give an Agent a desktop character and voice. |
| [Meeting Recording](/features/meeting-recording) | Record a meeting, review its transcript, and extract follow-ups. |
| [Transcription](/features/transcription) | Turn an existing audio or video file into a searchable transcript. |
| [Live Captioning](/features/live-captioning) | Read realtime subtitles and revisit captioning sessions. |
| [Voice Notes](/features/voice-notes) | Save a spoken note into a knowledge base. |
| [Speech Recognition](/ai/speech-recognition) | Configure speech models for dictation, recording, files, and captions. |
| [Text-to-Speech](/ai/text-to-speech) | Read text aloud or create an audio file. |
| [Dictionary and Speakers](/configuration/speech-assets) | Maintain recognition vocabulary and speaker names. |
## Context and knowledge
| Guide | What you can do |
| - | - |
| [Context Awareness](/features/context-awareness) | How EnConvo understands your screen and provides relevant assistance |
| [Appshots](/features/appshots) | Attach the frontmost app window to an AI conversation. |
| [Screen Doodle](/features/screen-doodle) | Mark up a screen region and attach it to the Dynamic Island. |
| [Quick Capture](/features/quick-capture) | Save the current app content to a knowledge base. |
| [Knowledge Base](/ai/knowledge-base) | Collect documents, notes, webpages, and linked folders, then use them in conversations. |
| [Memory](/ai/memory) | Review and maintain facts an Agent can reuse. |
| [Web Search](/ai/web-search) | Find current sources and use them in an Agent response. |
| [Read Web Pages](/ai/web-fetch) | Fetch a URL as context or import web material into a knowledge base. |
| [Connect AI Clients to Knowledge Base](/advanced/knowledge-base-mcp) | Let local AI clients search selected Enconvo knowledge bases. |
## Write and create
| Guide | What you can do |
| - | - |
| [Writing Toolkit](/features/writing-tools) | Rewrite, explain, summarize, and transform selected text. |
| [Translation](/ai/translate) | Translate text, screenshots, and dictated input. |
| [OCR](/ai/ocr) | Extract text from images and selected screen regions. |
| [Image Generation](/ai/image-generation) | Generate and edit images with a configured image provider. |
| [Video Generation](/ai/video-generation) | Create video from text or an input image. |
| [Visual Answers](/features/visual-answers) | Ask for diagrams, visual explanations, and interactive widgets in chat. |
| [Files and Folders](/ai/file-tools) | Let an Agent find, read, and edit local files. |
| [Code Runner](/ai/code-runner) | Run shell commands and interact with persistent terminal sessions from an Agent. |
| [Media Utilities](/features/media-tools) | Compress images, video, and audio, or extract a soundtrack. |
| [Quick Links](/features/quick-links) | Open a website or browser search with a command. |
## Agents and automation
| Guide | What you can do |
| - | - |
| [Agents](/ai/agents) | Create an assistant with instructions, models, and tools. |
| [AI Commands](/features/ai-commands) | Save a prompt as a reusable command. |
| [Workflows Introduction](/workflows/introduction) | Build repeatable automations with visual editing, sequential steps, and parallel jobs. |
| [Creating Workflows](/workflows/creating-workflows) | Create and inspect workflows in the Visual editor or YAML, with an editing assistant. |
| [Advanced Workflows](/workflows/advanced-workflows) | Branching, loops, output contracts, subworkflows, per-task models, and complete example workflows |
| [Scheduled Tasks](/workflows/scheduled-jobs) | Have an Agent do something on a schedule, set up by describing it in a chat. |
| [Variables](/workflows/variables) | Insert current input, app context, and dates into reusable prompts. |
| [Skills](/configuration/skills) | Extend EnConvo with task-specific AI capabilities using Agent Skills |
| [Hooks](/configuration/hooks) | Run commands or webhooks automatically when EnConvo events happen |
## Connect tools and apps
| Guide | What you can do |
| - | - |
| [Plugins Overview](/extensions/overview) | Find, install, configure, and use Enconvo plugins. |
| [Built-in Command Catalog](/extensions/built-in-extensions) | Find built-in commands and the guides for their behavior. |
| [MCP (Model Context Protocol)](/features/mcp) | Connect AI to external tools, data sources, and services with MCP servers |
| [Browser Control](/features/browser-control) | Read and operate real browser tabs through the Enconvo Companion extension. |
| [Enconvo Browser Extension](/features/browser-extension) | Use Enconvo with your real browser session for signed-in websites, website approvals, and browser automation |
| [Computer Use](/features/computer-use) | Let EnConvo interact with macOS apps by clicking, typing, scrolling, dragging, and reading app state |
| [Apple Ecosystem Integration](/integrations/apple-ecosystem) | Seamlessly integrate with Apple Mail, Reminders, Calendar, Contacts, Messages, Notes, Maps, and Shortcuts |
| [Gmail Integration](/integrations/gmail) | Read, search, and manage Gmail directly from Enconvo |
| [Messaging Channels](/integrations/messaging) | Connect an Enconvo Agent to Telegram or Discord and control incoming access. |
## Settings and account
| Guide | What you can do |
| - | - |
| [Settings Reference](/configuration/settings-reference) | Find every current settings section and its task guide. |
| [Credentials and Provider Profiles](/configuration/credentials) | Configure API keys, account connections, and shared provider profiles. |
| [macOS Permissions](/configuration/permissions) | Grant the permissions required by the features you use. |
| [Keyboard Shortcuts](/configuration/keyboard-shortcuts) | Find and customize shortcuts without relying on another Mac’s bindings. |
| [Notifications](/configuration/notifications) | Choose how Enconvo tells you an Agent has finished. |
| [Account, Profile, and Usage](/configuration/account) | Manage your Enconvo account and inspect Cloud usage. |
| [Privacy and Security](/configuration/privacy-security) | Understand which data stays local and which services process your requests. |
| [Updates](/configuration/updates) | Choose Production, Beta, or Dev updates and install new EnConvo versions |
| [Plans and Usage](/pricing) | Understand app licensing, Cloud points, and provider billing. |
| [Frequently Asked Questions](/faq) | Find the right feature and resolve common setup questions. |
## Developer resources
[Create an extension](/extensions/developing), [inspect SDK entry points](/extensions/extension-api-reference), or [discover installed CLI/API schemas](/advanced/cli-local-api). Detailed references cover [knowledge-base retrieval](/advanced/knowledge-base-advanced), [MCP](/advanced/mcp-advanced), and [context](/advanced/context-awareness-deep-dive).
# Video Walkthroughs
Source: https://docs.enconvo.ai/reference/video-walkthroughs
Short demonstrations of real Enconvo interface flows.
These walkthroughs show the actual Enconvo interface. Steps are paused for readability, and the accompanying guides contain the same instructions in text. Example drafts are discarded after capture.
## Pair your iPhone
A narrated tutorial: sign in on the iPhone app, show the pairing code on your Mac, scan it, and continue your Mac's chats from your phone.
[Read the guide and watch the video](/integrations/iphone-app).
<Frame>
<img alt="Pair your iPhone" />
</Frame>
## Build your first workflow
A narrated tutorial: create a workflow from the starter template, add a step by hand, let the workflow assistant add another, then run it and inspect every step's output.
[Read the guide and watch the video](/workflows/build-your-first-workflow).
<Frame>
<img alt="Build your first workflow" />
</Frame>
## Schedule a task
Open Scheduled, pick a starter task, look over a task's details, and open its editor. The starter draft is not sent, and the example task was deleted after capture.
[Read the guide and watch the video](/workflows/scheduled-jobs#watch-the-steps).
<Frame>
<img alt="Schedule a task" />
</Frame>
## Browse the Avatar gallery
Switch to Downloaded, search for Tia, inspect Optional downloads, then return to Gallery. No package is downloaded and no assignment is changed.
[Read the guide and watch the video](/features/avatar#watch-the-steps).
<Frame>
<img alt="Browse the Avatar gallery" />
</Frame>
## Prepare dictionary entries
Enter a term and description, switch to Batch add, and enter three example lines. The draft is discarded; no dictionary entry is saved.
[Read the guide and watch the video](/configuration/speech-assets#watch-the-steps).
<Frame>
<img alt="Prepare dictionary entries" />
</Frame>
## Explore the workflow editor
Switch between Visual and YAML, inspect run inputs, and open a step inspector. The workflow is neither changed nor executed.
[Read the guide and watch the video](/workflows/creating-workflows#watch-the-steps).
<Frame>
<img alt="Explore the workflow editor" />
</Frame>
# Advanced Workflows
Source: https://docs.enconvo.ai/workflows/advanced-workflows
Branching, loops, output contracts, subworkflows, per-task models, and complete example workflows
## Overview
This page covers the control-flow and reliability features of the
`agent-workflow/v1` DSL, plus complete examples. Shell paths and tool/provider availability must match your Mac before running them. If
you're new to the DSL, start with [Creating Workflows](/workflows/creating-workflows).
In the Visual editor you don't need to write these by hand: the step inspector's
[Behavior](/workflows/creating-workflows#step-behavior) section sets `if`,
`else_of`, `run_when`, `foreach`, `loop`, `retries`, `required`, `needs`, and the
output schema from plain-language choices.
## Branching
### `if` — conditional tasks
Attach `if:` to run a task only when a condition is true. When the condition is
false, the task **and everything downstream of it** cascade-skip:
```yaml theme={null}
jobs:
main:
steps:
- id: deploy
if: inputs.ready
command: ./deploy.sh
```
Conditions are template expressions evaluated for truthiness — for example
`inputs.score >= 60`, `steps.check.output.exitCode == 0`, or a plain boolean
input.
### `else_of` — the else branch
`else_of:` runs a task only when the referenced task was condition-skipped. It's
the "else" side of an `if`:
```yaml theme={null}
jobs:
main:
steps:
- id: deploy
if: inputs.ready
command: ./deploy.sh
- id: notify_skip
else_of: deploy
command: osascript -e 'display notification "deploy skipped"'
```
### `run_when: always` — join and cleanup
A task with `needs` normally skips if any dependency skipped, and the run stops
if a required dependency fails. `run_when: always` overrides both — the task runs
as long as its dependencies have finished, whether they succeeded, skipped, or
failed. Use it for joins and cleanup:
```yaml theme={null}
jobs:
main:
steps:
- id: build
command: ./build.sh
- id: cleanup
needs:
- build
run_when: always
uses: transform
value: Build finished; inspect its status in Runs.
```
### `enabled: false` — turn a step off
`enabled: false` keeps a step in the workflow but skips it on every run. Unlike
a skipped condition, a step that is off does not skip what comes after it: its
dependents still run, and anything that reads its output gets an empty value.
Its `else_of` step skips too. Remove the key (or set it to `true`) to turn the
step back on. In the editor, use **Turn off step** in the inspector.
```yaml theme={null}
jobs:
main:
steps:
- id: draft
command: ./draft.sh
- id: notify
enabled: false
command: ./notify.sh
- id: publish
command: ./publish.sh
```
## Loops
### `foreach` — fan out over a list
`foreach:` runs the task once per item. Inside, `{{ item }}` is the current
element and `{{ index }}` is its position. Downstream tasks receive the collected
array of outputs:
```yaml theme={null}
inputs:
questions:
type: array
default:
- What is it?
- Why does it matter?
jobs:
main:
steps:
- id: answer
foreach: '{{ inputs.questions }}'
prompt: 'Answer in one sentence: {{ item }}'
- id: digest
uses: transform
value: '{% for a in steps.answer.output %}- {{ a }}
{% endfor %}'
```
`foreach` also accepts an inline array, and it composes with the other executors
(a `foreach` of `tool:` calls, of subworkflows, and so on). An empty list
produces an empty result and downstream tasks still run.
### `loop` — repeat until a condition holds
`loop:` repeats a task. `until:` is checked after each round against `output`
(that round's result); `{{ round }}` is the round number and `{{ last }}` is the
previous round's output. Exhausting `maxRounds` without satisfying `until` fails
the task.
```yaml theme={null}
jobs:
main:
steps:
- id: poll
run: curl -s -o /dev/null -w '%{http_code}' https://example.com/status
loop:
until: output.stdout | trim == '200'
maxRounds: 10
```
Omit `until` to loop a fixed number of times:
```yaml theme={null}
jobs:
main:
steps:
- id: retry_build
command: ./build.sh
loop:
maxRounds: 3
```
## Reliability
* **`retries`** — retry a failed task. Either a count (`retries: 2`) or an object
(`retries: { maxAttempts: 3, delayMs: 500 }`).
* **`required: false`** — a failure of this task does **not** abort the run;
downstream tasks continue.
* **`timeoutMs`** — kill a shell task that runs too long.
```yaml theme={null}
jobs:
main:
steps:
- id: flaky_fetch
tool: web_fetch/web_fetch
params:
link_url: '{{ inputs.url }}'
retries:
maxAttempts: 3
delayMs: 1000
- id: optional_enrich
run: ./enrich.sh || exit 1
required: false
```
## Output contracts
Attach an `output_schema` (a JSON Schema object) to a `prompt` or `agent` task to
enforce the shape of the reply. You do **not** need to describe the JSON format in
the prompt text — the requested shape is provided to the generation step, and the reply is parsed
and validated before downstream steps use it. Configure `retries` to retry a
failed step; a reply that still fails validation fails the step.
```yaml theme={null}
jobs:
main:
steps:
- id: extract
prompt: 'Extract the invoice details from: {{ inputs.text }}'
output_schema:
type: object
required:
- payer
- amount
- date
properties:
payer:
type: string
amount:
type: number
date:
type: string
- id: record
uses: transform
value: '{{ steps.extract.output.payer }} paid {{ steps.extract.output.amount }}'
```
## Per-task model overrides
`prompt` and `agent` tasks accept optional `provider:` and `model:` to switch the
LLM for that task only. This is a **run-scoped** override — your saved model
configuration is untouched. Use a cheap model for bulk steps and a stronger one
where it matters:
Set `provider` to the installed provider command name and `model` to a model ID
shown by that provider in your current build. For example, copy both values from
your working provider configuration into the prompt step. Model availability
and permissions are account-specific; the examples on this page use your
configured default model.
<Note>
`provider` is a provider command (e.g. `enconvo_ai`, `open_ai`, `ollama`) and
`model` is a model id for that provider. Both are only valid on `prompt`/`agent`
tasks.
</Note>
## Subworkflows
Compose workflows with `uses: workflow`, either by `workflowId:` (a saved
workflow) or an inline `workflow:` block. The task's output is the child run
result — reference the child's task outputs via `output.outputs['job.step']`:
```yaml theme={null}
jobs:
main:
steps:
- id: build_each
foreach: '{{ inputs.targets }}'
uses: workflow
inputs:
target: '{{ item }}'
workflow:
version: agent-workflow/v1
title: Build target
description: Build and package one target.
jobs:
main:
steps:
- id: compile
run: make {{ inputs.target }}
- id: package
run: tar czf {{ inputs.target }}.tgz build/
- id: summary
uses: transform
value: '{% for r in steps.build_each.output %}{{ r.status }} {% endfor %}'
```
## Templates reference
| Reference | Where |
| - | - |
| `{{ inputs.x }}` | Anywhere — workflow inputs |
| `{{ steps.<id>.output }}` | Anywhere — a previous step in the same job |
| `{{ jobs.<job>.<step>.output }}` | A completed step in a dependency job |
| `{{ item }}` / `{{ index }}` | Inside a `foreach` task |
| `{{ round }}` / `{{ last }}` | Inside a `loop` task |
| `{{ now }}` | Current timestamp |
| `{{ env.HOME }}` | Process environment variables |
Templates support Nunjucks filters (`| trim`, `| int`, `| dump`, `| default(...)`,
`{% for %}`, etc.), which is how you reshape data between tasks.
## Complete examples
### Research → summarize → report
Search the web, summarize the findings, and assemble a Markdown report. Note the
sequential steps within one job — no `needs` wiring required:
```yaml theme={null}
version: agent-workflow/v1
title: Research Brief
description: Search the web on a topic and produce a short Markdown brief.
inputs:
topic:
type: string
default: coffee brewing
jobs:
main:
steps:
- id: search
tool: web_search/web_search
params:
search_query: '{{ inputs.topic }} latest'
limit: 5
- id: summarize
prompt: 'Summarize the key points from these results in 4 bullets.
Results: {{ steps.search.output }}
'
- id: report
uses: transform
value: "# {{ inputs.topic }} \u2014 brief ({{ now }})\n{{ steps.summarize.output }}\n"
```
### Conditional routing
Approve or reject based on a score, then always write a final report:
```yaml theme={null}
version: agent-workflow/v1
title: Lead Router
description: Route a lead by score, reporting the outcome either way.
inputs:
score:
type: number
default: 42
jobs:
main:
steps:
- id: approve
if: inputs.score >= 60
uses: transform
value: approved
- id: reject
else_of: approve
uses: transform
value: rejected
- id: report
needs:
- approve
- reject
run_when: always
uses: transform
value: 'outcome: {{ steps.approve.output | default('''') }}{{ steps.reject.output | default('''')
}}'
```
### Loop until converged
Refine a draft repeatedly until a self-check approves it, capping the rounds:
```yaml theme={null}
version: agent-workflow/v1
title: Refine Until Good
description: Improve a draft until a self-check approves it.
inputs:
brief:
type: string
default: A tweet announcing our new feature.
jobs:
main:
steps:
- id: refine
prompt: 'Improve this draft. Return the improved draft and whether it is ready.
Previous attempt: {{ last | default(inputs.brief) }}
'
output_schema:
type: object
required:
- draft
- approved
properties:
draft:
type: string
approved:
type: boolean
loop:
until: output.approved == true
maxRounds: 4
- id: publish
uses: transform
value: '{{ steps.refine.output.draft }}'
```
## Related
<CardGroup>
<Card title="Creating workflows" icon="pen-to-square" href="/workflows/creating-workflows">
The editor, the editing assistant, and each executor.
</Card>
<Card title="Introduction" icon="book-open" href="/workflows/introduction">
The task model and how workflows are run.
</Card>
</CardGroup>
# Build Your First Workflow
Source: https://docs.enconvo.ai/workflows/build-your-first-workflow
A narrated video tutorial: create, edit, extend, run, and inspect a workflow in eight steps.
Workflows chain prompts, agents, and tools into one repeatable run. This tutorial builds one from start to finish: create it from the **Tour of step kinds** template, add a step by hand, let the workflow assistant add another, then run it and read every step's output.
<YouTubePlayer title="How to Build a Workflow in Enconvo | Step-by-Step Tutorial" />
The video is 2 minutes 24 seconds long. The written steps below follow the same order, with the matching timestamp for each step.
## What you'll build
The **Tour of step kinds** template already runs out of the box. Over the tutorial, it grows into a small content pipeline:
| Step | Type | What it does |
| - | - | - |
| Get today's date | Shell | Prints today's date |
| List saved workflows | Tool | Lists your existing workflows (runs in parallel with the date) |
| Ask the model for an idea | Prompt | Suggests one new automation about the `topic` input |
| Let the agent expand it | Agent | Turns the idea into a three-step plan |
| Write a tweet | Prompt | **Added by hand** — turns the plan into one punchy tweet |
| Translate the tweet into Japanese | Prompt | **Added by the assistant** — translates the tweet |
## Steps
<Steps>
<Step title="Create a workflow (0:07)">
Open **Settings → Workflows → Manage** and select **New workflow**. Under **Or start from a template**, choose **Tour of step kinds**; the workflow is created and the editor opens in **Visual** mode. (In the video, which was recorded before the New workflow dialog, the starter is called *Starter Workflow*.)
</Step>
<Step title="Read the graph (0:18)">
Read the graph from the top. The **Inputs** node declares what a run needs; here it is a single `topic`. The first two steps sit side by side because they belong to separate jobs, so they run in parallel. Each result then flows down into the steps below it, which run in order.
</Step>
<Step title="Edit a step (0:28)">
Select a step to open it in the inspector, where you can change its ID, title, and prompt. Double curly braces pull values into a step: `{{ inputs.topic }}` reads a run input, and `{{ steps.idea.output }}` reads an earlier step's result. That is how steps talk to each other.
</Step>
<Step title="Add a step (0:37)">
Select the **+** below the last step and pick a step type — Prompt, Agent, Shell, Tool, and more. Give the new Prompt step the ID `tweet`, the title "Write a tweet", and this prompt:
```text wrap theme={null}
Turn this plan into one punchy tweet: {{ steps.plan.output }}
```
<Tip>
After you rename a step ID, press Return before moving to the next field.
</Tip>
</Step>
<Step title="Or just ask the workflow assistant (0:57)">
Instead of editing by hand, select **Assistant** in the toolbar and describe the change in the panel that opens beside the canvas:
```text wrap theme={null}
Add a final step that translates the tweet into Japanese
```
The assistant edits the graph for you and lists the steps it changed; select **Revert** on its reply if you don't like the result. In the video it adds a `translate_ja` step whose prompt reads `{{ steps.tweet.output }}`. Review the new step before you save — assistant edits stay unsaved until you select **Save**.
</Step>
<Step title="It's just YAML (1:16)">
Select **YAML** in the toolbar to see the same workflow as source. There is one plain file per workflow, saved at `~/.enconvo/workflows/<id>.yaml`, so it is easy to read, diff, and share. Select **Visual** to return to the graph. See [the full YAML](#the-finished-workflow) below.
</Step>
<Step title="Run it and check the output (1:28)">
Select **Inputs**, set the run values — the video uses `{"topic": "matcha"}` — and choose **Run**. Running steps glow blue and finished steps turn green. The Agent step takes longer than the others.
When the run finishes, select any step and open its **Output** tab to see exactly what it produced. The last step picked up the tweet and translated it, with no copy and paste.
</Step>
<Step title="Find past runs (2:05)">
Every run is kept under **Runs** in the toolbar, so you can come back to any result later.
</Step>
</Steps>
<Note>
Running a workflow calls real models and tools. It can use provider credits, and Shell or Tool steps act with your Mac account's permissions. Review a workflow's steps before you run it.
</Note>
## The finished workflow
Here is the workflow built in the video, written out as YAML. The **YAML** view may format it slightly differently.
```yaml theme={null}
version: agent-workflow/v1
title: Starter Workflow
description: "Starter workflow showing parallel jobs and the four executors: command (shell), prompt (LLM), agent, and tool (Local API)."
tags:
- demo
inputs:
topic:
type: string
description: Topic to brainstorm an automation for
default: coffee
jobs:
date:
steps:
- id: today
name: Get today's date
command: 'date "+%Y-%m-%d"'
catalog:
steps:
- id: my_workflows
name: List saved workflows (tool)
tool: workflow/list
with:
limit: 5
ideate:
needs: [date, catalog]
steps:
- id: idea
name: Ask the model for an idea
prompt: "Today is {{ jobs.date.today.output.stdout | trim }}. Existing workflows: {{ jobs.catalog.my_workflows.output.summaries | dump }}. Suggest ONE new automation about {{ inputs.topic }} that is not in the list, in one sentence."
- id: plan
name: Let the agent expand it
agent: agent/main
message: "Expand this automation idea into a three-step execution plan: {{ steps.idea.output }}"
- id: tweet
name: Write a tweet
prompt: "Turn this plan into one punchy tweet: {{ steps.plan.output }}"
- id: translate_ja
name: Translate the tweet into Japanese
prompt: "Translate this tweet into natural, fluent Japanese. Keep hashtags, emojis, and links intact. Reply with only the translated tweet: {{ steps.tweet.output }}"
```
The `ideate` job waits for `date` and `catalog` through `needs`, so it can read their results with `jobs.<job>.<step>.output`. Within a job, later steps read earlier ones with `steps.<id>.output`.
## Next steps
<CardGroup>
<Card title="Workflows introduction" icon="diagram-project" href="/workflows/introduction">Jobs, steps, and every executor a step can use.</Card>
<Card title="Creating workflows" icon="pen-to-square" href="/workflows/creating-workflows">The Visual editor, YAML, and the editing assistant in detail.</Card>
<Card title="Advanced workflows" icon="code-branch" href="/workflows/advanced-workflows">Conditions, loops, retries, output schemas, and subworkflows.</Card>
<Card title="Scheduled jobs" icon="clock" href="/workflows/scheduled-jobs">Run an Agent instruction or script at a set time.</Card>
</CardGroup>
# Creating Workflows
Source: https://docs.enconvo.ai/workflows/creating-workflows
Create and inspect workflows in the Visual editor or YAML, with an editing assistant.
Select **Workflows** under **Scheduled** in the Chat Window sidebar, or open **Settings → Workflows → Manage**, then select **New workflow**, or open an existing workflow with **Edit**. In the Chat Window, switching to a chat and back keeps the workflow you were editing open. To rename a workflow, select its name at the top of the editor, type the new name, and press Return; Esc keeps the old name. To find a workflow, type in **Search workflows**; the list updates as you type, and the clear button or Esc shows every workflow again. Press ↓ in **Search workflows** to go to the first workflow, ↑ and ↓ to move between workflows, Return to open one, and Delete to delete it. Deleting a workflow also deletes the scheduled tasks that run it; the confirmation says how many before you delete. If the workflow is running, its run is stopped first.
The workflow list shows each workflow's number of steps, when it was last edited, and how its last run went. Select the last run to open the workflow with that run's results on the canvas. Select the play button on a row to open the workflow and run it right away; if it needs inputs you haven't filled in, the **Inputs** panel opens first. While a workflow is running, its play button becomes a stop button; select it to stop the run without opening the workflow. A workflow that runs on a schedule shows when its next run is, or **Schedule paused** when all of its scheduled tasks are off; select it to open the workflow with its schedules in the Runs panel. The list updates on its own when you come back to it and when a scheduled run starts. Use the sort menu above the list to order workflows by **Recently edited**, **Recently run**, or **Name**; your choice is remembered. Select the copy button to duplicate a workflow under a new title, so you can change the copy without touching the original; the list scrolls to the copy and highlights it. Press ⌘F or / to jump to **Search workflows**. Select a tag on a row to show only the workflows with that tag; it works together with **Search workflows**. A row shows up to four tags; select **+N** to see the rest. Select the tag again, the × next to it above the list, or press Esc in **Search workflows** to show every workflow again.
## Start a new workflow
Select **New workflow** to open a dialog with these ways to start. When you don't have any workflows yet, the workflow list offers the same starts right there: **Describe what it should do**, **Blank workflow**, and the templates.
* **Describe it.** Write what the workflow should do, for example "Translate a text into Japanese and Spanish at the same time", and select **Build it** (or press ⌘Return). The workflow opens with the assistant already building it; review its steps and select **Save** when they look right.
* **Start from a template.** Pick **Blank**, **Research a topic**, **Summarize a web page**, **Notes from a YouTube video**, **Write and read aloud**, or **Tour of step kinds** (a shell command, a tool, a prompt, and an agent, with two jobs running side by side). Every template is a complete workflow you can run right away.
* **Import a file.** Select **Choose file…**, or drop a `.yaml`, `.yml`, or `.json` workflow file anywhere on the dialog, for example one a teammate shared. The workflow is saved as a new workflow, so it never replaces one you already have. If its title matches one in your list, it's named like a copy, such as "News copy". If the file isn't a valid workflow, the dialog stays open and tells you why.
* **Paste it.** Paste a workflow's YAML or JSON, such as one shared in a chat, into the description box. **Build it** becomes **Import it**, and the workflow is created exactly as pasted.
To share a workflow or keep a copy, select the share button (the download icon) on its row in the workflow list, or in the editor toolbar:
* **Export as a YAML file…** saves a `.yaml` file where you choose. Import it with **New workflow** > **Choose file…** on any Mac.
* **Copy YAML** copies the workflow, ready to paste into a chat or into the **New workflow** description box, which imports it.
Both include changes you haven't saved yet when you use them from the editor.
<Frame>
<img alt="Actual Enconvo workflow graph with two parallel jobs and a step inspector" />
</Frame>
## Build with the Visual editor
1. Select **Visual** in the editor toolbar.
2. Use **Add step here** between nodes to insert a step, or **Add parallel job** for a separate branch. The step list opens with **Recently used**, the last few steps and tools you picked, so the ones you add often are one click away. A plugin with many tools lists its first eight; select **Show N more** to see the rest, or type to search.
3. Select a step to open its inspector. Edit its ID, title, and executor settings, and open **Behavior** to change how it runs.
4. Select the **Inputs** node to configure the workflow's declared inputs: a name, a type (text, number, true/false, list, or object), a description, a default, and whether a run needs a value. Under each name, the panel shows how steps read the input, such as `{{ inputs.topic }}`, and how many steps do. Renaming an input updates those steps to the new name. A name can use letters, digits, and underscores, can't start with a digit, and must not match another input.
5. Review the graph and use **Undo** or **Redo** while editing.
6. Select **Save** after reviewing your changes.
Each step card shows the step's name and, under it, what the step does: the tool or kind of step, then the start of its main setting, such as *Web Search · ‹topic› news* or the first words of a prompt. Values it reads from inputs and earlier steps appear in ‹ › by name. A step without a name shows its ID in words; hover a card to see its ID.
A tool step's card shows its plugin's icon. Small marks on the card show how the step runs: only when a condition is true, once for each item in a list, repeating, retrying if it fails, running even after an earlier step fails, or letting the workflow continue if it fails. Hover a mark to read what it means; change it in the step's **Behavior** section.
The step picker searches built-in steps, installed tools, and MCP tools. It leaves out tools that only open an Enconvo window or list a provider's models and voices; a workflow can still call them by name in its YAML. If you are not sure which one you need, type what the step should do, such as “summarize the article in three bullets”, and select **Ask the assistant to add** at the bottom of the picker (⌘Return). When nothing matches, Return does the same. The assistant adds the step exactly where you opened the picker, before or after the neighbouring step or as a new parallel job, and you can revert it like any other assistant reply.
The inspector provides **Config** and **Output** tabs. **Run step** executes the selected step; it can perform real tool calls or shell commands. Check that required upstream values exist before running an individual step.
The **Config** tab starts with the step's **Name**, which the step card shows, and its **Step ID**, which other steps use to read its result. **What it does** names the step's tool or kind. To make the step do something else, select **Change** and pick another tool or kind of step, or describe what it should do and select **Ask the assistant to change it**. The step keeps its ID, so steps that read its result still work, and keeps when and how it runs: its condition, repeat, retries, and what it waits for. The new tool's settings start empty. A prompt that becomes an agent, or an agent that becomes a prompt, keeps its text, model, and output schema. A name the editor gave the step follows the new tool; a name you wrote stays. Select **Undo** to go back.
To reuse a step, select **Duplicate** in the inspector or on the step card when you hover it. The copy keeps all of the step's settings, appears right after the original, and gets the next free ID, such as `fetch_2`.
Steps in a job run from top to bottom. To change the order, drag a step's card up or down within its job; the other cards move aside to show where it will land. You can also select a step and choose **Move up** or **Move down** in the inspector, or press ⌥↑ or ⌥↓. Press ⌘Z to undo a move. If a step ends up above a step whose result it reads, its card shows a warning until you move it back below.
To leave a step out for now without deleting it, select it and choose **Turn off step**. Its card fades and shows **Off**, runs skip it, and the steps after it still run. Choose **Turn on step** to bring it back.
To change several steps at once, hold ⌘ or Shift and click their cards. A bar at the top of the canvas shows how many steps are picked, with **Turn off** (or **Turn on**) and **Delete** for all of them. If the delete would break other steps, or empty a job, Enconvo asks first. The confirmation lists each step that depends on the ones you're deleting and why, such as **Uses its output** or **Waits for it to finish**; select one to call off the delete and open that step so you can fix it first. The same happens when you delete a single step. Press Esc or click an empty spot on the canvas to clear the pick, and ⌘Z to undo.
To copy steps, select one (or pick several) and press ⌘C, or select **Copy** in the bar; ⌘X cuts them. Then select the step they should follow and press ⌘V. The copies land right after it, or at the end of the job when a job is selected, and they keep their settings. A copy whose ID is already taken gets a new one, such as `fetch_2`, and pasted steps that read from each other follow the new names. Steps paste into another workflow the same way, and ⌘V also accepts a YAML or JSON step list copied from a workflow file. Press ⌘A to pick every step, and ⌫ to delete the selected or picked steps.
To jump to a step in a large workflow, press ⌘F or select the search button on the canvas, type part of the step's name, ID, tool, or text, and pick it; the step is selected and brought into view. When you delete or paste steps, a notice says what changed; select Undo in it to take that change back. Use the zoom controls in the bottom-right corner of the canvas, or press ⌘= and ⌘- to zoom in and out and ⌘0 to fit the whole workflow in view; select the zoom level to return to 100%. Press ⌘S to save from anywhere in the editor, in Visual or YAML, even while typing in a step's settings. Press ⌘Return to run the workflow; it is saved first if it has changes. In the YAML editor, the assistant, and other multi-line fields, select **Run** instead. If the workflow has a problem, such as a step with an empty prompt or a missing description, Save and Run stop and say what to fix; select **Show** to open the step or the workflow's title and description. Steps with problems have a red mark on their card; hover over it to read what's wrong. In YAML, select **Validate** to check the whole document. While a run is in progress, **Run** becomes **Stop**; after you select it, it shows **Stopping…** until the run has stopped. While a workflow has unsaved changes, the editor header shows **Unsaved**; select it to see the YAML lines added and removed since the last save, and select **Discard changes** to go back to the saved version; in the Visual editor, ⌘Z brings your changes back. If you go back to the workflow list with unsaved changes, choose **Save and leave**, **Discard**, or **Keep editing**. Unsaved changes are also kept on this Mac while you edit: if the window closes or reloads before you save, reopening the workflow shows a bar at the top with **Restore**, which puts your changes back as one step you can undo, or **Discard**. Changes are offered back only if the saved workflow hasn't changed since. In the workflow list, such a workflow shows an **Unsaved changes** tag, and deleting it discards those changes too. To see every canvas shortcut, select the keyboard button next to **Add parallel job**, or press ?.
### Step behavior
The **Behavior** section of the inspector sets how a step runs without editing YAML. Its header lists what you changed, such as *Only if… · Retries 2×*, or shows **Default**.
| Setting | Choices | YAML it writes |
| - | - | - |
| **Runs** | Every time; only if a condition is true; otherwise, when an earlier step's condition is false. **Run even if earlier steps fail or are skipped** keeps the step running after a failure upstream. | `if`, `else_of`, `run_when` |
| **Repeats** | Once; once for each item in a list; in rounds until a condition is met, up to a maximum number of rounds | `foreach`, `loop` |
| **If it fails** | Stop the workflow, or keep going so later steps still run. **Retries** runs the step again before it counts as failed, with an optional wait between tries. | `required: false`, `retries` |
| **Waits for** | The previous step; nothing, so it starts right away; or the steps you tick from a list of earlier steps and steps in other jobs | `needs` |
**Output schema** takes an optional JSON Schema for a structured result. Choosing a default again removes the setting from the YAML. The [Advanced workflows](/workflows/advanced-workflows) page explains each setting in detail.
## Edit YAML
Select **YAML** to work with the same document as source. The **Valid / Invalid** badge and **Validate** action help find malformed definitions. Use letters, digits, and underscores for job and step IDs; start with a letter or underscore. When you switch back to **Visual**, ⌘Z takes back your YAML edits in one step.
```yaml theme={null}
version: agent-workflow/v1
title: Greeting
description: Produce a greeting and a formatted result without calling a model.
inputs:
name:
type: string
default: world
jobs:
main:
steps:
- id: greeting
uses: transform
value: "Hello, {{ inputs.name }}!"
- id: result
uses: transform
value: "Result: {{ steps.greeting.output }}"
```
Run this example with `Ada` in the **name** field under **Inputs**. The final step produces `Result: Hello, Ada!`.
## Choose an executor
The following snippets are step entries: place them inside a job's `steps` list.
### Shell
```yaml theme={null}
- id: today
command: 'date "+%Y-%m-%d"'
```
Read the result with `steps.today.output.stdout`. Optional settings include `cwd`, `shell`, `timeoutMs`, and `env`. Commands use the permissions of your Mac account; review commands before running them.
### Prompt
```yaml theme={null}
- id: summarize
prompt: "Summarize this text: {{ inputs.text }}"
```
This calls a model once. Use [output schemas](/workflows/advanced-workflows#output-contracts) when later steps need structured fields.
### Agent
```yaml theme={null}
- id: plan
agent: agent/main
message: "Propose a three-step plan for {{ inputs.topic }}."
```
Use a command key for an installed Agent. Its enabled tools and provider settings determine what it can do.
### Tool
```yaml theme={null}
- id: saved
tool: workflow/list
with:
limit: 5
```
`tool` is a Local API route in slash form. `with` supplies parameters (`params` is an alias). Discover available routes in **Settings → Developer → APIs**, or ask the editing assistant to inspect installed tools.
### Transform and subworkflow
Use `uses: transform` with a `value` to combine inputs or previous outputs without calling a model. Use `uses: workflow` with a saved `workflowId`, or an inline `workflow` document, to run a reusable child process. See [Advanced Workflows](/workflows/advanced-workflows#subworkflows).
## Reference earlier results
| Expression | Value |
| - | - |
| `{{ inputs.name }}` | An input value |
| `{{ steps.greeting.output }}` | A previous step in the same job |
| `{{ jobs.research.search.output }}` | A completed step in another job |
| `{{ item }}` and `{{ index }}` | Current item and index in `foreach` |
| `{{ round }}` and `{{ last }}` | Round and previous output in a loop |
Add job-level `needs` before reading another job's output. Inspect tool results in **Output** rather than assuming every tool returns the same fields.
In the Visual editor you don't need to type these by hand. Select **Insert value** (the `{x}` button at the right of a step field, such as the prompt, command, a tool setting, or a condition) to list what that step can read: the workflow's inputs, the results of earlier steps in its job, the steps of jobs it waits for, and, for a repeated step, the current item or round. Search the list and pick one; it goes where your cursor was, or replaces the text you selected. A shell step offers its printed text as `{{ steps.<id>.stdout | trim }}`, and a step with an output schema or an earlier run also lists its result fields. Conditions, **Stop when**, and the list a step repeats over get the right form for that field, such as a bare `steps.check.output.ok` in a condition.
A field that reads something it can't reach shows a warning underneath with what to change: an input the workflow doesn't declare, a step that runs later or is the step itself, a step that belongs to another job, or a job this one doesn't wait for. On the canvas, a step card with such a value shows a warning icon next to its title; hover it to see what to fix. Warnings don't stop you from saving.
## Use the editing assistant
Select **Assistant** in the editor toolbar to open the assistant panel beside the canvas, then describe what you want, for example: “Add a prompt step that summarizes the previous result.” For a new, empty workflow you can describe the whole process instead, such as “Every morning, fetch the top Hacker News stories and summarize them.” Press Return to send and Shift-Return for a new line, and choose the model under the composer.
While the assistant works, the panel shows what it is doing, such as reading the workflow, checking a tool's parameters, or editing, and the canvas updates as it goes. The canvas is read-only until the reply finishes; select **Stop** to end it early.
You don't have to wait for a reply to finish before asking for more. Press Return while the assistant is working and your message waits in a queue above the composer; queued messages are sent one at a time, in order, as each reply finishes. Drag a queued message to reorder it, or use its **⋯** menu to edit it, and select the trash icon to remove it. If you select **Stop** or a reply fails, the queue is marked **Parked** and nothing more is sent on its own; select **Send** on a queued message when you're ready.
When a message can't wait, such as a correction to what the assistant is doing, press ⌘Return instead of Return, or select **Send now** on a queued message. The current reply stops, keeps the edits it already made, and is marked **Interrupted**, and your message is sent right away. The rest of the queue isn't parked; it's sent in order after that.
Each reply that changes the workflow ends with a card that lists the steps it added, changed, or removed:
* Select a step on the card to select it on the canvas and bring it into view. Step IDs the assistant names in its reply, such as `summarize`, work the same way.
* Select **Revert** on the latest card to put the workflow back the way it was before that reply. **Undo** (⌘Z) also takes back a whole reply in one step.
* To ask about one step, select it on the canvas and choose **Ask Assistant** in its inspector. The step is attached to your next message, so “make this more reliable” means that step.
* When a step fails in a run, choose **Fix with Assistant** on the run summary or in the step's **Output** tab. Your message carries the step and its error, so you don't have to copy the error in.
* To ask about part of a step's result, select text in its **Output** tab and choose **Ask Assistant** under the selection. The text appears as a quote above the message box and goes with your next message, so you can ask what it means or how to change the step that produced it.
* Select **New chat** at the top of the panel to start over; the earlier chat stays in the list. Select the chat's name at the top of the panel to switch back to an earlier chat about the same workflow or to delete one. A saved workflow keeps its last ten chats in this browser.
To set defaults the assistant should always follow, select **Settings** (the sliders icon) at the top of the panel and write them under **Instructions**, for example “Save files to \~/Downloads.”, “Use anthropic/claude-haiku-4-5 for prompt steps.”, or “Reply in Chinese.” Press ⌘Return or select **Save**. The instructions apply to every workflow the assistant builds or edits, and a dot on the Settings icon shows they are on. To stop using them, clear the box and save.
When a reply finishes, the steps it added are tagged **Added** on the canvas and the steps it changed are tagged **Edited**, so you can see what to review. The tags stay until you save, undo, or revert the reply.
To try the assistant's latest change, select **Run** on its reply card. It runs the workflow the same way as **Run** in the toolbar, asking for inputs first when it needs them. Select **Revert** instead to undo the change.
If a reply leaves the workflow invalid, the editor switches to YAML and shows the errors. Fix them there, or ask the assistant to fix them. Assistant edits remain unsaved until you select **Save**.
## Run and inspect
1. Select **Inputs** and fill in the values for this run.
2. Validate the definition and inspect any commands or tool calls.
3. Choose **Run** and watch step status in the graph.
4. Select a step's **Output** tab to inspect its result or error. After a run, each step card also shows the first line of what the step returned, or why it failed, in place of its description; select that line to open the step's **Output** tab. Select **Copy** in the **Output** tab to copy the step's result, or its error when it returned nothing, for example to paste into a chat or a document.
5. Open **Runs** to inspect previous runs.
6. Save the workflow when you are satisfied with its definition.
### Run inputs
**Inputs** in the toolbar opens a form with one field for each input the workflow declares, showing its type, its description, and its default:
* Leave a field blank to use its default. Lists and objects take JSON, such as `["a", "b"]`.
* An input marked **Required** that has no default needs a value. If it is empty, or a value has the wrong type, **Run** stops before saving or running anything and points at the field to fix.
* Press ⌘Return in a field to run.
* The form starts from the values the workflow last ran with in Enconvo. Select **Clear** to empty every field at once, so the next run uses the defaults again. Renaming an input keeps the value you typed for it.
* While a past run from **Recent runs** is on the canvas, select **Use that run’s values** to fill the form with the inputs it ran with, then run it again as it was or with a change.
* A blank field shows its default in gray. To change a long default rather than retype it, select **Edit default** beside the field to put the default in it, then edit.
* In the Visual editor, select **Edit inputs** to change what the workflow asks for. If steps still read an input you remove, Enconvo names them and asks before removing it. Select **Edit as JSON** to type the inputs as one JSON object, including keys the workflow doesn't declare. **Use form** switches back.
### When a run ends
When a run ends, a summary appears at the bottom of the canvas:
* If a step failed, the summary names it and shows the line of its error that says what went wrong, such as `command not found: datex` rather than only an exit code. Select **Show error** to open that step's **Output** tab and bring the step into view on the canvas.
* Select **Fix with Assistant** to hand the failed step and its error to the assistant. It starts its reply with the cause, then fixes the step. If the cause is outside the workflow, such as a missing API key, a network error, or a missing file, it tells you what to change instead of editing. A failed step's **Output** tab has the same **Fix with Assistant** button.
* Select **Resume** to continue a failed or stopped run. Steps that already finished keep their results; the failed step and everything after it run again. If you edited a step after the run, that step and the steps after it run again too. If you change the run inputs, the whole workflow runs from the start. **Resume** also appears next to **Run** in the toolbar until you start another run.
* After a clean run, select **Show output** to see the last step's result. The summary fades after a few seconds unless something needs your attention; select **×** to close it sooner.
**Recent runs** lists the workflow's earlier runs, newest first. Each row shows whether the run succeeded, failed, or is still running, when it started, how long it took, whether a schedule (**Scheduled**) or a chat (**From chat**) started it, the inputs it ran with (hover to see them all), and the error if it failed; the run shown on the canvas is marked **Showing**. Select a row to show that run's step results on the canvas. When some runs failed and others didn't, select **Failed** above the list to see only the failed runs, and **All runs** to see every run again.
**Schedule**, at the top of the Runs panel, lists the scheduled tasks that run this workflow with when each runs next and the inputs it runs with. When a task's last run failed, hover **Last run failed** to see why, or select it to open that run on the canvas and see which step failed. Turn a task off or on with its switch, select the pencil to change its schedule, or choose **Add schedule** to create a task with this workflow already picked and its inputs filled in from **Run inputs**. Scheduled runs use the saved workflow, so save your changes before the next run. All scheduled tasks are also in **Scheduled**.
Saving writes `~/.enconvo/workflows/<id>.yaml`. Editing a definition and running it are separate actions. A run can consume provider credits or change external data depending on its steps.
## Watch the steps
<video aria-label="Explore the workflow editor">
<source type="video/mp4" />
[Download the walkthrough](/videos/guides/workflow-editor.mp4).
</video>
Switch between Visual and YAML, inspect run inputs, and open a step inspector. The workflow is neither changed nor executed. This silent walkthrough uses real interface captures with pauses added for reading. The written steps above provide the same instructions.
# Workflows Introduction
Source: https://docs.enconvo.ai/workflows/introduction
Build repeatable automations with visual editing, sequential steps, and parallel jobs.
A workflow describes a repeatable process: read information, transform it, ask a model, call an Agent, or use an installed tool. Open **Settings → Workflows → Manage** to browse workflows and their run history.
<Tip>
New to workflows? Watch the 2½-minute video tutorial [Build Your First Workflow](/workflows/build-your-first-workflow) to create, edit, and run one from start to finish.
</Tip>
## Choose the right automation
| Need | Use |
| - | - |
| Reuse a prompt on selected text | [AI Commands](/features/ai-commands) |
| Let an assistant decide which tools to use | [Agents](/ai/agents) |
| Define a repeatable sequence with inspectable outputs | A workflow |
| Run an Agent instruction or script at a set time | [Scheduled Tasks](/workflows/scheduled-jobs) |
## Jobs and steps
Current workflows use `version: agent-workflow/v1` with a **jobs** map. Each job contains an ordered **steps** list. Steps within a job run sequentially. Jobs start in parallel unless `needs` makes one job wait for another.
```yaml theme={null}
version: agent-workflow/v1
title: Quick Summary
description: Summarize supplied text into three bullets.
inputs:
text:
type: string
default: "A sample paragraph to summarize."
jobs:
main:
steps:
- id: summarize
prompt: "Summarize in three bullets: {{ inputs.text }}"
```
<Note>
The old top-level `tasks` format is no longer accepted. Move each sequence into `jobs.<name>.steps`, give steps explicit IDs, and use `steps.<id>.output` within a job or `jobs.<job>.<step>.output` across jobs.
</Note>
## What a step can do
| Executor | Fields | Result |
| - | - | - |
| Shell | `command` or `run` | Command output, including `stdout`, `stderr`, and `exitCode` |
| Prompt | `prompt` | A model reply; use an output schema for structured data |
| Agent | `agent` and `message` | The selected Agent's reply |
| Tool | `tool` and `with` | An installed Local API endpoint's result |
| Transform | `uses: transform` and `value` | A templated value |
| Subworkflow | `uses: workflow` with `workflowId` or `workflow` | A child workflow run result |
Each step has exactly one executor. A workflow can add conditions, loops, retries, and output schemas; see [Advanced Workflows](/workflows/advanced-workflows).
## Where to run a workflow
* Open it in **Workflows**, set **Inputs**, and choose **Run**.
* Search for a saved workflow in SmartBar. Launcher text is available as `inputs.input_text`.
* Mention an available workflow with `@` in chat so an Agent can use it.
Saved workflow files live at `~/.enconvo/workflows/<id>.yaml`. The filename is the workflow ID. Keep that ID stable to preserve the link with its run history.
Continue with [Creating Workflows](/workflows/creating-workflows) for the visual editor, YAML, assistant, and a first run.
# Scheduled Tasks
Source: https://docs.enconvo.ai/workflows/scheduled-jobs
Have an Agent do something for you on a schedule, set up by describing it in a chat.
A scheduled task asks an Agent to do something at a time you choose, once or again and again: a morning news brief, a weekly plan, a price check. Each run starts its own conversation, and the result shows up in the task. You can also have Enconvo notify you on your Mac or send the result to an IM chat.
<Frame>
<img alt="The Scheduled view with a weekday morning task: its schedule and next runs, instruction, results, and notifications in one panel" />
</Frame>
## Set up a task by chatting
<Steps>
<Step title="Open Scheduled">
In the **Chat Window** sidebar, select **Scheduled**, then **New task**.
</Step>
<Step title="Say what to do and when">
Describe the task and its timing in the composer, for example “Every weekday at 8:00, brief me on the most important AI news in five bullets with links.” Or pick a starter such as **Morning briefing** or **Plan my week**, which fills the composer for you to adjust before sending. If you have saved workflows, a few of them appear under the starters; pick one to fill in a request that runs that workflow every day at 9:00, then change the time or add input values before sending.
</Step>
<Step title="Check the confirmation">
Enconvo creates the task right away, shows it as a card in the chat, and replies with when it will run, in plain words and your local time. If you leave out the time, it picks a sensible one and says so; it asks a question only when the task can't work without the answer, such as which product to watch. The task appears under **Set up in this chat** above the conversation and in the task list. Keep chatting to change, pause, or resume it.
</Step>
</Steps>
<Frame>
<img alt="The Schedule a task screen with a composer and six starter tasks" />
</Frame>
Scheduling chats are kept, but they don't appear under **Chats** in the sidebar. To return to one, such as a chat where Enconvo is waiting for your answer, select the chat's name above the conversation and choose it under **Scheduling chats**. You can delete a chat there too; tasks set up in it keep running.
You can also ask in any chat, such as “Remind me tomorrow at 9 to send the invoice” or “Every Monday morning, list my week's deadlines.” The Agent sets up the same kind of task, shows its card, and confirms when it will run. Select **Open** on the card to see it in **Scheduled**. A card in an older chat shows whether the task was paused, finished, or deleted since.
Write the task as a complete instruction. Each run starts a fresh conversation that doesn't see the chat you set it up in, so “Summarize today's top AI news in five bullets with links” works better than “Do that again tomorrow.”
## Manage a task
Select a task in the list to see its details: whether it's active, paused, or needs attention, then one panel with its schedule, instruction, where results go, and notifications. When the last run failed or its result wasn't sent, a note under the name says why and offers a fix: **Fix with chat** (an Agent task) opens the task's chat with a request to fix it that names the error, and **Run again** runs it once more; **Send again** retries sending the result, and **Change where results go** opens the results picker. Choosing **Only Enconvo** there also clears a note about a result that wasn't sent.
| Control | What it does |
| - | - |
| **Run now** | Runs the task once right away. It really runs, so the Agent may use tools or points. |
| **Change with chat** | Reopens the chat the task was set up in (or starts a new one if there isn't one) so you can describe a change, such as “move it to 7:30” or “add weather.” |
| **Task name** | Select the name to rename the task. Press Return to save or Esc to cancel. |
| **Schedule** | Shows when the task runs and its next run. Schedules read in plain words, such as **Every day at 09:00 and 18:00** or **Every year on Jan 1 at 03:00**, the same in the list, Settings, and the chat card. Select it to change the time in place: pick **Once**, **Every day**, **Weekly**, **Monthly**, **Interval**, or **Cron**, check the next runs, and select **Save**. The switch next to it pauses future runs without deleting the task. |
| **Instruction → Edit** | Changes what the Agent is asked to do (or the command, for a shell-command task) in place. Press ⌘↩ or select **Save**; Esc cancels. |
| **Results** | Shows where each run's result goes. Select it and pick a chat you've talked to an Agent in through an IM channel, or **Only Enconvo** to keep results in each run's conversation; the change saves right away. **Another chat…** opens the editor to enter a chat ID. |
| **Notify me when it runs** | Posts a Mac notification when a run finishes, with the first line of the result. Click it to open the task. |
| **… → Edit details** | Opens the form editor for every field at once, including the Agent, the description, and a maximum number of runs. |
| **… → All runs** | Opens the full run history with filters. |
| **… → Delete** | Deletes the task and its run history. |
**Recent runs** lists each run's time with the first line of its result, all collapsed; select a run to read the whole result or error. Under an expanded run, select **Ask follow-ups** to continue from it in its conversation, for example to ask for more detail on one item, **Copy** to copy the result or error, or **Send again** when its result wasn't sent.
Search with **Search tasks** by name or instruction. The list groups tasks as **Needs attention** (the last run failed or its result was not sent), **Upcoming**, **Paused**, and **Finished** (a one-time task that has run).
To act on a task without opening it, point to it in the list and select **…**, or Control-click it, then choose **Run now**, **Pause** or **Resume**, **Edit details**, or **Delete**. Press ↓ in **Search tasks** to go to the first task, then ↑ and ↓ to move between tasks.
## Use the form editor
Select **Set up a task with the form instead** on the new-task screen, or **Edit details** on a task, to fill in every field yourself.
<Frame>
<img alt="Edit scheduled task dialog with an Agent, an instruction, and a weekly Monday to Friday schedule at 09:00" />
</Frame>
1. Name the task and choose **Ask an agent** with an Agent and instruction, **Run a workflow** to run one of your saved [workflows](/workflows/introduction), or **Run a shell command** for a script on your Mac. For a workflow, fill in any inputs it should get; inputs left empty use the workflow's defaults.
2. Under **When**, choose **Once**, **Every day**, **Weekly**, **Monthly**, **Interval**, or **Cron**, and check the **Next runs (local time)** preview. In **Cron**, the line under the expression says what it means as you type, such as `0 9-17 * * 1-5` reading **Every hour from 09:00 to 17:00 on weekdays**.
3. Under **Send the result**, turn on **Send each result to a chat** to deliver results to an IM chat. You may need to talk to the Agent in that chat first so it appears in the picker.
4. **More options** adds a description and a maximum number of runs.
5. Select **Save** (or **Create task**). **Test run** saves the task and runs it immediately.
Shell-command tasks, and sending results to a chat by its ID, are set up only in this editor; the scheduling chat handles Agent and workflow tasks. A shell-command task notifies you only when a run fails (**Notify me if it fails**), since such tasks often run every few minutes.
## Schedule a workflow
A workflow task runs a saved workflow at the times you choose, the same as selecting **Run** in the workflow editor. Pick **Run a workflow** in the editor, or ask the scheduling chat, for example "Run my Content Pipeline every weekday at 9 with the topic AI news": it finds the workflow by name, fills the inputs you mention, and leaves the rest at their defaults. Each run's result is the output of the workflow's last step, so it can be sent to a chat or shown in a notification like any other result. If a step fails, the run is marked failed with that step's error.
* The task's details show the workflow and its inputs. Select **Open** to see the workflow, or **Change** to pick another workflow or change the inputs.
* Under an expanded run, select **Open run** to see each step of that run in **Workflows**. When the last run failed, the note under the task's name offers **Open the failed run**.
* A run stops after 29 minutes. If the workflow is deleted, its runs fail with a note to choose another workflow.
## Manage many tasks in Settings
**Settings → Agents → Scheduled Tasks** lists every task in a table, including shell-command tasks. Filter by **Active**, **Paused**, or **Needs attention**, search, and select several tasks to pause, resume, or delete them together. A task's history shows each run's status:
| Status | What to check |
| - | - |
| Failed | The instruction, the Agent's tools, the shell exit status, or the error details |
| Succeeded / Not delivered | The task ran, but its IM channel or chat needs attention |
| Done · no more runs | A one-time task has finished |
| Paused | Turn it back on if you want future runs |
In the history, **Open conversation** opens an Agent run, **Copy result** copies its output, and **Send again** sends the result to the configured chat again, as a real message.
## Scheduling details
* Tasks run on your Mac, so Enconvo must be running and your Mac awake. A sleeping or offline Mac doesn't run tasks; don't rely on it as an always-on scheduler.
* Times are in your Mac's local time zone. Check the next-run times after travel or a time-zone change.
* A one-time task needs a future time and moves to **Finished** after it runs.
* Monthly tasks on the 29th to 31st skip months without that date.
* Mac notifications also follow **Send a system notification** in [Notifications](/configuration/notifications) and macOS Focus. A notification is skipped when you're already looking at that run.
* Run history keeps recent runs only. Copy anything important before deleting a task.
Related: [IM Channels](/integrations/messaging), [Agents](/ai/agents), [Notifications](/configuration/notifications), [Workflows](/workflows/introduction).
## Watch the steps
<video aria-label="Schedule a task">
<source type="video/mp4" />
[Download the walkthrough](/videos/guides/scheduled-tasks.mp4).
</video>
Open Scheduled, pick the Morning briefing starter, open a task's details, and open Edit details. The starter draft is not sent, nothing runs, and the example task was deleted after capture. This silent walkthrough uses real interface captures with pauses added for reading. The written steps above provide the same instructions.
# Variables
Source: https://docs.enconvo.ai/workflows/variables
Insert current input, app context, and dates into reusable prompts.
Variables supply changing values to prompts and preferences that support templating. Open **Settings → Agents → Variables** to browse the available variables.
## Available context
| Variable source | Value supplied |
| - | - |
| Input Text | Current SmartBar input |
| Selection Text | Text selected in the current app |
| Latest Clipboard | Most recent clipboard content |
| Active Application | Frontmost app information |
| Active Application Screenshot | Image of the frontmost window |
| Active Screen Screenshot | Image of the active screen |
| Focused Window Content | Content extracted from the focused window |
| Browser Active Tab | Active tab URL and available page content |
| Finder Current Directory | Current Finder folder |
| Finder Selected Files | Selected files in Finder |
| History Messages | Current conversation history |
| Now | Current date and time |
| Opened Applications / Names | Running app information |
## Use a variable
1. Open the AI Command, Agent instruction, or workflow field you want to customize.
2. Confirm that the field supports variables; use its picker when available.
3. Insert the appropriate value and test with harmless sample content.
4. Review whether an empty input or unavailable permission changes the result.
A text prompt can use supported template names such as:
```text theme={null}
Today is {{ now }}.
Rewrite the following input as a concise checklist:
{{ input_text }}
```
Variable availability depends on the command and context. Do not assume an ordinary text field evaluates templates. Screenshots and app content can require macOS permissions and a model that accepts the resulting input.
Related: [AI Commands](/features/ai-commands), [Context Awareness](/features/context-awareness), [Creating Workflows](/workflows/creating-workflows).