hitcc-claude-code-reverse-engineering

What this skill does

```markdown
---
name: hitcc-claude-code-reverse-engineering
description: Documentation knowledge base for reverse-engineering Claude Code CLI v2.1.84 — covers runtime logic, agent loop, tool use, MCP, plugin/skill systems, and rewrite architecture
triggers:
  - how does claude code cli work internally
  - reverse engineer claude code
  - understand claude code agent loop
  - claude code tool use implementation
  - claude code mcp integration details
  - rewrite claude code cli
  - claude code session persistence logic
  - claude code prompt assembly pipeline
---

# HitCC — Claude Code CLI Reverse-Engineering Knowledge Base

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

HitCC is a structured documentation knowledge base that reverse-engineers the full runtime logic of **Claude Code CLI v2.1.84** (Node.js). It is not source code — it is topic-oriented analysis covering startup, agent loop, tool execution, prompt assembly, session persistence, MCP, plugins, skills, TUI, and rewrite architecture.

Use this skill when you need to understand how Claude Code works internally, build a compatible alternative, or reference its architecture for your own agentic coding shell.

---

## What HitCC Covers

| Area | Topics |
|---|---|
| Runtime | CLI entry, command tree, mode dispatch, session/transcript persistence |
| Execution | Agent Loop, tool execution core, Hook runtime, Permission/Sandbox/Approval |
| Prompt | Input compilation, prompt assembly, context layering, attachment lifecycle |
| Model | Model adapter, provider selection, auth, stream handling, remote transport |
| Ecosystem | MCP, Plugin, Skill, TUI, Remote persistence, Bridge, Plan system |
| Rewrite | Candidate layering, directory skeleton, open questions, blocking judgments |
| Network | `web-search`, `web-fetch`, telemetry, control plane |
| Settings | Sources, paths, merging, caching, write-back, key consumption surfaces |

---

## Getting the Analyzed Package

HitCC documents Claude Code CLI v2.1.84. To obtain the exact package analyzed:

```bash
npm pack @anthropic-ai/[email protected]
```

This downloads `anthropic-ai-claude-code-2.1.84.tgz` for static analysis. HitCC does **not** redistribute original source.

---

## Installation / Setup

HitCC is a documentation repository — no package install required.

```bash
git clone https://github.com/hitmux/HitCC.git
cd HitCC
```

### Optional: Run Recovery Tools

Python scripts under `recovery_tools/` perform initial cleanup on obfuscated/encrypted source:

```python
# recovery_tools/ scripts — Python 3.x required
# Example: run a cleanup pass on unpacked CLI source
python recovery_tools/cleanup.py --input ./unpacked_cli --output ./cleaned_cli
```

> No external dependencies are documented; use a standard Python 3 environment.

---

## Recommended Reading Order

```
docs/
├── 00-overview/
│   ├── 00-index.md                          ← Start here for global entry
│   ├── 01-scope-and-evidence.md             ← What is known vs. unknown
│   └── 02-document-style-and-structure-conventions.md
├── 01-runtime/
│   ├── 01-product-cli-and-modes.md          ← CLI shape, command tree, mode dispatch
│   ├── 02-session-transcript-persistence.md
│   ├── 03-input-compilation-and-agent-loop.md
│   ├── 04-model-adapter-and-provider.md
│   ├── 05-web-search-and-web-fetch.md
│   ├── 06-telemetry-and-control-plane.md
│   └── 07-settings-system.md
├── 02-execution/
│   ├── 01-tool-execution-core.md
│   ├── 02-hook-runtime-and-permissions.md
│   ├── 03-prompt-assembly-and-context.md
│   └── 04-attachments-and-tool-use-context.md
├── 03-ecosystem/
│   ├── 01-resume-fork-sidechain-subagent.md
│   ├── 02-remote-persistence-and-bridge.md
│   ├── 03-mcp-integration.md
│   ├── 04-skill-and-plugin.md
│   └── 05-tui-runtime.md
├── 04-rewrite/
│   ├── 01-candidate-architecture.md
│   └── 02-open-questions-and-judgment.md
└── 05-appendix/
    ├── glossary.md
    └── evidence-map.md
