OCode - Terminal-Native AI Coding Assistant

Powered by Ollama Models

OCode 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.

🌟 Features

Core Capabilities

• Terminal-native workflow – runs directly in your shell environment
• Deep codebase intelligence – automatically maps and understands your entire project
• Autonomous task execution – handles multi-step development tasks end-to-end
• Direct Ollama integration – streams completions from local/remote Ollama without proxies
• Extensible plugin layer – Model Context Protocol (MCP) enables third-party integrations

What OCode Can Do

| Domain | Capabilities | |--------|-------------| | Code Generation & Modification | Multi-file refactors, TDD scaffolding, optimization, documentation | | Project Understanding | Architecture analysis, dependency tracking, cross-file reasoning | | Development Automation | Git workflows, test execution, build & CI integration | | Data Processing | JSON/YAML parsing and querying, data validation, format conversion | | System Operations | Process monitoring, environment management, network connectivity testing | | Interactive Operations | Natural language queries, contextual exploration, debugging assistance |

🛠️ Available Tools

OCode includes 19+ specialized tools organized by category:

File Operations

• file_edit - Edit and modify source files with precision
• file_ops - Read, write, and manage file operations
• glob - Pattern-based file discovery and matching
• find - Search for files and directories
• ls - List directory contents with filtering
• head_tail - Read file beginnings and endings
• wc - Count lines, words, and characters

Text Processing

• grep - Advanced text search with regex support
• text_tools - Text manipulation and formatting
• diff - Compare files and show differences

Data Processing

• json_yaml - Parse, query, and manipulate JSON/YAML data with JSONPath
• notebook_tools - Work with Jupyter notebooks

System Operations

• ps - Monitor and query system processes
• env - Manage environment variables and .env files
• ping - Test network connectivity
• bash - Execute shell commands safely
• which - Locate system commands

Development Tools

• git_tools - Git operations and repository management
• architect - Project architecture analysis and documentation
• agent - Delegate complex tasks to specialized agents
• memory_tools - Manage context and session memory

Integration

• mcp - Model Context Protocol integration
• curl - HTTP requests and API testing

🚀 Quick Installation

One-Line Installation

# Automated installation (recommended)
curl -fsSL https://raw.githubusercontent.com/haasonsaas/ocode/main/scripts/install.sh | bash

This will:

• ✅ Check Python 3.8+ and dependencies
• 🐍 Set up virtual environment (optional)
• 📦 Install OCode with enhanced multi-action detection
• 🤖 Configure 19+ specialized tools including data processing and system monitoring
• 🔧 Set up shell completion
• ✨ Test enhanced conversation parsing

Manual Installation

If you prefer to install manually or need custom setup:

🔧 Detailed Installation & Setup

Prerequisites

Required:

• Python 3.8+ - Check with python --version or python3 --version
• pip - Should come with Python, verify with pip --version

For full functionality:

• Ollama - Local LLM server (Installation Guide)
• Git - For git integration features

Step 0: Python Environment Setup

If you don't have Python 3.8+ installed:

macOS:

# Using Homebrew (recommended)
brew install python@3.11

# Or download from python.org
# https://www.python.org/downloads/

Linux (Ubuntu/Debian):

# Update package list
sudo apt update

# Install Python 3.11 and pip
sudo apt install python3.11 python3.11-venv python3.11-pip

# Set as default (optional)
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 1

Linux (CentOS/RHEL/Fedora):

# Fedora
sudo dnf install python311 python311-pip python311-venv

# CentOS/RHEL (using EPEL)
sudo yum install epel-release
sudo yum install python311 python311-pip

Windows:

# Download from python.org and run installer
# https://www.python.org/downloads/windows/
# Make sure to check "Add Python to PATH" during installation

# Or using Chocolatey
choco install python311

# Or using winget
winget install Python.Python.3.11

Verify Python installation:

# Check Python version
python3 --version
# or
python --version

# Check pip
python3 -m pip --version
# or
pip --version

# If you get "command not found", try:
python3.11 --version
/usr/bin/python3 --version

Set up virtual environment (strongly recommended):

# Create a dedicated directory for OCode
mkdir ~/ocode-workspace
cd ~/ocode-workspace

# Create virtual environment
python3 -m venv ocode-env

