claude-code-from-scratch : reconstruire un agent de codage en 5000 lignes
Build your own Claude Code from scratch. 🔍 Claude Code 开源了 50 万行代码，读不动？用 ~5000 行 TypeScript / Python 从零复现核心架构，11 章分步教程带你理解 coding agent 精髓
En bref
- De quoi s’agit-il ?
- Le dépôt Windy3f3f3f3f propose un tutoriel en 13 chapitres et deux implémentations (TypeScript et Python) qui reproduisent l'architecture d'un agent de codage. Le projet est pédagogique, pas opérationnel : il faut le lire comme un cours, pas comme un outil à déployer.
- À qui s’adresse-t-il ?
- À adopter si vous voulez comprendre comment fonctionne un agent de codage en écrivant vous-même la boucle, les outils et la gestion du contexte. À éviter si vous cherchez un outil prêt pour la production : le dépôt se présente lui-même comme un projet d'apprentissage et ne garantit aucune conformité avec l'implémentation réelle de Claude Code.
- Puis-je l’utiliser commercialement ?
- Oui. MIT est une licence permissive : vous pouvez utiliser, modifier et vendre un logiciel qui en dépend, à condition de conserver les mentions de droit d’auteur et de licence.
- Est-il encore maintenu ?
- Oui. Les derniers commits datent d’il y a 69 jours.
- En quel langage est-il écrit ?
- Principalement Python, d’après les statistiques de langage de GitHub.
Ces réponses reposent sur les données GitHub du projet (dernière synchronisation le 15 septembre 2026) et sur notre analyse. Elles ne constituent pas un avis juridique.
ANALYSE OPEN SOURCE APPROFONDIE
Un cours de mécanique, pas un produit
Le problème visé est précis : le code source de Claude Code compte plusieurs centaines de milliers de lignes, ce qui rend l'apprentissage par lecture directe difficile. Le dépôt répond en proposant environ 5000 lignes écrites deux fois, en TypeScript et en Python, découpées en 13 chapitres. Le public est donc l'ingénieur qui veut comprendre la boucle d'un agent, pas celui qui cherche un assistant à installer dans son éditeur.
Le README est explicite sur ce point : le projet suit le comportement observable publiquement de Claude Code et les pratiques courantes des agents, sans garantie de correspondance avec l'implémentation interne. Il rappelle aussi que Claude Code est une marque d'Anthropic et qu'aucun lien n'existe entre les deux. Cette honnêteté évite la confusion, mais elle fixe la limite : vous n'apprenez pas l'architecture réelle, vous apprenez une architecture plausible construite sur les mêmes principes.
La boucle, les outils et les quatre couches de compression
Le chapitre 1 décrit la boucle centrale : appel au LLM, exécution des outils, répétition. Le chapitre 2 couvre 13 outils avec exécution parallèle et démarrage anticipé en flux, plus une protection par mtime et un chargement différé. Le chapitre 7 détaille quatre niveaux de compression du contexte et la persistance des résultats volumineux. Le chapitre 8 ajoute quatre types de mémoire avec rappel sémantique et préchargement asynchrone.
Les chapitres suivants empilent des capacités : système de compétences avec découverte et deux modes (inline et fork), Plan Mode en lecture seule avec validation à quatre options, architecture multi-agents de type fork-return, et intégration MCP via JSON-RPC sur stdio. Le chapitre 13 établit la comparaison globale et le chapitre 14 liste 22 tests manuels.
Le README fournit un tableau de correspondance entre les fichiers du projet et ceux de Claude Code, par exemple agent.ts face à query.ts, ou tools.ts face à Tool.ts et ses 66 outils. C'est utile pour situer chaque brique, à condition de garder en tête que la comparaison porte sur des fichiers observés de loin, pas sur un code partagé.
Faire tourner un chapitre sans clé API
L'argument le plus concret du dépôt est la possibilité d'exécuter chaque chapitre isolément. Quatre commandes suffisent, telles que documentées :
node steps/run.mjs --list node steps/run.mjs 7 node steps/run.mjs 7 --diff node steps/run.mjs 7 --py
Le mode par défaut utilise un modèle simulé local, sans réseau, et --diff montre uniquement les lignes ajoutées par rapport au chapitre précédent. Pour brancher un vrai modèle, il faut ajouter --live. Le README insiste sur un point de méthode : le code du chapitre, les blocs cités dans la documentation et la sortie affichée proviennent tous de la même source, ce qui évite les divergences classiques entre texte et code.
Pour l'installation complète, la version TypeScript passe par git clone, npm install et npm run build. La version Python exige Python 3.11 ou plus et s'installe avec pip install -e . depuis le dossier python, puis se lance via mini-claude-py ou python -m mini_claude. Le nom de commande diffère volontairement pour ne pas entrer en conflit avec la version TypeScript.
Deux backends, un modèle par défaut discutable
La configuration repose sur des variables d'environnement. Le format Anthropic utilise ANTHROPIC_API_KEY, avec ANTHROPIC_BASE_URL en option pour passer par un proxy. Le format compatible OpenAI utilise OPENAI_API_KEY et OPENAI_BASE_URL. Le modèle par défaut indiqué est claude-opus-4-6, modifiable par MINI_CLAUDE_MODEL ou par l'argument --model, ce dernier étant prioritaire sur la variable.
Le choix d'un modèle haut de gamme par défaut se comprend pour un tutoriel : les capacités de raisonnement facilitent la démonstration des outils et de la compression. Il se paie ailleurs. Les options --max-cost et --max-turns existent précisément parce que la consommation peut déraper, et le README les présente comme des garde-fous. Pour des essais répétés, il est plus raisonnable de fixer MINI_CLAUDE_MODEL sur un modèle plus léger avant de lancer la moindre session interactive.
Les modes d'exécution et leurs angles morts
Le projet expose cinq modes de permission, décrits au chapitre 6 avec des règles déclaratives et une détection des commandes dangereuses. En ligne de commande, cela donne --yolo pour ignorer les confirmations, --accept-edits pour approuver automatiquement les modifications de fichiers, --dont-ask pour un usage en CI où toute opération nécessitant une confirmation est refusée, --plan pour analyser sans modifier, et --resume pour reprendre une session.
Le mode --yolo mérite une mise en garde que le README formule à peine : il exécute automatiquement les commandes dangereuses. Sur un dépôt de travail, c'est un choix risqué, et rien dans le matériel fourni ne décrit de bac à sable, de conteneur ou de journal d'audit. Le mode --dont-ask est l'inverse exact et convient mieux à un environnement automatisé, au prix d'un agent qui abandonne dès qu'une confirmation serait nécessaire.
La limitation la plus nette reste la nature du projet. Le README le dit sans détour : c'est un projet d'apprentissage, sans garantie de conformité avec l'implémentation réelle. Il n'y a pas de promesse de support, pas d'engagement de compatibilité, et les tests mentionnés sont manuels, au nombre de 22, pas une suite automatisée.
Ce que change une réimplémentation face à un cadre d'agent
L'alternative naturelle est un cadre d'agent existant, du type LangChain ou un SDK d'agent fourni par un éditeur de modèle. La différence n'est pas la qualité mais la finalité. Un cadre vous donne des abstractions prêtes à l'emploi : gestion des messages, appel d'outils, mémoire, souvent avec des intégrations nombreuses. Vous assemblez et vous déployez.
Ici, l'abstraction est justement ce qu'on cherche à voir. Le chapitre 7 sur les quatre couches de compression n'existe que parce qu'il faut écrire soi-même la logique qui décide quoi résumer et quand. Le chapitre 11 sur les sous-agents fork-return n'a d'intérêt que si l'on construit le passage de contexte entre parent et enfant. Un cadre masque ces décisions, ce qui est un avantage en production et un obstacle en apprentissage.
Le revers est réel : rien dans ce dépôt ne prétend remplacer un cadre pour un usage quotidien. Le choix se fait donc sur l'objectif, pas sur la performance.
Coût de maintenance et portée de la licence MIT
La licence MIT autorise la réutilisation, la modification et la redistribution, y compris dans un contexte commercial, sous réserve de conserver la notice de copyright et le texte de licence. Le dépôt n'énonce aucune restriction supplémentaire, et il n'y a pas de clause de non-responsabilité particulière au-delà de celle de la MIT. Cela ne constitue pas un avis juridique : faites relire la notice si vous réutilisez le code dans un produit.
Sur la maintenance, le matériel disponible donne peu d'éléments. La dernière publication est une version v1.0.0 datée du 31 mars 2026, et le dernier envoi sur la branche main est daté du 9 juillet 2026. Le dépôt n'est pas archivé. Le rythme de mise à jour n'est pas documenté, et aucune politique de compatibilité entre versions n'apparaît. Si vous suivez le tutoriel chapitre par chapitre, prévoyez de figer une révision plutôt que de suivre la branche main, car un changement dans steps/run.mjs ou dans les sorties attendues casserait la continuité pédagogique.
Un point pratique : deux implémentations maintenues en parallèle, TypeScript et Python, doublent la surface à faire évoluer. C'est un choix cohérent avec l'objectif comparatif du chapitre 13, mais c'est aussi une charge que le projet devra assumer sur la durée.
Conclusion éditoriale
À adopter si vous voulez comprendre comment fonctionne un agent de codage en écrivant vous-même la boucle, les outils et la gestion du contexte. À éviter si vous cherchez un outil prêt pour la production : le dépôt se présente lui-même comme un projet d'apprentissage et ne garantit aucune conformité avec l'implémentation réelle de Claude Code. Avant de vous engager, vérifiez que la version Python 3.11+ fonctionne avec votre configuration et que le mode --live accepte bien le backend que vous utilisez.
Notes de la communauté