{"id":27142396,"url":"https://github.com/zighouse/zai.vim","last_synced_at":"2026-04-15T13:34:00.527Z","repository":{"id":284677085,"uuid":"955393367","full_name":"zighouse/zai.vim","owner":"zighouse","description":"A vim plugin to chat with a background job such as deepseek service.","archived":false,"fork":false,"pushed_at":"2026-01-25T12:12:35.000Z","size":3393,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-26T02:08:35.725Z","etag":null,"topics":["aichat","deepseek","neovim","vim","vim-plugin"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zighouse.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-26T15:11:04.000Z","updated_at":"2026-01-25T12:12:38.000Z","dependencies_parsed_at":"2025-09-12T17:11:50.320Z","dependency_job_id":"692fd172-b39e-48d0-b9e9-36b92403f059","html_url":"https://github.com/zighouse/zai.vim","commit_stats":null,"previous_names":["zighouse/zai.vim"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/zighouse/zai.vim","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zighouse%2Fzai.vim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zighouse%2Fzai.vim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zighouse%2Fzai.vim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zighouse%2Fzai.vim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zighouse","download_url":"https://codeload.github.com/zighouse/zai.vim/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zighouse%2Fzai.vim/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31842963,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T13:28:40.153Z","status":"ssl_error","status_checked_at":"2026-04-15T13:28:29.396Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aichat","deepseek","neovim","vim","vim-plugin"],"created_at":"2025-04-08T07:46:24.347Z","updated_at":"2026-04-15T13:34:00.519Z","avatar_url":"https://github.com/zighouse.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Zai.Vim AI Assistant\n\n[中文说明](README_zh.md)\n\n![Plugin Screenshot](screenshot.gif)\n\nZai.Vim is a Vim plugin that integrates AI assistants directly into your Vim editor. It manages multiple AI chat sessions simultaneously, records conversation logs, and allows loading logs to continue previous conversations. Switch freely and control at will.\n\n## Features\n\n- **Flexible model and prompt switching**: Change models and prompts mid-conversation\n- **File attachment support**: Attach text files as conversation context\n- **Multiple session support**: Handle multiple chat sessions concurrently\n- **Session logging**: Save, load, and preview conversation history\n- **Voice input support**: Real-time speech recognition using zasr-server for hands-free text input\n\n## Installation\n\n### Requirements\n\n- Vim 8.0+ or Neovim\n- Python 3.6+\n- AI API KEY\n  - Example: DeepSeek API Key (set to the `DEEPSEEK_API_KEY` environment variable)\n- Required Python Packages (Core Dependencies):\n  - `openai` - OpenAI API client\n  - `requests` - HTTP request library\n  - `appdirs` - Application directory management\n  - `chardet` - Character encoding detection\n  - `PyYAML` - YAML configuration file parsing\n  - `tiktoken` - OpenAI token counting\n- Optional Python Packages (Install as needed):\n  - Web Features: `beautifulsoup4`, `selenium`, `undetected-chromedriver`, `html2text`\n  - File Operations: `python-magic` (File type detection)\n  - System Tools: `distro` (Linux distribution detection), `docker` (Docker Python SDK)\n  - AI Tools: `transformers` (Hugging Face library)\n  - Voice Input (ASR): `websockets`, `pyaudio`\n  - Utility Tools: `lunarcalendar` (Lunar calendar)\n- System Dependencies (Recommended for Linux):\n  - Docker Engine (for secure shell execution):\n    ```bash\n    # Ubuntu/Debian\n    sudo apt install docker.io docker-compose\n    sudo usermod -aG docker $USER\n    sudo systemctl restart docker\n    # Log out and log back in for the docker group to take effect\n    ```\n  - Chrome/Chromium Browser (for web search):\n    ```bash\n    # Ubuntu/Debian\n    sudo apt install chromium-browser\n    # Or install Google Chrome from the official website\n    ```\n  - Other Development Tools:\n    ```bash\n    sudo apt install build-essential python3-dev\n    ```\n  Note: Docker and Chrome are also available on Windows, but configuration is more complex. Using Linux is recommended.\n- Optional Vim Plugins:\n  - iamcco/markdown-preview.nvim (Chat preview)\n  - junegunn/fzf.vim (Log search)\n- Installation Methods:\n  - Using requirements.txt: `pip install -r requirements.txt`\n  - Using the installation script: `python3 python3/install.py`\n  - Install core dependencies only: `python3 python3/install.py --skip-core` (if already installed)\n  - Install full functionality: `python3 python3/install.py --all-optional`\n  - Install system dependencies (Linux): See the System Dependencies section above\n\n### Using a plugin manager\n\nWith vim-plug:\n```vim\nPlug 'zighouse/zai'\n```\n\nWith Vundle:\n```vim\nPlugin 'zighouse/zai'\n```\n\nWith lazy.nvim:\n```lua\nreturn {\n    {\n        \"zighouse/zai.vim\",\n        config = function()\n            vim.g.zai_default_model = \"deepseek-chat\"\n        end\n    }\n}\n```\n\nManual Installation:  \n\nLinux/Mac:\n```bash\nmkdir -p ~/.vim/pack/plugins/start\ncd ~/.vim/pack/plugins/start\ngit clone https://github.com/zighouse/zai.vim.git\npip install -r requirements.txt\n# or use install.py\npython python3/install.py\n```\n\nWindows:\n```dos\nmd %USERPROFILE%\\vimfiles\\pack\\plugins\\start\ncd %USERPROFILE%\\vimfiles\\pack\\plugins\\start\ngit clone https://github.com/zighouse/zai.vim.git\npip install -r requirements.txt\n# or use install.py\npython python3\\install.py\n```\n\nRun `git pull` in the installation directory to update manually.\n\nAlternatively, [download the zip](https://github.com/zighouse/zai.vim/archive/refs/heads/main.zip) and extract the zai.vim-main folder to the appropriate directory.\n\n### Voice Input (ASR) Setup\n\nTo enable voice input functionality, you need to set up zasr-server (a real-time speech recognition server):\n\n#### Quick Installation (Recommended)\n\nUse the automated installer:\n\n```bash\n# Install zasr-server and dependencies\npython3 python3/install.py --install-zasr\n\n# Install Python ASR dependencies\npython3 python3/install.py --optional asr\n```\n\nThe installer will:\n- Check for zasr project (expects it at `~/mywork/github/zasr`)\n- Build zasr-server from source if needed\n- Install to `~/.local/share/zai/zasr`\n- Guide you through model selection\n- Show memory and disk requirements\n\n#### Manual Installation\n\nIf you prefer manual setup or need customization:\n\n1. **Install zasr-server**:\n\n```bash\n# Clone zasr repository\ngit clone https://github.com/zighouse/zasr.git\ncd zasr\n\n# Download dependencies\ncd third_party\nbash download_deps.sh\n\n# Build zasr-server\ncd ..\nmkdir -p build \u0026\u0026 cd build\ncmake ..\nmake -j$(nproc)\n```\n\n2. **Install to deployment directory**:\n\n```bash\n# Install zasr to ~/.local/share/zai/zasr\n./scripts/install.sh --dir ~/.local/share/zai/zasr --from-binary\n```\n\n3. **Download ASR models**:\n\n```bash\n# Interactive model download\n~/.local/share/zai/zasr/scripts/download-models.sh\n\n# Or download all models\n~/.local/share/zai/zasr/scripts/download-models.sh --type all\n```\n\n**Model Options**:\n- **SenseVoice** (500MB RAM): Multi-lingual (Chinese, English, Japanese, Korean, Cantonese)\n- **Streaming Zipformer zh** (400MB RAM): Chinese only, low latency\n- **Streaming Zipformer bilingual** (450MB RAM): Chinese-English bilingual\n\n4. **Start zasr-server**:\n\n```bash\n# Using the control script (recommended)\n~/.local/share/zai/zasr/scripts/zasrctl start\n\n# Check status\n~/.local/share/zai/zasr/scripts/zasrctl status\n\n# Stop server\n~/.local/share/zai/zasr/scripts/zasrctl stop\n```\n\n5. **Install Python dependencies for ASR**:\n\n```bash\n# Option 1: Using install.py\npython3 python3/install.py --optional asr\n\n# Option 2: Manual install\npip install websockets pyaudio\n```\n\n**Note**: On Linux, you may also need to install PortAudio development headers:\n\n```bash\nsudo apt install portaudio19-dev python3-dev build-essential cmake\n```\n\n6. **Enable ASR in Vim**:\n\n**Option 1: Auto-enable on plugin load** (Recommended)\n\nAdd to your `.vimrc` or `init.vim`:\n\n```vim\n\" Auto-enable ASR when plugin loads\nlet g:zai_auto_enable_asr = 1\n```\n\n**Option 2: Manual enable**\n\nAdd to your `.vimrc` or `init.vim`:\n\n```vim\n\" Enable ASR functionality\ncall zai#asr#setup()\n```\n\nOr run in Vim: `:call zai#asr#setup()`\n\n#### Advanced Deployment\n\nFor production deployment or customization, see the [zasr deployment guide](https://github.com/zighouse/zasr/blob/main/README-deploy.md) in the zasr repository.\n\n**Key zasr resources**:\n- [zasr README](https://github.com/zighouse/zasr/blob/main/README.md) - Basic usage and architecture\n- [zasr README-deploy.md](https://github.com/zighouse/zasr/blob/main/README-deploy.md) - Deployment and configuration\n- Model downloads: [sherpa-onnx releases](https://github.com/k2-fsa/sherpa-onnx/releases)\n\n**Environment Variables**:\n- `ZASR_SERVER_URL`: WebSocket server URL (default: `ws://localhost:2026`)\n\nFor more information about zasr-server, visit: https://github.com/zighouse/zasr\n\n## Configuration\n\n### Log Directory\n\n`g:zai_log_dir` configures the log file storage path.\n\nDefault paths:\n- Linux/Mac: `~/.local/share/zai/log`\n- Windows: `%USERPROFILE%\\AppData\\Local\\zai\\log`\n\nRecommendation: Configure a custom log path on Windows as the default path is system-hidden.\n\n### Interface Language\n\n`g:zai_lang` configures Zai's interface language.\nDefaults to English or based on user environment.\nSet to Chinese:\n```vim\nlet g:zai_lang = 'zh_CN.UTF-8'\n```\n\n### API Configuration\n\n`g:zai_base_url` configures the AI service's base URL.\n\n`g:zai_api_key_name` configures the API key environment variable name.\nThe API key must be set in the system environment variables.\n\nExample (Linux ~/.bashrc):\n```bash\nDEEPSEEK_API_KEY=sk-********************************\n```\n\n`g:zai_default_model` configures the default AI model.\n\n`g:zai_use_ai`  Chooses an assistant from AI assistants configuration. It is a replacement for configurations of base-url, key and model. It depends an AI assistants configuration.\n\nWhen multiple AI models can be used, or multiple AI assistant services are available, you can provide a YAML file as the AI assistants configuration on this location:\n\n* Linux/Mac: ~/.local/share/zai/assistants.yaml\n* Windows: %USERPROFILE%\\AppData\\Local\\Zai\\assistants.yaml\n\nSample code of assistants.yaml:\n```yaml\n- name: deepseek                        # AI Assistant Name/ LLM Provider (customizable)\n  base-url: https://api.deepseek.com    # api for llm base url\n  api-key-name: DEEPSEEK_API_KEY        # environment name of the api key\n  tokenizer: deepseek-ai/DeepSeek-V3.2  # for tokens calculation, optional\n  model:                                # selected models from the provider's model list\n  - name: deepseek-chat                       # model identifier from provider\n    size: 685.40B                             # model size, optional.\n    context: 128K                             # context length, not a must but recommended.\n    out-length: { default: 4K, max: 8K }      # output sequence length, optional\n    cost: { hit: 0.2, in: 2, out: 3, unit: RMB/MTk } # optional\n    features: json, tool-call, complete, fim         # optional\n  - name: deepseek-reasoner\n    size: 685.40B\n    context: 128K\n    out-length: { default: 32K, max: 64K }\n    cost: { hit: 0.2, in: 2, out: 3, unit: RMB/MTk }\n    features: json, tool-call, complete\n\n- name: Gemini\n  api-key-name: GEMINI_API_KEY\n  base-url: https://generativelanguage.googleapis.com/v1beta/openai/\n  model:\n    - gemini-2.5-flash-lite   # in:$0.1/mtk out:$0.4/mtk free-level no-call\n    - gemini-2.5-flash        # in:$0.30/mtk out:$2.5/mtk free-level no-call\n    - gemini-2.5-pro          # in:$1.25/mtk out:$10/mtk free-level no-call\n    - gemini-3-flash-preview  # in:$0.5/mtk out:$3/mtk free-level no-call\n    - gemini-3-pro-preview    # in:$2/mtk out:$12/mtk non-free\n\n- name: Moonshot\n  api-key-name: MOONSHOT_API_KEY\n  base-url: https://api.moonshot.cn/v1\n  model:\n  - name: kimi-k2-0905-preview # tokens:256k, coder\n  - name: kimi-k2-turbo-preview # tokens:256k\n  - name: moonshot-v1-128k # tokens:128k\n  - name: moonshot-v1-128k-vision-preview\n  - name: kimi-latest # 128k\n  - name: kimi-thinking-preview\n\n- name: \"Volces Ark\"\n  api-key-name: VOLCES_API_KEY\n  base-url: https://ark.cn-beijing.volces.com/api/v3\n  model:\n  - name: doubao-seed-1-6-251015\n\n- name: \"Selicon Flow\"\n  api-key-name: SILICONFLOW_API_KEY\n  base-url: https://api.siliconflow.cn\n  model:\n  - name: Qwen/Qwen3-30B-A3B\n    tokenizer: Qwen/Qwen3-30B-A3B # specify individual tokenizer\n  - name: Pro/deepseek-ai/DeepSeek-V3.2\n    size: 671B\n    context: 160K\n    out-length: { default: 4K, max: 8K }\n    cost: { in: 2, out: 3, unit: RMB/MTk }\n    features: talk, prefix, tools, infer, moe\n  - name: Pro/zai-org/GLM-4.7\n    size: 355B\n    active: 32B\n    context: 198K\n    cost: { hit: 0.8, in: 4.0, out: 16.0, unit: RMB/MTk }\n    features: talk, prefix, tools, moe, infer\n  - name: Pro/moonshotai/Kimi-K2-Thinking\n    size: 1T\n    context: 256K\n    cost: { in: 4, out: 16, unit: RMB/MTk }\n    features: talk, prefix, tools, infer, moe\n\n- name: aliyun\n  api-key-name: ALIYUN_API_KEY\n  base-url: https://dashscope.aliyuncs.com/compatible-mode/v1\n  model:\n  - qwen3-max\n  - qwen3-max-preview\n  - qwen3-coder-plus\n```\n\nOnce it is provided the AI assistants configure as above, then these code make the `Silicon Flow` as the default AI assistant and with the model K2.\n\n```vim\n let g:zai_use_ai = \"Silicon Flow\"\n let g:model = \"moonshotai/Kimi-K2-Instruct-0905\"\n```\n\nAlso, a 0-based index in the list of assistants config can be used as same as the name.\n\n## Usage\n\n### VIM Commands\n\n| Command                | Description                          | Mode          |\n|------------------------|--------------------------------------|---------------|\n| `:help`                | Open Zai help                        | Zai interface only |\n| `:Zai`                 | Open Zai interface                   | -             |\n| `\u003cleader\u003ezo`           | Open Zai interface                   | Normal mode   |\n| `:ZaiClose`            | Close Zai interface                  | -             |\n| `\u003cleader\u003ezX`           | Close Zai interface                  | Normal mode   |\n| `:q`                   | Close Zai interface                  | Zai interface only |\n| `:ZaiGo`               | Send input content                   | -             |\n| `\u003cCR\u003e`                 | Send input content                   | Input window normal mode |\n| `:ZaiAdd`              | Add selection to input               | -             |\n| `\u003cleader\u003eza`           | Add selection to input               | Visual mode   |\n| `:ZaiNew`              | Create new chat                      | Zai interface only |\n| `:[count]ZaiPrev`      | Select previous chat                 | Zai interface only |\n| `:[count]cp`           | Select previous chat                 | Zai interface only |\n| `:[count]ZaiNext`      | Select next chat                     | Zai interface only |\n| `:[count]cn`           | Select next chat                     | Zai interface only |\n| `:ZaiGoto id`          | Select chat by ID                    | Zai interface only |\n| `:cn id`               | Select chat by ID                    | Zai interface only |\n| `:ZaiPreview`          | Preview chat in browser              | Zai interface only |\n| `\u003cleader\u003edp`           | Preview chat in browser              | Zai interface normal mode |\n| `:ZaiOpenLog`          | Open Zai log                         | -             |\n| `:ZaiGrepLog \u003cpatten\u003e` | Grep Zai log                         | -             |\n| `:ZaiRg \u003cpattern\u003e \u003cdir\u003e` | Rg in a directory                  | -             |\n| `:ZaiLoad`             | Load Zai log as context              | -             |\n| `\u003cleader\u003ezl`           | Load Zai log as context              | -             |\n| `:ZaiConfig`           | Edit AI assistants configuration     | -             |\n\n### Voice Input (ASR)\n\nVoice input allows you to dictate text directly in insert mode using real-time speech recognition.\n\n| Command/Key            | Description                          | Mode          |\n|------------------------|--------------------------------------|---------------|\n| `\u003cC-G\u003e`                | Toggle ASR on/off                    | Insert mode   |\n| `:ASRToggle`           | Toggle ASR on/off                    | -             |\n| `:ASRStart`            | Start voice input                    | -             |\n| `:ASRStop`             | Stop voice input                     | -             |\n\n**How it works**:\n1. Press `\u003cC-G\u003e` in insert mode to start ASR\n2. Speak into your microphone\n3. Text appears in real-time as you speak (partial results)\n4. ASR automatically stops after 3 seconds of silence\n5. Press `\u003cC-G\u003e` again to manually stop\n\n**Requirements**:\n- zasr-server must be running on `ws://localhost:2026`\n- Python packages: `websockets`, `pyaudio`\n- Working microphone\n\n**Tips**:\n- Ensure zasr-server is running before starting ASR\n- Check status messages for connection and recognition feedback\n- The system detects silence automatically (3 seconds)\n- Partial results are updated in-place until final results are confirmed\n\n### Interface Overview\n\nZai interface consists of three parts:\n- Top: Session list window\n- Middle: Display window showing conversation content\n- Bottom: Input window for questions and commands\n\nThe interface opens with the first chat session (ID starts from 0). Press `\u003cCR\u003e` in input window to send content. Responses and errors appear in the display window with log file path notifications.\n\n## Session Commands\n\nSession commands configure AI assistant settings and are processed by Zai's background task. They can be sent alone or mixed with user queries.\n\n### Available Commands\n\n- `:-\u003e?` - Change command prefix\n- `:help` - Show help information\n- `:exit`/`:quit` - Force exit remote AI service\n- `:show \u003cconfig\u003e` - Display configuration items\n- `:file \u003cfile-path\u003e` - Attach text file\n- `:-file` - Clear all attachments\n- `:base-url \u003curl\u003e` - Set base url of AI service\n- `:api-key-name \u003ckey-name\u003e` - Set variable of API Key to access AI service\n- `:model \u003cname\u003e` - Set AI model\n- `:prompt \u003ctext\u003e` - Set system prompt\n- `:prompt\u003c\u003cEOF` - Set multi-line prompt (end with EOF)\n- `:-prompt` - Clear custom prompt\n- `:temperature \u003cfloat\u003e` - Set creativity parameter (0-2)\n- `:-temperature` - Clear temperature setting\n- `:top_p \u003cfloat\u003e` - Set top-p sampling (0-1)\n- `:-top_p` - Clear top-p setting\n- `:max_tokens \u003cinteger\u003e` - Set maximum tokens\n- `:-max_tokens` - Clear maximum tokens setting\n- `:complete_type \u003cstr\u003e` - Set file type for code completion\n- `:prefix \u003cstr\u003e` - Set prefix for code completion\n- `:prefix\u003c\u003cEOF` - Set multi-line prefix (end with EOF)\n- `:suffix \u003cstr\u003e` - Set suffix for fill-in-middle completion\n- `:suffix\u003c\u003cEOF` - Set multi-line suffix (end with EOF)\n- `:talk_mode \u003cmode\u003e` - Set conversation mode (instant, chain)\n- `:logprobs \u003cint\u003e` - Show top token probabilities (0-20)\n- `:history_safety_factor \u003cfloat\u003e` - Set safety factor for history pruning (0.1-0.5, default 0.25)\n- `:history_keep_last_n \u003cint\u003e` - Keep last N rounds in history (\u003e=1, default 6)\n- `:no-log` - Disable logging\n- `:-no-log` - Enable logging\n- `:load \u003clog-file\u003e` - Load context from Zai log file\n- `:-\u003cparam\u003e` - Reset any parameter to default (e.g., `:-temperature`)\n\nSession Commands with AI assistants YAML configuration:\n\n- `:list ai` - List all AI assistants\n- `:show ai [name|index]` - Display the AI assistant\n- `:use  ai \u003cname|index\u003e` - Use an AI assistant picked up from the list.\n- `:model \u003cname|index\u003e` - Choose one of valid model from list of current AI assistant.\n- `:use  ai \u003cname|index\u003e model \u003cname|index\u003e` - Combination of `use ai` and `model` commands.\n\nSession commands with AI calling tools:\n\n- `:list tool` - List all available toolsets for AI calling.\n- `:show tool [name]` - Show details of an AI calling toolset.\n- `:use tool [name]` - Use an AI calling toolset.\n- `:sandbox path` - Specify a sandbox path for file toolset.\n\nSession commands with taskbox docker container:\n\n- `:show taskbox` - Display taskbox information.\n- `:start taskbox` - Run taskbox docker container.\n- `:stop taskbox` - Stop taskbox docker container.\n\nSession commands with web tools:\n\n- `:search \u003ckey words\u003e` - Search the web (default by google).\n- `:goto url`           - Fetch the content of url.\n- `:down url`           - Download file from url.\n\n\n### Available Toolsets\n\nZai provides several tool sets that AI can call to interact with the system:\n\n1. **file** - File operations\n   - `ls` - List files and directories\n   - `mkdir` - Create directories\n   - `copy_file` - Copy files or directories\n   - `read_file` - Read file content\n   - `write_file` - Write to file\n   - `search_in_file` - Search within files\n   - `substitute_file` - Replace text in files\n   - `diff_file` - Compare files\n   - `patch_file` - Apply patches\n\n2. **web** - Web operations\n   - `web_get_content` - Fetch web page content\n   - `web_search` - Search the web using SearXNG metasearch engine (supports multiple engines: DuckDuckGo, Google, Bing, Brave, Baidu, etc.)\n   - `web_download_file` - Download files from URLs\n\n3. **shell** - Secure shell execution\n   - `execute_shell` - Execute commands in Docker container (taskbox)\n   - Supports Python and shell commands with isolation\n\n4. **grep** - File searching\n   - `grep` - Search for patterns in files (like Unix grep)\n\n5. **ai** - AI operations (experimental)\n   - `generate_image` - Generate images with AI\n\n6. **browser** - Browser automation (experimental)\n   - `open_browser` - Open URLs in browser\n   - `get_page_content` - Get dynamic page content\n   - `screenshot` - Take screenshots\n\n7. **os** - System information\n   - `get_os_info` - Get date, locale, OS version\n\n### Tool Usage Examples\n\nLoad all tools from a toolset:\n```\n:use tool file\n```\n\nLoad specific functions from a toolset:\n```\n:use tool file.read_file\n:use tool file: read_file write_file\n```\n\nLoad multiple toolsets:\n```\n:use tool file web\n```\n\nCheck available tools:\n```\n:list tool\n```\n\nShow details of a toolset:\n```\n:show tool file\n```\n\n### Configuration Items\n\nDisplayable configuration items:\n- `api-key-name` - AI API Key Name\n- `base-url` - AI API Base URL\n- `model` - AI system model\n- `prompt` - AI system prompt\n- `temperature` - Creativity parameter (0-2)\n- `max-tokens` - Maximum tokens\n- `logprobs` - Top token probabilities (0-20)\n- `top-p` - Top-P sampling (0-1)\n- `presence-penalty` - Repetition penalty (-2 to 2)\n- `frequency-penalty` - Frequency penalty (-2 to 2)\n- `history-safety-factor` - Safety factor for history pruning (0.1-0.5)\n- `history-keep-last-n` - Number of recent rounds to keep (\u003e=1)\n- `log-file` - Log file path\n- `prefix` - Command prefix\n\n### Model Configuration Examples\n\nDeepSeek configuration:\n```vim\nlet g:zai_base_url = \"https://api.deepseek.com\"\nlet g:zai_api_key_name = \"DEEPSEEK_API_KEY\"\nlet g:zai_default_model = \"deepseek-chat\"\n```\n\nChange model during conversation:\n```\n:model deepseek-reasoner\n```\n\nSiliconFlow configuration:\n```vim\nlet g:zai_base_url = \"https://api.siliconflow.cn\"\nlet g:zai_api_key_name = \"SILICONFLOW_API_KEY\"\nlet g:zai_default_model = \"deepseek-ai/DeepSeek-R1\"\n```\n\n### Prompt Settings\n\nSingle-line prompt:\n```\n:prompt Please provide professional translation assistance as a computer technology expert.\n```\n\nMulti-line prompt (block syntax):\n```\n:prompt\u003c\u003cEOF\nAs a code expert assistant, please analyze problems step by step.\nWhen providing solutions, use the format:\n  ### [Title]\n  [Step-by-step explanation]\n  ### Summary: [One-sentence summary]\nEOF\n```\n\n### Parameter Settings\n\nSet creativity parameter:\n```\n:temperature 0.3\n```  \n\nSupported parameter commands:\n- `:top_p float` - Top-P sampling (0-1)\n- `:max_tokens integer` - Maximum tokens\n- `:presence_penalty float` - Repetition penalty (-2 to 2)\n- `:frequency_penalty float` - Frequency penalty (-2 to 2)\n- `:logprobs float` - Top token probabilities (0-20)\n\nClear settings with minus prefix:\n```\n:-temperature\n```\n\n### MCP Service Configuration (for Claude Code)\n\nZai provides a Model Context Protocol (MCP) server that enables Claude Code (claude.ai/code) to access web search, content fetching, and file download capabilities.\n\n#### Prerequisites\n\n1. **Install MCP Python package**:\n   ```bash\n   pip install mcp\n   ```\n\n2. **Ensure Docker is installed and running** (required for SearXNG web search):\n   ```bash\n   # Verify Docker is available\n   docker --version\n   ```\n\n#### MCP Tools Available\n\nThe MCP server provides the following tools:\n\n1. **web_search** - Web search powered by SearXNG metasearch engine\n   - Supports multiple search engines: DuckDuckGo, Google, Bing, Brave, Baidu, Yandex, Qwant, Startpage\n   - Parameters:\n     - `request` (required): Search query\n     - `engine`: Specific search engine (empty for auto-selection)\n     - `category`: Search category (e.g., 'general', 'images', 'videos', 'news')\n     - `time_range`: Time filter ('day', 'week', 'month', 'year')\n     - `language`: Language code (e.g., 'en', 'zh', 'auto')\n     - `safesearch`: Safe search level (0=off, 1=moderate, 2=strict)\n     - `max_results`: Maximum number of results (default: 10)\n     - `return_format`: Output format ('markdown', 'html', 'links', 'json')\n\n2. **web_get_content** - Fetch web page content\n   - Returns clean text, markdown, HTML, or extracted links\n   - Parameters:\n     - `url` (required): URL to fetch\n     - `return_format`: Output format ('clean_text', 'markdown', 'html', 'links')\n\n3. **web_download_file** - Download files from URLs\n   - Useful for downloading images, archives, etc.\n   - Parameters:\n     - `url` (required): URL to download\n     - `output_path`: Full output path (optional)\n     - `output_dir`: Output directory (optional)\n     - `filename`: Custom filename (optional)\n     - `timeout`: Download timeout in seconds (default: 60)\n\n#### Configuration\n\nAdd the MCP server to your Claude Code configuration file (typically `~/.config/claude-code/config.json` or `~/.claude/config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"zai-web\": {\n      \"command\": \"python3\",\n      \"args\": [\n        \"/path/to/zai.vim/python3/mcp_web_server.py\"\n      ],\n      \"env\": {\n        \"PYTHONPATH\": \"/path/to/zai.vim/python3\"\n      }\n    }\n  }\n}\n```\n\nReplace `/path/to/zai.vim` with the actual path to your zai.vim installation directory.\n\n#### Usage\n\nOnce configured, Claude Code will automatically have access to web search and content fetching capabilities. The SearXNG container will be auto-started on first use.\n\nExample prompts you can use in Claude Code:\n- \"Search for information about Python async/await best practices\"\n- \"Fetch the content from https://example.com and summarize it\"\n- \"Find the latest news about Vim plugins\"\n\n### Command Prefix\n\nDefault command prefix is `:`. Available prefix characters:\n```\n: / ~ \\ ; ! # $ % \u0026 ? @ ^ _ * + = , . \u003c \u003e ` ' \" ( ) [ ] { }\n```\n\nChange prefix example:\n```\n:-\u003e/\n```\n\n## Project Configuration\n\nZai supports project-level configuration through a `zai.project/zai_project.yaml` file (or `zai_project.yaml` for backward compatibility) in your project directory. This allows you to define project-specific settings like sandbox directory and Docker container configuration for the `tool_shell` tool.\n\n### Configuration File Location\n\nThe configuration file is searched upward from the current working directory:\n- `zai.project/zai_project.yaml` (new format)\n- `zai_project.yaml` (legacy format, prints warning)\n\n### Configuration Structure\n\nThe configuration file should contain a list of configuration objects. The first one is used for the current project.\n\nExample `zai.project/zai_project.yaml`:\n```yaml\n- sandbox_home: /path/to/project/sandbox\n  shell_container:\n    # Other Docker SDK parameters can be included\n    # It is used mostly for tool_shell running a docker container, see to run():\n    # https://docker-py.readthedocs.io/en/stable/containers.html\n    image: taskbox:latest            # the docker image to use\n    name: my-project-taskbox         # name of this container\n    Dockerfile: Dockerfile.taskbox   # if the image is not exist, use this dockerfile to create a new one.\n    working_dir: /sandbox            # working dir\n    user: \"1000:1000\"  # UID:GID as host user, or any user provided in docker image, e.g. \"sandbox\"\n    volumes:\n      - \"/host/path:/container/path:rw\"\n      - \"/home/for/project/.git:/sandbox/project/.git:ro\"\n      - \"/ccache/for/project:/ccache/.git:ro\"\n    network_mode: \"bridge\"\n    environment:\n      CCACHE_DIR: \"/ccache\"\n      CCACHE_MAXSIZE: \"10G\"\n    mem_limit: \"4g\"\n    cpu_period: 100000\n    cpu_quota: 50000\n    detach: true\n    auto_remove: true\n    network_mode: \"bridge\"\n    command: [\"tail\", \"-f\", \"/dev/null\"]\n```\n\n### Container Startup Installations\n\nZai now supports automatic software installation when a Docker container starts. You can define packages to be installed in the `zai_project.yaml` file, and they will be automatically installed when the container is created or started.\n\n#### Installation Configuration Fields\n\nAdd the following fields to your project configuration:\n\n1. **`pip_install`**: Python packages to install via pip\n   - Supports multiple formats:\n     - Simple list: `[\"PyYAML\", \"appdirs\"]`\n     - Structured format with options: \n       ```yaml\n       - packages: [torch, torchvision, torchaudio]\n         options: [--index-url, https://download.pytorch.org/whl/cpu]\n       ```\n     - Mixed format: `[\"PyYAML\", [\"torch\", \"--index-url\", \"https://download.pytorch.org/whl/cpu\"]]`\n   - **Permission note**: If container user is not root, add `--user` flag to options\n     to install packages in user directory and avoid permission errors:\n     ```yaml\n     - packages: [requests, numpy]\n       options: [--user]\n     ```\n\n2. **`apt_install`**: System packages to install via package manager\n   - Supports multiple package managers: `apt`, `dnf`, `yum`, `rpm`, `pacman`\n   - Automatically handles `sudo` permissions when needed\n   - Supports multiple formats:\n     - **Simple list** (defaults to `apt`): `[\"vim\", \"curl\", \"git\"]`\n     - **Structured format with apt**:\n       ```yaml\n       - packages: [vim, git, build-essential]\n         options: [-y]\n       ```\n     - **Specify package manager**:\n       ```yaml\n       package_manager: dnf\n       packages: [vim, git, curl]\n       options: [-y]\n       ```\n     - **Multiple installation specs**:\n       ```yaml\n       - package_manager: apt\n         packages: [vim, curl]\n         options: [-y]\n       - package_manager: dnf\n         packages: [htop, ncdu]\n         options: [-y]\n       ```\n\n3. **`post_start_commands`**: Generic commands to execute\n   - List of shell commands to run after package installations\n   - Useful for installing tools with other package managers (cargo, go, npm, etc.)\n   - Example: \n     ```yaml\n     - \"cargo install bat\"\n     - \"go install github.com/xxx/tool@latest\"\n     - \"echo 'Installation complete'\"\n     ```\n\n#### Installation Process\n\n1. When a persistent container is started (or created for the first time):\n   - **System packages**: Package manager is updated (e.g., `apt-get update`, `dnf check-update`)\n   - **Automatic sudo handling**: If container user is not root, Zai automatically uses `sudo` when available\n   - **Package installation**: Packages in `apt_install` are installed with appropriate package manager\n   - **Python packages**: `pip` is upgraded to the latest version\n   - **Package installation**: Packages in `pip_install` are installed\n   - **Generic commands**: Commands in `post_start_commands` are executed in order\n\n2. **Smart permission handling**:\n   - If container user is root (UID=0), commands run directly\n   - If `sudo` is available in container, commands are prefixed with `sudo`\n   - If neither root nor sudo is available, commands run directly (may fail with permission errors)\n   - All package managers (`apt`, `dnf`, `yum`, etc.) benefit from this automatic permission handling\n\n3. **Error handling**:\n   - Package manager update failures show warnings but installation continues\n   - If `pip` upgrade fails, a warning is shown but installation continues\n   - Individual package installation failures are logged but don't stop the process\n   - All errors are reported to stderr for debugging\n\n#### Complete Example\n\n```yaml\n- sandbox_home: /path/to/project/sandbox\n  shell_container:\n    image: python:3.11-slim\n    name: my-project-container\n    working_dir: /sandbox\n  \n  # Python package installations\n  pip_install:\n    - packages: [PyYAML, appdirs, requests]\n    - packages: [torch, torchvision, torchaudio]\n      options: [--index-url, https://download.pytorch.org/whl/cpu]\n  \n  # Linux package installations  \n  apt_install:\n    - packages: [vim, curl, git, build-essential]\n  \n  # Generic commands\n  post_start_commands:\n    - \"cargo install bat exa\"\n    - \"echo 'Development environment ready'\"\n    - \"python3 --version \u0026\u0026 pip --version\"\n```\n\n### Configuration Fields\n\n- `sandbox_home`: Directory for sandboxed file operations. Defaults to `~/.local/share/zai/sandbox`.\n- `shell_container`: Configuration for the `tool_shell` Docker container.\n  - `image`: Docker image name (default: `taskbox:latest`)\n  - `name`: Container name (default: `zai-tool-shell-taskbox`)\n  - `working_dir`: Container working directory (default: `/sandbox`)\n  - `user`: User UID:GID (default: host user's UID:GID)\n  - `volumes`: List of volume mounts in `host:container:mode` format\n  - `network_mode`: Docker network mode (default: `bridge`)\n  - Other Docker SDK parameters are passed directly to container creation.\n\n### Tool Shell\n\nThe `tool_shell` tool provides secure shell execution in a Docker container (taskbox) with:\n- Isolated environment\n- Persistent containers across calls\n- Project-specific configuration\n- Network access control\n- Resource limits\n\nExample usage in AI conversation:\n```\n:use tool shell\nPlease list files in the current directory.\n**Assistant:**\n  - **tool call**: `execute_shell` ({\"command\": \"ls -la\"...)\n  - return: `execute_shell`\n```\n\nThe tool automatically uses project configuration if available, otherwise uses defaults.\n\n### Sandbox Directory\n\nThe sandbox directory is used by file-related tools (`tool_file`, `tool_shell`) as a safe workspace. Files outside the sandbox cannot be accessed for security.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n### Third-Party Dependencies\n\nThis plugin uses several third-party Python packages with different licenses:\n\n- **Core Dependencies**: openai (MIT), requests (Apache 2.0), appdirs (MIT), chardet (LGPLv3), PyYAML (MIT), tiktoken (MIT)\n- **Web Features** (Optional): beautifulsoup4 (MIT), selenium (Apache 2.0), undetected-chromedriver (MIT)\n- **System Tools** (Optional): docker (Apache 2.0), python-magic (MIT), distro (GPLv3)\n- **AI Tools** (Optional): transformers (Apache 2.0)\n- **Voice Input** (ASR): websockets (MIT), pyaudio (MIT)\n\nFor complete third-party license information, please see the [LICENSE](LICENSE) file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzighouse%2Fzai.vim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzighouse%2Fzai.vim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzighouse%2Fzai.vim/lists"}