EnConvo

https://docs.enconvo.ai
Admin
EnConvo is a native macOS AI companion that is contextually aware of your screen and apps, providing...
Tokens:86,961
Snippets:1,524
Trust Score:3.8
Update:5 months ago
Show doc for...
Tokens:
Raw
### Python MCP Server Project Setup

Source: https://docs.enconvo.ai/advanced/mcp-advanced

Installs the MCP library for Python.

```bash
mkdir my-mcp-server
cd my-mcp-server
pip install mcp
```

--------------------------------

### TypeScript MCP Server Project Setup

Source: https://docs.enconvo.ai/advanced/mcp-advanced

Installs necessary dependencies for creating an MCP server in TypeScript.

```bash
mkdir my-mcp-server
cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk
npm install -D typescript @types/node
```

--------------------------------

### Execute Python Virtual Environment and Install Package

Source: https://docs.enconvo.ai/ai/code-runner

This example demonstrates how an AI agent can instruct the Code Runner to create a Python virtual environment and install a package using pip. Ensure the Python interpreter and pip are available in the environment.

```shell
python3 -m venv myenv
source myenv/bin/activate && pip install pandas
```

--------------------------------

### Install Skill from GitHub Repository

Source: https://docs.enconvo.ai/configuration/skills

Command to install a skill directly from a GitHub repository URL, supporting subdirectory paths.

```bash
/skill-installer https://github.com/anthropics/skills/tree/main/skills/pptx
```

--------------------------------

### Install Extension from GitHub

Source: https://docs.enconvo.ai/extensions/overview

Clone an extension repository from GitHub and install it into EnConvo by pointing to the local folder.

```bash
# Clone extension repository
git clone https://github.com/enconvo/extension-name

# Install in EnConvo
# Settings → Extensions → Install from folder
```

--------------------------------

### Install Skill from EnConvo Skills Store

Source: https://docs.enconvo.ai/configuration/skills

Command to install a skill by its name from the EnConvo Skills Store.

```bash
/skill-installer pdf
```

--------------------------------

### Loop Example: Process URLs

Source: https://docs.enconvo.ai/workflows/advanced-workflows

An example demonstrating how to loop through a list of URLs, fetch content from each, and summarize the fetched content.

```text
URL List → Loop Items (for each url)
             → Web Fetch ({{current_item}})
             → Summarize ({{fetch_result}})
           → Collect Summaries → Format Report
```

--------------------------------

### Initialize New EnConvo Extension

Source: https://docs.enconvo.ai/extensions/developing

Use this command to create a new EnConvo extension project. Navigate into the created directory and install dependencies.

```bash
npx create-enconvo-extension my-extension
cd my-extension
npm install
```

--------------------------------

### Access Extensions via SmartBar

Source: https://docs.enconvo.ai/extensions/overview

Use a forward slash '/' prefix in the SmartBar to quickly invoke installed extensions with their commands.

```bash
/translate Hello world to Spanish
/code explain this function
/image a sunset over mountains
/summarize this article
```

--------------------------------

### Example Image Generation Prompts

Source: https://docs.enconvo.ai/ai/image-generation

Use these prompts in SmartBar to generate various types of images. Simply type /image followed by your description.

```text
/image A serene mountain lake at sunset with snow-capped peaks
/image Minimalist logo for a tech startup, blue and white colors
/image Cute cartoon cat sitting on a stack of books
/image Professional headshot of a friendly robot in a business suit
```

--------------------------------

### Install Ollama using Homebrew

Source: https://docs.enconvo.ai/providers/ollama

Use this command to install Ollama on macOS via Homebrew.

```bash
brew install ollama
```

--------------------------------

### Skill Directory Structure Example

Source: https://docs.enconvo.ai/configuration/skills

A typical skill directory includes a SKILL.md file for instructions and metadata, along with optional scripts, references, and assets.

```tree
my-skill/
├── SKILL.md          # Required: instructions + metadata
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
└── assets/           # Optional: templates, resources
```

--------------------------------

### Provider Selection Example

Source: https://docs.enconvo.ai/extensions/built-in-extensions

Demonstrates how consumer extensions target specific provider extensions using a command key format. Configure default providers in extension settings or let AI agents choose automatically.

```plaintext
chat_with_ai (consumer) → llm|open_ai (provider)
tts (consumer) → tts_providers|openai_tts_provider (provider)
translate (consumer) → translate_providers|deepl_translate_provider (provider)
```

--------------------------------

### SmartBar Built-in Calculator Examples

Source: https://docs.enconvo.ai/features/smartbar

Type mathematical expressions directly into the SmartBar input to get instant results. Supports standard arithmetic, trigonometric functions, and more. Press Enter to copy the result.

```text
2+3*4       → 14
```

```text
sqrt(144)   → 12
```

```text
sin(45)     → 0.7071...
```

```text
100/3       → 33.333...
```

--------------------------------

### MCP Store Manifest Example

Source: https://docs.enconvo.ai/advanced/mcp-advanced

Define a manifest for publishing an MCP server to the store, including name, version, description, transport, command, and configuration options.

```json
{
  "name": "my-awesome-server",
  "version": "1.0.0",
  "description": "Does awesome things with AI",
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "my-awesome-server"],
  "config": {
    "api_key": {
      "type": "password",
      "description": "Your API key for the awesome service",
      "required": true
    }
  }
}
```

