Metadata-Version: 2.4
Name: ocaya
Version: 2.15.6
Summary: OCAYA — web-first general-purpose AI assistant
Project-URL: Homepage, https://github.com/mistralai/mistral-vibe
Project-URL: Repository, https://github.com/mistralai/mistral-vibe
Project-URL: Issues, https://github.com/mistralai/mistral-vibe/issues
Project-URL: Documentation, https://github.com/mistralai/mistral-vibe#readme
Author: Mistral AI
License: Apache-2.0
License-File: LICENSE
Keywords: ai,cli,developer-tools,general-assistant,llm,mistral,ocaya
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Requires-Dist: agent-client-protocol==0.10.1
Requires-Dist: annotated-types==0.7.0
Requires-Dist: anyio==4.13.0
Requires-Dist: attrs==26.1.0
Requires-Dist: beautifulsoup4==4.14.3
Requires-Dist: browser-use>=0.2.0
Requires-Dist: cachetools==7.0.6
Requires-Dist: certifi==2026.4.22
Requires-Dist: cffi==2.0.0
Requires-Dist: charset-normalizer==3.4.7
Requires-Dist: click==8.3.3; sys_platform != 'emscripten'
Requires-Dist: colorama==0.4.6; sys_platform == 'win32'
Requires-Dist: cryptography==47.0.0
Requires-Dist: eval-type-backport==0.3.1
Requires-Dist: gitdb==4.0.12
Requires-Dist: gitpython==3.1.47
Requires-Dist: giturlparse==0.14.0
Requires-Dist: google-auth==2.49.2
Requires-Dist: googleapis-common-protos==1.74.0
Requires-Dist: h11==0.16.0
Requires-Dist: httpcore==1.0.9
Requires-Dist: httpx-sse==0.4.3
Requires-Dist: httpx==0.28.1
Requires-Dist: humanize==4.15.0
Requires-Dist: idna==3.13
Requires-Dist: importlib-metadata==8.7.1
Requires-Dist: jaraco-classes==3.4.0
Requires-Dist: jaraco-context==6.1.2
Requires-Dist: jaraco-functools==4.4.0
Requires-Dist: jeepney==0.9.0; sys_platform == 'linux'
Requires-Dist: jsonpatch==1.33
Requires-Dist: jsonpath-python==1.1.5
Requires-Dist: jsonpointer==3.1.1
Requires-Dist: jsonschema-specifications==2025.9.1
Requires-Dist: jsonschema==4.26.0
Requires-Dist: keyring==25.7.0
Requires-Dist: langchain-mistralai>=0.2.0
Requires-Dist: linkify-it-py==2.1.0
Requires-Dist: markdown-it-py==4.0.0
Requires-Dist: markdownify==1.2.2
Requires-Dist: mcp==1.27.1
Requires-Dist: mdit-py-plugins==0.5.0
Requires-Dist: mdurl==0.1.2
Requires-Dist: mistralai==2.4.4
Requires-Dist: more-itertools==11.0.2
Requires-Dist: opentelemetry-api==1.39.1
Requires-Dist: opentelemetry-exporter-otlp-proto-common==1.39.1
Requires-Dist: opentelemetry-exporter-otlp-proto-http==1.39.1
Requires-Dist: opentelemetry-proto==1.39.1
Requires-Dist: opentelemetry-sdk==1.39.1
Requires-Dist: opentelemetry-semantic-conventions==0.60b1
Requires-Dist: packaging==26.2
Requires-Dist: pexpect==4.9.0
Requires-Dist: platformdirs==4.9.6
Requires-Dist: playwright>=1.49.0
Requires-Dist: protobuf==6.33.6
Requires-Dist: ptyprocess==0.7.0
Requires-Dist: pyasn1-modules==0.4.2
Requires-Dist: pyasn1==0.6.3
Requires-Dist: pycparser==3.0; implementation_name != 'PyPy'
Requires-Dist: pydantic-core==2.46.3
Requires-Dist: pydantic-settings==2.14.0
Requires-Dist: pydantic==2.13.3
Requires-Dist: pygments==2.20.0
Requires-Dist: pyjwt==2.12.1
Requires-Dist: pyperclip==1.11.0
Requires-Dist: python-dateutil==2.9.0.post0
Requires-Dist: python-dotenv==1.2.2
Requires-Dist: python-multipart==0.0.27
Requires-Dist: pywin32-ctypes==0.2.3; sys_platform == 'win32'
Requires-Dist: pywin32==311; sys_platform == 'win32'
Requires-Dist: pyyaml==6.0.3
Requires-Dist: referencing==0.37.0
Requires-Dist: requests==2.33.1
Requires-Dist: rich==15.0.0
Requires-Dist: rpds-py==0.30.0
Requires-Dist: secretstorage==3.5.0; sys_platform == 'linux'
Requires-Dist: six==1.17.0
Requires-Dist: smmap==5.0.3
Requires-Dist: sounddevice==0.5.5
Requires-Dist: soupsieve==2.8.3
Requires-Dist: sse-starlette==3.4.1
Requires-Dist: starlette==1.0.0
Requires-Dist: textual-speedups==0.2.1
Requires-Dist: textual==8.2.7
Requires-Dist: tomli-w==1.2.0
Requires-Dist: tree-sitter-bash==0.25.1
Requires-Dist: tree-sitter==0.25.2
Requires-Dist: truststore==0.10.4
Requires-Dist: typing-extensions==4.15.0
Requires-Dist: typing-inspection==0.4.2
Requires-Dist: uc-micro-py==2.0.0
Requires-Dist: urllib3==2.6.3
Requires-Dist: uvicorn==0.46.0; sys_platform != 'emscripten'
Requires-Dist: watchfiles==1.1.1
Requires-Dist: websockets==16.0
Requires-Dist: zipp==3.23.1
Requires-Dist: zstandard==0.25.0
Provides-Extra: browser
Requires-Dist: browser-use>=0.2.0; extra == 'browser'
Requires-Dist: langchain-mistralai>=0.2.0; extra == 'browser'
Requires-Dist: playwright>=1.49.0; extra == 'browser'
Description-Content-Type: text/markdown

