claw-code 0.2.3

Local Claude Code alternative powered by Ollama - zero API costs

🚀 Claw Code — Local Claude Code Powered by Ollama

Free. Offline. No API Keys. Works on Your Laptop.

Experience Claude Code locally and offline, powered by open models like Qwen and Phi through Ollama. Zero API costs, zero data leakage, pure local execution.

Current Version: 0.2.2 | Status: ✅ Production Ready

---

📖 Table of Contents

• Quick Start
• Why Claw Code?
• Features
• Hardware Requirements
• Deep Architecture
• Installation & Setup
• Usage Guide
• Configuration
• API Reference
• Troubleshooting
• What's New in v0.2.2
• Roadmap

---

Quick Start

Install

pip install claw-code

Seamless Setup (Auto-Detects Everything)

claw-code

# First time: Automatic wizard runs
# ✓ Detects your PC RAM
# ✓ Checks Ollama installation 
# ✓ Downloads perfect model for your system
# ✓ Creates ~/.claude.json
# ✓ Launches REPL

# Every time after: Skips wizard, launches REPL immediately

Start Coding

claw> Write a Python function to merge sorted arrays
# Streams response real-time from local model...

claw> Refactor it to use less memory
# Continues the conversation with context awareness

claw> /exit
# Session auto-saved to resume later (Phase 3)

---

Why Claw Code?

Feature	Claw Code	Claude API	ChatGPT
Cost	✅ Free	❌ $0.003/1K tokens	❌ $20/month
Runs Offline	✅ 100% local	❌ Requires internet	❌ Cloud only
Data Privacy	✅ On your machine	⚠️ Anthropic stores	❌ OpenAI stores
Works on Laptop	✅ 8GB+ RAM	❌ Requires account	❌ Requires account
Commands/Tools	✅ Full support	✅ Full support	❌ Limited
Multi-Turn	✅ Stateful sessions	✅ Stateful sessions	✅ Stateful sessions

---

Hardware Requirements

Choose your model based on available RAM:

≤ 8GB VRAM   →  phi4-mini (3.8B)       [M1 MacBook Air, budget laptops]
8-16GB VRAM  →  qwen2.5-coder:7b ⭐     [Most users, recommended]
16GB+ VRAM   →  qwen2.5-coder:14b       [Complex tasks, power users]

All models run locally with zero internet after download.

---

Features

✅ Core Features (Implemented)

• Interactive REPL — Familiar prompt interface with history
• Streaming Output — Real-time token display as model generates
• Multi-Turn Conversations — Full context awareness across turns
• Slash Commands — /help, /session, /clear, /exit etc.
• Hardware Auto-Detection — Uses PSUtil to pick best model
• Configuration Persistence — First-run setup creates ~/.claude.json
• Seamless Setup — Wizard auto-runs first time, skips thereafter
• Windows Support — Unicode handling for Windows console
• Local Execution — 100% offline, no API keys needed
• Cost Tracking — Approximate token counting (not consumed cost)
• Demo Mode — Graceful fallback when Ollama unavailable

🔄 In Development (Phase 3-5)

• Session Persistence — Save/resume conversations
• Tool Execution — Shell commands, file operations
• Permission System — Approve/deny tool access
• VSCode Integration — Extension for editor automation
• Web GUI — Browser-based interface
• Plugin System — Extend with custom tools
• Advanced Routing — Semantic command matching

---

API Reference

Python API

Query Engine

from src.query_engine import QueryEnginePort

# Get engine instance
engine = QueryEnginePort.from_workspace()

# Stream response
for token in engine.stream_message("Your prompt"):
    print(token, end="", flush=True)

# Add to history
engine.add_message("assistant", "Previous response...")

# Get formatted context
context = engine.get_context()

Configuration

from src.config import load_config, write_model_to_config

# Load config
config = load_config()
print(config.model)  # "qwen2.5-coder:7b"

# Update model
write_model_to_config("phi4-mini")

HTTP API (Ollama)

Used internally, but you can call directly:

# List models
curl http://localhost:11434/api/tags

# Generate (streaming)
curl http://localhost:11434/api/generate -d '{
  "model": "qwen2.5-coder:7b",
  "prompt": "def hello():",
  "stream": true
}'

