OCode: Native AI Coding Assistant for Your Terminal (Ollama)

OCode operates locally via Ollama. It is a terminal-native AI coding assistant designed specifically for command-line environments. With no GUI and no cloud dependencies, it provides enterprise-grade AI capabilities directly within your shell.

By living in the terminal, OCode gains a deep understanding of your codebase. It maps project structures, traces dependencies, and performs cross-file reasoning to provide accurate technical assistance.

Using natural language, you can refactor files, spin up TDD test harnesses, optimize code, or generate documentation. For instance, asking OCode to “add JWT token support to the user auth module” will prompt it to write the necessary logic across relevant files. Beyond coding, it manages Git workflows, executes test suites, and interfaces with build tools to automate repetitive developer tasks.

Feature Breakdown

OCode includes a suite of over 19 specialized tools.

File Tools

• file_edit – Modify source files using precise cursor positioning and block operations.
• file_ops – Manage read/write actions, batch copying, moving, and deletion.
• glob/find/ls – Search with advanced filters and sorting; list directory contents.
• head_tail/wc – Inspect file headers/footers and count lines, words, or characters.

Text & Data Tools

• grep/text_tools – Perform regex searches, data extraction, and string replacement.
• json_yaml – Parse and query data using JSONPath. Quickly extract database connection strings or configurations.
• notebook_tools – Manage Jupyter notebook operations and conversions.

System & Dev Tools

• ps/env/ping – Monitor active processes, manage environment variables, and test network connectivity (e.g., checking Python process memory usage).
• git_tools/architect – Manage Git repositories and analyze architecture. Compare branches, generate commit messages, and export project documentation.
• agent/mcp – Delegate multi-step tasks to specialized agents via the Model Context Protocol.

Installation

One-line installation (recommended)

Run the following command:

curl -fsSL https://raw.githubusercontent.com/haasonsaas/ocode/main/scripts/install.sh | bash

This script verifies your Python version (3.8+), optionally creates a virtual environment, installs OCode and its toolset, and configures shell auto-completion.

Manual installation

1. Install dependencies

OCode requires Python 3.8+ and pip. It is recommended to use a virtual environment:

mkdir ~/ocode-workspace && cd $_
python3 -m venv ocode-env
source ocode-env/bin/activate  # Windows: ocode-env\Scripts\activate

Install Ollama (the local LLM backend):

# macOS via Homebrew
brew install ollama
# Linux
curl -fsSL https://ollama.ai/install.sh | sh

Launch Ollama and download a model:

ollama serve
ollama pull llama3.2  # alternatives: codellama or gemma2

2. Install OCode

git clone https://github.com/haasonsaas/ocode.git
cd ocode
pip install -e .

3. Initialize your project

Navigate to your project directory and run:

python -m ocode_python.core.cli init

This generates .ocode/settings.json, where you can configure the model, permissions, and context parameters.

Examples

Interactive Session

Enter interactive mode to issue natural language commands:

python -m ocode_python.core.cli
# Commands: /help, /model, /save

One-shot Commands

Code generation:

ocode -p "Create a user registration API endpoint with email verification"

Code review:

ocode -m codellama:70b -p "Review payment processing code for security flaws"

Data processing:

ocode -p "Parse config.json and extract all env vars starting with prod" --out json

Compound Commands

OCode can decompose complex requests into executable steps:

ocode -p "Run tests and commit the code if they pass"  # Triggers test_runner then git_commit
ocode -p "Find all TODO comments and replace with FIXME"  # Triggers grep then file_edit

Configuration & Performance

Model & Context

Model Selection:

• Lightweight tasks: llama3.2:3b for rapid responses.
• Complex refactoring: codellama:70b for deep reasoning and long-context tasks.

export OCODE_MODEL="codellama:70b"

Context Tuning:

{
  "max_context_files": 50,
  "max_tokens": 8192,
  "ignore_patterns": [".git", "node_modules"]
}

Permissions

You can restrict OCode’s operations through the configuration file:

{
  "permissions": {
    "allow_file_write": true,
    "allow_shell_exec": false,
    "blocked_paths": ["/etc", "/bin"],
    "blocked_commands": ["rm -rf", "sudo"]
  }
}

Common Issues

1. Command not found

If the shorthand command fails, use the full module path: python -m ocode_python.core.cli --help. Ensure your virtual environment is active, or install via pipx for global access: pipx install git+https://github.com/haasonsaas/ocode.git

2. Ollama connection failure

Verify the service is active: ps aux | grep ollama. Test the API connectivity: curl http://localhost:11434/api/version. For remote instances, set the host variable: OLLAMA_HOST="http://server-ip:11434"

3. Suboptimal response quality

Try a different model: ocode config --set model=llama3.2:latest. Lowering the temperature (between 0.1 and 0.7) can result in more deterministic and focused output: ocode config --set temperature=0.2

Security

OCode utilizes a whitelist-first security model. Potentially destructive operations, such as system command execution, are restricted by default. Users can implement strict path and command filtering.

Enterprise configuration example:

{
  "permissions": {
    "allow_file_read": true,
    "allow_git_ops": true,
    "allowed_paths": ["/home/user/projects"],
    "blocked_commands": ["rm", "chmod"]
  }
}

OCode integrates deeply with Ollama models to provide a terminal-native AI experience. It streamlines development through automated code generation, project analysis, and task automation—all while keeping your data local and secure.