# OCAYA

[![PyPI Version](https://img.shields.io/pypi/v/ocaya)](https://pypi.org/project/ocaya)
[![Python Version](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/downloads/release/python-3120/)
[![CI Status](https://github.com/mistralai/mistral-vibe/actions/workflows/ci.yml/badge.svg)](https://github.com/mistralai/mistral-vibe/actions/workflows/ci.yml)
[![License](https://img.shields.io/github/license/mistralai/mistral-vibe)](https://github.com/mistralai/mistral-vibe/blob/main/LICENSE)

**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**

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

**Windows**

First, install uv:

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

Then use uv:

```bash
uv tool install ocaya
```

### Using pip

```bash
pip install ocaya
```

## Table of Contents

- [Features](#features)
  - [Built-in Agents](#built-in-agents)
  - [Subagents and Task Delegation](#subagents-and-task-delegation)
  - [Interactive User Questions](#interactive-user-questions)
- [Terminal Requirements](#terminal-requirements)
- [Quick Start](#quick-start)
- [Usage](#usage)
  - [Interactive Mode](#interactive-mode)
  - [Trust Folder System](#trust-folder-system)
  - [Programmatic Mode](#programmatic-mode)
- [Voice Mode](#voice-mode)
- [Slash Commands](#slash-commands)
  - [Built-in Slash Commands](#built-in-slash-commands)
  - [Custom Slash Commands via Skills](#custom-slash-commands-via-skills)
- [Skills System](#skills-system)
  - [Creating Skills](#creating-skills)
  - [Skill Discovery](#skill-discovery)
  - [Managing Skills](#managing-skills)
- [Configuration](#configuration)
  - [Configuration File Location](#configuration-file-location)
  - [API Key Configuration](#api-key-configuration)
  - [Custom System Prompts](#custom-system-prompts)
  - [Custom Agent Configurations](#custom-agent-configurations)
  - [Tool Management](#tool-management)
  - [MCP Server Configuration](#mcp-server-configuration)
  - [Session Management](#session-management)
  - [Update Settings](#update-settings)
  - [Custom OCAYA Home Directory](#custom-ocaya-home-directory)
- [Editors/IDEs](#editorsides)
- [Resources](#resources)
- [Data collection & usage](#data-collection--usage)
- [License](#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`).
- **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:

```bash
ocaya --agent plan
```

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

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

   ```bash
   cd /path/to/your/project
   ```

2. Run OCAYA:

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

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

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

```bash
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](https://agentskills.io/specification).

### Creating Skills

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

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

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

## 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](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

```toml
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:

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

```toml
compaction_prompt_id = "my_compaction_prompt"
```

### Custom Agent Configurations

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

```bash
ocaya --agent my_custom_agent
```

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

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

[tools.websearch]
permission = "always"

[tools.webfetch]
permission = "always"
```

### Tool Management

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

```toml
[[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

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

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

### Update Settings

```toml
enable_auto_update = false
enable_notifications = false
```

### Custom OCAYA Home Directory

Override the default `~/.ocaya` directory:

```bash
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](https://agentclientprotocol.com/overview/clients). See the [ACP Setup documentation](docs/acp-setup.md) for setup instructions.

## Resources

- [CHANGELOG](CHANGELOG.md) - What's new in each version
- [CONTRIBUTING](CONTRIBUTING.md) - Feedback, bug reports, and feature requests

## Data collection & usage

Use of OCAYA is subject to Mistral AI's [Privacy Policy](https://legal.mistral.ai/terms/privacy-policy). You can disable telemetry in `config.toml`:

```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](LICENSE) file for the full license text.
