claw-code 0.2.2__tar.gz → 0.2.3__tar.gz

claw_code-0.2.3/PKG-INFO

@@ -0,0 +1,943 @@
+Metadata-Version: 2.4
+Name: claw-code
+Version: 0.2.3
+Summary: Local Claude Code alternative powered by Ollama - zero API costs
+Author-email: Claw Code Contributors <instructkr@github.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/instructkr/claw-code
+Project-URL: Documentation, https://github.com/instructkr/claw-code#readme
+Project-URL: Repository, https://github.com/instructkr/claw-code.git
+Project-URL: Issues, https://github.com/instructkr/claw-code/issues
+Keywords: ai,claude,ollama,code-generation,local-llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests<3.0,>=2.28.0
+Requires-Dist: psutil<6.0,>=5.9.0
+Requires-Dist: prompt-toolkit<4.0,>=3.0.0
+Requires-Dist: rich<14.0,>=12.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Dynamic: license-file
+
+# 🚀 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](#quick-start)
+- [Why Claw Code?](#why-claw-code)
+- [Features](#features)
+- [Hardware Requirements](#hardware-requirements)
+- [Deep Architecture](#deep-architecture)
+- [Installation & Setup](#installation--setup)
+- [Usage Guide](#usage-guide)
+- [Configuration](#configuration)
+- [API Reference](#api-reference)
+- [Troubleshooting](#troubleshooting)
+- [What's New in v0.2.2](#whats-new-in-v022)
+- [Roadmap](#roadmap)
+
+---
+
+## Quick Start
+
+### Install
+
+```bash
+pip install claw-code
+```
+
+### Seamless Setup (Auto-Detects Everything)
+
+```bash
+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
+
+```bash
+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
+```python
+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
+```python
+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:
+
+```bash
+# 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:**
+```python
+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:**
+```python
+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:**
+```python
+# 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:**
+```json
+{
+  "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:**
+```python
+# 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)
+```python
+@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)
+```python
+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)
+```python
+@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](https://ollama.ai)) — Required once, auto-detected
+- **5-10 GB** free disk space (for model download)
+
+### Step 1: Install Python Package
+
+```bash
+pip install claw-code
+```
+
+### Step 2: Run (Wizard Runs Automatically on First Time)
+
+```bash
+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
+
+```bash
+claw> your prompt here
+```
+
+---
+
+## Usage Guide
+
+### Interactive REPL
+
+The main interface follows a familiar prompt pattern:
+
+```bash
+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:
+
+```json
+{
+  "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)
+```json
+{
+  "model": "phi4-mini",
+  "max_tokens": 2048,
+  "temperature": 0.6
+}
+```
+
+#### Power User (16GB+ RAM)
+```json
+{
+  "model": "qwen2.5-coder:14b",
+  "max_tokens": 8000,
+  "temperature": 0.7
+}
+```
+
+#### Remote Ollama Server
+```json
+{
+  "ollama_base_url": "http://192.168.1.100:11434"
+}
+```
+
+---
+
+## Troubleshooting
+
+### Installation Issues
+
+#### "Python not found"
+Ensure Python 3.9+ is installed and in PATH:
+```bash
+python --version
+```
+
+#### "pip not found"
+On some systems, use `python -m pip`:
+```bash
+python -m pip install claw-code
+```
+
+### Ollama Issues
+
+#### "ollama: command not found"
+Download Ollama from https://ollama.ai and verify installation:
+```bash
+ollama --version
+```
+
+#### "Connection refused" during startup
+Ollama must be running. In another terminal:
+```bash
+ollama serve
+# Or let claw-code auto-start it (if configured)
+```
+
+#### "Model not found" error
+Download the model first:
+```bash
+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:
+```json
+{
+  "model": "phi4-mini"
+}
+```
+
+#### "Not enough disk space"
+Models require 3-14GB free space. Check available:
+```bash
+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:
+```bash
+pip install --upgrade claw-code
+```
+
+#### "No Windows console found"
+When piping input/output, prompt-toolkit requires a real console:
+```bash
+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:
+```bash
+claw-code  # Old config
+# (Ctrl+C to exit)
+# Edit ~/.claude.json
+claw-code  # New config loaded
+```
+
+#### "Invalid config" error
+Reset to defaults:
+```bash
+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:
+```bash
+git clone https://github.com/instructkr/claw-code
+cd claw-code
+```
+
+2. Create virtual environment:
+```bash
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+```
+
+3. Install in editable mode:
+```bash
+pip install -e ".[dev]"
+```
+
+4. Run tests:
+```bash
+pytest tests/ -v
+```
+
+5. Check code quality:
+```bash
+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`:
+```python
+SLASH_COMMANDS = {
+    # ... existing commands ...
+    "/mycommand": "Description of /mycommand",
+}
+```
+
+2. Add handler in `run_repl()`:
+```python
+if user_input.startswith("/mycommand"):
+    handle_mycommand(...)
+```
+
+3. Implement handler:
+```python
+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](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.**