Metadata-Version: 2.4
Name: claw-code
Version: 0.2.0
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.

  ⭐ The fastest repo in history to surpass 50K stars, reaching the milestone in just 2 hours after publication ⭐

---

## Quick Start (3 Minutes)

### Install

```bash
pip install claw-code
```

### Setup (Auto-Detects Your Hardware)

```bash
claw-code init
# ✓ Detects your PC RAM
# ✓ Downloads perfect model for your system
# ✓ Creates ~/.claude.json
```

### Start Coding

```bash
claw-code

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 locally

claw> /exit
# ✓ Session auto-saved to resume later
```

---

## 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

✅ **Interactive REPL** — Slash commands for control  
✅ **Code Generation** — Write, refactor, optimize, debug code  
✅ **Multi-Turn Conversations** — Full context awareness  
✅ **Session Persistence** — Resume conversations later  
✅ **Local Execution** — No API, no costs, no tracking  
✅ **Streaming Output** — Real-time token responses  
✅ **Hardware Auto-Detection** — Picks best model for you  
✅ **Command Routing** — Smart matching to operations  
✅ **Tool System** — Permission-aware integrations  

---

## Available Commands (in REPL)

```
/help     — Show all commands
/model    — Display current model and settings
/session  — Show token usage and conversation stats
/resume   — Resume a previous session
/clear    — Clear conversation history
/exit     — Exit (optionally save session)
```

---

## Architecture

```
┌─────────────────────────────────────────────┐
│         Claw Code REPL                      │
│     (Your terminal, your machine)           │
└────────────────┬────────────────────────────┘
                 │
┌────────────────▼────────────────────────────┐
│    Query Engine + Session Management        │
│  (Multi-turn conversation, permissions)     │
└────────────────┬────────────────────────────┘
                 │
┌────────────────▼────────────────────────────┐
│     Ollama Adapter                          │
│  (Local HTTP to Ollama server)              │
└────────────────┬────────────────────────────┘
                 │
┌────────────────▼────────────────────────────┐
│     Local Ollama Server + Model             │
│  (qwen2.5-coder:7b or similar)             │
│  (Runs on localhost:11434)                 │
└─────────────────────────────────────────────┘
```

**All processing happens locally. No data leaves your machine.**

---

## Getting Started

### Prerequisites

