OCAYA

Web-first general-purpose AI assistant, powered by Mistral.

OCAYA is a command-line AI assistant that handles web research, document writing, file management, system automation, and more. It provides a conversational interface through a powerful set of tools, grounded in real-world information via built-in web search and fetch.

[!WARNING] OCAYA works on Windows, but we officially support and target UNIX environments.

One-line install (recommended)

Linux and macOS

curl -LsSf https://mistral.ai/vibe/install.sh | bash

Windows

First, install uv:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Then use uv:

uv tool install ocaya

Using pip

pip install ocaya

Table of Contents

• Features
  • Built-in Agents
  • Subagents and Task Delegation
  • Interactive User Questions
• Terminal Requirements
• Quick Start
• Usage
  • Interactive Mode
  • Trust Folder System
  • Programmatic Mode
• Voice Mode
• Slash Commands
  • Built-in Slash Commands
  • Custom Slash Commands via Skills
• Skills System
  • Creating Skills
  • Skill Discovery
  • Managing Skills
  • Bundled Skills
• Configuration
  • Configuration File Location
  • API Key Configuration
  • Custom System Prompts
  • Custom Agent Configurations
  • Tool Management
  • MCP Server Configuration
  • Session Management
  • Update Settings
  • Custom OCAYA Home Directory
• Editors/IDEs
• Resources
• Data collection & usage
• License

Features

• Web-First Research: OCAYA invokes websearch or webfetch before answering questions about current events, live data, or user-provided URLs — never relying on stale training-memory alone.
• General-Purpose: Handles web research, document writing, file and folder management, system automation, opening applications and URLs, clipboard operations, and general Q&A — not limited to coding tasks.
• Powerful Toolset: A suite of tools for file manipulation, code searching, version control, and command execution.
  • Read, write, and patch files (read, write_file, edit).
  • Execute shell commands in a stateful terminal (bash).
  • Recursively search code with grep (with ripgrep support).
  • Search the web (websearch) and fetch pages (webfetch).
  • Read from or write to the system clipboard (clipboard).
  • Open URLs, files, and applications (open_app).
  • Manage a todo list to track work.
  • Ask interactive questions (ask_user_question).
  • Delegate tasks to subagents (task).
  • Generate formatted documents as DOCX, PDF, or HTML (create_document).
• Project-Aware Context: OCAYA automatically scans your project's file structure and Git status to provide relevant context.
• Advanced CLI Experience: Built with modern libraries for a smooth workflow.
  • Autocompletion for slash commands (/) and file paths (@).
  • Image attachments via @ mentions.
  • Persistent command history.
  • Beautiful themes.
• Highly Configurable: Customize models, providers, tool permissions, and UI preferences through config.toml.
• Safety First: Features tool execution approval and hard limits on destructive operations.
• Multiple Built-in Agents: Choose from different agent profiles tailored for specific workflows.

Built-in Agents

OCAYA comes with several built-in agent profiles:

• default: Standard agent that requires approval for tool executions. Best for general use.
• plan: Read-only agent for exploration and planning.
• accept-edits: Auto-approves file edits only. Useful for code refactoring.
• auto-approve: Auto-approves all tool executions. Use with caution.

Use the --agent flag to select a different agent:

ocaya --agent plan

To change the default agent, set default_agent in your config.toml:

default_agent = "plan"

Valid values are default, plan, accept-edits, auto-approve, lean (only when listed in installed_agents), or the name of any custom agent file in ~/.ocaya/agents/ or .ocaya/agents/.

Note: default_agent only applies to interactive sessions. In programmatic mode (-p / --prompt), OCAYA falls back to auto-approve when --agent is not provided.

Subagents and Task Delegation

OCAYA supports subagents for delegating tasks. The task tool lets the agent delegate work to subagents:

> Can you explore the codebase structure?

🤖 I'll use the task tool to delegate this to the explore subagent.

> task(task="Analyze the project structure and architecture", agent="explore")

OCAYA comes with a built-in explore subagent — a read-only subagent for codebase exploration.

Interactive User Questions

The ask_user_question tool allows the agent to ask clarifying questions during its work:

> Can you help me refactor this function?

🤖 I need to understand your requirements better.

> ask_user_question(questions=[{
    "question": "What's the main goal of this refactoring?",
    "options": [
        {"label": "Performance", "description": "Make it run faster"},
        {"label": "Readability", "description": "Make it easier to understand"}
    ]
}])

Terminal Requirements

OCAYA's interactive interface requires a modern terminal emulator. Recommended:

• WezTerm (cross-platform)
• Alacritty (cross-platform)
• Ghostty (Linux and macOS)
• Kitty (Linux and macOS)

Quick Start

1. Navigate to your project directory:

   cd /path/to/your/project
   

2. Run OCAYA:

   ocaya
   

3. On first run, OCAYA will:

   • Create a default configuration at ~/.ocaya/config.toml
   • Prompt for your Mistral API key if not configured
   • Save your API key to ~/.ocaya/.env

   Alternatively, run ocaya --setup to configure separately.

4. Start interacting:

   > Search the web for the latest Python 3.13 release notes
   
   🤖 I'll use websearch to find the latest information.
   

Usage

Interactive Mode

Run ocaya to enter the interactive chat loop.