--------------------------------

### Apple Mail Usage Examples

Source: https://docs.enconvo.ai/integrations/apple-ecosystem

These examples demonstrate how to interact with the Apple Mail integration using natural language commands. They cover actions like viewing emails, composing new messages, and archiving messages.

```text
"Show me my unread emails"
```

```text
"Send an email to alice@example.com about the project deadline"
```

```text
"Archive all emails from notifications@github.com"
```

```text
"What did Bob say in his last email?"
```

--------------------------------

### Manual Extension Installation Path

Source: https://docs.enconvo.ai/features/browser-control

Specifies the directory path for manually loading the Enconvo Companion extension. Ensure Enconvo is restarted if the folder does not exist.

```bash
~/.enconvo/chrome_extension/
```

--------------------------------

### Example Questions for Recording Analysis

Source: https://docs.enconvo.ai/features/meeting-recording

Ask specific questions about meeting content to get precise answers. This feature leverages semantic search against transcriptions to retrieve relevant information.

```text
What did we decide about the pricing strategy?
Who is responsible for the design mockups?
What was the timeline discussed for the product launch?
Did anyone mention concerns about the budget?
Summarize what Speaker 2 said about customer feedback
What were the main disagreements in the meeting?
```

--------------------------------

### Example Text-to-Video Prompt

Source: https://docs.enconvo.ai/ai/video-generation

Use this structure for creating effective text-to-video prompts. Ensure prompts are in English and include subject, action, setting, style, and camera movement.

```text
A golden retriever running through a field of wildflowers at sunset,
slow motion, cinematic lighting, warm tones
```

```text
A futuristic city skyline at night with flying cars and neon lights,
drone shot sweeping across the buildings, cyberpunk aesthetic
```

```text
A cup of coffee being poured in slow motion, close-up shot,
steam rising, soft morning light through a window
```

--------------------------------

### Load and Get Command Configuration

Source: https://docs.enconvo.ai/extensions/extension-api-reference

Use CommandManageUtils to load a command's full configuration or get raw command info synchronously.

```typescript
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");
```

--------------------------------

### Pull a Local LLM Model with Ollama

Source: https://docs.enconvo.ai/configuration/privacy-security

Use this command to download and install a local language model for offline use with EnConvo. Ensure Ollama is installed first.

```bash
ollama pull llama3.2
```

--------------------------------

### SKILL.md Frontmatter Example

Source: https://docs.enconvo.ai/configuration/skills

The SKILL.md file requires a frontmatter block with 'name' and 'description' fields to define the skill's identity and trigger conditions.

```markdown
---
name: my-skill
description: Explain exactly when this skill should and should not trigger.
---

Step-by-step instructions for EnConvo to follow.
```

--------------------------------

### Check Node.js Version

Source: https://docs.enconvo.ai/getting-started/troubleshooting

Verify your installed Node.js version. EnConvo requires Node.js 18 or higher. Update if necessary.

```bash
node --version
```

```bash
brew install node
```

--------------------------------

### Write a Simple Command Handler

Source: https://docs.enconvo.ai/extensions/developing

Implement the `Command` interface in `src/index.ts` to handle extension commands. This example shows a command that displays a toast notification and returns a greeting.

```typescript
import { Command, showToast } from '@enconvo/api';

export default class HelloCommand implements Command {
  async run(input: string): Promise<string> {
    showToast({ title: 'Hello!', message: input });
    return `Hello, ${input || 'World'}!`;
  }
}
```

--------------------------------

### Run Extension in Development Mode

Source: https://docs.enconvo.ai/extensions/developing

Use 'npm run dev' to start your extension with hot reload enabled for a faster development cycle.

```bash
npm run dev
```

--------------------------------

### Agent Output Format Example

Source: https://docs.enconvo.ai/ai/agents

Specifies the desired output structure for an agent. This ensures consistent and usable results, especially for structured data.

```markdown
# Output Format
**Subject:** [suggested subject line]

[email body]

---
**Tone:** [formal/casual/neutral]
**Word count:** [count]
```

--------------------------------

### Full-Text Search Example

Source: https://docs.enconvo.ai/advanced/knowledge-base-advanced

Demonstrates how full-text search with fuzzy matching can be used for keyword-based retrieval in LanceDB.

```text
Query "OAuth2 PKCE flow"
  → Full-text index lookup with fuzziness
  → Return matching chunks
```

--------------------------------

### Apple Shortcuts Integration

Source: https://docs.enconvo.ai/integrations/apple-ecosystem

Run any installed Apple Shortcut directly from EnConvo by using natural language commands. Supports text input and output.

```text
"Run my 'Morning Routine' shortcut"
```

```text
"List all my shortcuts"
```

```text
"Execute the 'Resize Image' shortcut with the file on my desktop"
```

--------------------------------

### Changelog Generator Skill Example

Source: https://docs.enconvo.ai/configuration/skills

This skill generates a changelog from git commits, categorizing them into features, fixes, and breaking changes. It includes a detailed output format example.

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

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

```
```

--------------------------------

### Transcription Output Example

Source: https://docs.enconvo.ai/features/meeting-recording

