{"id":43083204,"url":"https://github.com/cognautic/cli","last_synced_at":"2026-03-08T11:02:18.611Z","repository":{"id":319110425,"uuid":"1071663395","full_name":"cognautic/cli","owner":"cognautic","description":"Code with AI with Cognautic CLI","archived":false,"fork":false,"pushed_at":"2026-03-01T11:02:07.000Z","size":523,"stargazers_count":3,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"latest","last_synced_at":"2026-03-01T14:52:53.492Z","etag":null,"topics":["claude-code","cli","code-with-ai","cognautic","cognautic-cli"],"latest_commit_sha":null,"homepage":"https://cognautic.vercel.app/cli/","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/cognautic.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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-10-07T16:39:47.000Z","updated_at":"2026-03-01T11:02:10.000Z","dependencies_parsed_at":null,"dependency_job_id":"f6f3d5eb-80ab-4e84-8813-5eec9b262ff1","html_url":"https://github.com/cognautic/cli","commit_stats":null,"previous_names":["cognautic/cli"],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/cognautic/cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cognautic%2Fcli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cognautic%2Fcli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cognautic%2Fcli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cognautic%2Fcli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cognautic","download_url":"https://codeload.github.com/cognautic/cli/tar.gz/refs/heads/latest","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cognautic%2Fcli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30253935,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-08T08:59:44.879Z","status":"ssl_error","status_checked_at":"2026-03-08T08:58:02.867Z","response_time":56,"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":["claude-code","cli","code-with-ai","cognautic","cognautic-cli"],"created_at":"2026-01-31T15:04:17.163Z","updated_at":"2026-03-08T11:02:18.604Z","avatar_url":"https://github.com/cognautic.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cognautic CLI\n\n**A Python-based CLI AI coding agent that provides agentic development capabilities with multi-provider AI support and real-time interaction.**\n\n⚠️ **Under Development** - Some features may be unavailable\n\nJoin our Discord: [https://discord.gg/QrfpWDuZqd](https://discord.gg/QrfpWDuZqd)  \nFollow us on Instagram: [https://www.instagram.com/cognautic/](https://www.instagram.com/cognautic/)\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pepy.tech/projects/cognautic-cli\"\u003e\n    \u003cimg src=\"https://static.pepy.tech/personalized-badge/cognautic-cli?period=total\u0026units=INTERNATIONAL_SYSTEM\u0026left_color=BLACK\u0026right_color=GREEN\u0026left_text=downloads\" alt=\"PyPI Downloads\" width=\"520\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n## Voice Input (NEW)\n\nCognautic CLI supports one-shot speech-to-text to quickly prefill your prompt.\n\n### Installation\n\n- Recommended (extras):\n  - `pip install -e .[voice]`\n- Or install dependencies directly:\n  - `pip install SpeechRecognition PyAudio`\n- Linux note: PyAudio often requires PortAudio headers first:\n  - Debian/Ubuntu: `sudo apt install portaudio19-dev`\n\n### Usage\n\n- Press `Ctrl+G` in the chat prompt to start a one-shot capture. After you speak, the recognized text is prefilled as the next prompt so you can edit or send.\n- Use the slash command `/voice` to capture once and prefill the next prompt.\n\n### Troubleshooting\n\n- ALSA warnings: The CLI suppresses common ALSA/libportaudio stderr noise while accessing the microphone.\n- \"No default microphone\": Ensure a working input device is selected and not in use by another app.\n- Network required: The default recognizer uses Google's Web Speech API.\n- Prefer offline STT (e.g., Vosk or faster-whisper)? Open an issue to request integration.\n\n---\n\n## Vim Editor Integration (NEW)\n\nCognautic CLI now includes built-in vim editor integration, allowing you to edit files directly from the chat interface without leaving the terminal.\n\n### Installation\n\nVim must be installed on your system:\n\n```bash\n# On Arch Linux\nsudo pacman -S vim\n\n# On Debian/Ubuntu\nsudo apt install vim\n\n# On macOS\nbrew install vim\n```\n\n### Usage\n\n#### Open vim without a file\n```bash\n/editor\n```\nOpens vim in an empty buffer. Perfect for quick notes or scratch work.\n\n#### Open vim with a specific file\n```bash\n/editor myfile.txt\n/editor src/main.py\n/editor /absolute/path/to/file.js\n```\nOpens vim with the specified file. Supports both relative (to current workspace) and absolute paths.\n\n#### Editing and returning to chat\n\n1. Make your changes in vim\n2. Press **Ctrl+E** to save and exit back to chat\n3. Or use `:wq` to save and quit, or `:q!` to quit without saving\n\n**Key Features:**\n- ✅ Seamless integration - edit files without leaving Cognautic\n- ✅ Ctrl+E shortcut - quick save and return to chat\n- ✅ Path support - works with relative and absolute paths\n- ✅ Workspace aware - relative paths are resolved from current workspace\n\n**Example workflow:**\n```bash\nYou: /editor config.json\n# Vim opens, you make changes, press Ctrl+E\nINFO: Returned to chat mode\n\nYou: I've updated the configuration file\nAI: Great! Let me review those changes...\n```\n\n```\n\n---\n\n## MCP (Model Context Protocol) Support (NEW! 🔌)\n\nCognautic CLI now supports the **Model Context Protocol (MCP)**, an open standard by Anthropic for connecting AI systems with external data sources and tools.\n\n### What is MCP?\n\nMCP allows Cognautic to:\n- **Connect to external MCP servers** to access their tools, resources, and prompts\n- **Expose its own capabilities** as an MCP server for other clients to use\n\n### Quick Start\n\n```bash\n# Start Cognautic CLI\ncognautic chat\n\n# View MCP help\n/mcp\n\n# Connect to a server\n/mcp connect filesystem\n\n# List available tools\n/mcp tools\n\n# Use MCP tools naturally\nYou: Use the filesystem MCP server to list all Python files in my project\n```\n\n### Available Commands\n\n- `/mcp` - Show MCP help\n- `/mcp list` - List connected MCP servers\n- `/mcp connect \u003cserver\u003e` - Connect to a configured server\n- `/mcp disconnect \u003cserver\u003e` - Disconnect from a server\n- `/mcp tools` - List all available tools from connected servers\n- `/mcp resources` - List all available resources\n- `/mcp config` - Show MCP server configurations\n\n### Pre-configured Servers\n\nCognautic includes default configurations for popular MCP servers:\n\n1. **Filesystem Server** - Access local files and directories\n   ```bash\n   /mcp connect filesystem\n   ```\n\n2. **GitHub Server** - Interact with GitHub repositories\n   ```bash\n   # Configure your token in ~/.cognautic/mcp_servers.json first\n   /mcp connect github\n   ```\n\n3. **PostgreSQL Server** - Query PostgreSQL databases\n   ```bash\n   # Configure connection string in ~/.cognautic/mcp_servers.json first\n   /mcp connect postgres\n   ```\n\n### Configuration\n\nMCP servers are configured in `~/.cognautic/mcp_servers.json`:\n\n```json\n{\n  \"servers\": {\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/home/user\"],\n      \"env\": {},\n      \"transport\": \"stdio\"\n    }\n  }\n}\n```\n\n### Installing MCP Servers\n\n```bash\n# Install filesystem server\nnpm install -g @modelcontextprotocol/server-filesystem\n\n# Install GitHub server\nnpm install -g @modelcontextprotocol/server-github\n\n# Install PostgreSQL server\nnpm install -g @modelcontextprotocol/server-postgres\n```\n\n### Documentation\n\n- **[MCP_SUPPORT.md](MCP_SUPPORT.md)** - Comprehensive guide with architecture and troubleshooting\n- **[MCP_QUICK_REFERENCE.md](MCP_QUICK_REFERENCE.md)** - Quick reference and common commands\n- **[modelcontextprotocol.io](https://modelcontextprotocol.io)** - Official MCP specification\n\n---\n\n## Plugin System (NEW! 🔌)\n\nCognautic CLI features a powerful plugin system that allows you to extend its functionality with custom commands, tools, and features without modifying the core codebase.\n\n### What are Plugins?\n\nPlugins are self-contained extensions that can:\n- **Add custom slash commands** (e.g., `/debug`, `/format`, `/test`)\n- **Register AI tools** to extend what the AI can do\n- **Intercept messages** to modify or enhance interactions\n- **Access Cognautic's AI engine** to create intelligent features\n- **Interact with the workspace** and execute commands\n\n### Quick Start\n\n```bash\n# Start Cognautic CLI\ncognautic chat\n\n# Install a plugin (automatically loads it)\n/plugin install examples/plugins/debug-assistant\n\n# Use the plugin's commands\n/debug                    # Analyze workspace for bugs\n/debugfile test.js --fix  # Analyze and fix specific file\n```\n\n### Plugin Commands\n\n| Command | Description |\n|---------|-------------|\n| `/plugin install \u003cpath\u003e` | Install and auto-load a plugin from a directory |\n| `/plugin list` | List all installed plugins with their status |\n| `/plugin load \u003cname\u003e` | Load a specific plugin |\n| `/plugin unload \u003cname\u003e` | Unload a plugin from memory |\n| `/plugin uninstall \u003cname\u003e` | Completely remove a plugin |\n| `/plugin info \u003cname\u003e` | Show detailed information about a plugin |\n\n#### 2. Hello World\n**Location:** `examples/plugins/hello-world/`\n\nA simple example plugin demonstrating basic plugin structure and capabilities.\n\n**Commands:**\n```bash\n/hello          # Simple greeting\n/greet \u003cname\u003e   # Personalized greeting\n/stats          # Show plugin statistics\n```\n\n### Creating Your Own Plugin\n\n**1. Create plugin directory:**\n```bash\nmkdir my-plugin\ncd my-plugin\n```\n\n**2. Create `plugin.json`:**\n```json\n{\n  \"name\": \"my-plugin\",\n  \"version\": \"1.0.0\",\n  \"description\": \"My awesome plugin\",\n  \"author\": \"Your Name\",\n  \"entry_point\": \"my_plugin.Plugin\",\n  \"dependencies\": []\n}\n```\n\n**3. Create `my_plugin.py`:**\n```python\nfrom cognautic.plugin_manager import BasePlugin, PluginAPI\n\nclass Plugin(BasePlugin):\n    async def on_load(self):\n        # Register a custom command\n        self.api.register_command(\n            \"mycommand\",\n            self.my_command,\n            \"Description of my command\"\n        )\n        self.api.print(\"My plugin loaded!\", style=\"green\")\n    \n    async def my_command(self, args, context):\n        self.api.print(\"Hello from my plugin!\")\n        \n        # Use AI\n        response = await self.api.ask_ai(\"What is Python?\")\n        self.api.print(response)\n```\n\n**4. Install and use:**\n```bash\n/plugin install /path/to/my-plugin\n/mycommand\n```\n\n### Plugin API\n\nPlugins have access to a rich API:\n\n**Command Registration:**\n- `api.register_command(command, handler, description)` - Add custom commands\n- `api.register_tool(tool)` - Add tools for AI to use\n\n**Context Access:**\n- `api.get_workspace()` - Get current workspace path\n- `api.get_provider()` - Get current AI provider\n- `api.get_model()` - Get current AI model\n- `api.get_config_manager()` - Access configuration\n- `api.get_ai_engine()` - Access AI engine\n- `api.get_memory_manager()` - Access conversation memory\n\n**Utilities:**\n- `api.print(message, style)` - Print with Rich formatting\n- `api.execute_command(cmd)` - Run shell commands\n- `api.ask_ai(prompt)` - Send prompts to AI\n\n**Lifecycle Hooks:**\n- `on_load()` - Called when plugin loads\n- `on_unload()` - Called when plugin unloads\n- `on_message(message, role)` - Intercept messages\n\n### Documentation\n\n- **[PLUGIN_DEVELOPMENT.md](PLUGIN_DEVELOPMENT.md)** - Complete plugin development guide\n- **[examples/plugins/README.md](examples/plugins/README.md)** - Plugin examples and tutorials\n- **[PLUGIN_SYSTEM_SUMMARY.md](PLUGIN_SYSTEM_SUMMARY.md)** - Implementation overview\n\n### Plugin Ideas\n\n- **Code formatters** - Auto-format code in different styles\n- **Test generators** - Generate unit tests for functions\n- **Documentation generators** - Create docs from code\n- **Deployment tools** - Deploy to various platforms\n- **Database tools** - Query and manage databases\n- **API clients** - Interact with external APIs\n- **Custom linters** - Project-specific code quality checks\n\n---\n\n## Repository Documenter (NEW! 📚)\n\nCognautic CLI includes a built-in **Repository Documenter** that automatically generates comprehensive documentation for any public git repository using AI.\n\n### What is Repository Documenter?\n\nThe Repository Documenter analyzes a git repository's structure, code, and configuration files to create:\n- **Comprehensive Documentation** - Complete README-style documentation in Markdown\n- **Architecture Diagrams** - Python scripts using Graphviz to visualize project architecture\n- **Project Overview** - What the project does and its purpose\n- **Installation Guide** - How to install and set up the project\n- **Usage Instructions** - How to use the project\n- **Code Structure** - Explanation of directory structure and key modules\n\n### Quick Start\n\n```bash\n# Start Cognautic CLI\ncognautic chat\n\n# Generate documentation for any public repository\n/docrepo https://github.com/user/awesome-project\n```\n\n### Usage\n\n```bash\n/docrepo \u003cgit_url\u003e\n```\n\n**Examples:**\n```bash\n# Document a GitHub repository\n/docrepo https://github.com/fastapi/fastapi\n\n# Document a GitLab repository\n/docrepo https://gitlab.com/user/project\n\n# Document using SSH URL\n/docrepo git@github.com:user/repo.git\n```\n\n### Output Files\n\nThe command generates two files in your current workspace:\n\n1. **`{repo_name}_DOCS.md`** - Comprehensive documentation in Markdown format\n   - Project overview and purpose\n   - Installation instructions\n   - Usage guide\n   - Code structure explanation\n   - Architecture description\n\n2. **`extra/{repo_name}_graph.py`** - Python script to generate architecture diagram\n   - Self-contained script using Graphviz\n   - Run with: `python extra/{repo_name}_graph.py`\n   - Generates visual architecture diagram\n\n### Features\n\n- ✅ **One-Command Documentation** - Generate everything with a single command\n- ✅ **AI-Powered Analysis** - Deep understanding of code structure and purpose\n- ✅ **Smart File Selection** - Automatically identifies key files (README, package.json, requirements.txt, etc.)\n- ✅ **Multi-Language Support** - Python, JavaScript, TypeScript, Rust, Go, Java, C/C++, Ruby, PHP, and more\n- ✅ **Automatic Cleanup** - Cleans up temporary cloned repositories\n- ✅ **Token Optimized** - Intelligently limits file contents to prevent context overflow\n\n### Example Workflow\n\n```bash\n# Navigate to your workspace\n/workspace ~/projects\n\n# Generate documentation for a repository\n/docrepo https://github.com/django/django\n\n# AI analyzes the repository...\n# ✓ Cloning repository...\n# ✓ Analyzing file structure...\n# ✓ Found 1,234 files\n# ✓ Sending request to AI...\n# ✓ Documentation saved to: django_DOCS.md\n# ✓ Graph script saved to: extra/django_graph.py\n\n# View the generated documentation\ncat django_DOCS.md\n\n# Generate the architecture diagram\ncd extra\npython django_graph.py\n```\n\n### Supported File Types\n\n**Configuration Files:**\n- README.md, package.json, requirements.txt\n- pyproject.toml, setup.py, Cargo.toml\n- go.mod, pom.xml, build.gradle\n- composer.json\n\n**Source Code:**\n- Python (.py), JavaScript (.js), TypeScript (.ts, .tsx, .jsx)\n- Rust (.rs), Go (.go), Java (.java)\n- C/C++ (.c, .cpp, .h), Ruby (.rb), PHP (.php)\n- Vue (.vue), Swift (.swift), Kotlin (.kt)\n- Scala (.scala), C# (.cs)\n\n### Requirements\n\n- **Git** - Must be installed on your system\n- **Public Repository** - Repository must be publicly accessible\n- **AI Provider** - Any configured AI provider (OpenAI, Anthropic, Google, etc.)\n- **Graphviz** (optional) - To run the generated architecture diagram scripts\n\n### Tips\n\n- Use with larger, more capable models for better documentation quality\n- The generated graph script requires `graphviz` Python package: `pip install graphviz`\n- Documentation quality improves with well-structured repositories\n- Works best with repositories that have clear file organization\n\n---\n\n## Multi-Agent Collaboration (NEW! 🤖🤝🤖)\n\nCognautic CLI now supports **Multi-Agent Collaboration** where multiple AI models work together on your projects through a structured three-phase workflow.\n\n### What is Multi-Agent Collaboration?\n\nMulti-Agent mode enables different AI models to collaborate in real-time:\n- **Phase 1: Discussion** - Agents analyze the task and discuss approaches\n- **Phase 2: Planning** - Agents coordinate and divide the work\n- **Phase 3: Execution** - Agents work in parallel with live side-by-side view\n\n### Quick Start\n\n```bash\n# Start Cognautic CLI\ncognautic chat\n\n# Activate multi-agent mode with 2+ models\n/multiagent openai gpt-4 anthropic claude-3-sonnet google gemini-pro\n\n# Send your project request\nBuild a todo app with React frontend and Node.js backend\n```\n\n### Usage\n\n```bash\n/multiagent provider1 model1 provider2 model2 [provider3 model3 ...]\n```\n\n**Examples:**\n```bash\n# Two agents\n/multiagent openai gpt-4 google gemini-pro\n\n# Three agents for complex projects\n/multiagent openai gpt-4 anthropic claude-3-sonnet google gemini-2.5-flash\n\n# Mix different providers\n/multiagent openrouter gpt-4 groq llama-3.1-70b google gemini-pro\n```\n\n### The Three-Phase Workflow\n\n#### Phase 1: Discussion 💬\nAgents take turns analyzing your request:\n- **Agent 1** analyzes the task and identifies main components\n- **Agent 2** reviews Agent 1's analysis and adds their perspective  \n- **Agent 3+** continue the discussion, pointing out missed items\n\n**Example:**\n```\nAgent 1 (GPT-4): \"We need authentication, database models, and API endpoints...\"\nAgent 2 (Claude): \"Good analysis. I'd add input validation and rate limiting...\"\nAgent 3 (Gemini): \"Building on previous points, let's use PostgreSQL and Docker...\"\n```\n\n#### Phase 2: Planning 📋\nAgents coordinate to divide the work:\n- **Coordinator** (Agent 1) creates task assignments\n- Other agents review and suggest modifications\n- Tasks are assigned with priorities and file responsibilities\n\n**Example Plan:**\n```\nAgent 1: Set up project structure (Priority: 1)\nAgent 2: Implement authentication system (Priority: 1)\nAgent 3: Create API endpoints and documentation (Priority: 2)\n```\n\n#### Phase 3: Real-Time Execution ⚡\nAgents work in parallel with **side-by-side split-screen view**:\n\n```\n┌─────────────────────┬─────────────────────┬─────────────────────┐\n│ Agent 1 (GPT-4)     │ Agent 2 (Claude)    │ Agent 3 (Gemini)    │\n├─────────────────────┼─────────────────────┼─────────────────────┤\n│ Creating package.   │ Setting up Express  │ Creating Docker     │\n│ json...             │ server...           │ files...            │\n│ ✓ Created React app │ ✓ Created routes    │ ✓ Created Dockerfile│\n│ Creating components │ Creating models     │ Creating tests      │\n│ ...                 │ ...                 │ ...                 │\n└─────────────────────┴─────────────────────┴─────────────────────┘\n```\n\n### Features\n\n- ✅ **Diverse Perspectives** - Different models bring different strengths\n- ✅ **Quality Assurance** - Agents review each other's plans\n- ✅ **Parallel Execution** - Faster than sequential single-agent work\n- ✅ **Shared Workspace** - All agents work in same folder for easy integration\n- ✅ **Live Streaming** - See exactly what each agent is doing in real-time\n- ✅ **Auto YOLO Mode** - Automatically enabled for smooth collaboration\n\n### Best Practices\n\n1. **Choose Diverse Models**: Use different models for varied perspectives\n   - GPT-4 for complex reasoning\n   - Claude for detailed analysis\n   - Gemini for creative solutions\n\n2. **Optimal Agent Count**:\n   - 2 agents: Good for simple tasks\n   - 3 agents: Ideal for most projects\n   - 4+ agents: For complex, multi-faceted projects\n\n3. **Clear Requests**: Be specific about what you want built\n\n4. **Review Integration**: Agents work in parallel, so review how their work fits together\n\n### Example Workflow\n\n```bash\n# Set up workspace\n/workspace ~/projects/my-app\n\n# Activate multi-agent mode\n/multiagent openai gpt-4 anthropic claude-3-sonnet google gemini-pro\n\n# Send request\nCreate a modern web application with:\n- React frontend with TypeScript\n- Express.js backend\n- PostgreSQL database\n- User authentication\n- RESTful API\n- Docker deployment\n\n# Watch the agents collaborate!\n# ✓ Discussion phase complete\n# ✓ Planning phase complete  \n# ✓ Execution phase complete (side-by-side view)\n# 🎉 Project ready in your workspace!\n```\n\n### Documentation\n\n- **[MULTIAGENT.md](MULTIAGENT.md)** - Comprehensive user guide\n- **[MULTIAGENT_IMPLEMENTATION.md](MULTIAGENT_IMPLEMENTATION.md)** - Technical documentation\n\n---\n\n## Overview\n\nCognautic CLI is a Python-based command-line interface that brings AI-powered development capabilities directly to your terminal. It provides agentic tools for file operations, command execution, web search, and code analysis with support for multiple AI providers. The tool is accessed through a single `cognautic` command with various subcommands.\n\n\u003e **⚠️ Development Notice:** Cognautic CLI is currently under development. Some features may be unavailable or subject to change.\n\n### Project Information\n\n| Property | Value |\n|----------|-------|\n| **Developer** | Cognautic |\n| **Written in** | Python |\n| **Operating system** | Cross-platform |\n| **Type** | AI Development Tool |\n| **Status** | Under Development |\n| **Repository** | [github.com/cognautic/cli](https://github.com/cognautic/cli) |\n\n---\n\n## Features\n\n- **Multi-Agent Collaboration**: Enable multiple AI models to collaborate on projects through discussion, planning, and parallel execution (NEW! 🤖🤝🤖)\n- **Ask Question Mode**: AI proactively asks clarifying questions when confused or uncertain (NEW! 🤔)\n- **Multi-Provider AI Support**: Integrate with OpenAI, Anthropic, Google, Together AI, OpenRouter, and more AI providers\n- **Local Model Support**: Run free open-source Hugging Face models locally without API keys\n- **Plugin System**: Extend Cognautic with custom commands and tools via plugins\n- **MCP (Model Context Protocol) Support**: Connect to external MCP servers and expose Cognautic's capabilities\n- **Agentic Tools**: File operations, command execution, web search, and code analysis\n- **Intelligent Web Search**: Automatically searches the web when implementing features requiring current/external information\n- **Rules Management**: Define global and workspace rules to guide AI behavior\n- **Real-time Communication**: WebSocket server for live AI responses and tool execution\n- **Secure Configuration**: Encrypted API key storage and permission management\n- **Interactive CLI**: Rich terminal interface with progress indicators, colored output, and command history\n- **Terminal Mode**: Toggle between Chat and Terminal modes with `Shift+Tab` for seamless workflows\n- **Native Tool Support**: Full integration with provider SDKs (including the new `google-genai` SDK) for stable, multi-turn tool calling with parallel execution support (NEW! 🛠️)\n- **Zero-Confirm Agentic Flow**: Recursive execution model that eliminates legacy \"continue\" prompts, allowing the AI to complete complex multi-step tasks autonomously (NEW! ⚡)\n- **Eager Tool Execution**: Real-time tool detection and execution during streaming for immediate feedback\n- **Background Commands**: Run long tasks in the background and manage them with `/ps` and `/ct \u003cprocess_id\u003e`\n- **Command Auto-Completion**: Tab-completion for slash commands with inline descriptions\n- **Safety Modes**: Confirmation prompts by default (Safe Mode) with quick toggle to YOLO mode via `/yolo` or `Ctrl+Y`\n- **Directory Context \u0026 Code Navigation**: Built-in tools for project structure awareness and symbol search/navigation\n- **Better Input \u0026 Exit Controls**: Multi-line input with `Alt+Enter` and safe exit with double `Ctrl+C`\n- **Multi-Model Testing**: Compare models side-by-side with `/mml ...`\n\n---\n\n## Installation\n\n### Prerequisites\n\nEnsure you have Python 3.8 or higher installed:\n\n```bash\npython --version\n```\n\n### Download the Wheel File\n\nDownload the latest `.whl` file from the official repository:\n\n```bash\n# Visit https://github.com/cognautic/cli/releases\n# Download the latest cognautic_cli-z.z.z-py3-none-any.whl file\n```\n\n### Installation with pip\n\nInstall the downloaded wheel file using pip:\n\n```bash\n# Navigate to your downloads folder\ncd ~/Downloads\n\n# Install the wheel file\npip install cognautic_cli-z.z.z-py3-none-any.whl\n\n#or (Now Available On PyPi)\npip install cognautic-cli\n```\n\n### Installation with pipx (Recommended)\n\nFor isolated installation, use pipx:\n\n```bash\n# Install pipx if you don't have it\npip install pipx\npipx ensurepath\n\n# Install Cognautic CLI with pipx\npipx install cognautic_cli-z.z.z-py3-none-any.whl\n\n#or (Now Available On PyPi)\npip install cognautic-cli\n```\n\n### Verify Installation\n\nCheck that Cognautic CLI is installed correctly:\n\n```bash\ncognautic --version\n```\n\n### Updating Cognautic CLI\n\nTo update to a newer version, download the new wheel file and:\n\n```bash\n# With pip (force reinstall)\npip install cognautic_cli-y.y.y-py3-none-any.whl --force-reinstall\n\n#or\npip install --upgrade cognautic-cli\n\n# With pipx\npipx upgrade cognautic-cli\n# Or force reinstall with pipx\npipx install cognautic_cli-y.y.y-py3-none-any.whl --force\n```\n\n_**Note:** Replace `y.y.y` and `z.z.z` with actual version numbers (e.g., 1.0.0, 1.1.0)._\n\n### Uninstallation\n\nTo remove Cognautic CLI:\n\n```bash\n# With pip\npip uninstall cognautic-cli\n\n# With pipx\npipx uninstall cognautic-cli\n```\n\n---\n\n## Quick Start\n\n### Step 1: Install Cognautic CLI\n\n```bash\npip install cognautic_cli-x.x.x-py3-none-any.whl\n```\n\n### Step 2: Run Setup\n\n```bash\ncognautic setup --interactive\n```\n\nThis will guide you through:\n- Configuring API keys for your preferred AI providers\n- Setting default provider and model\n- Basic preferences\n\n### Step 3: Start Chatting\n\n```bash\ncognautic chat\n```\n\nNow you can chat with AI and use slash commands like:\n- `/help` - Show available commands\n- `/provider openai` - Switch AI provider\n- `/model gpt-4` - Change model\n- `/workspace ~/myproject` - Set working directory\n- `/lmodel microsoft/phi-2` - Load local model\n\n**That's it!** Start chatting and let the AI help you code.\n\n---\n\n## Available Slash Commands\n\nOnce you're in chat mode (`cognautic chat`), use these commands:\n\n### Workspace \u0026 Configuration\n\n```bash\n/workspace \u003cpath\u003e    # Change working directory (alias: /ws)\n/setup               # Run interactive setup wizard\n/config list         # Show current configuration\n/config set \u003ckey\u003e \u003cvalue\u003e  # Set configuration value\n/config get \u003ckey\u003e    # Get configuration value\n/config delete \u003ckey\u003e # Delete configuration key\n/config reset        # Reset to defaults\n/help                # Show all available commands\n```\n\n### AI Provider \u0026 Model Management\n\n```bash\n/provider [name]           # Switch AI provider (openai, anthropic, google, openrouter, together, ollama, etc.)\n/model [model_id]          # Switch AI model\n/model list                # Fetch available models from provider's API (supports Ollama via /api/tags)\n/lmodel \u003cpath\u003e             # Load local Hugging Face model\n/lmodel unload             # Unload current local model\n/endpoint \u003cprov\u003e \u003curl\u003e     # Override provider base URL (e.g., ollama http://localhost:11434/api)\n```\n\n### Session Management\n\n```bash\n/session             # Show current session info\n/session list        # List all sessions\n/session new         # Create new session\n/session load \u003cid\u003e   # Load existing session\n/session delete \u003cid\u003e # Delete session\n/session title \u003ctext\u003e # Update session title\n```\nNote: You can also load sessions by numeric index from `/session list` using `/session load \u003cindex\u003e`.\n\n### Display \u0026 Interface\n\n```bash\n/speed [instant|fast|normal|slow]  # Set typing speed\n/editor [filepath]   # Open vim editor (Ctrl+E to save and exit)\n/clear               # Clear chat screen\n/exit or /quit       # Exit chat session\n```\n\n### Safety \u0026 Confirmation\n\n```bash\n/yolo                 # Toggle between Safe (confirm) and YOLO (no confirm) modes\n```\n\n### Ask Question Mode\n\n```bash\n/askq [on|off]        # Toggle ask question mode (AI can ask clarifying questions)\n```\n\n**What is Ask Question Mode?**\n\nWhen enabled, the AI will proactively ask clarifying questions when it encounters:\n- Framework/technology not specified (e.g., \"build an app\" → asks which framework)\n- Database/storage not specified (e.g., \"store data\" → asks which database)\n- Programming language ambiguous (e.g., \"create API\" → asks which language)\n- Multiple valid approaches (e.g., \"add auth\" → asks which method)\n- Styling/UI framework not clear (e.g., \"make it look good\" → asks which approach)\n\n**Example:**\n```bash\nYou: build a todo app\n\nAI: \n╭────────────────────────────────────────╮\n│  🤔 AI has a question:                 │\n│  Which framework would you prefer?     │\n╰────────────────────────────────────────╯\n\n  1. React with Vite\n  2. Vue.js\n  3. Python Flask\n  4. Something else\n\nYour choice: 1\n\nAI: Great! I'll build a todo app using React with Vite...\n```\n\n**Features:**\n- ✅ AI provides 2-3 specific options\n- ✅ Automatic \"Something else\" option for custom answers\n- ✅ Answer automatically sent to AI (no manual re-prompting)\n- ✅ Beautiful terminal UI with Rich panels\n- ✅ Seamless conversation flow\n\n\n### Background Processes\n\n```bash\n/ps                   # List running background processes\n/ct \u003cprocess_id\u003e      # Terminate a background process by its ID\n```\n\n### Multi-Model Testing\n\n```bash\n/mml \u003cprov1\u003e \u003cmodel1\u003e [prov2] \u003cmodel2\u003e ...   # Run models side-by-side with live streaming\n# Example: /mml google gemini-2.5-flash openrouter gpt-4\n/qmml                                        # Quit multi-model mode\n```\n\n### Multi-Agent Collaboration\n\n```bash\n/multiagent \u003cprov1\u003e \u003cmodel1\u003e \u003cprov2\u003e \u003cmodel2\u003e ...   # Enable multi-agent collaboration mode\n# Example: /multiagent openai gpt-4 anthropic claude-3-sonnet google gemini-pro\n# Agents will discuss, plan, and work together on your project\n```\n\n### Rules Management\n\n```bash\n/rules                               # Display all rules (global + workspace)\n/rules add global \u003ctext\u003e [desc]      # Add a global rule\n/rules add workspace \u003ctext\u003e [desc]   # Add a workspace rule\n/rules remove global \u003cindex\u003e         # Remove a global rule by index\n/rules remove workspace \u003cindex\u003e      # Remove a workspace rule by index\n/rules clear global                  # Clear all global rules\n/rules clear workspace               # Clear all workspace rules\n```\n\n### Repository Documentation\n\n```bash\n/docrepo \u003cgit_url\u003e   # Generate comprehensive documentation for a git repository\n# Example: /docrepo https://github.com/user/awesome-project\n```\n\n---\n\n## Command-Line Usage\n\nCognautic CLI provides these main commands:\n\n### Setup Command\n\n```bash\ncognautic setup --interactive           # Interactive setup wizard\ncognautic setup --provider openai       # Quick provider setup\n```\n\n### Chat Command\n\n```bash\ncognautic chat                          # Start interactive chat\ncognautic chat --provider anthropic     # Chat with specific provider\ncognautic chat --model claude-3-sonnet  # Chat with specific model\ncognautic chat --project-path ./my_project  # Set workspace\ncognautic chat --session \u003cid\u003e           # Continue existing session\n```\n\n### Config Command\n\n```bash\ncognautic config list                   # Show all configuration\ncognautic config set \u003ckey\u003e \u003cvalue\u003e      # Set configuration value\ncognautic config get \u003ckey\u003e              # Get configuration value\ncognautic config delete \u003ckey\u003e           # Delete configuration key\ncognautic config reset                  # Reset to defaults\n```\n\n### Providers Command\n\n```bash\ncognautic providers                     # List all AI providers and endpoints\n```\n\n### Key Bindings\n\n- **Enter**: Send message\n- **Alt+Enter**: New line (multi-line input)\n- **Shift+Tab**: Toggle Chat/Terminal mode\n- **Ctrl+C** (twice within 2s): Exit CLI\n- **Ctrl+Y**: Toggle YOLO/Safe mode\n- **Ctrl+G**: One-shot voice capture to prefill the next prompt\n- **Tab**: Auto-complete slash commands and `@` file paths (accept selection)\n\n---\n\n## Supported AI Providers\n\n| Provider | Models | API Key Required |\n|----------|--------|------------------|\n| **OpenAI** | GPT models (GPT-4, GPT-3.5) | `OPENAI_API_KEY` |\n| **Anthropic** | Claude models (Claude-3 Sonnet, Haiku) | `ANTHROPIC_API_KEY` |\n| **Google** | Gemini models | `GOOGLE_API_KEY` |\n| **Together AI** | Various open-source models | `TOGETHER_API_KEY` |\n| **OpenRouter** | Access to multiple providers | `OPENROUTER_API_KEY` |\n| **Ollama** | Local models via Ollama daemon | ❌ No API key needed! |\n| **Local Models** | Hugging Face models (Llama, Mistral, Phi, etc.) | ❌ No API key needed! |\n\n### Using Local Models (NEW! 🎉)\n\nRun free open-source AI models locally without any API keys:\n\n```bash\n# Install dependencies\npip install transformers torch accelerate\n\n# Start chat and load a local model\ncognautic chat\n/lmodel microsoft/phi-2\n/provider local\n\n# Now chat with your local model!\n```\n\n**Popular local models:**\n- `microsoft/phi-2` - Small and fast (2.7B)\n- `TinyLlama/TinyLlama-1.1B-Chat-v1.0` - Ultra lightweight (1.1B)\n- `meta-llama/Llama-2-7b-chat-hf` - High quality (7B)\n- `mistralai/Mistral-7B-Instruct-v0.2` - Excellent performance (7B)\n\n**Benefits:**\n- ✅ Complete privacy - no data sent externally\n- ✅ No API costs\n- ✅ Works offline\n- ✅ Full control over model behavior\n\n📖 **[Read the full Local Models Guide →](LOCAL_MODELS.md)**\n\n---\n\n## Intelligent Web Search (NEW! 🔍)\n\nCognautic CLI now features **intelligent web search** that automatically researches information when needed. The AI will search the web when:\n\n- **Implementing APIs**: \"Implement Stripe payment integration\"\n- **Using Latest Libraries**: \"Create a React app with TailwindCSS\"\n- **Research Requests**: \"What's the best way to implement real-time chat?\"\n- **Current Best Practices**: \"Build a modern authentication system\"\n\n### Example Usage\n\n```bash\nYou: Implement OpenAI API in my Python project\n\nAI: 🔍 Searching for latest OpenAI API documentation...\n    ✅ Found: OpenAI API Reference\n    📝 Creating implementation with current best practices...\n    \n    [Creates files with up-to-date API usage]\n```\n\n### When Web Search is Used\n\n✅ **Automatically triggered for:**\n- Latest API documentation\n- Current framework/library versions\n- Modern best practices\n- Technologies requiring external information\n\n❌ **Not used for:**\n- Basic programming concepts\n- Simple file operations\n- General coding tasks\n\n📖 **[Read the full Web Search Guide →](docs/WEB_SEARCH_TOOL.md)** | **[Quick Reference →](docs/WEB_SEARCH_QUICK_REFERENCE.md)**\n\n---\n\n## Configuration\n\nConfiguration files are stored in `~/.cognautic/`:\n\n- `config.json`: General settings and preferences\n- `api_keys.json`: Encrypted API keys for AI providers\n- `sessions/`: Chat session history and context\n- `cache/`: Temporary files and model cache\n\n---\n\n## Command Usage\n\nAll Cognautic CLI functionality is accessed through the single `cognautic` command. The general syntax is:\n\n```bash\ncognautic \u003csubcommand\u003e [options] [arguments]\n```\n\n### Getting Help\n\n```bash\n# Show general help\ncognautic --help\n\n# Show help for specific command\ncognautic chat --help\n```\n\n### Version Information\n\n```bash\ncognautic --version\n```\n\n---\n\n## WebSocket Server \u0026 Real-time Streaming\n\nCognautic CLI includes a powerful WebSocket server that enables **real-time, streaming AI responses**. Instead of waiting for the complete response, you receive AI-generated content as it's being produced, providing a much more interactive experience.\n\n### Starting the WebSocket Server\n\nThe WebSocket server starts automatically when you run chat mode:\n\n```bash\n# Start with default settings (port 8765)\ncognautic chat\n\n# Specify custom port\ncognautic chat --websocket-port 9000\n\n# With specific provider and model\ncognautic chat --provider openai --model gpt-4o-mini --websocket-port 8765\n```\n\n### Key Features\n\n- ✨ **Real-time Streaming**: AI responses stream chunk-by-chunk as they're generated\n- 🔄 **Bi-directional**: Full duplex WebSocket communication\n- 🔐 **Session Management**: Automatic session creation and context preservation\n- 🤖 **Multi-provider**: Works with all supported AI providers\n- 🛠️ **Tool Execution**: Execute tools and file operations via WebSocket\n\n### Client Examples\n\n**Python Client:**\n```bash\npython examples/websocket_client_example.py\n\n# Interactive mode\npython examples/websocket_client_example.py interactive\n```\n\n**Web Browser:**\n```bash\n# Open in your browser\nopen examples/websocket_client.html\n```\n\n### Basic Usage Example\n\n```python\nimport asyncio\nimport json\nimport websockets\n\nasync def chat():\n    uri = \"ws://localhost:8765\"\n    async with websockets.connect(uri) as ws:\n        # Receive welcome message\n        welcome = json.loads(await ws.recv())\n        print(f\"Connected! Session: {welcome['session_id']}\")\n        \n        # Send chat message with streaming enabled\n        await ws.send(json.dumps({\n            \"type\": \"chat\",\n            \"message\": \"Explain Python async/await\",\n            \"stream\": true\n        }))\n        \n        # Receive streaming response in real-time\n        while True:\n            response = json.loads(await ws.recv())\n            \n            if response['type'] == 'stream_chunk':\n                print(response['chunk'], end='', flush=True)\n            elif response['type'] == 'stream_end':\n                break\n\nasyncio.run(chat())\n```\n\n### API Documentation\n\nFor complete WebSocket API documentation, see **[WEBSOCKET_API.md](WEBSOCKET_API.md)**.\n\n---\n\n## Examples\n\n### Simple Chat Session\n\nStart chatting with AI:\n\n```bash\n$ cognautic chat\n ██████╗ ██████╗  ██████╗ ███╗   ██╗ █████╗ ██╗   ██╗████████╗██╗ ██████╗\n██╔════╝██╔═══██╗██╔════╝ ████╗  ██║██╔══██╗██║   ██║╚══██╔══╝██║██╔════╝\n██║     ██║   ██║██║  ███╗██╔██╗ ██║███████║██║   ██║   ██║   ██║██║     \n██║     ██║   ██║██║   ██║██║╚██╗██║██╔══██║██║   ██║   ██║   ██║██║     \n╚██████╗╚██████╔╝╚██████╔╝██║ ╚████║██║  ██║╚██████╔╝   ██║   ██║╚██████╗\n ╚═════╝ ╚═════╝  ╚═════╝ ╚═╝  ╚═══╝╚═╝  ╚═╝ ╚═════╝    ╚═╝   ╚═╝ ╚═════╝\n\n💡 Type '/help' for commands, 'exit' to quit\n🌐 WebSocket server: ws://localhost:8765\n📁 Workspace: /home/user/projects\n--------------------------------------------------\n\nYou [projects]: Can you help me create a Python function?\nAI: Of course! I'd be happy to help you create a Python function...\n\nYou [projects]: /workspace ~/myproject\n✅ Workspace changed to: /home/user/myproject\n\nYou [myproject]: Create a file called utils.py with helper functions\nAI: I'll create that file for you...\n```\n\n### First-Time Setup\n\n```bash\n$ cognautic\n🎉 Welcome to Cognautic! Let's get you set up.\n🔑 No API keys found. Let's configure them.\n\nWhich AI provider would you like to use?\n1. OpenAI (GPT-4, GPT-3.5)\n2. Anthropic (Claude)\n3. Google (Gemini)\n4. Other providers...\n\nChoice [1-4]: 2\n🔐 Please enter your Anthropic API key: sk-ant-...\n✅ API key saved securely!\n\n🚀 Setup complete! You're ready to go.\n```\n\n### Using Local Models\n\nRun AI models locally without API keys:\n\n```bash\n$ cognautic chat\nYou: /lmodel microsoft/phi-2\n🔄 Loading local model from: microsoft/phi-2\n⏳ This may take a few minutes depending on model size...\nLoading local model from microsoft/phi-2 on cuda...\n✅ Model loaded successfully on cuda\n✅ Local model loaded successfully!\n💡 Use: /provider local - to switch to the local model\n\nYou: /provider local\n✅ Switched to provider: local\n\nYou: Hello! Can you help me code?\nAI: Hello! Yes, I'd be happy to help you with coding...\n```\n\n### Working with Multiple Providers\n\nSwitch between different AI providers:\n\n```bash\nYou: /provider openai\n✅ Switched to provider: openai\n\nYou: /model gpt-4o\n✅ Switched to model: gpt-4o\n\nYou: Write a Python function to sort a list\nAI: Here's a Python function...\n\nYou: /provider anthropic\n✅ Switched to provider: anthropic\n\nYou: /model claude-3-sonnet-20240229\n✅ Switched to model: claude-3-sonnet-20240229\n```\n\n### Using @ Path Suggestions\n\nType `@` followed by a path fragment to get filesystem suggestions relative to the current workspace. Use Up/Down to navigate; press Tab to accept. Enter sends the message.\n\n```bash\nYou [myproject]: Please review @README\nYou [myproject]: Please review @README.md\n\nYou [myproject]: Refactor @src/\nYou [myproject]: Refactor @src/utils/\n```\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcognautic%2Fcli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcognautic%2Fcli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcognautic%2Fcli/lists"}