PocketFlow-Tutorial-Codebase-Knowledge README

The project's README from github.com/The-Pocket/PocketFlow-Tutorial-Codebase-Knowledge. As one markdown file: README.md.

Turns Codebase into Easy Tutorial with AI

License: MIT

Ever stared at a new codebase written by others feeling completely lost? This tutorial shows you how to build an AI agent that analyzes GitHub repositories and creates beginner-friendly tutorials explaining exactly how the code works.

This is a tutorial project of Pocket Flow, a 100-line LLM framework. It crawls GitHub repositories and builds a knowledge base from the code. It analyzes entire codebases to identify core abstractions and how they interact, and transforms complex code into beginner-friendly tutorials with clear visualizations.

  🔸 🎉 Reached Hacker News Front Page (April 2025) with >900 up‑votes: Discussion »

🤯 All these tutorials are generated entirely by AI by crawling the GitHub repo!

🚀 Getting Started

  1. Clone this repository

    git clone https://github.com/The-Pocket/PocketFlow-Tutorial-Codebase-Knowledge

  2. Install dependencies:

    pip install -r requirements.txt

  3. Set up LLM in utils/call_llm.py by providing credentials. To do so, you can put the values in a .env file. By default, you can use the AI Studio key with this client for Gemini Pro 2.5 by setting the GEMINI_API_KEY environment variable. If you want to use another LLM, you can set the LLM_PROVIDER environment variable (e.g. XAI), and then set the model, url, and API key (e.g. XAI_MODEL, XAI_URL,XAI_API_KEY). If using Ollama, the url is http://localhost:11434/ and the API key can be omitted. You can use your own models. We highly recommend the latest models with thinking capabilities (Claude 3.7 with thinking, O1). You can verify that it is correctly set up by running:

    python utils/call_llm.py

  4. Generate a complete codebase tutorial by running the main script:

    # Analyze a GitHub repository
python main.py --repo https://github.com/username/repo --include "*.py" "*.js" --exclude "tests/*" --max-size 50000

# Or, analyze a local directory
python main.py --dir /path/to/your/codebase --include "*.py" --exclude "*test*"

# Or, generate a tutorial in Chinese
python main.py --repo https://github.com/username/repo --language "Chinese"
    • --repo or --dir - Specify either a GitHub repo URL or a local directory path (required, mutually exclusive)
    • -n, --name - Project name (optional, derived from URL/directory if omitted)
    • -t, --token - GitHub token (or set GITHUB_TOKEN environment variable)
    • -o, --output - Output directory (default: ./output)
    • -i, --include - Files to include (e.g., "*.py" "*.js")
    • -e, --exclude - Files to exclude (e.g., "tests/*" "docs/*")
    • -s, --max-size - Maximum file size in bytes (default: 100KB)
    • --language - Language for the generated tutorial (default: "english")
    • --max-abstractions - Maximum number of abstractions to identify (default: 10)
    • --no-cache - Disable LLM response caching (default: caching enabled)

The application will crawl the repository, analyze the codebase structure, generate tutorial content in the specified language, and save the output in the specified directory (default: ./output).

🐳 Running with Docker

To run this project in a Docker container, you'll need to pass your API keys as environment variables.

  1. Build the Docker image

    docker build -t pocketflow-app .

  2. Run the container

    You'll need to provide your GEMINI_API_KEY for the LLM to function. If you're analyzing private GitHub repositories or want to avoid rate limits, also provide your GITHUB_TOKEN.

    Mount a local directory to /app/output inside the container to access the generated tutorials on your host machine.

    Example for analyzing a public GitHub repository:

    docker run -it --rm \
  -e GEMINI_API_KEY="YOUR_GEMINI_API_KEY_HERE" \
  -v "$(pwd)/output_tutorials":/app/output \
  pocketflow-app --repo https://github.com/username/repo

    Example for analyzing a local directory:

    docker run -it --rm \
  -e GEMINI_API_KEY="YOUR_GEMINI_API_KEY_HERE" \
  -v "/path/to/your/local_codebase":/app/code_to_analyze \
  -v "$(pwd)/output_tutorials":/app/output \
  pocketflow-app --dir /app/code_to_analyze

💡 Development Tutorial


Pocket Flow Codebase Tutorial

PocketFlow-Tutorial-Codebase-Knowledge (The-Pocket/PocketFlow-Tutorial-Codebase-Knowledge)

Searching Database…

12.7K ·GitHub
PocketFlow-Tutorial-Codebase-Knowledge
What is this?A tool that crawls a GitHub repository (or local directory), analyzes the codebase with an LLM to find core abstractions and how they interact, and turns that analysis into a beginner-friendly tutorial with visualizations.
Is this a library I import, or a script I run?It's a command-line script (main.py) you run directly, built on Pocket Flow, the author's own 100-line LLM framework for chaining agent steps.
How do I generate a tutorial for a repo?Clone the repo, install dependencies, configure LLM credentials in utils/call_llm.py (or a .env file), then run the main script with --repo or --dir . Output goes to ./output by default.
Do I need an API key before I can use it?Yes, you need an LLM API key. By default it uses Google AI Studio's GEMINI_API_KEY for Gemini Pro 2.5, but you can switch providers (e.g. set LLM_PROVIDER=XAI) or point it at a local Ollama server without an API key.
Does it work well with any LLM?No — the authors recommend using the latest reasoning/thinking-capable models (Claude 3.7 with thinking, O1) since weaker models struggle to correctly identify codebase abstractions.
Who is this useful for?Developers who need to quickly understand an unfamiliar codebase instead of reading it line by line from scratch.
Can it analyze my private repos?Yes, pass a GitHub token via --token or the GITHUB_TOKEN environment variable to access private repositories or avoid rate limits.
Can I run it in Docker instead of installing Python dependencies locally?Yes, there's a Dockerfile — build the image, pass your GEMINI_API_KEY (and optionally GITHUB_TOKEN) as environment variables, and mount a local folder to /app/output to retrieve the generated tutorial.
Can the tutorial be generated in a language other than English?Yes, the --language flag lets you choose the output language for the generated tutorial; English is the default.
What is Pocket Flow?It's the author's minimalist 100-line LLM framework used to build this tutorial-generating agent, designed so agents can build other agents.
Are there example tutorials I can look at first?Yes, the README links AI-generated tutorials for popular repos like FastAPI, Flask, Requests, CrewAI, LangGraph, and NumPy Core, all produced by crawling those repos with this tool.
What are similar projects?PocketFlow, Raven, ai-agent-book, DeepCode, ai-system-design, minimind, wikiskill, Prompt-Engineering-Guide
Which topics is it in?llm-framework, large-language-model, llm-agent, coding, llms, llm-agents, large-language-models, knowledge-base, documentation, tutorial, agent, education
Creator
The-Pocket
Size
11.6 MB
Stars
12.7K
Updated
CommitMay 31
Age
1y
Commits · 90 Days