# Pull model
curl http://localhost:11434/api/pull -d '{
  "name": "qwen2.5-coder:7b"
}'

---

Deep Architecture

System Design Overview

┌──────────────────────────────────────────────────────────┐
│           User Terminal (REPL Interface)                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐   │
│  │   Prompt     │  │   Commands   │  │ Completions  │   │
│  │   Handling   │  │   Parser     │  │   Engine     │   │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘   │
└─────────┼──────────────────┼──────────────────┼───────────┘
          │                  │                  │
          └──────────────────┼──────────────────┘
                             │
              ┌──────────────▼──────────────┐
              │   Command Router            │
              │  (Parsing & Dispatch)       │
              └──────────────┬──────────────┘
                             │
          ┌──────────────────┼──────────────────┐
          │                  │                  │
          ▼                  ▼                  ▼
    ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
    │   Slash      │  │   Query      │  │   Tool       │
    │   Commands   │  │   Engine     │  │   System     │
    │   Handler    │  │  (AI/LLM)    │  │  (Perms)     │
    └──────────────┘  └──────┬───────┘  └──────────────┘
                             │
              ┌──────────────▼──────────────┐
              │   Request Formatter         │
              │  (Prompt + Context)         │
              └──────────────┬──────────────┘
                             │
              ┌──────────────▼──────────────┐
              │   HTTP Client               │
              │  (Ollama Integration)       │
              └──────────────┬──────────────┘
                             │
          ┌──────────────────┼──────────────────┐
          ▼                  ▼                  ▼
    ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
    │   Local      │  │   Config     │  │   Session    │
    │   Ollama     │  │   Manager    │  │   Store      │
    │   (localhost │  │  ~/.claude   │  │  ~/.claw     │
    │   :11434)    │  │   .json      │  │  Sessions/   │
    └──────────────┘  └──────────────┘  └──────────────┘

Layer Breakdown

1. Presentation Layer (src/repl.py)

• Interactive REPL with prompt-toolkit
• Rich console output with proper Windows Unicode handling
• Tab completion for commands
• Streaming output for real-time responses
• Status bar showing model, tokens, session info

Key Functions:

run_repl()          # Main REPL loop
print_banner()      # Startup display
handle_input()      # Parse user input
stream_response()   # Stream model output
handle_commands()   # Route /slash commands

2. Command Router (src/command_graph.py + handlers)

• Regexp-based routing to match user input to handlers
• Priority-based dispatch (specific commands first)
• Fallback to query engine for natural language
• Error handling with graceful fallbacks

Routing Priority:

1. Exact match   (/help, /exit, /model)
2. Prefix match  (/ses... → /session)
3. Fuzzy match   (help → /help)
4. Query engine  (everything else → AI)

3. Query Engine (src/query_engine.py)

• Multi-turn conversation with context awareness
• Prompt formatting with role-based context
• Token counting for budget tracking
• Response streaming from Ollama HTTP API

Core Methods:

stream_message()      # Send prompt, stream response
add_message()         # Add to conversation history
get_context()         # Build prompt with history
format_prompt()       # System + user prompt

4. Ollama Integration (src/services/ollama_setup.py)

• Auto-discovery of running Ollama instance
• Model listing from Ollama API
• Auto-start daemon (Windows-safe subprocess handling)
• HTTP client with proper error handling

Connection Pattern:

# Ollama API Endpoints Used
/api/tags              # List available models
/api/generate          # Send prompt (streaming)
/api/show/:name        # Get model metadata
/api/pull              # Download model

5. Configuration Manager (src/config.py)

• Smart config loading from ~/.claude.json
• Field filtering (compatibility with GitHub Copilot settings)
• Defaults fallback for first-time users
• Config persistence after setup wizard

Config Structure:

{
  "provider": "ollama",
  "ollama_base_url": "http://localhost:11434",
  "model": "qwen2.5-coder:7b",
  "max_tokens": 4000,
  "temperature": 0.7,
  "auto_detect_vram": true
}

6. Seamless Setup System (src/init_wizard.py + main.py)

• First-time wizard runs automatically if config missing
• Smart skipping if Ollama + models already installed
• Hardware detection via PSUtil
• Model recommendation based on available VRAM

Smart Behavior:

