DeepCode: Open Agentic Coding Framework

Paper Link: https://arxiv.org/abs/2512.07921

Source Code: https://github.com/HKUDS/DeepCode

The Challenge of Teaching an AI to Read and Code

Imagine asking a brilliant chef to cook a complex, multi-course meal from a 50-page cookbook, but with a catch: the chef can only remember one page at a time. They might perfectly execute the recipe on page 5, but by the time they get to page 30, they've forgotten the crucial prep steps from the beginning. The result would be a collection of well-made components that don't come together into a coherent meal.

This is the core challenge that today's most powerful Large Language Models (LLMs) face when asked to perform a complex task like converting a dense scientific paper into a complete, working code repository. They are caught in a fundamental conflict between information overload (the entire paper is too much to process at once) and the context bottleneck (their working memory is too small to hold all the details).

To solve this, DeepCode introduces a paradigm shift: it treats the entire process as a problem of principled information-flow management. Instead of just feeding the AI more information, it focuses on maximizing the Signal-to-Noise Ratio at every step. This guide walks through DeepCode's intelligent, three-phase process that acts as a master plan and a sophisticated memory system, deliberately filtering out noise and amplifying the critical signals needed to transform a complex idea into a functional reality.

1. The Big Picture: DeepCode's Three-Phase Solution

To solve this complex puzzle, DeepCode breaks down the monumental task of "reading a paper and writing code" into three distinct, manageable phases. Each phase has a clear purpose and builds on the last, creating an organized and efficient workflow designed to maximize clarity and precision.

Here is a high-level overview of the entire process:

Now, let's explore each of these phases in detail to understand how DeepCode moves from a document to a fully functional codebase.

2. Phase 1: Creating the Master Plan (Blueprint Generation)

The goal of this initial phase is source compression. Instead of feeding the entire, messy scientific paper to the coding AI at once, DeepCode first distills its contents into a precise, machine-readable plan. This blueprint acts as the single source of truth for the entire project, ensuring nothing gets lost or misinterpreted. This is achieved through three key activities.

1. Chopping the Paper into Manageable Pieces This step, called Hierarchical Content Segmentation, is like creating a detailed, digital table of contents for the paper. The system scans the document and breaks it down into "chunks" based on its structure (e.g., "3. Methodology," "3.1. Model Architecture"). Each chunk is tagged with its heading, creating an index. This allows the AI agents in the next step to look up specific information on-demand (like asking "Show me the section on 'Model Architecture'") instead of having to re-read the entire paper every time they need a detail.
2. Assembling a Team of AI Specialists Next, DeepCode uses a Multi-Agent Specification Analysis approach, a "divide and conquer" strategy that assigns two specialist AIs to analyze the indexed paper. By separating "architectural vision" from "engineering precision," DeepCode ensures both the high-level structure and low-level details are captured without compromise.
   • The Concept Agent: This AI acts as the "big-picture architect." It reads the high-level sections of the paper (like the introduction and methodology) to understand the main ideas, the scientific goals, and the overall structure of the software that needs to be built. It maps out the core components and how they should interact.
   • The Algorithm Agent: This AI is the "details-obsessed engineer." It meticulously scans the technical sections of the paper to extract every critical detail. This includes specific equations, pseudocode from algorithm boxes, network architectures, and the exact numbers for settings like learning rates (hyperparameters).
3. Finalizing the Blueprint Finally, a Code Planning Agent takes the high-level overview from the Concept Agent and the granular details from the Algorithm Agent and synthesizes them into a single, unambiguous Implementation Blueprint. This final document is the master plan and contains five key sections:
   • Project File Hierarchy: A complete list of all the files that need to be created and the folder structure to organize them in.
   • Component Specification: Detailed instructions for every function and class, linking them directly to the specific equations or pseudocode from the paper.
   • Verification Protocol: A clear plan for how to test the final code, including what metrics to check to confirm it matches the paper's results.
   • Execution Environment: A list of all necessary software dependencies and library versions required to run the code.
   • Staged Development Plan: A step-by-step roadmap defining the order in which to build the code components.

