{"id":30257625,"url":"https://github.com/haasonsaas/ocode","last_synced_at":"2025-09-18T07:46:09.723Z","repository":{"id":295740627,"uuid":"990975064","full_name":"haasonsaas/ocode","owner":"haasonsaas","description":"OCode is a sophisticated terminal-native AI coding assistant that provides deep codebase intelligence and autonomous task execution","archived":false,"fork":false,"pushed_at":"2025-06-27T05:25:30.000Z","size":654,"stargazers_count":100,"open_issues_count":0,"forks_count":7,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-06-27T05:27:52.335Z","etag":null,"topics":["ai-agent","ai-coding","coding-assistant","ollama","self-hosted"],"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/haasonsaas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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-27T00:03:55.000Z","updated_at":"2025-06-27T05:25:34.000Z","dependencies_parsed_at":"2025-06-05T03:34:18.896Z","dependency_job_id":null,"html_url":"https://github.com/haasonsaas/ocode","commit_stats":null,"previous_names":["haasonsaas/ocode"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/haasonsaas/ocode","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haasonsaas%2Focode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haasonsaas%2Focode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haasonsaas%2Focode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haasonsaas%2Focode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/haasonsaas","download_url":"https://codeload.github.com/haasonsaas/ocode/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haasonsaas%2Focode/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270594163,"owners_count":24612661,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-15T02:00:12.559Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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-agent","ai-coding","coding-assistant","ollama","self-hosted"],"created_at":"2025-08-15T16:02:43.531Z","updated_at":"2025-09-18T07:46:04.679Z","avatar_url":"https://github.com/haasonsaas.png","language":"Python","funding_links":[],"categories":["Python","Terminal \u0026 CLI Agents"],"sub_categories":[],"readme":"# OCode - Terminal-Native AI Coding Assistant\n\n\u003e **Powered by Ollama Models**\n\nOCode is a sophisticated terminal-native AI coding assistant that provides deep codebase intelligence and autonomous task execution. Built to work seamlessly with local Ollama models, OCode brings enterprise-grade AI assistance directly to your development workflow.\n\n## 🌟 Features\n\n### Core Capabilities\n- **Terminal-native workflow** – runs directly in your shell environment\n- **Deep codebase intelligence** – automatically maps and understands your entire project\n- **Autonomous task execution** – handles multi-step development tasks end-to-end\n- **Direct Ollama integration** – streams completions from local/remote Ollama without proxies\n- **Extensible plugin layer** – Model Context Protocol (MCP) enables third-party integrations\n\n### What OCode Can Do\n| Domain | Capabilities |\n|--------|-------------|\n| **Code Generation \u0026 Modification** | Multi-file refactors, TDD scaffolding, optimization, documentation |\n| **Project Understanding** | Architecture analysis, dependency tracking, cross-file reasoning |\n| **Development Automation** | Git workflows, test execution, build \u0026 CI integration |\n| **Data Processing** | JSON/YAML parsing and querying, data validation, format conversion |\n| **System Operations** | Process monitoring, environment management, network connectivity testing |\n| **Interactive Operations** | Natural language queries, contextual exploration, debugging assistance |\n\n### 🛠️ Available Tools\n\nOCode includes 19+ specialized tools organized by category:\n\n#### **File Operations**\n- `file_edit` - Edit and modify source files with precision\n- `file_ops` - Read, write, and manage file operations\n- `glob` - Pattern-based file discovery and matching\n- `find` - Search for files and directories\n- `ls` - List directory contents with filtering\n- `head_tail` - Read file beginnings and endings\n- `wc` - Count lines, words, and characters\n\n#### **Text Processing**\n- `grep` - Advanced text search with regex support\n- `text_tools` - Text manipulation and formatting\n- `diff` - Compare files and show differences\n\n#### **Data Processing**\n- `json_yaml` - Parse, query, and manipulate JSON/YAML data with JSONPath\n- `notebook_tools` - Work with Jupyter notebooks\n\n#### **System Operations**\n- `ps` - Monitor and query system processes\n- `env` - Manage environment variables and .env files\n- `ping` - Test network connectivity\n- `bash` - Execute shell commands safely\n- `which` - Locate system commands\n\n#### **Development Tools**\n- `git_tools` - Git operations and repository management\n- `architect` - Project architecture analysis and documentation\n- `agent` - Delegate complex tasks to specialized agents\n- `memory_tools` - Manage context and session memory\n\n#### **Integration**\n- `mcp` - Model Context Protocol integration\n- `curl` - HTTP requests and API testing\n\n## 🚀 Quick Installation\n\n### One-Line Installation\n\n```bash\n# Automated installation (recommended)\ncurl -fsSL https://raw.githubusercontent.com/haasonsaas/ocode/main/scripts/install.sh | bash\n```\n\nThis will:\n- ✅ Check Python 3.8+ and dependencies\n- 🐍 Set up virtual environment (optional)\n- 📦 Install OCode with enhanced multi-action detection\n- 🤖 Configure 19+ specialized tools including data processing and system monitoring\n- 🔧 Set up shell completion\n- ✨ Test enhanced conversation parsing\n\n### Manual Installation\n\nIf you prefer to install manually or need custom setup:\n\n## 🔧 Detailed Installation \u0026 Setup\n\n### Prerequisites\n\n**Required:**\n- **Python 3.8+** - Check with `python --version` or `python3 --version`\n- **pip** - Should come with Python, verify with `pip --version`\n\n**For full functionality:**\n- **Ollama** - Local LLM server ([Installation Guide](https://ollama.ai))\n- **Git** - For git integration features\n\n### Step 0: Python Environment Setup\n\n**If you don't have Python 3.8+ installed:**\n\n**macOS:**\n```bash\n# Using Homebrew (recommended)\nbrew install python@3.11\n\n# Or download from python.org\n# https://www.python.org/downloads/\n```\n\n**Linux (Ubuntu/Debian):**\n```bash\n# Update package list\nsudo apt update\n\n# Install Python 3.11 and pip\nsudo apt install python3.11 python3.11-venv python3.11-pip\n\n# Set as default (optional)\nsudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 1\n```\n\n**Linux (CentOS/RHEL/Fedora):**\n```bash\n# Fedora\nsudo dnf install python311 python311-pip python311-venv\n\n# CentOS/RHEL (using EPEL)\nsudo yum install epel-release\nsudo yum install python311 python311-pip\n```\n\n**Windows:**\n```bash\n# Download from python.org and run installer\n# https://www.python.org/downloads/windows/\n# Make sure to check \"Add Python to PATH\" during installation\n\n# Or using Chocolatey\nchoco install python311\n\n# Or using winget\nwinget install Python.Python.3.11\n```\n\n**Verify Python installation:**\n```bash\n# Check Python version\npython3 --version\n# or\npython --version\n\n# Check pip\npython3 -m pip --version\n# or\npip --version\n\n# If you get \"command not found\", try:\npython3.11 --version\n/usr/bin/python3 --version\n```\n\n**Set up virtual environment (strongly recommended):**\n```bash\n# Create a dedicated directory for OCode\nmkdir ~/ocode-workspace\ncd ~/ocode-workspace\n\n# Create virtual environment\npython3 -m venv ocode-env\n\n# Activate virtual environment\n# On macOS/Linux:\nsource ocode-env/bin/activate\n\n# On Windows:\nocode-env\\Scripts\\activate\n\n# Your prompt should now show (ocode-env)\n# Verify you're in the virtual environment\nwhich python  # Should show path to venv\npython --version\n```\n\n**If you have permission issues with pip:**\n```bash\n# Option 1: Use --user flag (installs to user directory)\npython3 -m pip install --user --upgrade pip\n\n# Option 2: Use virtual environment (recommended)\npython3 -m venv venv\nsource venv/bin/activate\npip install --upgrade pip\n\n# Option 3: Fix pip permissions (macOS)\nsudo chown -R $(whoami) /usr/local/lib/python3.*/site-packages\n\n# Option 4: Use homebrew Python (macOS)\nbrew install python@3.11\n# Then use /opt/homebrew/bin/python3 instead\n```\n\n### Step 1: Install Ollama\n\n**macOS:**\n```bash\n# Using Homebrew (recommended)\nbrew install ollama\n\n# Or download from https://ollama.ai\n```\n\n**Linux:**\n```bash\n# One-line installer\ncurl -fsSL https://ollama.ai/install.sh | sh\n\n# Or using package manager\n# Ubuntu/Debian\nsudo apt install ollama\n\n# Arch Linux\nyay -S ollama\n```\n\n**Windows:**\n```bash\n# Download from https://ollama.ai\n# Or use WSL with Linux instructions above\n```\n\n**Start Ollama:**\n```bash\n# Start the Ollama service\nollama serve\n\n# In a new terminal, download a model\nollama pull llama3.2\n# or\nollama pull codellama\n# or\nollama pull gemma2\n```\n\n**Verify Ollama is working:**\n```bash\n# Check if service is running\ncurl http://localhost:11434/api/version\n\n# Should return something like: {\"version\":\"0.7.1\"}\n\n# List available models\nollama list\n```\n\n### Step 2: Install OCode\n\n**Method 1: Enhanced Installation Script (Recommended)**\n```bash\n# Clone and run installation script\ngit clone https://github.com/haasonsaas/ocode.git\ncd ocode\n./scripts/install.sh\n```\n\n**Method 2: Development Installation**\n```bash\n# Clone the repository\ngit clone https://github.com/haasonsaas/ocode.git\ncd ocode\n\n# Create virtual environment (recommended)\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n\n# Install in development mode with enhanced features\npip install -e .\n\n# This will install new dependencies for data processing:\n# - pyyaml\u003e=6.0 (YAML parsing)\n# - jsonpath-ng\u003e=1.5.3 (JSONPath queries)\n# - python-dotenv\u003e=1.0.0 (Environment file handling)\n```\n\n**Method 3: Direct Git Installation**\n```bash\npip install git+https://github.com/haasonsaas/ocode.git\n```\n\n**Method 4: Using pipx (Isolated installation)**\n```bash\n# Install pipx if you don't have it\npip install pipx\n\n# Install ocode\npipx install git+https://github.com/haasonsaas/ocode.git\n```\n\n### Step 3: Verify Installation\n\n```bash\n# Check if ocode command is available\npython -m ocode_python.core.cli --help\n\n# Should show:\n# Usage: python -m ocode_python.core.cli [OPTIONS] COMMAND [ARGS]...\n# OCode - Terminal-native AI coding assistant powered by Ollama models.\n```\n\n**If you get \"command not found\":** See [Troubleshooting](#-troubleshooting) section below.\n\n### Step 4: Initialize Your First Project\n\n```bash\n# Navigate to your project directory\ncd /path/to/your/project\n\n# Initialize OCode for this project\npython -m ocode_python.core.cli init\n\n# Should output:\n# ✓ Initialized OCode in /path/to/your/project\n# Configuration: /path/to/your/project/.ocode/settings.json\n```\n\n### Step 5: Test Your Setup\n\n```bash\n# Set Ollama host (if using default localhost, this isn't needed)\nexport OLLAMA_HOST=http://localhost:11434\n\n# Test with a simple prompt\npython -m ocode_python.core.cli -p \"Hello! Tell me about this project.\"\n\n# Test enhanced multi-action detection\npython -m ocode_python.core.cli -p \"Run tests and commit if they pass\"\n\n# Test comprehensive tool listing\npython -m ocode_python.core.cli -p \"What tools can you use?\"\n\n# Should connect to Ollama and demonstrate enhanced conversation parsing\n```\n\n## ✨ Enhanced Features\n\nOCode includes advanced conversation parsing with multi-action detection:\n\n### 🤖 Multi-Action Query Detection\n```bash\n# These queries now correctly identify multiple required actions:\npython -m ocode_python.core.cli -p \"Run tests and commit if they pass\"           # test_runner + git_commit\npython -m ocode_python.core.cli -p \"Find all TODO comments and replace them\"     # grep + file_edit\npython -m ocode_python.core.cli -p \"Analyze architecture and write documentation\" # architect + file_write\npython -m ocode_python.core.cli -p \"Create a component and write tests for it\"   # file_write + test_runner\npython -m ocode_python.core.cli -p \"Parse config.json and update environment\"    # json_yaml + env\npython -m ocode_python.core.cli -p \"Monitor processes and kill high CPU ones\"    # ps + bash\n```\n\n### 🧠 Smart Tool Selection\n- **14+ Query Categories**: Agent management, file operations, testing, git, architecture analysis, data processing\n- **19+ Specialized Tools**: Comprehensive coverage for development workflows including data processing and system monitoring\n- **Context Optimization**: Intelligent file analysis based on query type\n- **Agent Delegation**: Recommendations for complex multi-step workflows\n\n### 🚀 Performance Improvements\n- **Tool fixation eliminated**: No more defaulting to tool lists\n- **Context strategies**: none/minimal/targeted/full based on query complexity\n- **Enhanced accuracy**: \u003e97% query categorization accuracy\n\n## 📖 Usage Guide\n\n### Basic Commands\n\n**Interactive Mode:**\n```bash\n# Start interactive session\npython -m ocode_python.core.cli\n\n# Interactive mode commands:\n# /help      - Show available commands\n# /exit      - Exit OCode\n# /model     - Change model\n# /clear     - Clear conversation context\n# /save      - Save current session\n# /load      - Load previous session\n```\n\n**Single Prompt Mode:**\n```bash\n# Ask a question\npython -m ocode_python.core.cli -p \"Explain the authentication system\"\n\n# Request code changes\npython -m ocode_python.core.cli -p \"Add error handling to the user login function\"\n\n# Generate code\npython -m ocode_python.core.cli -p \"Create a REST API endpoint for user profiles\"\n```\n\n**Specify Model:**\n```bash\n# Use a specific model\npython -m ocode_python.core.cli -m llama3.2 -p \"Review this code for security issues\"\n\n# Use a larger model for complex tasks\npython -m ocode_python.core.cli -m codellama:70b -p \"Refactor the entire payment processing module\"\n```\n\n**Different Output Formats:**\n```bash\n# JSON output\npython -m ocode_python.core.cli -p \"List all functions in main.py\" --out json\n\n# Streaming JSON (for real-time processing)\npython -m ocode_python.core.cli -p \"Generate tests for UserService\" --out stream-json\n```\n\n### Configuration Management\n\n**View current configuration:**\n```bash\npython -m ocode_python.core.cli config --list\n```\n\n**Get specific setting:**\n```bash\npython -m ocode_python.core.cli config --get model\npython -m ocode_python.core.cli config --get permissions.allow_file_write\n```\n\n**Set configuration:**\n```bash\npython -m ocode_python.core.cli config --set model=llama3.2:latest\npython -m ocode_python.core.cli config --set temperature=0.1\npython -m ocode_python.core.cli config --set permissions.allow_shell_exec=true\n```\n\n**Environment Variables:**\n```bash\n# Model selection\nexport OCODE_MODEL=\"codellama:7b\"\n\n# Ollama server location\nexport OLLAMA_HOST=\"http://192.168.1.100:11434\"\n\n# Enable verbose output\nexport OCODE_VERBOSE=true\n\n# Custom temperature\nexport OCODE_TEMPERATURE=0.2\n```\n\n### Project Configuration\n\n**Project-specific settings (.ocode/settings.json):**\n```json\n{\n  \"model\": \"llama3.2:latest\",\n  \"max_tokens\": 4096,\n  \"temperature\": 0.1,\n  \"permissions\": {\n    \"allow_file_read\": true,\n    \"allow_file_write\": true,\n    \"allow_shell_exec\": false,\n    \"allow_git_ops\": true,\n    \"allowed_paths\": [\"/path/to/your/project\"],\n    \"blocked_paths\": [\"/etc\", \"/bin\", \"/usr/bin\"]\n  }\n}\n```\n\n## 🎯 Common Usage Patterns\n\n### Code Generation\n```bash\n# Generate new features\nocode -p \"Create a user authentication system with JWT tokens\"\n\n# Add functionality to existing code\nocode -p \"Add input validation to all API endpoints\"\n\n# Generate documentation\nocode -p \"Add comprehensive docstrings to all functions in utils.py\"\n```\n\n### Code Analysis \u0026 Review\n```bash\n# Understand existing code\nocode -p \"Explain how the database connection pooling works\"\n\n# Security review\nocode -p \"Review the payment processing code for security vulnerabilities\"\n\n# Performance analysis\nocode -p \"Identify performance bottlenecks in the user search functionality\"\n```\n\n### Testing \u0026 Quality Assurance\n```bash\n# Generate tests\nocode -p \"Write comprehensive unit tests for the UserRepository class\"\n\n# Fix failing tests\nocode -p \"Run the test suite and fix any failing tests\"\n\n# Code coverage\nocode -p \"Improve test coverage for the authentication module\"\n```\n\n### Git Integration\n```bash\n# Smart commits\nocode -p \"Create a git commit with a descriptive message for these changes\"\n\n# Code review\nocode -p \"Review the changes in the current branch and suggest improvements\"\n\n# Branch analysis\nocode -p \"Compare this branch with main and summarize the changes\"\n```\n\n### Data Processing \u0026 Analysis\n```bash\n# JSON/YAML processing\nocode -p \"Parse the config.json file and extract all database connection strings\"\n\n# Data validation\nocode -p \"Validate the structure of all YAML files in the configs/ directory\"\n\n# JSONPath queries\nocode -p \"Query user data: find all users with admin roles using JSONPath\"\n\n# Environment management\nocode -p \"Load variables from .env.production and compare with current environment\"\n```\n\n### System Monitoring \u0026 Operations\n```bash\n# Process monitoring\nocode -p \"Show all Python processes and their memory usage\"\n\n# Performance analysis\nocode -p \"Find processes consuming more than 50% CPU and analyze them\"\n\n# Network connectivity\nocode -p \"Test connectivity to all services defined in docker-compose.yml\"\n\n# Environment troubleshooting\nocode -p \"Check if all required environment variables are set for production\"\n```\n\n### Project Management\n```bash\n# Architecture review\nocode -p \"Analyze the current project architecture and suggest improvements\"\n\n# Dependency analysis\nocode -p \"Review project dependencies and identify outdated packages\"\n\n# Migration planning\nocode -p \"Create a plan to migrate from Python 3.8 to Python 3.11\"\n```\n\n## 🔧 Advanced Configuration\n\n### Model Selection Strategy\n\n**For different task types:**\n```bash\n# Fast responses for simple queries\nexport OCODE_MODEL=\"llama3.2:3b\"\n\n# Balanced performance for general coding\nexport OCODE_MODEL=\"llama3.2:latest\"  # Usually 7B-8B\n\n# Complex reasoning and large refactors\nexport OCODE_MODEL=\"codellama:70b\"\n\n# Specialized coding tasks\nexport OCODE_MODEL=\"codellama:latest\"\n```\n\n### Performance Tuning\n\n**Large codebase optimization:**\n```json\n{\n  \"max_context_files\": 50,\n  \"max_tokens\": 8192,\n  \"context_window\": 16384,\n  \"ignore_patterns\": [\n    \".git\", \"node_modules\", \"*.log\",\n    \"dist/\", \"build/\", \"*.pyc\"\n  ]\n}\n```\n\n**Network optimization:**\n```bash\n# For remote Ollama instances\nexport OLLAMA_HOST=\"http://gpu-server:11434\"\nexport OCODE_TIMEOUT=300  # 5 minute timeout for large requests\n```\n\n### Security Configuration\n\n**Restrictive permissions:**\n```json\n{\n  \"permissions\": {\n    \"allow_file_read\": true,\n    \"allow_file_write\": false,\n    \"allow_shell_exec\": false,\n    \"allow_git_ops\": false,\n    \"allowed_paths\": [\"/home/user/projects\"],\n    \"blocked_paths\": [\"/\", \"/etc\", \"/bin\", \"/usr\"],\n    \"blocked_commands\": [\"rm\", \"sudo\", \"chmod\", \"chown\"]\n  }\n}\n```\n\n**Development permissions:**\n```json\n{\n  \"permissions\": {\n    \"allow_file_read\": true,\n    \"allow_file_write\": true,\n    \"allow_shell_exec\": true,\n    \"allow_git_ops\": true,\n    \"allowed_commands\": [\"npm\", \"yarn\", \"pytest\", \"git\"],\n    \"blocked_commands\": [\"rm -rf\", \"sudo\", \"format\"]\n  }\n}\n```\n\n## 🐛 Troubleshooting\n\n### Installation Issues\n\n**Problem: `ocode: command not found`**\n\n*Solution 1: Use the full module path*\n```bash\n# Use the full Python module path\npython -m ocode_python.core.cli --help\n\n# Or if using virtual environment\nsource venv/bin/activate\npython -m ocode_python.core.cli --help\n```\n\n*Solution 2: Install and check script location*\n```bash\n# Install in development mode\npip install -e .\n\n# Find where scripts were installed\npip show ocode | grep Location\n\n# Add to PATH if needed\necho 'export PATH=\"$HOME/.local/bin:$PATH\"' \u003e\u003e ~/.bashrc\nsource ~/.bashrc\n```\n\n*Solution 3: Use pipx*\n```bash\npip install pipx\npipx install git+https://github.com/haasonsaas/ocode.git\n```\n\n**Problem: `ModuleNotFoundError` when importing**\n\n*Solution:*\n```bash\n# Reinstall dependencies\npip install -e .\n\n# Or force reinstall\npip uninstall ocode\npip install -e .\n\n# Check Python path\npython -c \"import sys; print('\\n'.join(sys.path))\"\n```\n\n**Problem: Permission denied during installation**\n\n*Solution:*\n```bash\n# Install without sudo using --user flag\npip install --user ocode\n\n# Or use virtual environment\npython -m venv ocode-env\nsource ocode-env/bin/activate\npip install ocode\n```\n\n### Ollama Connection Issues\n\n**Problem: `Failed to connect to Ollama`**\n\n*Diagnosis:*\n```bash\n# Check if Ollama is running\nps aux | grep ollama\n\n# Check if port is open\nnetstat -ln | grep 11434\n# or\nlsof -i :11434\n\n# Test direct connection\ncurl http://localhost:11434/api/version\n```\n\n*Solutions:*\n```bash\n# Start Ollama service\nollama serve\n\n# Check for different port\nexport OLLAMA_HOST=\"http://localhost:11434\"\n\n# For Docker installations\ndocker ps | grep ollama\ndocker logs ollama-container-name\n\n# Check firewall (Linux)\nsudo ufw status\nsudo ufw allow 11434\n\n# Check firewall (macOS)\nsudo pfctl -sr | grep 11434\n```\n\n**Problem: `Model not found` errors**\n\n*Solution:*\n```bash\n# List available models\nollama list\n\n# Pull required model\nollama pull llama3.2\n\n# Update OCode config to use available model\nocode config --set model=llama3.2:latest\n\n# Or set environment variable\nexport OCODE_MODEL=\"llama3.2:latest\"\n```\n\n**Problem: Slow responses or timeouts**\n\n*Solutions:*\n```bash\n# Increase timeout\nexport OCODE_TIMEOUT=600  # 10 minutes\n\n# Use smaller model\nexport OCODE_MODEL=\"llama3.2:3b\"\n\n# Check system resources\ntop\ndf -h\nfree -h\n\n# Monitor Ollama logs\nollama logs\n```\n\n### Configuration Issues\n\n**Problem: Configuration not loading**\n\n*Diagnosis:*\n```bash\n# Check config file location\nocode config --list\n\n# Verify file exists and is readable\nls -la .ocode/settings.json\ncat .ocode/settings.json\n```\n\n*Solutions:*\n```bash\n# Reinitialize project\nrm -rf .ocode/\nocode init\n\n# Fix JSON syntax\npython -m json.tool .ocode/settings.json\n\n# Reset to defaults\nocode config --set model=llama3.2:latest\n```\n\n**Problem: Permission denied errors**\n\n*Solution:*\n```bash\n# Check current permissions\nocode config --get permissions\n\n# Enable required permissions\nocode config --set permissions.allow_file_write=true\nocode config --set permissions.allow_shell_exec=true\n\n# Add allowed paths\nocode config --set permissions.allowed_paths='[\"/path/to/project\"]'\n```\n\n### Performance Issues\n\n**Problem: High memory usage**\n\n*Solutions:*\n```bash\n# Reduce context size\nocode config --set max_context_files=10\nocode config --set max_tokens=2048\n\n# Use smaller model\nexport OCODE_MODEL=\"llama3.2:3b\"\n\n# Monitor memory usage\nps aux | grep ollama\nhtop\n```\n\n**Problem: Slow startup**\n\n*Solutions:*\n```bash\n# Preload model in Ollama\nollama run llama3.2:latest \"hello\"\n\n# Reduce project scan scope\necho \"node_modules/\\n.git/\\ndist/\" \u003e\u003e .ocodeignore\n\n# Use SSD for project files\n# Move project to faster storage\n```\n\n### Network Issues\n\n**Problem: Connection refused (remote Ollama)**\n\n*Solutions:*\n```bash\n# Test network connectivity\nping your-ollama-server\ntelnet your-ollama-server 11434\n\n# Check Ollama server binding\n# On Ollama server, ensure it binds to 0.0.0.0:11434\nOLLAMA_HOST=0.0.0.0 ollama serve\n\n# Update client configuration\nexport OLLAMA_HOST=\"http://your-server-ip:11434\"\n```\n\n### Model Issues\n\n**Problem: Model gives poor responses**\n\n*Solutions:*\n```bash\n# Try different models\nocode config --set model=codellama:latest\nocode config --set model=llama3.2:70b\n\n# Adjust temperature\nocode config --set temperature=0.1  # More focused\nocode config --set temperature=0.7  # More creative\n\n# Increase context\nocode config --set max_tokens=8192\nocode config --set max_context_files=30\n```\n\n**Problem: Model responses cut off**\n\n*Solutions:*\n```bash\n# Increase token limit\nocode config --set max_tokens=8192\n\n# Use model with larger context window\nexport OCODE_MODEL=\"llama3.2:latest\"\n\n# Break large requests into smaller parts\nocode -p \"First, analyze the authentication system\"\nocode -p \"Now suggest improvements for the auth system\"\n```\n\n### Debugging Commands\n\n**Enable verbose logging:**\n```bash\n# Environment variable\nexport OCODE_VERBOSE=true\n\n# CLI flag\nocode -v -p \"Debug this issue\"\n\n# Config setting\nocode config --set verbose=true\n```\n\n**Check system information:**\n```bash\n# OCode version and config\nocode --help\nocode config --list\n\n# Python environment\npython --version\npip list | grep ocode\n\n# Ollama status\nollama list\ncurl http://localhost:11434/api/version\n\n# System resources\ndf -h\nfree -h\nps aux | grep -E \"(ollama|ocode)\"\n```\n\n**Log analysis:**\n```bash\n# Check OCode logs (if implemented)\ntail -f ~/.ocode/logs/ocode.log\n\n# Check system logs\n# macOS\nlog show --predicate 'process CONTAINS \"ollama\"' --last 1h\n\n# Linux\njournalctl -u ollama -f\ntail -f /var/log/syslog | grep ollama\n```\n\n## 🔌 Model Context Protocol (MCP)\n\nOCode includes full MCP support for extensible AI integrations:\n\n### Starting MCP Server\n```bash\n# Start OCode MCP server\npython -m ocode_python.mcp.server --project-root .\n\n# Or via Docker\ndocker run -p 8000:8000 ocode-mcp-server\n```\n\n### MCP Capabilities\n- **Resources**: Project files, structure, dependencies, git status\n- **Tools**: All OCode tools (file ops, git, shell, testing)\n- **Prompts**: Code review, refactoring, test generation templates\n\n## 🔒 Security\n\nOCode implements enterprise-grade security:\n\n### Permission System\n- **Whitelist-first** security model\n- **Configurable** file access controls\n- **Sandboxed** command execution\n- **Blocked dangerous** operations by default\n\n### Safe Defaults\n```json\n{\n  \"permissions\": {\n    \"allow_file_read\": true,\n    \"allow_file_write\": true,\n    \"allow_shell_exec\": false,\n    \"blocked_paths\": [\"/etc\", \"/bin\", \"/usr/bin\"],\n    \"blocked_commands\": [\"rm\", \"sudo\", \"chmod\"]\n  }\n}\n```\n\n## 📚 Documentation\n\nAdditional technical documentation is available in the [docs/](docs/) directory:\n\n- [Manual CLI Testing Guide](docs/manual-cli-testing.md) - Instructions for testing the CLI\n- [Reliability Improvements](docs/reliability-improvements.md) - Recent enhancements to tool reliability\n- [Timeout Analysis](docs/timeout-analysis.md) - Detailed timeout implementation analysis\n\nFor the full documentation index, see [docs/index.md](docs/index.md).\n\n## 🤝 Contributing\n\nWe welcome contributions! Here's how to get started:\n\n### Development Setup\n```bash\ngit clone https://github.com/haasonsaas/ocode.git\ncd ocode\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate\n\n# Install in development mode with dev dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Code quality checks\nblack ocode_python/\nisort ocode_python/\nflake8 ocode_python/\nmypy ocode_python/\n```\n\n## 📄 License\n\nThis project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) - see the [LICENSE](LICENSE) file for details.\n\nThe AGPL-3.0 is a strong copyleft license that requires any modifications to be released under the same license. This ensures that the software remains free and open source, and that any improvements made to it are shared with the community.\n\n## 🙏 Acknowledgments\n\n- [Ollama](https://ollama.ai) for local LLM infrastructure\n- [Model Context Protocol](https://modelcontextprotocol.io) for tool integration standards\n- The open-source AI and developer tools community\n\n---\n\n**Made with ❤️ for developers who want AI assistance without vendor lock-in.**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhaasonsaas%2Focode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhaasonsaas%2Focode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhaasonsaas%2Focode/lists"}