```

**Fastest path:**
1. `docs/00-overview/01-scope-and-evidence.md` — confidence boundaries
2. `docs/01-runtime/01-product-cli-and-modes.md` — overall product shape
3. `docs/02-execution/` — agent loop, tools, prompts
4. `docs/03-ecosystem/` — MCP, plugin, skill, TUI
5. `docs/04-rewrite/` — engineering strategy

---

## Key Architectural Concepts

### Agent Loop (from docs/01-runtime/03-input-compilation-and-agent-loop.md)

Claude Code's core loop follows this pattern:

```
User Input
  → Input Compilation Pipeline
    → Context assembly (system prompt + rules + attachments)
    → Tool definitions injection
  → LLM Request (streaming)
    → Stream handler collects tool_use blocks
  → Tool Execution Core
    → Concurrent execution with permission checks
    → Hook runtime (pre/post hooks)
  → Result injection → next loop iteration
  → Compact branch (context window management)
```

### Tool Execution Core

Tools run with a concurrent execution model gated by the Permission/Sandbox/Approval system:

```python
# Conceptual rewrite pattern based on HitCC docs/02-execution/01-tool-execution-core.md

import asyncio
from typing import Any

async def execute_tools_concurrent(
    tool_calls: list[dict],
    permission_checker,
    hook_runner,
) -> list[dict]:
    """
    Mirrors Claude Code's concurrent tool dispatch with permission gating.
    """
    async def run_single(tool_call: dict) -> dict:
        tool_name = tool_call["name"]
        tool_input = tool_call["input"]

        # Pre-execution hook
        await hook_runner.run_pre_hook(tool_name, tool_input)

        # Permission check (may trigger approval UI)
        allowed = await permission_checker.check(tool_name, tool_input)
        if not allowed:
            return {"tool_use_id": tool_call["id"], "error": "permission_denied"}

        # Dispatch to tool implementation
        result = await dispatch_tool(tool_name, tool_input)

        # Post-execution hook
        await hook_runner.run_post_hook(tool_name, result)

        return {"tool_use_id": tool_call["id"], "content": result}

    return await asyncio.gather(*[run_single(tc) for tc in tool_calls])
```

### Session / Transcript Persistence

```python
# Pattern from docs/01-runtime/02-session-transcript-persistence.md

import json
import os
from pathlib import Path
from datetime import datetime

TRANSCRIPT_DIR = Path.home() / ".claude" / "transcripts"

def persist_turn(session_id: str, turn: dict) -> None:
    """Append a conversation turn to the session transcript."""
    session_file = TRANSCRIPT_DIR / f"{session_id}.jsonl"
    session_file.parent.mkdir(parents=True, exist_ok=True)
    with open(session_file, "a") as f:
        f.write(json.dumps(turn) + "\n")

def load_transcript(session_id: str) -> list[dict]:
    """Load all turns for session recovery/resume."""
    session_file = TRANSCRIPT_DIR / f"{session_id}.jsonl"
    if not session_file.exists():
        return []
    with open(session_file) as f:
        return [json.loads(line) for line in f if line.strip()]

def fork_session(source_id: str, new_id: str, fork_at_turn: int) -> None:
    """Fork a session at a specific turn index."""
    turns = load_transcript(source_id)
    forked = turns[:fork_at_turn]
    for turn in forked:
        persist_turn(new_id, turn)
```

### Settings System

```python
# Pattern from docs/01-runtime/07-settings-system.md

import json
import os
from pathlib import Path
from typing import Any

SETTINGS_PATHS = [
    Path("/etc/claude/settings.json"),               # system-wide
    Path.home() / ".claude" / "settings.json",       # user-level
    Path(".claude") / "settings.json",                # project-level (cwd)
]

def load_merged_settings() -> dict:
    """
    Load and merge settings from all sources.
    Later sources override earlier ones (project > user > system).
    """
    merged: dict[str, Any] = {}
    for path in SETTINGS_PATHS:
        if path.exists():
            with open(path) as f:
                layer = json.load(f)
            merged = deep_merge(