This is an example of the structured transcription output, showing timestamps, speaker labels, and dialogue segments.

```plaintext
[00:00:12] Speaker 1: Let's start with the Q3 review. Revenue
is up 15% compared to last quarter.

[00:00:28] Speaker 2: That's great. Can you break down the
growth by product line?

[00:00:35] Speaker 1: Sure. The cloud platform grew 22%,
while consulting services grew 8%.

[00:01:02] Speaker 3: What about customer retention rates?
```

--------------------------------

### Vector Similarity Search Example

Source: https://docs.enconvo.ai/advanced/knowledge-base-advanced

Illustrates the process of embedding a query and comparing it against stored vectors to find semantically similar chunks.

```text
Query "How does authentication work?"
  → Embed query → [0.12, -0.45, 0.78, ...]
  → Compare against all chunk vectors
  → Return top-K most similar chunks
```

--------------------------------

### Agent Behavior Definition Example

Source: https://docs.enconvo.ai/ai/agents

Outlines the expected behavior and constraints for an agent. This helps in shaping the agent's interaction style and output quality.

```markdown
# Behavior
- Ask clarifying questions before writing (recipient, purpose, tone)
- Default to professional but friendly tone
- Keep emails concise -- under 200 words when possible
- Include a clear subject line suggestion
- Offer formal and casual variants when tone is ambiguous
```

--------------------------------

### Explicit Skill Invocation Examples

Source: https://docs.enconvo.ai/configuration/skills

Skills can be invoked directly in the prompt using a '/' prefix followed by the skill name and a query. This ensures the desired skill is used.

```bash
/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
```

--------------------------------

### NativeAPI.callCommand

Source: https://docs.enconvo.ai/extensions/extension-api-reference

Invoke any other extension command programmatically. This allows extensions to interact with and trigger functionalities of other installed extensions.

```APIDOC
## NativeAPI.callCommand

### Description
Invoke any other extension command programmatically.

### Method Signature
`NativeAPI.callCommand(commandId: string, payload?: any): Promise<any>`

### Parameters
#### Path Parameters
- **commandId** (string) - Required - The unique identifier of the command to invoke.
- **payload** (any) - Optional - The data to pass to the command.

### Request Example
```typescript
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"
});
```
```

--------------------------------

### Create Custom MCP Server with TypeScript

Source: https://docs.enconvo.ai/features/mcp

Use this snippet to define and start a custom MCP server in TypeScript. It includes defining a tool and connecting to the transport layer.

```typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new McpServer({
  name: "my-custom-server",
  version: "1.0.0"
});

// Define a tool
server.tool(
  "get_weather",
  "Get current weather for a city",
  { city: { type: "string", description: "City name" } },
  async ({ city }) => {
    const weather = await fetchWeather(city);
    return {
      content: [{ type: "text", text: JSON.stringify(weather) }]
    };
  }
);

// Start the server
const transport = new StdioServerTransport();
await server.connect(transport);
```

--------------------------------

### Variable Usage Examples

Source: https://docs.enconvo.ai/workflows/creating-workflows

Reference data between actions using double curly braces. Available variables include original input, step outputs, clipboard content, and current date.

```text
{{input}}
{{step1.output}}
{{clipboard}}
{{date}}
{{selection}}
```

--------------------------------

### Multiple Hooks for One Event

Source: https://docs.enconvo.ai/configuration/hooks

Configure multiple hooks to execute concurrently for a single event. This example shows a mix of command and HTTP hooks.

```json
{
  "run_status_changed": [
    {
      "hooks": [
        { "type": "command", "command": "echo 'log' >> /tmp/hooks.log" },
        { "type": "http", "url": "http://localhost:8080/webhook" },
        { "type": "command", "command": "bash ~/.config/enconvo/hooks/notify.sh" }
      ]
    }
  ]
}
```

--------------------------------

### Workflow Example: Research Document Processing

Source: https://docs.enconvo.ai/advanced/knowledge-base-advanced

This workflow demonstrates how to automate the process of adding research documents to a knowledge base, searching for related content, generating a summary, and saving it.

```yaml
Trigger: New file in ~/Documents/research/
  → Add to Knowledge Base "research"
  → Search for related content
  → Generate summary
  → Save summary to notes
```

--------------------------------

### Single File API Route

Source: https://docs.enconvo.ai/extensions/extension-api-reference

Files in `src/api/` are auto-discovered as API routes. This example shows a simple status endpoint.

```typescript
// src/api/status.ts
export default async function main(request: Request) {
  return Response.json({ status: "ok", uptime: process.uptime() });
}
```

--------------------------------

### Read OpenClaw Gateway Token

Source: https://docs.enconvo.ai/providers/openclaw

Use this command to extract the Gateway token from the default OpenClaw configuration file. Ensure the `jq` utility is installed.

```bash
jq -r '.gateway.auth.token' ~/.openclaw/openclaw.json
```

--------------------------------

### Context Detection Pipeline

Source: https://docs.enconvo.ai/advanced/context-awareness-deep-dive

This diagram outlines the steps Enconvo takes to gather context when invoked. It starts with user interaction and proceeds through detecting the application, window title, selected text, and specific content from browsers, code editors, or Finder before assembling a context object for the AI.

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

--------------------------------

### Agent Role Definition Example