- **Python 3.9+**
- **Ollama** ([download here](https://ollama.ai))
- **5-10 GB** free disk space (for model download)

### Step 1: Install Python Package

```bash
pip install claw-code
```

### Step 2: Run Setup Wizard

```bash
claw-code init
```

The wizard will:
1. ✅ Check Ollama installed
2. ✅ Detect your system RAM
3. ✅ Recommend best model
4. ✅ Pull model (first time: ~2-5 min)
5. ✅ Verify everything works
6. ✅ Create config (~/.claude.json)

### Step 3: Start Coding

```bash
claw-code

claw> your first prompt here
```

---

## Usage Examples

### Write Code

```
claw> Write a async Python function to fetch data from an API

[Receives well-structured async code with error handling]

claw> Add retry logic with exponential backoff

[Gets updated code with retry mechanism]
```

### Debug Code

```
claw> This function is slow. Why?
def find_duplicates(items):
    result = []
    for i in range(len(items)):
        for j in range(i+1, len(items)):
            if items[i] == items[j]:
                result.append(items[i])
    return result

[Gets analysis + optimized version]
```

### Learn Concepts

```
claw> Explain what a closure is in JavaScript

[Gets clear explanation with examples]

claw> Show me 3 practical uses in modern code

[Gets real-world examples]
```

---

## Configuration

Claw Code creates `~/.claude.json` with sensible defaults:

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

**Edit manually to:**
- Change models: `"model": "phi4-mini"` or `"qwen2.5-coder:14b"`
- Point to remote Ollama: Edit `ollama_base_url`
- Adjust creativity: `"temperature": 0.5` (lower = more focused)

---

## Troubleshooting

### "ollama: command not found"
Download Ollama from https://ollama.ai

### "Connection refused" when initializing
Make sure Ollama is running:
```bash
ollama serve  # In another terminal
```

### "Not enough disk space"
Models are 3-14GB. Free up disk space or use smaller model:
```bash
claw-code config
# Edit ~/.claude.json to use "phi4-mini"
```

### Slow responses
- First response warms up model (1-2 min)
- Subsequent responses faster
- Smaller models (phi4-mini) are faster than larger ones

---

## Advanced: Extend Claw Code

See [CONTRIBUTING.md](CONTRIBUTING.md) for:
- Adding new commands
- Integrating custom tools
- Building plugins
- Custom routing logic
- Local model integration

---

## Architecture & Technical Details

See [ARCHITECTURE.md](ARCHITECTURE.md) for deep dive on:
- System design
- Command/tool registry
- Permission model
- Session persistence
- Ollama integration
- Extension points

---

## Roadmap

### Phase 3: Tool Execution (Coming Soon)
Run actual shell/Python commands from the CLI

### Phase 4: GUI & VSCode Integration
Web UI and VSCode extension

### Phase 5: Advanced Features
Memory, file operations, plugins, custom models

---

## Contributing

Want to help? See [CONTRIBUTING.md](CONTRIBUTING.md) for:
- How to set up dev environment
- Extension points (commands, tools, routing)
- PR process
- Code guidelines

**We welcome contributors!** All skill levels okay.

---

## Community

Join our community to share ideas, ask questions, and collaborate:

[![Discord](https://img.shields.io/badge/Join%20Discord-instruct.kr-5865F2?logo=discord&style=for-the-badge)](https://instruct.kr/)

[GitHub Discussions](https://github.com/instructkr/claw-code/discussions) for Q&A and feature requests

---

## License

Apache License 2.0 — See [LICENSE](LICENSE)

**Summary:** You can use, modify, and distribute Claw Code freely. Great for commercial use. Attribution appreciated but not required.

---

## Performance Comparison

| Metric | Claw Code | Claude Code (API) |
|--------|-----------|-------------------|
| Setup time | 3 min | 5 min (account + API key) |
| Cost | FREE | $$$$ |
| Privacy | 100% local | Sent to Anthropic |
| Offline | ✅ Yes | ❌ No |
| Speed (first response) | 1-2 min* | <1 sec |
| Speed (subsequent) | 15-40 tok/s | 50-100 tok/s |
| Model choice | 3 options | Latest Claude |

*First response includes model loading. Subsequent responses are much faster.

---

## FAQ

**Q: Is this affiliated with Anthropic?**  
A: No. This is an independent open-source project. We rebuild Claude Code's architecture using local Ollama models.

**Q: Can I use this commercially?**  
A: Yes! Apache 2.0 license allows commercial use. See [LICENSE](LICENSE).

**Q: Will my code be tracked?**  
A: No. Everything runs locally. Your code never leaves your computer.

**Q: How much does it cost?**  
A: Free. One-time model download ($0). No subscriptions.

**Q: Can I use a different model?**  
A: Yes! Edit `~/.claude.json` and use any Ollama model.

**Q: How do I update?**  
A: `pip install --upgrade claw-code`

---

## Backstory

At 4 AM on March 31, 2026, the Claude Code source leaked. Rather than panic, I spent the morning clean-room porting the essential architecture to Python, then integrated it with Ollama for zero-cost local execution. The entire effort was orchestrated using [oh-my-codex (OmX)](https://github.com/Yeachan-Heo/oh-my-codex).

**Result:** A functional Claude Code alternative that costs nothing and runs offline.

---

## Star History

See the chart at the top of this README.

> AI startup worker Sigrid Jin, who attended the Seoul dinner, single-handedly used 25 billion of Claude Code tokens last year. At the time, usage limits were looser, allowing early enthusiasts to reach tens of billions of tokens at a very low cost.
>
> Despite his countless hours with Claude Code, Jin isn't faithful to any one AI lab. The tools available have different strengths and weaknesses, he said. Codex is better at reasoning, while Claude Code generates cleaner, more shareable code.
>
> Jin flew to San Francisco in February for Claude Code's first birthday party, where attendees waited in line to compare notes with Cherny. The crowd included a practicing cardiologist from Belgium who had built an app to help patients navigate care, and a California lawyer who made a tool for automating building permit approvals using Claude Code.
>
> "It was basically like a sharing party," Jin said. "There were lawyers, there were doctors, there were dentists. They did not have software engineering backgrounds."
>
> — *The Wall Street Journal*, March 21, 2026, [*"The Trillion Dollar Race to Automate Our Entire Lives"*](https://lnkd.in/gs9td3qd)

![WSJ Feature](assets/wsj-feature.png)

---

## Porting Status

The main source tree is now Python-first.

- `src/` contains the active Python porting workspace
- `tests/` verifies the current Python workspace
- the exposed snapshot is no longer part of the tracked repository state

The current Python workspace is not yet a complete one-to-one replacement for the original system, but the primary implementation surface is now Python.

## Why this rewrite exists

I originally studied the exposed codebase to understand its harness, tool wiring, and agent workflow. After spending more time with the legal and ethical questions—and after reading the essay linked below—I did not want the exposed snapshot itself to remain the main tracked source tree.

This repository now focuses on Python porting work instead.

## Repository Layout

```text
.
├── src/                                # Python porting workspace
│   ├── __init__.py
│   ├── commands.py
│   ├── main.py
│   ├── models.py
│   ├── port_manifest.py
│   ├── query_engine.py
│   ├── task.py
│   └── tools.py
├── tests/                              # Python verification
├── assets/omx/                         # OmX workflow screenshots
├── 2026-03-09-is-legal-the-same-as-legitimate-ai-reimplementation-and-the-erosion-of-copyleft.md
└── README.md
```

## Python Workspace Overview

The new Python `src/` tree currently provides:

- **`port_manifest.py`** — summarizes the current Python workspace structure
- **`models.py`** — dataclasses for subsystems, modules, and backlog state
- **`commands.py`** — Python-side command port metadata
- **`tools.py`** — Python-side tool port metadata
- **`query_engine.py`** — renders a Python porting summary from the active workspace
- **`main.py`** — a CLI entrypoint for manifest and summary output

## Quickstart

Render the Python porting summary:

```bash
python3 -m src.main summary
```

Print the current Python workspace manifest:

```bash
python3 -m src.main manifest
```

List the current Python modules:

```bash
python3 -m src.main subsystems --limit 16
```

Run verification:

```bash
python3 -m unittest discover -s tests -v
```

Run the parity audit against the local ignored archive (when present):

```bash
python3 -m src.main parity-audit
```

Inspect mirrored command/tool inventories:

```bash
python3 -m src.main commands --limit 10
python3 -m src.main tools --limit 10
```

## Current Parity Checkpoint

The port now mirrors the archived root-entry file surface, top-level subsystem names, and command/tool inventories much more closely than before. However, it is **not yet** a full runtime-equivalent replacement for the original TypeScript system; the Python tree still contains fewer executable runtime slices than the archived source.


## Built with `oh-my-codex`

The restructuring and documentation work on this repository was AI-assisted and orchestrated with Yeachan Heo's [oh-my-codex (OmX)](https://github.com/Yeachan-Heo/oh-my-codex), layered on top of Codex.

- **`$team` mode:** used for coordinated parallel review and architectural feedback
- **`$ralph` mode:** used for persistent execution, verification, and completion discipline
- **Codex-driven workflow:** used to turn the main `src/` tree into a Python-first porting workspace

### OmX workflow screenshots

![OmX workflow screenshot 1](assets/omx/omx-readme-review-1.png)

*Ralph/team orchestration view while the README and essay context were being reviewed in terminal panes.*

![OmX workflow screenshot 2](assets/omx/omx-readme-review-2.png)

*Split-pane review and verification flow during the final README wording pass.*

## Community

Join the [**instructkr Discord**](https://instruct.kr/) — the best Korean language model community. Come chat about LLMs, harness engineering, agent workflows, and everything in between.

[![Discord](https://img.shields.io/badge/Join%20Discord-instruct.kr-5865F2?logo=discord&style=for-the-badge)](https://instruct.kr/)

## Star History

See the chart at the top of this README.

## Ownership / Affiliation Disclaimer

- This repository does **not** claim ownership of the original Claude Code source material.
- This repository is **not affiliated with, endorsed by, or maintained by Anthropic**.
