DeepTutor is a free, open-source AI learning workspace that runs the same agent loop across tutoring, problem solving, quiz generation, research, visualization, and guided mastery practice.
It builds versioned knowledge bases from your textbooks, research papers, and technical documents, then gives you an agent-native tutor that cites its sources, generates matching practice problems, and adapts to your progress across every session.
The project has earned over 25,000 GitHub stars since its release. It comes out of the HKUDS Group at the University of Hong Kong, led by Bingxi Zhao under Prof. Chao Huang, with a published paper on arXiv (2604.26962).
The engine went through a complete architecture rewrite in early 2026. Every feature (chat, quiz generation, book compilation) now runs on one extensible agent loop, and capabilities are plugins you can extend with community skills.
You can install it via PyPI, pull the Docker image, or build from source. The default setup talks to cloud LLMs (OpenAI, Anthropic, Gemini, or any OpenAI-compatible endpoint), but you can point it at a local Ollama, vLLM, or LM Studio server if you want everything to stay on your machine.
All your documents, knowledge bases, chat histories, and generated content stay in a local data/ directory.
Update Note (June 2026):
DeepTutor has moved from its original dual-loop architecture to a unified agent-native loop (v1.4.x). You can now install it with one pip install deeptutor command, run it in a single Docker container behind one port, connect your local Claude Code or Codex as a subagent, deploy persistent
For structured learning paths beyond tutoring chat, browse these free beginner courses.
Features
Agent-Native Chat That Carries Context Across Workflows: Every capability (solving, quizzing, researching, visualizing, guided learning) runs on the same agent loop. You switch the objective without switching engines, and your knowledge bases, notebooks, question banks, and memory persist across every workflow. The agent thinks in rounds, calls tools when useful, observes results, and can pause mid-turn to ask you a clarifying question before continuing.
Versioned Knowledge Bases with Multiple Retrieval Engines: Upload textbooks, research papers, and technical manuals to build an AI-powered knowledge base. You pick the retrieval engine per knowledge base: LlamaIndex (now with FAISS vector retrieval for speed on large collections), LightRAG (with local/global/hybrid/mix modes), LightRAG Server (offload retrieval to a standalone server over HTTP), GraphRAG (Microsoft), PageIndex (cloud reasoning-retrieval), or a linked Obsidian vault. Five document parsers are available: text-only, MinerU, Docling, markitdown, and PyMuPDF4LLM. PyMuPDF4LLM is the lightest image-capable option and needs zero model downloads.
Partners: Persistent AI Companions with Their Own Memory: Partners are long-running AI companions with their own SOUL.md persona, dedicated model policy, private memory workspace, skill library, and IM channels. A partner reads your shared memory as context but writes only to its own memory, and you can chat with it through the web interface or connect it to Slack, Discord, Telegram, Feishu, DingTalk, QQ, WeCom, WhatsApp, and eight other messaging platforms. Partner conversations support branching, resuming, exporting to Markdown, and saving to notebooks.
Consult Subagents Mid-Turn: Connect your local Claude Code or Codex CLI as a knowledge source, or link a Partner as a connected agent. Select one in the composer and DeepTutor consults it live mid-turn. The subagent runs its own loop, streams its trace in the sidebar, and the tutor narrates the result in its own voice. Multiple consults within one chat thread into a single session.
Three-Layer Inspectable Memory: Memory is not a hidden vector store. L1 captures append-only event traces per surface. L2 holds curated per-surface facts. L3 synthesizes across surfaces into your profile, preferences, and scope. Because L2 cites L1 and L3 cites L2, every claim in your profile traces back to the raw event that produced it. The Memory Graph lets you audit the full chain.
Deep Research and Literature Review: Systematic topic exploration with pattern identification and cross-domain synthesis. You pick a preset mode (quick for 1–2 subtopics, medium for 5, deep for 8, or auto for agent-determined depth). Parallel execution processes multiple topics concurrently. Final reports include clickable inline citations, a three-level outline, and a references section. You can export reports as Markdown or PDF.
Knowledge Reinforcement Through Practice: Generate targeted quizzes and practice problems calibrated to your knowledge level. Upload reference exams to create new questions that match the original format, style, and difficulty. The Mastery Path replaces the old fixed-stage learning flow with a one-on-one tutor chat that enforces a hard mastery gate. You do not advance past an objective until the system verifies you have mastered it, with server-side grading for memory and procedure objectives and explanation-based judging for concept objectives.
Guided Learning Paths with Spaced Repetition: Select notebooks to generate a progressive learning plan with 3–5 core knowledge points identified by the agent. Mastered objectives enter a spaced-repetition schedule for review. The learning dashboard shows your status map for every objective: new, learning, or mastered.
Interactive Document Editing and Book Engine: The Co-Writer Markdown editor includes AI-assisted rewriting, content expansion, compression, auto-annotation, Mermaid diagram rendering, and narrated scripts with text-to-speech audio in multiple voices. The Book Engine compiles multi-document projects into a “living book” with cross-referenced chapters.
Extensible Tools and Community Skills: Built-in tools cover code execution, web search, paper search, image and video generation, and Geogebra analysis. You can add MCP servers for external data and capabilities. EduHub is the default community skill registry. You can search, preview, and install skills from the browser or CLI, with automatic security verification (zip-slip and zip-bomb guards, file suffix whitelisting, provenance tracking). ClawHub is also supported as a first-class source.
Custom Assessment Generation and Exam Mimicking: Create questions from scratch by specifying topic, difficulty, question type, and count. Or upload a PDF exam and let the system parse its structure (question format, difficulty indicators, answer patterns, distractor styles), then generate entirely new problems that match. Extracted questions include type, difficulty, and answer metadata.
Use Cases
Exam Preparation: Upload past exams and course materials to generate practice problems that mirror actual test questions. The system maintains difficulty levels and question styles from reference materials while creating entirely new problems. The Mastery Path enforces verified mastery before you move on, so you do not skip past concepts you only half-understand.
Technical Documentation Study: Load programming manuals, API documentation, or framework guides into a knowledge base. Ask implementation questions and get answers with code execution. The agent runs Python to demonstrate concepts, validates solutions, and cites the exact source sections it drew from.
Research Paper Analysis: Build a knowledge base from academic papers in your field. The deep research module conducts systematic literature reviews, identifies patterns across papers, and discovers knowledge gaps. You can map existing research before starting your own projects, and the generated reports include structured outlines and full reference sections.
Self-Paced Course Creation: Transform textbooks into interactive learning sessions with automatically generated knowledge points and visual explanations. The guided learning module creates progressive paths through material with spaced-repetition scheduling. You can structure your study of complex subjects with a dashboard that tracks every objective’s status.
Collaborative Note Taking: Use notebooks to aggregate content from every module: problem solutions, generated questions, research reports, edited documents, and partner conversation exports. Study groups can build shared reference materials that grow throughout a semester, with everything saved as timestamped JSON and Markdown files.
Deploy a Teaching Assistant for Your Class: In multi-user mode, the first registered user becomes admin and controls model access, knowledge bases, and tool grants per student. Each student gets an isolated workspace with a redacted settings view. You can assign specific models and knowledge bases per user, making DeepTutor work as a class-wide AI tutoring platform with centralized resource management.
How to Install and Use DeepTutor
Installation Options
DeepTutor gives you four ways to install, from a one-line PyPI command to a full source checkout. Pick the one that matches your comfort level.
Option 1: PyPI (recommended for most users):
mkdir -p my-deeptutor && cd my-deeptutor
pip install -U deeptutor
deeptutor init
deeptutor startdeeptutor init prompts you for ports, your LLM provider, and optional embedding settings. deeptutor start launches the backend and frontend together. You need Python 3.11+ and Node.js 20+ on your PATH. The frontend opens at http://localhost:3782.
Option 2: Docker (single container, single port):
docker run --rm --name deeptutor \
-p 127.0.0.1:3782:3782 \
-v deeptutor-data:/app/data \
ghcr.io/hkuds/deeptutor:latestOnly port 3782 needs publishing. The Next.js frontend proxies /api/* and /ws/* to the backend internally, so you never expose the API port. To connect to a local Ollama or LM Studio instance on the host, add --add-host=host.docker.internal:host-gateway. Pre-release images are available at ghcr.io/hkuds/deeptutor:pre.
Option 3: From Source (for development or customization):
git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
( cd web && npm ci --legacy-peer-deps )
deeptutor init
deeptutor startOptional extras are available: pip install -e ".[partners]" for IM channels and MCP client support, pip install -e ".[math-animator]" for Manim visualization (requires LaTeX and ffmpeg), and pip install -e ".[parse-pymupdf4llm]" for the lightweight PDF parser.
Option 4: CLI Only (no web UI):
git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor
python3 -m venv .venv-cli && source .venv-cli/bin/activate
pip install -e ./packaging/deeptutor-cli
deeptutor init --cli
deeptutor chatThe CLI supports single-turn commands (deeptutor run <capability> <message>), interactive chat, knowledge base management, skill installation, partner management, and session inspection, all without the web server.
Configuration
DeepTutor no longer uses a project-root .env file for runtime settings. All configuration lives in data/user/settings/ as plain JSON and YAML files, editable through the browser Settings page or directly on disk:
model_catalog.json: LLM, embedding, and search provider profiles plus API keyssystem.json: Ports, API base URL, CORS, SSL verification, attachment directoryauth.json: Authentication toggle, username, password hash, token settingsmain.yaml: Runtime defaults and path injectionagents.yaml: Capability and tool temperature and token limitsintegrations.json: PocketBase and sidecar integration settingsinterface.json: UI language, theme, sidebar preferences
To verify your configuration is working, run deeptutor config show for a full summary of every setting the system sees. For health checks on individual providers, use the Settings UI in the browser. Each provider page shows connection status and lets you test endpoints directly.
Using the Workspace
DeepTutor’s interface is now a unified workspace rather than separate route-based tools. The chat composer is the central interaction point: you type what you want to do and the agent loop routes to the right capability. Knowledge bases, notebooks, question banks, partners, agents, and memory are accessible from the sidebar as persistent context sources, not separate applications you switch between.
Knowledge Base Management: Open the Knowledge Center from the sidebar. Create a new knowledge base, pick a retrieval engine (LlamaIndex with FAISS, LightRAG, GraphRAG, PageIndex, LightRAG Server, or Obsidian), choose a document parser, and upload your PDFs, TXT files, or Markdown documents. You can add documents incrementally with deeptutor kb add <kb_name> --docs <new_document.pdf>. Versioned indexes mean you can update a knowledge base without rebuilding from scratch.
Solving Problems: Select a knowledge base from the composer context picker, type your question, and the agent loop handles the rest: investigating through RAG, web search, or document lookup; planning the approach; executing solution steps; checking the answer; and formatting the output with inline citations.
Generating Questions and Mimicking Exams: Open the question generator from the sidebar. For custom generation, specify the topic, difficulty, question type, and count. For exam mimicking, upload a reference PDF. The system parses its structure and generates new problems matching the original format. Extracted metadata includes question type, difficulty, and answer patterns. All output saves to timestamped folders.
Deep Research: Enter a research topic in the composer with the research capability selected. Pick a preset mode: quick (1–2 subtopics), medium (5), deep (8), or auto. The parallel execution mode processes up to 5 topics concurrently. The final report includes clickable inline citations, a three-level outline, and a references section. Export as Markdown or PDF. If parallel mode hits API rate limits, check the cache file at data/user/research/cache/ for completed topics and reduce max_parallel_topics in settings.
Guided Learning and Mastery: Select notebooks from the sidebar, generate a learning plan, and the agent identifies 3–5 core knowledge points. The Mastery Path drives a hard gate. Memory and procedure objectives are quizzed with server-side grading, and concept objectives require you to explain the idea back in your own words. Mastered objectives enter spaced-repetition scheduling. The learning dashboard shows your status for every objective.
Co-Writer and Book Engine: Open the Co-Writer for Markdown editing with AI-assisted rewrite, shorten, expand, and auto-annotate. Mermaid diagrams render inline. The Narrate feature generates scripts with TTS audio in multiple voices. For larger projects, the Book Engine compiles multiple documents into a cross-referenced “living book.”
Remote Access and Multi-User Setup
For LAN access, set the API base URL in data/user/settings/system.json to your server’s IP. In Docker, only port 3782 needs publishing. The frontend proxies API and WebSocket traffic internally. For multi-user deployments, enable authentication in auth.json. The first registered user becomes admin and controls model catalogs, provider credentials, knowledge bases, and per-user tool grants. Each additional user gets an isolated workspace with access only to admin-assigned resources.
Pros
- Data Privacy: All documents, knowledge bases, chat histories, and generated content stay in your local
data/directory. The system only sends text to external services when making LLM API calls. - Verifiable Accuracy: Every answer includes precise citations to source materials. The three-layer memory system lets you trace any synthesized claim back to the raw event that produced it.
- Agent-Native Architecture: Every capability runs on the same agent loop, so context carries across workflows and you never switch engines. Capabilities are plugins, not separate applications.
- Multiple Installation Paths: PyPI one-liner, Docker single-container, full source build, or CLI-only mode. You pick based on your comfort with the command line.
- Flexible LLM Backend: Works with OpenAI, Anthropic, Gemini, Ollama, LM Studio, vLLM, llama.cpp, and any OpenAI-compatible endpoint. You can switch between cloud and local models.
- Extensible by Design: Add MCP servers for external tools, install community skills from EduHub or ClawHub, connect local coding agents as subagents, and extend document parsing with pluggable engines.
Cons
- Technical Setup Required: Even the PyPI path expects you to be comfortable with a terminal, API keys, and basic Python environment management. The Docker path is simpler but still requires Docker familiarity.
- API Costs: You pay for the LLM tokens your usage consumes. Deep research tasks with cloud models can accumulate costs quickly. Running a local LLM avoids per-token charges but needs capable hardware. Expect at least 16 GB of VRAM for a competent model.
- Resource Demands: Knowledge base indexing and parallel research consume significant RAM and CPU. Large knowledge bases with the full LlamaIndex engine need a machine with 16 GB or more of RAM for comfortable use. The PyMuPDF4LLM and text-only parsers are lighter options for resource-constrained setups.
- Rapid Release Cycle: The project ships releases every few days. Features and interfaces can change between versions. The documentation sometimes lags behind the latest release, and you may need to consult GitHub release notes for current behavior.
Alternatives & Related Resources
- OpenMAIC: Free AI Multi-Agent Interactive Classroom Generator
- DeepTutor Documentation: Official docs with setup guides for every installation method, partner channel configuration, and the full API reference.
- LightRAG: Fast retrieval-augmented generation framework from the same lab. DeepTutor’s default knowledge engine and also available as a standalone LightRAG Server backend.
- AI-Researcher: Research automation tool from HKUDS that inspired DeepTutor’s deep research module.
- RAG-Anything: Multimodal RAG system for handling diverse content types beyond text documents, from the same research group.
- DeepTutor Release Notes: Detailed changelog for every release. Useful for tracking feature additions and behavior changes between versions.
FAQs
Q: How is the agent-native architecture different from the old dual-loop design?
A: The original architecture split work across two separate loops (an Analysis Loop to gather context and a Solve Loop to produce answers), each with its own fixed agent pipeline. The current agent-native architecture runs everything on a single loop where the model decides which tools to call and when, observes results, and continues until the task is done. This removes the hard pipeline boundaries. Capabilities like solving, quizzing, and guided learning are now loop plugins that contribute tools and system-prompt blocks rather than separate execution paths. The practical result is that context carries across workflows, tool use is more flexible, and every feature improvement reaches all capabilities at once.
Q: Does DeepTutor work offline?
A: The application logic runs locally on your machine. If you configure it to use a local LLM server (Ollama, vLLM, LM Studio, or llama.cpp), you can run without an internet connection once models are downloaded and knowledge bases are indexed. The default configuration uses cloud APIs, which need internet access. Web search and paper search capabilities also require connectivity when enabled.
Q: How do I check that my configuration is set up correctly?
A: Run deeptutor config show from the terminal for a complete dump of every setting the system reads. In the browser, open Settings and check each provider page. The UI shows connection status and lets you test endpoints directly. If you see issues with LLM responses, first verify your API key and model name in data/user/settings/model_catalog.json, then confirm your provider’s base URL is reachable from the machine running DeepTutor. The backend logs only surface non-200 status codes by default, so connection errors show up clearly in the terminal.
Q: Who built DeepTutor and is there an academic paper?
A: DeepTutor is led by Bingxi Zhao within the HKUDS Group at the University of Hong Kong, directed by Prof. Chao Huang. The project has a published paper on arXiv (2604.26962) that describes the architecture and evaluation. The project iterates in fully open-source form with community contributions, and you can reach the team through GitHub issues, Discord, or the community WeChat and Feishu groups linked in the repository.
Q: What happens to my uploaded documents and data?
A: Everything stays in the local data/ directory on your machine or server. Knowledge bases, problem solutions, research reports, notebooks, generated questions, partner conversations, and memory files all save as JSON and Markdown with timestamps. The system sends document text to external services only when making LLM API calls for RAG queries, and only the relevant chunks, never the full document in a single request. In multi-user mode, each user’s workspace is isolated under data/users/<uid>/ and the exec sandbox mounts only that subtree.
Q: Can I add documents to an existing knowledge base without rebuilding it?
A: Yes. Use deeptutor kb add <kb_name> --docs <new_document.pdf> from the terminal. The system processes only the new document and merges it into the existing knowledge graph and vector store. You can also manage this through the Knowledge Center interface in the browser.
Q: How accurate is the exam mimic mode?
A: Accuracy depends on PDF parsing quality and how clearly the reference exam signals its patterns. The system analyzes question structure, difficulty indicators, answer formats, and distractor patterns, then generates problems that match those characteristics. The MinerU parser extracts question type, difficulty, and answer metadata, which improves fidelity. The mode cannot replicate unstated grading rubrics or instructor-specific preferences that are not visible in the reference document.
Q: What should I do when parallel research mode fails partway through?
A: Parallel mode failures usually come from concurrent API rate limits or memory exhaustion. Check data/user/research/cache/research_YYYYMMDD_HHMMSS/researching_progress.json to see which topics completed. The system saves partial results as it goes. Reduce max_parallel_topics in data/user/settings/main.yaml from 5 to 2 or 3, then rerun. If you are on a cloud API plan with low rate limits, switching to the sequential quick mode avoids the issue entirely.
Q: Can I run DeepTutor as a teaching assistant for my entire class?
A: Yes, with multi-user mode. Enable authentication in data/user/settings/auth.json. The first registered user becomes admin. From the admin Users page, you control which models, knowledge bases, tools, and MCP servers each student can access. Students get isolated workspaces. They cannot see each other’s chats, notebooks, or uploaded documents. You can pre-load course materials into knowledge bases and grant read-only access to the whole class.
