{"id":37702631,"url":"https://github.com/vibheksoni/verbalcodeai","last_synced_at":"2026-01-16T13:01:50.663Z","repository":{"id":294544948,"uuid":"985112092","full_name":"vibheksoni/VerbalCodeAi","owner":"vibheksoni","description":"VerbalCodeAI is a free, open-source AI tool that simplifies codebase navigation in your terminal, using Python 3.11.6 and Ollama. It indexes projects locally and quickly answers questions like “Where’s this function?”, saving developers time on debugging and onboarding.","archived":false,"fork":false,"pushed_at":"2025-06-07T00:42:16.000Z","size":6057,"stargazers_count":36,"open_issues_count":0,"forks_count":8,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-07T01:28:28.338Z","etag":null,"topics":["ai","artificial-intelligence","code-analysis","codebase-navigation","coding","developer-tools","git-integration","local-ai","ollama","open-source","privacy-focused","productivity","python","regex-search","semantic-search","terminal","verbalcodeai"],"latest_commit_sha":null,"homepage":"https://verbalcode.xyz/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vibheksoni.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}},"created_at":"2025-05-17T05:00:37.000Z","updated_at":"2025-06-07T00:42:20.000Z","dependencies_parsed_at":"2025-05-20T23:47:28.879Z","dependency_job_id":null,"html_url":"https://github.com/vibheksoni/VerbalCodeAi","commit_stats":null,"previous_names":["vibheksoni/verbalcodeai"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/vibheksoni/VerbalCodeAi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vibheksoni%2FVerbalCodeAi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vibheksoni%2FVerbalCodeAi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vibheksoni%2FVerbalCodeAi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vibheksoni%2FVerbalCodeAi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vibheksoni","download_url":"https://codeload.github.com/vibheksoni/VerbalCodeAi/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vibheksoni%2FVerbalCodeAi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28478888,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"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":["ai","artificial-intelligence","code-analysis","codebase-navigation","coding","developer-tools","git-integration","local-ai","ollama","open-source","privacy-focused","productivity","python","regex-search","semantic-search","terminal","verbalcodeai"],"created_at":"2026-01-16T13:01:49.874Z","updated_at":"2026-01-16T13:01:50.657Z","avatar_url":"https://github.com/vibheksoni.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# VerbalCodeAI 🤖\n\n[![GitHub stars](https://img.shields.io/github/stars/vibheksoni/VerbalCodeAi?style=social)](https://github.com/vibheksoni/VerbalCodeAi/stargazers)\n[![GitHub forks](https://img.shields.io/github/forks/vibheksoni/VerbalCodeAi?style=social)](https://github.com/vibheksoni/VerbalCodeAi/network/members)\n[![GitHub issues](https://img.shields.io/github/issues/vibheksoni/VerbalCodeAi)](https://github.com/vibheksoni/VerbalCodeAi/issues)\n[![GitHub license](https://img.shields.io/github/license/vibheksoni/VerbalCodeAi)](https://github.com/vibheksoni/VerbalCodeAi/blob/master/LICENSE)\n[![Python Version](https://img.shields.io/badge/python-3.11.6-blue)](https://www.python.org/downloads/release/python-3116/)\n[![Website](https://img.shields.io/badge/website-verbalcode.xyz-brightgreen)](https://verbalcode.xyz)\n\u003ca href=\"https://discord.gg/KpjSDEwWCF\" target=\"_blank\"\u003e\n  \u003cimg src=\"https://img.shields.io/static/v1?label=Discord\u0026message=Join%20Us\u0026color=7289DA\u0026logo=discord\u0026logoColor=white\u0026style=for-the-badge\" alt=\"Join our Discord\"/\u003e\n\u003c/a\u003e\n\nJoin our Discord server to hang out, ask questions, or offer help! We're currently looking for assistance in setting up the server, so if you're experienced with Discord setup, your help would be greatly appreciated! Click [here](https://discord.gg/KpjSDEwWCF) to join.\n\nEver felt lost in a complex codebase? Wish you had a smart assistant to help you navigate and understand code right in your terminal? VerbalCodeAI is here to help! This powerful AI-powered tool acts as your personal code companion, leveraging advanced embedding techniques and Large Language Model (LLM) integration. It offers intelligent code analysis, helps you search and understand your project, and provides assistance directly within your command-line interface, making your development workflow smoother and more efficient.\n\n```yaml\n.       .      .          .    .--.        .           .\n \\     /       |          |   :            |          / \\     o\n  \\   /.-. .--.|.-.  .-.  |   |    .-.  .-.| .-.     /___\\    .\n   \\ /(.-' |   |   )(   ) |   :   (   )(   |(.-'    /     \\   |\n    '  `--''   '`-'  `-'`-`-   `--'`-'  `-'`-`--'  '       `-' `-'\n                       [AI Assistant for Code]\n```\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"Showcase/VerbalCodeShowcase.gif\" alt=\"VerbalCodeAI Showcase\" style=\"max-width: 800px; max-height: 400px; width: 100%; height: auto;\"/\u003e\n\u003c/div\u003e\n\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eTable of Contents\u003c/strong\u003e\u003c/summary\u003e\n\n- [VerbalCodeAI 🤖](#verbalcodeai-)\n  - [Getting Started](#getting-started)\n    - [Prerequisites](#prerequisites)\n    - [Installation](#installation)\n      - [Windows](#windows)\n      - [Linux/macOS](#linuxmacos)\n    - [Manual Installation](#manual-installation)\n  - [Usage](#usage)\n    - [Starting the Application](#starting-the-application)\n    - [Indexing a Project](#indexing-a-project)\n    - [Main Menu Options](#main-menu-options)\n    - [Agent Mode Tools](#agent-mode-tools)\n    - [HTTP API Server](#http-api-server)\n    - [MCP Integration](#mcp-integration)\n      - [Setting Up the MCP Server](#setting-up-the-mcp-server)\n      - [Using with Claude Desktop](#using-with-claude-desktop)\n      - [Using with Cursor](#using-with-cursor)\n  - [Configuration](#configuration)\n    - [Supported LLM Providers](#supported-llm-providers)\n      - [Recommended Ollama Setup](#recommended-ollama-setup)\n      - [Anthropic Claude Models](#anthropic-claude-models)\n      - [Groq Models](#groq-models)\n    - [Performance Settings](#performance-settings)\n    - [UI Settings](#ui-settings)\n  - [Video Showcase](#video-showcase)\n  - [Image Showcase](#image-showcase)\n  - [Project Structure](#project-structure)\n  - [Contributing](#contributing)\n  - [License](#license)\n  - [Links](#links)\n  - [Acknowledgements](#acknowledgements)\n\n\u003c/details\u003e\n\n- 🔍 **Intelligent Code Search**: Find relevant code snippets using natural language queries\n- 📊 **Code Analysis**: Get insights about your codebase structure and dependencies\n- 🤖 **Agent Mode**: Let the AI explore and understand your codebase using various tools\n- 💬 **Chat with AI**: Ask questions about your code and get detailed explanations\n- 🌐 **Web Search Integration**: Search the web for code-related information without leaving the terminal\n- 🧠 **Memory System**: The AI remembers important information about your project\n- 🔄 **Version Control Integration**: Analyze git history and changes\n- 📝 **File Description**: Generate concise descriptions of code files\n- 🛠️ **Command Runner**: Execute system commands with AI assistance\n\n## Getting Started\n\n### Prerequisites\n\n- Python 3.11.6 (tested and recommended version)\n- [Ollama](https://ollama.com/download) (for local model execution)\n\n\u003e **Note:** The application has been specifically tested with Python 3.11.6 on Windows. While it may work with other versions, for the best experience, we recommend using the tested version.\n\n### Installation\n\n#### Windows\n\n1. Clone the repository:\n   ```\n   git clone https://github.com/vibheksoni/VerbalCodeAi.git\n   cd VerbalCodeAi\n   ```\n\n2. Run the setup script:\n   ```\n   setup_windows.bat\n   ```\n\n#### Linux/macOS\n\n1. Clone the repository:\n   ```\n   git clone https://github.com/vibheksoni/VerbalCodeAi.git\n   cd VerbalCodeAi\n   ```\n\n2. Make the setup script executable and run it:\n   ```\n   chmod +x setup_linux.sh\n   ./setup_linux.sh\n   ```\n\n### Manual Installation\n\nIf you prefer to set up manually:\n\n1. Create a virtual environment:\n   ```\n   python -m venv venv\n   ```\n\n2. Activate the virtual environment:\n   - Windows: `venv\\Scripts\\activate`\n   - Linux/macOS: `source venv/bin/activate`\n\n3. Install dependencies:\n   ```\n   pip install -r requirements.txt\n   ```\n\n4. Create a `.env` file with your configuration (see `.env.example` for reference)\n\n## Usage\n\n### Starting the Application\n\nAfter installation, activate your virtual environment and run:\n\n```\npython app.py\n```\n\n### Indexing a Project\n\nWhen you first start VerbalCodeAI, you'll be prompted to select a directory to index. This process analyzes your codebase and creates embeddings for efficient searching.\n\n### Main Menu Options\n\n- **Chat with AI**: Ask questions about your code\n- **Agent Mode**: Use AI with tools to explore your codebase\n- **Reindex Project**: Update the index after code changes\n- **Project Info**: View information about the indexed project\n- **Settings**: Configure application settings\n- **Exit**: Quit the application\n\n### Agent Mode Tools\n\nAgent Mode provides access to powerful tools:\n\n- **Search tools**: `embed_search`, `semantic_search`, `grep`, `regex_advanced_search`, `file_type_search`\n- **File tools**: `read_file`, `file_stats`, `directory_tree`, `get_file_description`, `get_file_metadata`\n- **Code analysis**: `find_functions`, `find_classes`, `find_usage`, `cross_reference`, `code_analysis`, `get_functions`, `get_classes`, `get_variables`, `get_imports`, `explain_code`\n- **Version control**: `git_history`, `version_control_search`, `search_imports`\n- **Project tools**: `get_project_description`, `get_instructions`, `create_instructions_template`\n- **Memory tools**: `add_memory`, `get_memories`, `search_memories`\n- **System tools**: `run_command`, `read_terminal`, `kill_terminal`, `list_terminals`\n- **Helper tools**: `ask_buddy` (with context-aware second opinions)\n- **Web tools**: `google_search`, `ddg_search`, `bing_news_search`, `fetch_webpage`, `get_base_knowledge`\n\n\u003e **💡 Pro Tip**: Agent Mode is the most cost-effective option when using cloud-based LLM providers. It makes fewer API calls compared to Chat Mode, which helps avoid rate limits and reduces costs. For the best experience with minimal expenses, consider using Agent Mode when working with paid API services.\n\n### HTTP API Server\n\nVerbalCodeAI includes a built-in HTTP API server that allows you to access its functionality programmatically. This is useful for integrating VerbalCodeAI with other tools or creating custom interfaces.\n\nTo start the HTTP API server:\n\n```bash\npython app.py --serve [PORT]\n```\n\nWhere `[PORT]` is the port number you want the server to listen on (default is 8000).\n\nThe server provides the following endpoints:\n\n- `GET /api/health` - Health check\n- `POST /api/initialize` - Initialize a directory\n- `POST /api/ask` - Ask the agent a question\n- `POST /api/index/start` - Start indexing a directory\n- `GET /api/index/status` - Get indexing status\n\nExample usage with curl:\n\n```bash\n# Health check\ncurl http://localhost:8000/api/health\n\n# Initialize a directory\ncurl -X POST http://localhost:8000/api/initialize -H \"Content-Type: application/json\" -d '{\"directory_path\": \"D:/path/to/your/project\"}'\n\n# Ask a question\ncurl -X POST http://localhost:8000/api/ask -H \"Content-Type: application/json\" -d '{\"question\": \"What does this codebase do?\"}'\n\n# Start indexing\ncurl -X POST http://localhost:8000/api/index/start -H \"Content-Type: application/json\" -d '{\"directory_path\": \"D:/path/to/your/project\"}'\n\n# Get indexing status\ncurl http://localhost:8000/api/index/status\n```\n\nBy default, the server only accepts connections from localhost (127.0.0.1). To allow connections from any IP address, set the `HTTP_ALLOW_ALL_ORIGINS` environment variable to `TRUE` in your `.env` file.\n\n### MCP Integration\n\nVerbalCodeAI supports the Model Context Protocol (MCP), allowing you to connect it to Claude Desktop and other MCP-compatible AI assistants. This integration enables Claude to directly interact with your codebase, providing a powerful AI-assisted development experience.\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"Showcase/MCP Showcase.PNG\" alt=\"MCP Integration with Claude Desktop\" style=\"width: 500px; height: 500px; max-width: 100%; object-fit: contain; margin: 10px;\"/\u003e\n  \u003cimg src=\"Showcase/MCP Showcase 2.PNG\" alt=\"MCP Showcase - Example 2\" style=\"width: 500px; height: 500px; max-width: 100%; object-fit: contain; margin: 10px;\"/\u003e\n\u003c/div\u003e\n\n#### Setting Up the MCP Server\n\nThe MCP server wraps the HTTP API server and provides tools for Claude to interact with VerbalCodeAI. Here's how to set it up:\n\n1. **Start the HTTP API Server**:\n   First, start the HTTP API server if it's not already running:\n\n   ```bash\n   python app.py --serve 8000\n   ```\n\n   You should see output confirming the server is running:\n\n   ```\n   Starting HTTP API server on 127.0.0.1:8000\n   Available endpoints:\n   - GET  /api/health - Health check\n   - POST /api/initialize - Initialize a directory\n   - POST /api/ask - Ask the agent a question\n   - POST /api/index/start - Start indexing a directory\n   - GET  /api/index/status - Get indexing status\n   Server is only accessible from localhost.\n   ```\n\n2. **Start the MCP Server**:\n   In a new terminal window, start the MCP server:\n\n   ```bash\n   python mcp_server.py\n   ```\n\n   The MCP server will automatically check if the HTTP API server is running and start it if needed.\n\n3. **Configure the MCP Server** (Optional):\n   You can configure the MCP server by setting the following environment variables in your `.env` file:\n\n   ```\n   # MCP Server Settings\n   MCP_API_URL=http://localhost:8000\n   MCP_HTTP_PORT=8000\n   ```\n\n#### Using with Claude Desktop\n\nTo use VerbalCodeAI with Claude Desktop:\n\n1. **Install the MCP SDK**:\n   ```bash\n   pip install mcp\n   ```\n\n2. **Install the MCP Server in Claude Desktop**:\n\n   **Method 1: Using the command line**\n   ```bash\n   mcp install mcp_server.py\n   ```\n\n   **Method 2: Using JSON configuration**\n\n   You can also configure Claude Desktop to use VerbalCodeAI by adding an entry to the MCP servers configuration file. This is especially useful if you're using a virtual environment or need custom configuration.\n\n   1. Locate your Claude Desktop configuration directory:\n      - Windows: `%APPDATA%\\Claude Desktop\\User Data\\Default\\`\n      - macOS: `~/Library/Application Support/Claude Desktop/User Data/Default/`\n      - Linux: `~/.config/Claude Desktop/User Data/Default/`\n\n   2. Create or edit the `mcp_servers.json` file in this directory:\n      ```json\n      {\n        \"mcpServers\": {\n          \"VerbalCodeAI\": {\n            \"command\": \"YOUR_VENV_PATH\\\\Scripts\\\\uv.EXE\",\n            \"args\": [\n              \"run\",\n              \"--with\",\n              \"mcp[cli]\",\n              \"--with\",\n              \"python-dotenv\",\n              \"--with\",\n              \"requests\",\n              \"mcp\",\n              \"run\",\n              \"PATH_TO_VERBALCODEAI\\\\mcp_server.py\"\n            ]\n          }\n        }\n      }\n      ```\n\n      Replace:\n      - `YOUR_VENV_PATH` with the path to your Python virtual environment (e.g., `D:\\\\VerbalCodeAi\\\\.venv`)\n      - `PATH_TO_VERBALCODEAI` with the path to your VerbalCodeAI installation (e.g., `D:\\\\VerbalCodeAi`)\n\n      Example for a Windows installation:\n      ```json\n      {\n        \"mcpServers\": {\n          \"VerbalCodeAI\": {\n            \"command\": \"D:\\\\VerbalCodeAi\\\\.venv\\\\Scripts\\\\uv.EXE\",\n            \"args\": [\n              \"run\",\n              \"--with\",\n              \"mcp[cli]\",\n              \"--with\",\n              \"python-dotenv\",\n              \"--with\",\n              \"requests\",\n              \"mcp\",\n              \"run\",\n              \"D:\\\\VerbalCodeAi\\\\mcp_server.py\"\n            ]\n          }\n        }\n      }\n      ```\n\n   3. Restart Claude Desktop for the changes to take effect.\n\n3. **Open Claude Desktop**:\n   - Launch Claude Desktop\n   - Click on the \"+\" button to start a new conversation\n   - Select \"VerbalCodeAI\" from the list of available tools\n\n4. **Initialize a Project**:\n   In Claude Desktop, you can now use the following tools:\n   - `initialize_directory(directory_path)` - Initialize a directory for use with VerbalCodeAI\n   - `ask_agent(question)` - Ask the agent a question about the codebase\n   - `start_indexing(directory_path)` - Start indexing a directory\n   - `get_indexing_status()` - Get the status of the indexing process\n   - `health_check()` - Check if the HTTP API server is running\n   - `start_http_server_tool(port)` - Start the HTTP API server if it's not running\n   - `set_api_url(url)` - Set the API URL for the HTTP API server\n\n   Example conversation:\n\n   ```\n   User: Can you help me analyze my project?\n\n   Claude: I'd be happy to help you analyze your project using VerbalCodeAI. First, let's check if the HTTP API server is running.\n\n   [Tool: health_check]\n   Result: {\"status\": \"ok\", \"message\": \"HTTP API server is running\"}\n\n   Great! Now let's initialize your project. What's the path to your project directory?\n\n   User: D:/my-project\n\n   Claude: I'll initialize your project now.\n\n   [Tool: initialize_directory]\n   Input: {\"directory_path\": \"D:/my-project\"}\n   Result: {\"status\": \"ok\", \"message\": \"Directory initialized successfully\"}\n\n   Now I'll start indexing your project to analyze the codebase.\n\n   [Tool: start_indexing]\n   Input: {\"directory_path\": \"D:/my-project\"}\n   Result: {\"status\": \"ok\", \"message\": \"Indexing started\"}\n\n   Let's check the indexing status.\n\n   [Tool: get_indexing_status]\n   Result: {\"status\": \"in_progress\", \"progress\": 45, \"message\": \"Indexing in progress\"}\n\n   The indexing is currently at 45%. Once it's complete, I can help you analyze your codebase. What would you like to know about your project?\n   ```\n\n#### Using with Cursor\n\n[Cursor](https://cursor.sh/) is an AI-powered code editor that supports MCP. To use VerbalCodeAI with Cursor:\n\n1. **Install Cursor** if you haven't already from [cursor.sh](https://cursor.sh/)\n\n2. **Start the MCP Server**:\n   ```bash\n   python mcp_server.py\n   ```\n\n3. **Connect Cursor to the MCP Server**:\n   - Open Cursor\n   - Go to Settings \u003e AI \u003e Model Context Protocol\n   - Add a new MCP server with the URL `http://localhost:3000` (or the port your MCP server is running on)\n   - Select \"VerbalCodeAI\" from the list of available tools\n\n4. **Use VerbalCodeAI in Cursor**:\n   - Open your project in Cursor\n   - Use the AI chat to interact with VerbalCodeAI\n   - You can ask questions about your codebase, get explanations, and more\n\n## Configuration\n\nVerbalCodeAI can be configured through the `.env` file:\n\n```\n# Provider can be: ollama, google, openai, anthropic, groq, or openrouter\nAI_CHAT_PROVIDER=ollama\nAI_EMBEDDING_PROVIDER=ollama\nAI_DESCRIPTION_PROVIDER=ollama\nAI_AGENT_BUDDY_PROVIDER=ollama\n\n# Azure OpenAI\n# when using openai as a provider and you want to use Azure OpenAI, set these variables\n# the endpoint should be in the format: https://\u003cyour-resource-name\u003e.openai.azure.com/\nAZURE_OPENAI_ENDPOINT=None\n# The API version to access your OpenAI resource. E.g. 2024-07-01-preview\nOPENAI_API_VERSION=None\n\n# API Keys for each functionality (only needed if using that provider)\n# The same key will be used for the selected provider in each category\nAI_CHAT_API_KEY=None\nAI_EMBEDDING_API_KEY=None\nAI_DESCRIPTION_API_KEY=None\nAI_AGENT_BUDDY_API_KEY=None\n\n# Model names for each provider\n# For ollama: llama2, codellama, mistral, etc. (embedding)\n# For OpenAI: gpt-4, gpt-3.5-turbo, text-embedding-ada-002 (embedding)\n# For OpenRouter: anthropic/claude-3-opus, openai/gpt-4-turbo, google/gemini-pro, etc.\n# For Google: gemini-pro, gemini-pro-vision\n# For Anthropic: claude-3-5-sonnet-latest, claude-3-opus-20240229, claude-3-haiku-20240307\n# For Groq: llama3-8b-8192, llama3-70b-8192, mixtral-8x7b-32768\nCHAT_MODEL=llama2\nEMBEDDING_MODEL=all-minilm:33m\nDESCRIPTION_MODEL=llama2\nAI_AGENT_BUDDY_MODEL=llama3.2\n\n# Model Tempratures\nCHAT_MODEL_TEMPERATURE=0.7\nDESCRIPTION_MODEL_TEMPERATURE=0.3\nAI_AGENT_BUDDY_MODEL_TEMPERATURE=0.7\nINTENT_DETECTION_TEMPERATURE=0.1\n\n# Model Max Tokens\nCHAT_MODEL_MAX_TOKENS=4096\nDESCRIPTION_MODEL_MAX_TOKENS=4096\nAI_AGENT_BUDDY_MODEL_MAX_TOKENS=4096\nINTENT_DETECTION_MAX_TOKENS=4096\n\n# Other Model Settings\nCHAT_MODEL_TOP_P=0.95\nCHAT_MODEL_TOP_K=40\nDESCRIPTION_MODEL_TOP_P=0.95\nDESCRIPTION_MODEL_TOP_K=40\nINTENT_DETECTION_TOP_P=0.95\nINTENT_DETECTION_TOP_K=40\n\n# Optional: Site information for OpenRouter rankings\nSITE_URL=http://localhost:3000\nSITE_NAME=Local Development\n\n# Performance settings (LOW, MEDIUM, MAX)\n# LOW: Minimal resource usage, suitable for low-end systems\n# MEDIUM: Balanced resource usage, suitable for most systems\n# MAX: Maximum resource usage, suitable for high-end systems\nPERFORMANCE_MODE=MEDIUM\n# Maximum number of threads to use (will be calculated automatically if not set)\nMAX_THREADS=16\n# Cache size for embedding queries (higher values use more memory but improve performance)\nEMBEDDING_CACHE_SIZE=1000\n# Similarity threshold for embedding search (lower values return more results but may be less relevant)\nEMBEDDING_SIMILARITY_THRESHOLD=0.05\n\n# API Rate Limiting Settings\n# Delay in milliseconds between embedding API calls to prevent rate limiting\n# Recommended: 100ms for Google, 0ms for OpenAI/Ollama (set to 0 to disable)\nEMBEDDING_API_DELAY_MS=100\n# Delay in milliseconds between description generation API calls to prevent rate limiting\n# Recommended: 100ms for Google, 0ms for OpenAI/Ollama (set to 0 to disable)\nDESCRIPTION_API_DELAY_MS=100\n\n# Maximum number of threads to use (will be calculated automatically if not set)\n# MAX_THREADS=16\n\n# UI Settings\n# Enable/disable markdown rendering (TRUE/FALSE)\nENABLE_MARKDOWN_RENDERING=TRUE\n# Show thinking blocks in AI responses (TRUE/FALSE)\nSHOW_THINKING_BLOCKS=FALSE\n# Enable streaming mode for AI responses (TRUE/FALSE) # Tends to be slower for some reason # Broken for openrouter TODO: Fix this at some point !\nENABLE_STREAMING_MODE=FALSE\n# Enable chat logging to save conversations (TRUE/FALSE)\nCHAT_LOGS=FALSE\n# Enable memory for AI conversations (TRUE/FALSE)\nMEMORY_ENABLED=TRUE\n# Maximum number of memory items to store\nMAX_MEMORY_ITEMS=10\n# Execute commands without confirmation (TRUE/FALSE)\n# When FALSE, the user will be prompted to confirm before executing any command\n# When TRUE, commands will execute automatically without confirmation\nCOMMANDS_YOLO=FALSE\n\n# HTTP API Server Settings\n# Allow connections from any IP address (TRUE/FALSE)\n# When FALSE, the server only accepts connections from localhost (127.0.0.1)\n# When TRUE, the server accepts connections from any IP address (0.0.0.0)\n# WARNING: Setting this to TRUE may expose your API to the internet\nHTTP_ALLOW_ALL_ORIGINS=FALSE\n\n# MCP Server Settings\n# URL of the HTTP API server\nMCP_API_URL=http://localhost:8000\n# Port to run the HTTP API server on\nMCP_HTTP_PORT=8000\n```\n\n### Supported LLM Providers\n\n- **Ollama**: Local models (default)\n- **Google AI**: Cloud-based models (requires API key)\n- **OpenAI**: OpenAI models for both chat and embeddings (requires API key)\n- **Anthropic**: Claude models for chat with streaming support (requires API key)\n- **Groq**: High-performance LLMs with extremely low latency (requires API key)\n- **OpenRouter**: Various cloud models (requires API key)\n\n#### Recommended Ollama Setup\n\nFor the best local experience without any API costs, the developer recommends using these Ollama models:\n- **Chat/Description**: `gemma3` - Google's Gemma 3 model provides excellent code understanding and generation\n- **Embeddings**: `all-minilm` - Efficient and accurate embeddings for code search and retrieval\n\nTo use these models, make sure they're installed in Ollama:\n```bash\nollama pull gemma3\nollama pull all-minilm\n```\n\nThen configure your `.env` file:\n```\nAI_CHAT_PROVIDER=ollama\nAI_EMBEDDING_PROVIDER=ollama\nAI_DESCRIPTION_PROVIDER=ollama\nCHAT_MODEL=gemma3\nEMBEDDING_MODEL=all-minilm:33m\nDESCRIPTION_MODEL=gemma3\n```\n\n#### Anthropic Claude Models\n\nAnthropic's Claude models are particularly strong at understanding and generating code. Available models include:\n- **claude-3-5-sonnet-latest**: Latest version of Claude 3.5 Sonnet, excellent balance of performance and speed\n- **claude-3-opus-20240229**: Most powerful Claude model with advanced reasoning capabilities\n- **claude-3-haiku-20240307**: Fastest and most cost-effective Claude model\n\nNote: Anthropic does not provide embedding capabilities, so you'll need to use a different provider for embeddings.\n\n#### Groq Models\n\nGroq provides ultra-fast inference for popular open-source models. Available models include:\n- **llama3-8b-8192**: Smaller Llama 3 model with 8B parameters, good balance of performance and speed\n- **llama3-70b-8192**: Larger Llama 3 model with 70B parameters, excellent reasoning capabilities\n- **mixtral-8x7b-32768**: Mixtral model with 8x7B parameters and 32k context window\n\nNote: Groq does not provide embedding capabilities, so you'll need to use a different provider for embeddings.\n\n### Performance Settings\n\n- **LOW**: Minimal resource usage, suitable for low-end systems\n- **MEDIUM**: Balanced resource usage, suitable for most systems\n- **MAX**: Maximum resource usage, suitable for high-end systems\n\n### UI Settings\n\n- **ENABLE_MARKDOWN_RENDERING**: Enable/disable markdown rendering in responses\n- **SHOW_THINKING_BLOCKS**: Show AI's thinking process in responses\n- **ENABLE_STREAMING_MODE**: Enable streaming responses (may be slower)\n- **CHAT_LOGS**: Save conversation logs to disk\n- **MEMORY_ENABLED**: Enable AI memory for conversations\n- **MAX_MEMORY_ITEMS**: Maximum number of memory items to store\n- **COMMANDS_YOLO**: When FALSE, prompts for confirmation before executing commands\n\n\n\n## Video Showcase\n\nCheck out a quick video demonstration of VerbalCodeAI in action:\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://youtu.be/5EnenUD-4E4?si=WIw-C4ne4JCP5dfZ\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://img.youtube.com/vi/5EnenUD-4E4/hqdefault.jpg\" alt=\"VerbalCodeAI Video Showcase\" width=\"480\"/\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nOr watch directly on [YouTube](https://youtu.be/5EnenUD-4E4?si=WIw-C4ne4JCP5dfZ).\n\n---\n\n## Image Showcase\n\nBelow are some screenshots and showcase images of VerbalCodeAI in action:\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"Showcase/Agent Mode New commands.PNG\" alt=\"Agent Mode New commands\" style=\"width: 350px; max-width: 100%; height: auto; margin: 10px;\"/\u003e\n  \u003cimg src=\"Showcase/Agent Showcase.png\" alt=\"Agent Showcase\" style=\"width: 350px; max-width: 100%; height: auto; margin: 10px;\"/\u003e\n  \u003cimg src=\"Showcase/First Implementation Chat With Ai.png\" alt=\"First Implementation Chat With Ai\" style=\"width: 350px; max-width: 100%; height: auto; margin: 10px;\"/\u003e\n  \u003cimg src=\"Showcase/Main Menu Showcase.PNG\" alt=\"Main Menu Showcase\" style=\"width: 350px; max-width: 100%; height: auto; margin: 10px;\"/\u003e\n  \u003cimg src=\"Showcase/Second Agent.PNG\" alt=\"Second Agent\" style=\"width: 350px; max-width: 100%; height: auto; margin: 10px;\"/\u003e\n  \u003cimg src=\"Showcase/Second Implementation Chat With Ai.PNG\" alt=\"Second Implementation Chat With Ai\" style=\"width: 350px; max-width: 100%; height: auto; margin: 10px;\"/\u003e\n\u003c/div\u003e\n\n---\n\n## Project Structure\n\n```\nVerbalCodeAi/\n├── app.py                  # Main application entry point\n├── mcp_server.py           # MCP server wrapper\n├── mcp_server_http.py      # HTTP-based MCP server implementation\n├── mods/                   # Core modules\n│   ├── banners.py          # ASCII art banners\n│   ├── http_api.py         # HTTP API server implementation\n│   ├── llms.py             # LLM integration\n│   ├── terminal_ui.py      # Terminal UI components\n│   ├── terminal_utils.py   # Terminal utilities\n│   └── code/               # Code processing modules\n│       ├── agent_mode.py   # Agent mode implementation\n│       ├── decisions.py    # AI decision making\n│       ├── directory.py    # Directory structure handling\n│       ├── embed.py        # Embedding generation and search\n│       ├── indexer.py      # File indexing\n│       ├── memory.py       # Memory management\n│       ├── terminal.py     # Terminal command execution\n│       └── tools.py        # Agent tools\n├── requirements.txt        # Python dependencies\n├── setup_windows.bat       # Windows setup script\n└── setup_linux.sh          # Linux setup script\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Links\n\n- [Website](https://verbalcode.xyz)\n- [GitHub Repository](https://github.com/vibheksoni/VerbalCodeAi)\n- [Report Issues](https://github.com/vibheksoni/VerbalCodeAi/issues)\n\n## Acknowledgements\n\n- [Ollama](https://ollama.com/) for local model execution\n- [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) for code parsing\n- All the open-source libraries that make this project possible\n\n---\n\n\u003cp align=\"center\"\u003e\n  Made with ❤️ by \u003ca href=\"https://github.com/vibheksoni\"\u003eVibhek Soni\u003c/a\u003e\n\u003c/p\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvibheksoni%2Fverbalcodeai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvibheksoni%2Fverbalcodeai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvibheksoni%2Fverbalcodeai/lists"}