• Multi-line Input: Press Ctrl+J or Shift+Enter to insert a newline.
• File Paths: Reference files using @ for autocompletion (e.g., > Read @src/agent.py).
• Shell Commands: Prefix with ! to run directly (e.g., > !ls -l).
• External Editor: Press Ctrl+G to edit input in an external editor.
• Tool Output Toggle: Press Ctrl+O.
• Todo View Toggle: Press Ctrl+T.
• Debug Console: Press Ctrl+\.
• Agent Selection: Press Shift+Tab to cycle through agents.

Start with a prompt:

ocaya "Summarize the README and suggest improvements."

Trust Folder System

OCAYA includes a trust system. When running in a new directory containing a .ocaya subfolder, it will ask you to confirm trust. Trusted folders are remembered in ~/.ocaya/trusted_folders.toml.

Programmatic Mode

Run OCAYA non-interactively with --prompt:

ocaya --prompt "Find all TODO comments in the project and summarize them."

Programmatic Mode Options

• --max-turns N: Limit assistant turns.
• --max-price DOLLARS: Set a cost limit.
• --max-tokens N: Set a token budget.
• --enabled-tools TOOL: Enable specific tools only.
• --output FORMAT: text (default), json, or streaming.

ocaya --prompt "Analyze the codebase" --max-turns 5 --output json

Voice Mode

[!WARNING] Voice mode is experimental and may change in future releases.

Toggle voice mode with /voice. Use Ctrl+R to start recording, any key to stop, Escape to cancel.

Slash Commands

Use slash commands for meta-actions during a session. Type /help to see all available commands.

Custom Slash Commands via Skills

Define custom slash commands through the skills system by setting user-invocable: true in a skill's metadata.

Skills System

Skills extend OCAYA's functionality through reusable components. OCAYA follows the Agent Skills specification.

Creating Skills

Skills live in directories with a SKILL.md file. Example at ~/.ocaya/skills/research/SKILL.md:

---
name: research
description: Deep web research and summarisation workflow
user-invocable: true
allowed-tools:
  - websearch
  - webfetch
  - write_file
---

# Research Skill

This skill performs structured web research and writes a summary document.

Skill Discovery

OCAYA discovers skills from:

1. skill_paths in config.toml
2. .agents/skills/ in trusted project directories
3. .ocaya/skills/ in trusted project directories
4. ~/.ocaya/skills/ and ~/.agents/skills/ (global)

Managing Skills

enabled_skills = ["research", "custom-*"]
disabled_skills = ["experimental-*"]

Bundled Skills

OCAYA ships with 17 ready-to-use skills from the Anthropic agent skills collection. They are installed into .ocaya/skills/ and discovered automatically when the project directory is trusted.

Configuration

Configuration File Location

OCAYA reads config.toml from ./.ocaya/config.toml first, then ~/.ocaya/config.toml.

API Key Configuration

Get a Mistral API key at https://console.mistral.ai. Configure it via:

1. Interactive setup: ocaya --setup
2. Environment variable: export MISTRAL_API_KEY="your_key"
3. .env file: Add MISTRAL_API_KEY=your_key to ~/.ocaya/.env

TLS and Corporate Certificate Authorities

enable_system_trust_store = true

SSL_CERT_FILE and SSL_CERT_DIR are also supported.

Custom System Prompts

Place AGENTS.md files in project directories or ~/.ocaya/AGENTS.md for user-level instructions.

To replace the system prompt entirely, create a markdown file in ~/.ocaya/prompts/ and set:

system_prompt_id = "my_custom_prompt"

This loads ~/.ocaya/prompts/my_custom_prompt.md. Project-local prompts in .ocaya/prompts/ override user-level ones.

Custom Compaction Prompts

compaction_prompt_id = "my_compaction_prompt"

Custom Agent Configurations

Add TOML files to ~/.ocaya/agents/ and use with --agent:

ocaya --agent my_custom_agent

Example ~/.ocaya/agents/research.toml:

system_prompt_id = "research"
disabled_tools = ["edit", "write_file"]

[tools.websearch]
permission = "always"

[tools.webfetch]
permission = "always"

Tool Management

# Only enable specific tools
enabled_tools = ["websearch", "webfetch", "bash"]

# Disable specific tools
disabled_tools = ["mcp_*"]

Supports exact names, glob patterns, and re: regex prefix.

MCP Server Configuration

[[mcp_servers]]
name = "fetch_server"
transport = "stdio"
command = "uvx"
args = ["mcp-server-fetch"]

[[mcp_servers]]
name = "my_http_server"
transport = "http"
url = "http://localhost:8000"
api_key_env = "MY_API_KEY"
startup_timeout_sec = 15
tool_timeout_sec = 120

Supported transports: http, streamable-http, stdio.

Session Management

# Continue from last session
ocaya --continue

# Resume a specific session
ocaya --resume abc123

Use --workdir to specify a working directory, and --add-dir to add extra directories:

ocaya --workdir /path/to/project --add-dir /path/to/library

Update Settings

enable_auto_update = false
enable_notifications = false

Custom OCAYA Home Directory

Override the default ~/.ocaya directory:

export OCAYA_HOME="/path/to/custom/ocaya/home"

This controls where OCAYA stores config.toml, .env, agents/, prompts/, tools/, logs/, and history.

Editors/IDEs

OCAYA works in editors and IDEs that support Agent Client Protocol. See the ACP Setup documentation for setup instructions.

Resources

• CHANGELOG - What's new in each version
• CONTRIBUTING - Feedback, bug reports, and feature requests

Data collection & usage

Use of OCAYA is subject to Mistral AI's Privacy Policy. You can disable telemetry in config.toml:

enable_telemetry = false

License

Copyright 2025 Mistral AI

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the LICENSE file for the full license text.