Source: https://docs.enconvo.ai/ai/agents

Defines a specific role for an agent to ensure focused and expert responses. Use this to guide the agent's persona and expertise.

```markdown
# Role
Professional email writer for business communication.
```

--------------------------------

### Generate API Documentation

Source: https://docs.enconvo.ai/configuration/skills

This skill generates API documentation from source code, focusing on endpoints or public functions. It documents method/path, description, parameters, response, and errors, formatting output in markdown with curl examples for HTTP endpoints.

```markdown
---
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" }
````

```

```

--------------------------------

### Agent Invocation from SmartBar

Source: https://docs.enconvo.ai/ai/agents

Demonstrates how to invoke agents directly from the SmartBar using the '@' prefix followed by the agent's name and query.

```bash
@deep-research What are the current trends in AI regulation?
@code-reviewer Review this pull request for security issues
@my-custom-bot Analyze the Q4 sales report
```

--------------------------------

### Create Custom MCP Server with Python

Source: https://docs.enconvo.ai/features/mcp

This Python snippet demonstrates how to create a custom MCP server, define a tool using a decorator, and run the server using stdio transport.

```python
from mcp.server import Server
from mcp.server.stdio import stdio_server

server = Server("my-custom-server")

@server.tool()
async def get_weather(city: str) -> str:
    """Get current weather for a city."""
    weather = await fetch_weather(city)
    return json.dumps(weather)

async def main():
    async with stdio_server() as (read, write):
        await server.run(read, write)
```

--------------------------------

### Basic Python MCP Server Implementation

Source: https://docs.enconvo.ai/advanced/mcp-advanced

Defines a simple MCP server with 'hello' and 'search_records' tools using the `mcp` library.

```python
import json
from mcp.server import Server
from mcp.server.stdio import stdio_server

server = Server("my-custom-server")


@server.tool()
async def hello(name: str) -> str:
    """Say hello to someone.

    Args:
        name: Person's name
    """
    return f"Hello, {name}!"


@server.tool()
async def search_records(
    query: str,
    limit: int = 10,
    category: str = "all"
) -> str:
    """Search records in the database.

    Args:
        query: Search query
        limit: Max results to return
        category: Filter by category (all, active, archived)
    """
    results = await perform_search(query, limit, category)
    return json.dumps(results, indent=2)


async def main():
    async with stdio_server() as (read, write):
        await server.run(read, write)


if __name__ == "__main__":
    import asyncio
    asyncio.run(main())
```

--------------------------------

### Run React Project Build

Source: https://docs.enconvo.ai/ai/code-runner

Use this command to build a React project and check for errors. The agent will execute the build and report the status.

```shell
npm run build
```

--------------------------------

### Referencing Documentation in Instructions

Source: https://docs.enconvo.ai/configuration/skills

Shows how to reference external documentation files within skill instructions using markdown.

```markdown
Consult `references/api-docs.md` for the API schema before making requests.
```

--------------------------------

### SKILL.md Frontmatter and Instructions

Source: https://docs.enconvo.ai/configuration/skills

Defines the skill's name, description, and provides step-by-step instructions for the AI. Use instruction-only skills unless deterministic behavior or external tooling is required.

```markdown
---
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.
```

--------------------------------

### environment

Source: https://docs.enconvo.ai/extensions/extension-api-reference

Access runtime context about the current command execution, including extension details, development status, and user interface settings.

```APIDOC
## environment

### Description
The `environment` object exposes runtime context about the current command execution.

### Properties
- **extensionName** (string): Current extension name.
- **commandName** (string): Current command name.
- **commandTitle** (string): Display title of the command.
- **assetsPath** (string): Path to extension's assets/ directory.
- **supportPath** (string): Per-extension support directory.
- **rootSupportPath** (string): Root support directory.
- **cachePath** (string): Cache directory.
- **isDevelopment** (boolean): true if running in dev mode.
- **appearance** (string): "light" | "dark".
- **textSize** (string): "medium" | "large".
- **chatConversationId** (string): Current conversation ID.
- **chatSessionId** (string): Current session ID.
- **enconvoVersion** (string): EnConvo app version.
- **runType** (string): "command" | "api" | "flow".
- **flowId** (string): Workflow ID (if running in a workflow).