# First run (no ~/.claude.json):
claw-code
  → Detects hardware
  → Starts Ollama (if needed)
  → Pulls best model
  → Saves config
  → Launches REPL
  
# Subsequent runs:
claw-code
  → Checks ~/.claude.json exists
  → Skips wizard entirely
  → Launches REPL immediately

7. Session Management (Phase 3)

• Session storage in ~/.claw/sessions/
• Conversation history serialization
• Token tracking per session
• Resume capability for multi-day work

---

Core Data Flow

User Input → REPL Response

User Types:
  "Write a Python fibonacci function"
  
  ↓
  
Input Parser (repl.py):
  Detects not a /command
  
  ↓
  
Command Router (command_graph.py):
  No exact match
  → Falls through to QueryEngine
  
  ↓
  
Query Engine (query_engine.py):
  1. Format prompt with system context
  2. Add to conversation history
  3. Calculate tokens
  4. Call Ollama HTTP API
  
  ↓
  
Ollama HTTP Client (requests):
  POST http://localhost:11434/api/generate
  Body: {model: "qwen2.5-coder:7b", prompt: "...", stream: true}
  
  ↓
  
Local Model (qwen2.5-coder:7b):
  Generates response token-by-token
  Streams back via HTTP
  
  ↓
  
Response Streamer (repl.py):
  1. Receive tokens from HTTP stream
  2. Decode tokens
  3. Print to console in real-time
  4. Track token count
  
  ↓
  
User Sees:
  "def fibonacci(n):\n    if n <= 1:\n        return n\n    ..."
  With typing animation effect

---

File Structure

claw-code/
├── src/                           # Python implementation
│   ├── main.py                    # Entry point, `claw-code` command
│   ├── repl.py                    # Interactive REPL loop
│   ├── config.py                  # Config loading & persistence
│   ├── query_engine.py            # LLM query interface
│   ├── command_graph.py           # Command routing logic
│   ├── init_wizard.py             # First-time setup wizard
│   ├── session_store.py           # Session load/save
│   │
│   ├── services/
│   │   ├── ollama_setup.py        # Ollama detection & auto-start
│   │   └── cost_tracker.py        # Token counting
│   │
│   ├── utils/
│   │   ├── prompt_formatter.py    # Prompt template formatting
│   │   └── validators.py          # Input validation
│   │
│   └── types/                     # Type definitions
│
├── rust/                          # Rust implementation (emerging)
│   ├── crates/
│   │   ├── api/                   # HTTP server
│   │   ├── runtime/               # VM/executor
│   │   └── commands/              # Integrated commands
│   └── Cargo.toml
│
├── tests/
│   └── test_parity_audit.py       # Python ↔ Rust parity tests
│
├── pyproject.toml                 # Package metadata (v0.2.2)
└── README.md                      # This file

---

Key Classes & Interfaces

ClaudeConfig (src/config.py)

@dataclass(frozen=True)
class ClaudeConfig:
    provider: str                 # "ollama" or "anthropic"
    ollama_base_url: str         # "http://localhost:11434"
    model: str                    # "qwen2.5-coder:7b"
    max_tokens: int              # 4000
    temperature: float           # 0.7
    auto_detect_vram: bool       # True

QueryEnginePort (src/query_engine.py)

class QueryEnginePort:
    def stream_message(prompt: str) -> Iterator[str]
    def add_message(role: str, content: str) -> None
    def get_context() -> str
    def format_prompt(user_input: str) -> str
    @classmethod
    def from_workspace() -> QueryEnginePort

ReplState (src/repl.py)

@dataclass
class ReplState:
    model: str                    # Current model
    engine: Optional[QueryEnginePort]
    session_id: str              # Current session UUID
    input_tokens: int            # Total input tokens
    output_tokens: int           # Total output tokens

---

Extensibility Points

1. Add New Commands → Register in SLASH_COMMANDS dict
2. Add Tools → Implement Tool interface + add to registry
3. Custom Models → Point ollama_base_url to different server
4. Plugins → Create src/plugins/ directory (Phase 5)

---

Installation & Setup

Prerequisites

• Python 3.9+ (3.12 recommended)
• Ollama (download here) — Required once, auto-detected
• 5-10 GB free disk space (for model download)

Step 1: Install Python Package

pip install claw-code

Step 2: Run (Wizard Runs Automatically on First Time)

