# 🎯 Claw Code - Reference Implementation

> **Clean-room Claude Code harness - mirrored for architectural study**

---

## ⚠️ IMPORTANT: Reference Only

This repository is a **mirror** of [instructkr/claw-code](https://github.com/instructkr/claw-code) for:
- ✅ Studying agent harness engineering patterns
- ✅ Comparing tool system architectures  
- ✅ Learning clean-room implementation approaches

**Do NOT copy code directly.** Study patterns, then implement independently.

---

## 📊 Stats

| Metric | Value |
|--------|-------|
| **Python** | 2,138 LOC, 66 files |
| **Rust** | 7,619 LOC, 28+ files |
| **Total** | ~10K LOC |
| **Author** | Sigrid Jin (@instructkr) |
| **Origin** | WSJ-featured clean-room rewrite |

---

## 🏗️ Architecture

### Python (`src/`)
```
runtime.py          → Agent runtime with routing
├── tools.py        → Tool harness (Bash, File, MCP)
├── commands.py     → Command system
├── query_engine.py → LLM orchestration
├── permissions.py  → Tool permission contexts
└── bootstrap/      → Initialization
```

### Rust (`rust/crates/`)
```
api/                → Anthropic-compatible client
tools/              → Tool system
compat-harness/     → Compatibility layer
rusty-claude-cli/   → CLI interface
```

---

## 🔗 Key Patterns

### 1. Tool Permission Context
```python
@dataclass
class ToolPermissionContext:
    deny_tools: set[str]
    deny_prefixes: tuple[str, ...]
    
    def blocks(self, tool_name: str) -> bool:
        return tool_name in self.deny_tools or \
               any(tool_name.startswith(p) for p in self.deny_prefixes)
```

### 2. Execution Registry
- Routes prompts to commands/tools
- Filters by permission context
- Handles execution lifecycle

### 3. Session Persistence
- JSON-based session store
- Turn-by-turn history
- Context preservation

---

## 📖 Branches

- `main` - Python-first implementation
- `dev/rust` - Rust port (active)
- `rcc/*` - Rust CLI components

---

## 🔗 External Links

- **Original Repo**: https://github.com/instructkr/claw-code
- **Author**: @instructkr (Sigrid Jin)
- **Context**: WSJ "The Trillion Dollar Race to Automate Our Entire Lives"

---

*Mirrored to Gitea: March 31, 2026*
*For: Timmy Foundation architectural reference*