📚 REFERENCE: Claw Code Architecture Documentation #1

New Issue

Timmy · 2026-03-31T20:55:26Z

Timmy commented

2026-03-31 20:55:26 +00:00

Overview

Claw Code is now mirrored in our Gitea as a reference implementation for agent harness engineering.

What is Claw Code?

Origin: Clean-room rewrite of Claude Code (post-leak)
Author: Sigrid Jin (@instructkr) - WSJ-featured power user (25B Claude tokens)
License: Study/research purposes (clean legal standing)
Size: ~10K LOC (Python + Rust)

Repository Structure

src/                    # Python implementation (2,138 LOC)
├── runtime.py          # Core agent runtime with routing
├── tools.py            # Tool harness (Bash, File, Edit, MCP)
├── commands.py         # Command system
├── query_engine.py     # LLM orchestration
├── permissions.py      # Tool permission contexts
├── bootstrap/          # Initialization
└── bridge/             # API bridging

rust/                   # Rust implementation (7,619 LOC)
├── crates/api/         # Anthropic-compatible client
├── crates/tools/       # Tool system
├── crates/compat-harness/
└── crates/rusty-claude-cli/

Key Patterns for Timmy/Hermes

1. Tool Harness Architecture

Permission contexts for tool execution
Tool registry with filtering capabilities
Execution registry for commands/tools

2. API Client Design

Native Anthropic API compatibility
SSE streaming support
Retry policy with backoff

3. Runtime Structure

Session management with persistence
Prompt routing to commands/tools
Bootstrap/runtime graph stages

4. Permission System

@dataclass
class ToolPermissionContext:
    deny_tools: set[str]
    deny_prefixes: tuple[str, ...]
    
    def blocks(self, tool_name: str) -> bool:
        # Implementation pattern

Relevance to Hermes

Claw Feature	Hermes Equivalent	Status
Tool harness	Hermes tools registry	Study for improvements
API client	Provider routing	Reference for Anthropic format
Permission ctx	Tool approval	Could enhance our system
Session store	SessionDB	Similar patterns
Bootstrap	CLI setup	Reference for initialization

Branches

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

External Links

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

Usage Notes

This is a read-only reference for:

Studying harness engineering patterns
Comparing tool system architectures
Learning from clean-room implementation

Do NOT copy code directly - study patterns and implement independently.

Mirrored by: Allegro
Date: 2026-03-31

## Overview Claw Code is now mirrored in our Gitea as a **reference implementation** for agent harness engineering. ## What is Claw Code? - **Origin**: Clean-room rewrite of Claude Code (post-leak) - **Author**: Sigrid Jin (@instructkr) - WSJ-featured power user (25B Claude tokens) - **License**: Study/research purposes (clean legal standing) - **Size**: ~10K LOC (Python + Rust) ## Repository Structure ``` src/ # Python implementation (2,138 LOC) ├── runtime.py # Core agent runtime with routing ├── tools.py # Tool harness (Bash, File, Edit, MCP) ├── commands.py # Command system ├── query_engine.py # LLM orchestration ├── permissions.py # Tool permission contexts ├── bootstrap/ # Initialization └── bridge/ # API bridging rust/ # Rust implementation (7,619 LOC) ├── crates/api/ # Anthropic-compatible client ├── crates/tools/ # Tool system ├── crates/compat-harness/ └── crates/rusty-claude-cli/ ``` ## Key Patterns for Timmy/Hermes ### 1. Tool Harness Architecture - Permission contexts for tool execution - Tool registry with filtering capabilities - Execution registry for commands/tools ### 2. API Client Design - Native Anthropic API compatibility - SSE streaming support - Retry policy with backoff ### 3. Runtime Structure - Session management with persistence - Prompt routing to commands/tools - Bootstrap/runtime graph stages ### 4. Permission System ```python @dataclass class ToolPermissionContext: deny_tools: set[str] deny_prefixes: tuple[str, ...] def blocks(self, tool_name: str) -> bool: # Implementation pattern ``` ## Relevance to Hermes | Claw Feature | Hermes Equivalent | Status | |--------------|-------------------|--------| | Tool harness | Hermes tools registry | Study for improvements | | API client | Provider routing | Reference for Anthropic format | | Permission ctx | Tool approval | Could enhance our system | | Session store | SessionDB | Similar patterns | | Bootstrap | CLI setup | Reference for initialization | ## Branches - `main` - Python-first implementation - `dev/rust` - Rust port (in progress) - `rcc/*` - Rust CLI components ## External Links - **Original**: https://github.com/instructkr/claw-code - **Author**: @instructkr (Sigrid Jin) - **Article**: WSJ "The Trillion Dollar Race to Automate Our Entire Lives" ## Usage Notes This is a **read-only reference** for: - Studying harness engineering patterns - Comparing tool system architectures - Learning from clean-room implementation Do NOT copy code directly - study patterns and implement independently. --- *Mirrored by: Allegro* *Date: 2026-03-31*

Rockachopa commented

2026-03-31 22:49:44 +00:00

We will be running an instance of this code. Do your best.

Timmy commented

2026-04-06 03:32:01 +00:00

Full forge triage: this is reference/archive material, not an active execution frontier. Keeping the documentation in-repo and closing the backlog item to reduce queue noise.

Timmy closed this issue

2026-04-06 03:32:02 +00:00

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Timmy/claw-code#1