claw-code

On first run:

1. ✅ Detects Ollama installation
2. ✅ Checks your VRAM using PSUtil
3. ✅ Recommends appropriate model
4. ✅ Downloads model (~2-5 minutes)
5. ✅ Verifies everything works
6. ✅ Creates ~/.claude.json config
7. ✅ Launches REPL immediately

On subsequent runs:

• Skips wizard entirely
• Launches REPL instantly

Step 3: Start Using

claw> your prompt here

---

Usage Guide

Interactive REPL

The main interface follows a familiar prompt pattern:

claw> Write a function to parse CSV files
# Model streams response in real-time

claw> Add error handling for missing values
# Context preserved across turns

claw> /session
# Shows current session stats

claw> /exit
# Option to save session

Core Commands

Command	Purpose	Example
/help	Show all commands	claw> /help
/model	Show current model & config	claw> /model
/session	Show token usage & stats	claw> /session
/clear	Clear conversation history	claw> /clear
/exit	Exit REPL (save option)	claw> /exit

Examples

Code Generation

claw> Write async Python code to fetch weather from API

[Returns structured async/await code with error handling]

Code Review

claw> Review this code for security issues:
def login(user, pass):
    conn = sqlite3.connect("users.db")
    results = conn.execute("SELECT * FROM users WHERE name='" + user + "'")
    return results[0][1] == pass

[AI identifies SQL injection vulnerability and suggests fix]

Learning

claw> Explain closures in JavaScript with examples

[Returns clear explanation with practical examples]

claw> Show me 3 real-world uses in modern frameworks

[Provides React, Vue, Angular examples]

---

Configuration

Config File Location: ~/.claude.json

Created automatically on first run. Edit manually to customize:

{
  "provider": "ollama",
  "ollama_base_url": "http://localhost:11434",
  "model": "qwen2.5-coder:7b",
  "max_tokens": 4000,
  "temperature": 0.7,
  "auto_detect_vram": true
}

Configuration Options

Option	Type	Purpose	Default
provider	string	LLM provider ("ollama" for now)	"ollama"
ollama_base_url	string	Ollama server URL	"http://localhost:11434"
model	string	Model name (must exist in Ollama)	"qwen2.5-coder:7b"
max_tokens	int	Max tokens per response	4000
temperature	float	Model creativity (0-1)	0.7
auto_detect_vram	bool	Auto-select model by VRAM	true

Common Configurations

Low-End Machine (≤8GB RAM)

{
  "model": "phi4-mini",
  "max_tokens": 2048,
  "temperature": 0.6
}

Power User (16GB+ RAM)

{
  "model": "qwen2.5-coder:14b",
  "max_tokens": 8000,
  "temperature": 0.7
}

Remote Ollama Server

{
  "ollama_base_url": "http://192.168.1.100:11434"
}

---

Troubleshooting

Installation Issues

"Python not found"

Ensure Python 3.9+ is installed and in PATH:

python --version

"pip not found"

On some systems, use python -m pip:

python -m pip install claw-code

Ollama Issues

"ollama: command not found"

Download Ollama from https://ollama.ai and verify installation:

ollama --version

"Connection refused" during startup

Ollama must be running. In another terminal:

ollama serve
# Or let claw-code auto-start it (if configured)

"Model not found" error

Download the model first:

ollama pull qwen2.5-coder:7b
# Then run claw-code again

Performance Issues

"Slow responses" or "First response takes 1-2 min"

This is normal on first run. The model is loading into VRAM. Subsequent responses are faster.

To improve:

• Use smaller model: phi4-mini instead of qwen2.5-coder:14b
• Ensure Ollama is the only heavy process running
• Check disk speed (model loaded from disk to RAM)

"Out of memory" errors

Model too large for available VRAM. Switch to smaller:

{
  "model": "phi4-mini"
}

"Not enough disk space"

Models require 3-14GB free space. Check available:

df -h  # On Unix/Mac
wmic logicaldisk get name,freespace  # On Windows

Windows-Specific Issues

"UnicodeEncodeError" in output

This typically means Windows console encoding issue. Upgrade to latest:

pip install --upgrade claw-code

"No Windows console found"

When piping input/output, prompt-toolkit requires a real console:

claw-code  # ✅ Works (interactive)
echo "" | claw-code  # ❌ Fails (piped input)

Configuration Issues

Changes to ~/.claude.json not taking effect

Config is loaded at startup. Changes require restart:

claw-code  # Old config
# (Ctrl+C to exit)
# Edit ~/.claude.json
claw-code  # New config loaded

"Invalid config" error

Reset to defaults:

rm ~/.claude.json
claw-code  # Recreates config

---

What's New in v0.2.2

✨ New Features

• Seamless Setup — Auto-running wizard now skips if already configured
• Windows Console Fix — Proper Unicode handling with ASCII fallback
• Smart Config Filtering — Ignores GitHub Copilot settings in ~/.claude.json
• Better Error Messages — Clear feedback on common issues

🐛 Bugs Fixed

• Config return value missing from load_config()
• Extra GitHub Copilot settings breaking ClaudeConfig dataclass
• Windows Unicode encoding error when printing banner
• Prompt-toolkit output handling on Windows

📦 Dependencies

• requests — HTTP client for Ollama
• psutil — Hardware detection for auto-select
• prompt-toolkit — Interactive REPL
• rich — Beautiful console formatting

🔄 Deployment Status

• ✅ Published to PyPI as claw-code==0.2.2
• ✅ All tests passing on Windows, macOS, Linux
• ✅ Clean install verified (no missing dependencies)
• ✅ UI/REPL verified launching correctly

---

Contributing & Development

Getting Started (Development)

1. Clone repository:

git clone https://github.com/instructkr/claw-code
cd claw-code

2. Create virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install in editable mode:

pip install -e ".[dev]"

4. Run tests:

pytest tests/ -v

5. Check code quality:

black src/ tests/
ruff check src/ tests/
mypy src/

Project Structure for Contributors

Key files to understand:

• src/main.py — Entry point, argument parsing
• src/repl.py — REPL loop, command handling
• src/query_engine.py — LLM integration
• src/config.py — Configuration management
• src/init_wizard.py — Seamless setup logic
• src/services/ollama_setup.py — Ollama detection/startup

Adding a New Command

1. Edit src/repl.py:

SLASH_COMMANDS = {
    # ... existing commands ...
    "/mycommand": "Description of /mycommand",
}

2. Add handler in run_repl():

if user_input.startswith("/mycommand"):
    handle_mycommand(...)

3. Implement handler:

def handle_mycommand(args):
    # Your logic here
    print("Command executed")

---

Roadmap

Phase 3: Session Management (🔄 Next)

• Save conversations to disk
• Resume sessions across restarts
• Session browsing and export
• Token usage analytics

Phase 4: Advanced Features

• Tool/command execution support
• File system operations
• Shell command integration
• Permission system

Phase 5: GUI & Extensions

• Web-based UI
• VSCode extension
• Plugin system
• Custom tool support

Phase 6: Enterprise Features

• Multi-user support
• Team sessions
• Usage quotas
• Audit logging

---

Comparison Matrix

Claw Code vs Alternatives

Feature	Claw Code	Claude API	ChatGPT	Copilot
Cost	Free	$0.003/1K tokens	$20/month	$10/month
Offline	✅ 100%	❌ Cloud	❌ Cloud	❌ Cloud
Privacy	✅ Local	⚠️ Stored	❌ Stored	⚠️ Stored
Setup	✅ 1 command	❌ API key	❌ Account	❌ Account
Customizable	✅ Open source	❌ Closed	❌ Closed	❌ Closed
Available Models	✅ Qwen, Phi, etc	❌ Claude only	❌ GPT only	❌ GPT only
Speed	⚡ Sub-second	~5-10s	~5-10s	~5-10s
Conversation	✅ Stateful	✅ Stateful	✅ Stateful	✅ Stateful

---

Acknowledgments

Built on the shoulders of giants:

• Ollama — Local LLM inference
• prompt-toolkit — Interactive CLI
• rich — Beautiful console output
• Qwen / Phi — Open models powering inference

---

License

Apache License 2.0 — See LICENSE for details.

Free for personal and commercial use.

---

Support & Community

• GitHub Issues — Report bugs or request features
• Discussions — Ask questions or share ideas
• Feedback — Help shape the roadmap

---

Made with ❤️ by Claw Code contributors.