### Usage Example
```typescript
import { environment } from "@enconvo/api";

console.log(environment.extensionName);
console.log(environment.isDevelopment);
```
```

--------------------------------

### Build and Test Extension

Source: https://docs.enconvo.ai/extensions/developing

Use `npm run build` to compile your extension and `npm run dev` for hot reloading during development.

```bash
npm run build
npm run dev  # Hot reload during development
```

--------------------------------

### Run Go Program

Source: https://docs.enconvo.ai/ai/code-runner

Compile and run a Go program using the 'go run' command. Ensure the Go source file is present in the working directory.

```shell
go run main.go
```

--------------------------------

### Custom Server Configuration

Source: https://docs.enconvo.ai/advanced/mcp-advanced

Define a custom server with a name, transport type, command, and arguments.

```json
{
  "name": "my-custom-server",
  "transport": "stdio",
  "command": "python",
  "args": ["/path/to/my-mcp-server/server.py"]
}
```

--------------------------------

### Add a stdio MCP Server

Source: https://docs.enconvo.ai/features/mcp

Configure a local MCP server that runs as a Node.js process. Specify the command, arguments, and any necessary paths.

```json
{
  "name": "filesystem",
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Documents"]
}
```

--------------------------------

### Dynamic Configuration with Template Strings

Source: https://docs.enconvo.ai/advanced/mcp-advanced

Use template strings for dynamic values in command, arguments, and environment variables, referencing built-in variables like `__dirname` and `HOME`, and user-provided configurations.

```json
{
  "command": "node",
  "args": ["${__dirname}/server.js"],
  "env": {
    "HOME": "${HOME}",
    "CUSTOM_SETTING": "${user_config.custom_setting}"
  }
}
```

--------------------------------

### Directory Route API Endpoint

Source: https://docs.enconvo.ai/extensions/extension-api-reference

Directory routes in `src/api/` enable auto-generated routers. This example defines a user list endpoint with parameter validation.

```typescript
// 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 });
}
```

--------------------------------

### Commander.addClickListener

Source: https://docs.enconvo.ai/extensions/extension-api-reference

Registers the main entry point handler for a command. This is the primary way to define what happens when a command is invoked.

```APIDOC
## Commander.addClickListener

### Description
Registers the main entry point handler for a command. This is the primary way to define what happens when a command is invoked.

### Method
```typescript
Commander.addClickListener(async (req: Request) => {
  const options = await req.json();
  // Process the request
  return EnconvoResponse.text("Hello from my extension!");
});
```

### Parameters
#### Request
- **req** (Request) - The incoming request object.
  - **req.json()**: Parses the request body as JSON, containing `RequestOptions`.

### Response
- The return value of the handler function determines the response to the EnConvo host.
```

--------------------------------

### Compile and Run C/C++ Program

Source: https://docs.enconvo.ai/ai/code-runner

Compile a C/C++ source file into an executable and then run it. Ensure the C/C++ compiler (like gcc) is available.

```shell
gcc -o app main.c && ./app
```

--------------------------------

### Check Extension Path and Package JSON

Source: https://docs.enconvo.ai/getting-started/troubleshooting

Verify that the extension directory exists at the specified path and contains a package.json file. This helps diagnose 'Extension not found' errors.

```bash
ls ~/.config/enconvo/extension/{extensionName}/
```

--------------------------------

### Configure Extension Metadata

Source: https://docs.enconvo.ai/extensions/developing

Edit the `package.json` file to define your extension's name, display name, description, version, and commands.

```json
{
  "name": "my-extension",
  "displayName": "My Extension",
  "description": "My custom EnConvo extension",
  "version": "1.0.0",
  "enconvo": {
    "commands": [
      {
        "name": "hello",
        "title": "Say Hello",
        "description": "A simple hello command"
      }
    ]
  }
}
```

--------------------------------

### Run Workflow from SmartBar

Source: https://docs.enconvo.ai/workflows/introduction

Execute a workflow from the SmartBar by typing the command followed by the workflow name and optional arguments.

```bash
/workflow [workflow-name]
/workflow Research Summary "AI in healthcare"
```

--------------------------------

### Call TTS API via HTTP POST

Source: https://docs.enconvo.ai/changelog

Example of how to call the Text-to-Speech (TTS) API using curl. Ensure the correct Content-Type and JSON payload are provided.

```bash
curl -X POST "http://localhost:54535/tts/tts" \
     -H 'Content-Type: application/json' \
     -d '{ "input_text": "hello, world" }'
```

--------------------------------

### Build Extension Commands

Source: https://docs.enconvo.ai/extensions/extension-api-reference

Command-line interface commands for building, developing, and publishing Enconvo extensions.

```bash
# Build for production
npx enconvo build

# Dev mode with hot reload
npx enconvo build --dev

# Generate API schema
npx enconvo generate-schema

# Generate API docs + schema
npx enconvo generate-docs

# Publish to store
npx enconvo publish
```

--------------------------------

### Basic TypeScript MCP Server Implementation

Source: https://docs.enconvo.ai/advanced/mcp-advanced

Defines a simple MCP server with 'hello' and 'search_records' tools. Requires `@modelcontextprotocol/sdk`.

```typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new McpServer({
  name: "my-custom-server",
  version: "1.0.0",
});

// Define a simple tool
server.tool(
  "hello",
  "Say hello to someone",
  {
    name: { type: "string", description: "Person's name" },
  },
  async ({ name }) => {
    return {
      content: [{ type: "text", text: `Hello, ${name}!` }],
    };
  }
);

// Define a tool with complex input
server.tool(
  "search_records",
  "Search records in the database",
  {
    query: { type: "string", description: "Search query" },
    limit: { type: "number", description: "Max results to return" },
    category: {
      type: "string",
      description: "Filter by category",
      enum: ["all", "active", "archived"],
    },
  },
  async ({ query, limit = 10, category = "all" }) => {
    // Your search logic here
    const results = await performSearch(query, limit, category);
    return {
      content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
    };
  }
);