# Activate virtual environment
# On macOS/Linux:
source ocode-env/bin/activate

# On Windows:
ocode-env\Scripts\activate

# Your prompt should now show (ocode-env)
# Verify you're in the virtual environment
which python  # Should show path to venv
python --version

If you have permission issues with pip:

# Option 1: Use --user flag (installs to user directory)
python3 -m pip install --user --upgrade pip

# Option 2: Use virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip

# Option 3: Fix pip permissions (macOS)
sudo chown -R $(whoami) /usr/local/lib/python3.*/site-packages

# Option 4: Use homebrew Python (macOS)
brew install python@3.11
# Then use /opt/homebrew/bin/python3 instead

Step 1: Install Ollama

macOS:

# Using Homebrew (recommended)
brew install ollama

# Or download from https://ollama.ai

Linux:

# One-line installer
curl -fsSL https://ollama.ai/install.sh | sh

# Or using package manager
# Ubuntu/Debian
sudo apt install ollama

# Arch Linux
yay -S ollama

Windows:

# Download from https://ollama.ai
# Or use WSL with Linux instructions above

Start Ollama:

# Start the Ollama service
ollama serve

# In a new terminal, download a model
ollama pull llama3.2
# or
ollama pull codellama
# or
ollama pull gemma2

Verify Ollama is working:

# Check if service is running
curl http://localhost:11434/api/version

# Should return something like: {"version":"0.7.1"}

# List available models
ollama list

Step 2: Install OCode

Method 1: Enhanced Installation Script (Recommended)

# Clone and run installation script
git clone https://github.com/haasonsaas/ocode.git
cd ocode
./scripts/install.sh

Method 2: Development Installation

# Clone the repository
git clone https://github.com/haasonsaas/ocode.git
cd ocode

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode with enhanced features
pip install -e .

# This will install new dependencies for data processing:
# - pyyaml>=6.0 (YAML parsing)
# - jsonpath-ng>=1.5.3 (JSONPath queries)
# - python-dotenv>=1.0.0 (Environment file handling)

Method 3: Direct Git Installation

pip install git+https://github.com/haasonsaas/ocode.git

Method 4: Using pipx (Isolated installation)

# Install pipx if you don't have it
pip install pipx

# Install ocode
pipx install git+https://github.com/haasonsaas/ocode.git

Step 3: Verify Installation

# Check if ocode command is available
python -m ocode_python.core.cli --help

# Should show:
# Usage: python -m ocode_python.core.cli [OPTIONS] COMMAND [ARGS]...
# OCode - Terminal-native AI coding assistant powered by Ollama models.

If you get "command not found": See Troubleshooting section below.

Step 4: Initialize Your First Project

# Navigate to your project directory
cd /path/to/your/project

# Initialize OCode for this project
python -m ocode_python.core.cli init

# Should output:
# ✓ Initialized OCode in /path/to/your/project
# Configuration: /path/to/your/project/.ocode/settings.json

Step 5: Test Your Setup

# Set Ollama host (if using default localhost, this isn't needed)
export OLLAMA_HOST=http://localhost:11434

# Test with a simple prompt
python -m ocode_python.core.cli -p "Hello! Tell me about this project."

# Test enhanced multi-action detection
python -m ocode_python.core.cli -p "Run tests and commit if they pass"

# Test comprehensive tool listing
python -m ocode_python.core.cli -p "What tools can you use?"

# Should connect to Ollama and demonstrate enhanced conversation parsing

✨ Enhanced Features

OCode includes advanced conversation parsing with multi-action detection:

🤖 Multi-Action Query Detection

# These queries now correctly identify multiple required actions:
python -m ocode_python.core.cli -p "Run tests and commit if they pass"           # test_runner + git_commit
python -m ocode_python.core.cli -p "Find all TODO comments and replace them"     # grep + file_edit
python -m ocode_python.core.cli -p "Analyze architecture and write documentation" # architect + file_write
python -m ocode_python.core.cli -p "Create a component and write tests for it"   # file_write + test_runner
python -m ocode_python.core.cli -p "Parse config.json and update environment"    # json_yaml + env
python -m ocode_python.core.cli -p "Monitor processes and kill high CPU ones"    # ps + bash

🧠 Smart Tool Selection

• 14+ Query Categories: Agent management, f