deep-agents-from-scratch: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This repository contains educational materials for building deep agents from scratch using LangGraph. It demonstrates progressive agent architectures through a series of Jupyter notebooks, starting with basic TODO list functionality and advancing to full agents with file systems and subagent spawning.

Development Commands

Environment Setup

# Install dependencies using uv (preferred package manager)
uv sync

# Run Jupyter notebooks
uv run jupyter notebook

# Alternative: activate virtual environment
source .venv/bin/activate
jupyter notebook

Code Quality

# Run linting with ruff (notebooks and source code)
uv run ruff check
uv run ruff check notebooks/

# Auto-fix linting issues where possible
uv run ruff check --fix
uv run ruff format

# Run type checking with mypy
uv run mypy src/

# Install dev dependencies (includes ruff and mypy)
uv sync --extra dev

LangGraph Studio Integration

# Start LangGraph Studio (if installed)
langgraph up

# The langgraph.json file defines two agents:
# - studio_react_agent: "./src/deep-agents-from-scratch/studio_react_agent.py:agent"
# - react_agent: "./src/deep-agents-from-scratch/react_agent.py:agent"

Architecture

Core Components

State Management (state.py)

• DeepAgentState: Extends LangGraph's AgentState with todos and files
• Todo: TypedDict for task tracking with status (pending/in_progress/completed)
• file_reducer: Merges file dictionaries in state updates

Virtual File System (file_tools.py)

• ls(): List files in virtual filesystem stored in agent state
• read_file(): Read file content with offset/limit support
• write_file(): Create/overwrite files in virtual filesystem
• edit_file(): Perform find-and-replace edits with exact string matching

Task Planning (todo_tool.py)

• write_todos(): Creates and updates structured task lists
• Uses LangGraph Command type for state updates
• Critical for context management and long-running tasks