docs: Add REFERENCE.md - architectural study documentation

2026-03-31 20:56:07 +00:00
parent 4586764a0e
commit 40e3e2edbc
1 changed files with 95 additions and 0 deletions
--- a/REFERENCE.md
+++ b/REFERENCE.md
@@ -0,0 +1,95 @@
+# 🎯 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*