// Start the server with stdio transport
const transport = new StdioServerTransport();
await server.connect(transport);
```

--------------------------------

### AI Prompt Configuration

Source: https://docs.enconvo.ai/workflows/creating-workflows

Configure an AI Prompt action to summarize input text. Use {{input}} to reference the data passed to this action.

```text
Summarize the following in 3 bullet points:
{{input}}
```

--------------------------------

### Test MCP Server Locally with Stdin

Source: https://docs.enconvo.ai/advanced/mcp-advanced

Run your server standalone and send test messages via stdin to verify tool definitions and responses before connecting it to EnConvo.

```bash
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node dist/index.js
```

--------------------------------

### Conditional Logic Example

Source: https://docs.enconvo.ai/workflows/creating-workflows

Implement conditional branching in workflows using YAML. The 'if' condition checks a variable's value, and 'then'/'else' specify actions based on the outcome.

```yaml
condition:
  if: "{{input.length}} > 1000"
  then: use_summary_action
  else: use_full_text
```

--------------------------------

### Quick Reference Card

Source: https://docs.enconvo.ai/configuration/keyboard-shortcuts

A quick reference for common EnConvo shortcuts. Print or bookmark this for easy access.

```text
SmartBar:       Shift + Cmd + D
```

```text
PopBar:         Shift + Cmd + Space
```

```text
Companion Bar:  Shift + Cmd + E
```

```text
Dictation:      Shift + Cmd + M
```

```text
New Chat:       Cmd + N (in SmartBar)
```

```text
Settings:       Cmd + ,
```

```text
Send Message:   Enter
```

```text
Add Context:    # (in SmartBar)
```

```text
Add Tool:       @ (in SmartBar)
```

```text
Use Skill:      / (in SmartBar)
```

```text
Copy Response:  Cmd + Shift + C
```

--------------------------------

### ServiceProvider.load

Source: https://docs.enconvo.ai/extensions/extension-api-reference

Load and instantiate any provider extension dynamically.

```APIDOC
## ServiceProvider.load

Load and instantiate any provider extension dynamically.

### Description
Allows for the dynamic loading and instantiation of provider extensions, such as LLM or TTS providers, based on specified options.

### Usage
```typescript
import { ServiceProvider, LLMProvider, TTSProvider } from "@enconvo/api";

// Load an LLM provider
const llm = ServiceProvider.load<LLMProvider>(options);

// Load a TTS provider
const tts = ServiceProvider.load<TTSProvider>(options);
```

The `options` object must include `extensionName` and `commandName` identifying the provider to load. Provider instances are cached by their options hash for reuse.
```

--------------------------------

### Interacting with Elements using References

Source: https://docs.enconvo.ai/features/browser-control

Interact with specific elements on a page using their unique @eN references. Ensure the page is snapshotted after any navigation or DOM changes to get updated references.

```text
click @e6
```

```text
fill @e5 "my search term"
```

```text
get_text @e4
```

--------------------------------

### Skill Directory Structure

Source: https://docs.enconvo.ai/configuration/skills

Illustrates the expected file and directory structure for a skill, including documentation and script files.

```tree
my-skill/
├── SKILL.md
├── references/
│   ├── api-docs.md
│   └── examples.md
└── scripts/
└── run.sh
```

--------------------------------

### Extension and Command Management Utilities

Source: https://docs.enconvo.ai/extensions/extension-api-reference

Utilities for working with extension metadata and configuration, including loading command configurations and retrieving raw command information.

```APIDOC
## 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");
```
```

--------------------------------

### Common Extension Hotkeys

Source: https://docs.enconvo.ai/configuration/keyboard-shortcuts

These are suggested shortcuts for popular extensions. They can be configured in the extension's preferences.

```text
Translate    Cmd + Shift + T  Translate selected text
```

```text
OCR          Cmd + Shift + O  Screenshot OCR
```

```text
Fix Spelling Cmd + Shift + G  Fix grammar on selected text
```

```text
Read Aloud   Cmd + Shift + R  Read selected text aloud
```

```text
Web Search   Cmd + Shift + W  Search the web for selected text
```

--------------------------------

### Download popular Ollama models

Source: https://docs.enconvo.ai/providers/ollama

Quickly download commonly used models for various purposes like general use, coding, or speed.

```bash
ollama pull llama3.1        # General purpose
ollama pull codellama       # Coding
ollama pull mistral         # Fast
ollama pull phi3            # Lightweight
ollama pull gemma2          # Google's model
ollama pull qwen2           # Multilingual
```

--------------------------------

### Basic Loop Structure

Source: https://docs.enconvo.ai/workflows/advanced-workflows

Iterate over a list of items using the Loop Items node. Configure the input list, item variable name, and the body of actions to perform on each item. Results can be optionally collected into a new list.

```text
Input (list) → Loop Items → Process Each Item → Collect Results → Output
```

--------------------------------

### Implement a List Command

Source: https://docs.enconvo.ai/extensions/developing

A command that presents a selectable list of items to the user. Define the items in `getItems` and handle the selection in `onSelect`.

```typescript
import { List, ListCommand } from '@enconvo/api';

export default class ListCommand implements ListCommand {
  async getItems(query: string): Promise<ListItem[]> {
    return [
      { title: 'Item 1', subtitle: 'Description', value: '1' },
      { title: 'Item 2', subtitle: 'Description', value: '2' }
    ];
  }
  
  async onSelect(item: ListItem): Promise<string> {
    return `Selected: ${item.value}`;
  }
}
```