With this master plan complete, the system is ready to move from planning to building.

3. Phase 2: Building the Code, Intelligently (Code Generation)

This phase is where the actual source code gets written, meticulously guided by the blueprint. The primary challenge here is building a large project with many interdependent files, one file at a time, without losing track of how they all connect. DeepCode uses two clever mechanisms to manage this complex process.

1. Using a "Smart Notebook" to Remember Code (CodeMem) As the AI writes each new file, it needs to remember what it has already built. Showing it the full text of every previously written file would quickly overload its memory (the context bottleneck). The Code Memory (CodeMem) mechanism solves this. After a file is written, a specialized summarization agent creates a "smart notebook entry" for it. This entry doesn't contain the full code, but rather a compact summary with four key pieces of information:
   • Core Purpose: A short sentence explaining what the file does.
   • Public Interface: A description of the functions and classes in this file that other files can use.
   • Dependency Edges: A list of which other files this one uses, and which other files are expected to use it.
   • Next Implementation Target: A decision on which file should be built next, based on the project's dependency graph and the overall plan.
2. By consulting this "smart notebook" of summaries instead of the raw code, the AI can ensure all the pieces of the project remain consistent and compatible without running out of memory.
3. Consulting an "Expert Library" for Tricky Parts (CodeRAG) Sometimes, a scientific paper describes what to do but not exactly how to implement it with standard coding practices. To prevent the AI from "hallucinating" or making errors, DeepCode uses a Retrieval-Augmented Generation (CodeRAG) framework. This gives the AI the ability to look up high-quality code examples from an indexed library of existing software projects. For instance, a paper might specify using a "standard Adam optimizer" but omit the boilerplate code for setting it up in PyTorch. CodeRAG retrieves a proven, standard implementation for that boilerplate, preventing the AI from inventing a potentially buggy version and grounding its work in real-world examples.

With the code generated, the next step is to make sure it's not just plausible, but functionally perfect.

4. Phase 3: Testing and Fixing Everything (Automated Verification)

This final phase is a crucial error correction loop. Its purpose is to transform the newly generated code—which might look right but contain hidden bugs—into a repository that is functionally faithful to the paper and actually runs without crashing. This is done in two stages.

1. The "Code Inspector" (Static Analysis) Before even trying to run the code, an Analysis Agent performs a static check. Think of this as an automated proofreader for the entire project. It scans the code repository and compares it against the original blueprint to find structural problems like missing files, empty files, and general code quality issues. If any problems are found, a Modification Agent makes precise, line-level fixes.
2. The "Test Drive" (Sandbox Execution) Once the code passes the static inspection, it's time for a dynamic test. The code is moved into a safe, isolated "sandbox" environment to be executed. A Sandbox Agent then tries to run the main parts of the program. This process is iterative:
   • The agent runs the code.
   • If it encounters an error (a "bug"), it carefully analyzes the error message to understand the cause.
   • It then relays this information to generate a "patch," which is applied to fix the specific lines of code causing the problem.
3. This run-fail-patch loop continues until the code executes successfully from start to finish, ensuring the final repository is robust and functional.

5. Conclusion: From Idea to Reality

DeepCode's "Plan, Build, Test" process systematically translates a complex scientific paper into a working codebase. Its success comes not from a bigger memory, but from a smarter process. By embracing principled information-flow management, it intelligently compresses, structures, and verifies information at every step, maximizing the task-relevant signal while filtering out noise.

This systematic approach is what allows DeepCode to reliably automate a highly complex task and achieve performance that can even surpass PhD-level human experts. By establishing a new foundation for autonomous scientific reproduction, this framework does more than just write code; it promises to accelerate research evaluation and discovery, changing the speed and reliability of science itself.