Windy3f3f3f3f/claude-code-from-scratch

What it solves

This project provides a minimal, educational implementation of a coding agent, designed to help developers understand the internal workings of complex AI coding assistants like Claude Code without having to navigate hundreds of thousands of lines of production code. It bridges the gap between a simple LLM chat and a fully autonomous agent capable of managing files, executing shell commands, and maintaining long-term memory.

How it works

The project implements a core "Agent Loop" that manages the interaction between a Large Language Model (LLM) and a set of tools. It supports both TypeScript and Python implementations. The system operates by sending prompts to an LLM (supporting Anthropic and OpenAI compatible backends), receiving tool calls, executing those tools locally, and feeding the results back into the loop until the task is completed.

Key architectural components include:

• Tool System: 13 built-in tools for file editing, searching, and shell execution, featuring mtime protection to prevent overwriting changes.
• Context Management: A four-layer compression pipeline (budget truncation, stale snip, microcompact, and auto-compact) to keep token usage efficient.
• Memory System: A semantic recall system using side-queries to retrieve relevant memories.
• ** لقب Skills & Agents**: A system for loading custom skills from directories and spawning sub-agents for complex tasks.
• MCP Integration: Support for the Model Context Protocol (MCP) via JSON-RPC over stdio to connect to external tool servers.

Who it’s for

Developers who want to learn how to build autonomous AI agents, specifically coding agents, by following a step-by-step tutorial that progresses from a basic loop to advanced features like multi-agent orchestration and semantic memory.

Highlights

• Step-by-Step Tutorial: 13 chapters of guided development, each with runnable code snapshots.
• Zero-Key Execution: Ability to run each chapter's code using local mocks, allowing learning without an API key.
• Dual Language Support: Full implementations in both TypeScript and Python.
• Advanced Agentic Features: Includes parallel tool execution, streaming output, and a declarative permission system for safety.
• Budget Control: Built-in limits for USD cost and turn counts to prevent runaway API expenses.