--------------------------------

### Command Entry Point Patterns

Source: https://docs.enconvo.ai/extensions/extension-api-reference

Defines patterns for command entry points, including standard commands, provider commands, and API routes.

```APIDOC
## 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<EnconvoResponse> {
  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" });
}
```
```

--------------------------------

### Show Git Changes

Source: https://docs.enconvo.ai/ai/code-runner

Execute this command to display a summary of file changes since the last commit. Useful for reviewing modifications before committing.

```shell
git diff --stat HEAD
```

--------------------------------

### Import UI Extension APIs

Source: https://docs.enconvo.ai/extensions/developing

Import UI components from `@enconvo/ui` to create interactive user interfaces within your extension.

```typescript
import {
  Form,
  List,
  Detail,
  Action,
} from '@enconvo/ui';
```

--------------------------------

### Force Local Model Usage

Source: https://docs.enconvo.ai/ai/local-llm

Prefix your prompt with '@local' to ensure the query is processed by a local model, bypassing cloud-based options.

```bash
@local Explain this code snippet
```

--------------------------------

### Configure Environment Variables for Secrets

Source: https://docs.enconvo.ai/advanced/mcp-advanced

Never hardcode API keys or secrets in your server code. Use the `env` configuration to pass them securely. Values can reference user configuration.

```json
{
  "env": { "API_KEY": "${user_config.api_key}" }
}
```

--------------------------------

### Check Extension Minimum App Version

Source: https://docs.enconvo.ai/getting-started/troubleshooting

Examine the extension's package.json to ensure it's compatible with your EnConvo version. Update EnConvo if it's older than the required minimum version.

```json
"minAppVersion": "1.8.8"
```

--------------------------------

### Write SKILL.md Bash Command

Source: https://docs.enconvo.ai/configuration/skills

This command uses 'cat' to create and write content to the SKILL.md file, defining a skill's metadata and instructions.

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

--------------------------------

### Schedule Workflow to Run Daily at 9 AM

Source: https://docs.enconvo.ai/workflows/advanced-workflows

Set up a workflow to execute every day at 9 AM using a cron expression. The workflow must be saved and enabled to run on schedule.

```cron
0 9 * * *
```

--------------------------------

### Configure OpenClaw Gateway Bind Mode

Source: https://docs.enconvo.ai/providers/openclaw

Configure the OpenClaw Gateway's bind mode. Use 'loopback' for local-only access or 'lan' to allow other devices on your network to reach the Gateway.

```bash
openclaw config set gateway.bind lan
```

--------------------------------

### Register Extension Command Listener

Source: https://docs.enconvo.ai/extensions/extension-api-reference

Register the main entry point for a command. Use `req.json()` to access merged command configuration and user parameters. This is the primary way to define extension behavior.

```typescript
import { Commander } from "@enconvo/api";

Commander.addClickListener(async (req: Request) => {
  const options = await req.json();
  // Process the request
  return EnconvoResponse.text("Hello from my extension!");
});
```

--------------------------------

### Dynamically load provider extensions with ServiceProvider.load

Source: https://docs.enconvo.ai/extensions/extension-api-reference

Use `ServiceProvider.load` to dynamically load and instantiate provider extensions like LLM or TTS providers. The `options` object must include `extensionName` and `commandName`.

```typescript
import { ServiceProvider } from "@enconvo/api";

// Load an LLM provider
const llm = ServiceProvider.load<LLMProvider>(options);

// Load a TTS provider
const tts = ServiceProvider.load<TTSProvider>(options);
```

--------------------------------

### Provider Command Entry Point

Source: https://docs.enconvo.ai/extensions/extension-api-reference

Defines the entry point for a provider command, typically returning an instance of a provider class.

```typescript
// src/my_provider.ts
export default function main(options: any) {
  return new MyProvider(options);
}
```

--------------------------------

### Implement a Simple Command

Source: https://docs.enconvo.ai/extensions/developing

A simple command that processes input and returns a string output. This is the most basic type of command.

```typescript
export default class SimpleCommand implements Command {
  async run(input: string): Promise<string> {
    // Process input and return result
    return `Processed: ${input}`;
  }
}
```

--------------------------------

### Run Swift Script

Source: https://docs.enconvo.ai/ai/code-runner

Execute a Swift script using the swift interpreter. Ensure the script is present in the working directory.

```shell
swift script.swift
```

--------------------------------

### Create Skill Directory Bash Command

Source: https://docs.enconvo.ai/configuration/skills

Use this command to create a new directory for your skill within the user's skill directory.

```bash
mkdir -p ~/.agents/skills/my-skill
```

--------------------------------

### Pull Llama 3 Model with Ollama

Source: https://docs.enconvo.ai/ai/local-llm

Use this command to download the Llama 3 model for use with Ollama.

```bash
ollama pull llama3
```

--------------------------------

### TypeScript MCP Server Build and Run Commands

Source: https://docs.enconvo.ai/advanced/mcp-advanced

Commands to compile the TypeScript code and run the MCP server.

```bash
npx tsc
node dist/index.js
```

--------------------------------

### Referencing a Script in SKILL.md

Source: https://docs.enconvo.ai/configuration/skills

Demonstrates how to reference and execute a shell script from within the skill's instructions. The script is called with a URL argument.

```markdown
---
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.

```
```

--------------------------------

### Convert PNG to JPEG with Python

Source: https://docs.enconvo.ai/ai/code-runner

This command executes a Python script to convert all PNG files in the Downloads folder to JPEG format. Ensure the script is saved as 'convert_images.py'.

```python
python3 convert_images.py
```

--------------------------------

### Enable OpenClaw Chat Completions API

Source: https://docs.enconvo.ai/providers/openclaw

Enable the OpenAI-compatible chat completions endpoint for the OpenClaw Gateway. This is a one-time configuration step.

```bash
openclaw config set gateway.http.endpoints.chatCompletions.enabled true
```

--------------------------------

### Stdio Transport Configuration

Source: https://docs.enconvo.ai/advanced/mcp-advanced

Configure the stdio transport for local servers, including command, arguments, and environment variables.

```json
{
  "transport": "stdio",
  "command": "node",
  "args": ["server.js"],
  "env": {
    "API_KEY": "your-api-key"
  }
}
```

--------------------------------

### Run Rust Program with Cargo

Source: https://docs.enconvo.ai/ai/code-runner

Compile and run a Rust program using Cargo. Ensure the Cargo project is set up in the working directory.

```shell
cargo run
```

--------------------------------

### Standard Command Entry Point

Source: https://docs.enconvo.ai/extensions/extension-api-reference

Defines the standard entry point for a command, processing input and returning a response.

```typescript
// src/my_command.ts
import { Commander, EnconvoResponse } from "@enconvo/api";

export default async function main(req: Request): Promise<EnconvoResponse> {
  const options = await req.json();
  const result = processInput(options.input_text);
  return EnconvoResponse.text(result);
}
```

--------------------------------

### Verify Ollama is Running

Source: https://docs.enconvo.ai/getting-started/troubleshooting

Use this command to check if the Ollama service is active. Ensure Ollama is running before attempting to connect.

```bash
ollama list
```

--------------------------------

### Import Storage Extension APIs

Source: https://docs.enconvo.ai/extensions/developing

Import storage classes from `@enconvo/storage` for managing persistent local data and sensitive information.

```typescript
import {
  LocalStorage,
  SecureStorage,
} from '@enconvo/storage';
```

--------------------------------

### API Route - Single File

Source: https://docs.enconvo.ai/extensions/extension-api-reference

Files placed in `src/api/` are automatically discovered and registered as API routes. A single file defines a route directly.

```APIDOC
### 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() });
}
```
```

--------------------------------

### Implement a Form Command

Source: https://docs.enconvo.ai/extensions/developing

A command that displays a form to gather user input before executing its main logic. Define the form structure in `getForm` and process the values in `run`.

```typescript
import { Form, FormCommand } from '@enconvo/api';

export default class FormCommand implements FormCommand {
  async getForm(): Promise<Form> {
    return {
      fields: [
        { name: 'topic', type: 'text', label: 'Topic' },
        { name: 'length', type: 'dropdown', options: ['short', 'medium', 'long'] }
      ]
    };
  }
  
  async run(values: Record<string, any>): Promise<string> {
    return `Writing about ${values.topic} (${values.length})`;
  }
}
```

--------------------------------

### Implement TTSProvider for custom TTS extensions

Source: https://docs.enconvo.ai/extensions/extension-api-reference

Extend the `TTSProvider` base class to create custom Text-to-Speech extensions. Implement `_toFile` to convert text to audio and save it.

```typescript
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<TTSProvider.TTSItem> {
    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);
}
```

--------------------------------

### Import AI Extension APIs

Source: https://docs.enconvo.ai/extensions/developing

Import AI-related functions from `@enconvo/ai` to integrate AI capabilities into your extension.

```typescript
import {
  chat,
  complete,
  embed,
  generateImage,
} from '@enconvo/ai';
```

--------------------------------

### Looping Through Items

Source: https://docs.enconvo.ai/workflows/creating-workflows

Process multiple items using a loop. Specify the collection to iterate over with 'for_each', the action to perform, and how to 'collect' results.

```yaml
loop:
  for_each: "{{items}}"
  action: translate_action
  collect: translated_items
```

--------------------------------

### Debugging Hooks with Sample JSON

Source: https://docs.enconvo.ai/configuration/hooks

Test custom hook scripts by piping sample event JSON data to them. This is useful for verifying script logic and output.

```bash
echo '{"event":"run_status_changed","params":{"commandKey":"my_agent|main","runStatus":"failed"},"timestamp":1742313600000}' | bash ~/.config/enconvo/hooks/on-status-change.sh
```

--------------------------------

### Basic Command Hook Configuration

Source: https://docs.enconvo.ai/configuration/hooks

Configure a command to run when an agent's status changes. The command is executed automatically without needing to restart the service.

```json
{
  "run_status_changed": [
    {
      "hooks": [
        {
          "type": "command",
          "command": "echo 'Agent status changed!' >> /tmp/enconvo.log"
        }
      ]
    }
  ]
}
```

--------------------------------

### Check Disk Space

Source: https://docs.enconvo.ai/ai/code-runner

Use this command to check the available disk space on the root directory. The output provides filesystem details and free space.

```shell
df -h /
```
Tokens:
Raw