DeepTutor is a free, open-source AI learning workspace for studying your own course materials, technical documents, research papers, books, websites, code repositories, and videos. It uses an agent-native tutor for grounded chat, research, question generation, reading, visualization, and mastery practice.
You can build knowledge bases from uploaded files, GitHub repositories, and documentation sites, then use those sources across tutoring and research sessions. The Learning Space now supports Courses, nested Little Tutor threads, Ask Questions, PDF and EPUB reading, and shared Books with private per-user learning progress.
DeepTutor is developed by the HKUDS Group at the University of Hong Kong and is released under the Apache 2.0 license. The repository has passed 37,000 GitHub stars, and the project has an accompanying arXiv paper (2604.26962).
You can install the full app from PyPI, run it in Docker, build from source, or use the CLI package from the repository. DeepTutor supports cloud model providers and local model servers, including Ollama, LM Studio, vLLM, and llama.cpp.
Workspace data is stored under DeepTutor’s local data/ directory. A fully local workflow depends on the providers you configure. Cloud LLMs, hosted search services, remote parsers, and other online integrations send requests outside your machine when used.
These free beginner courses provide structured introductions for readers who want a course-based starting point.
Features
Agent-Native Learning Workspace: Chat, research, question generation, visualization, mastery practice, reading, and course study share the same agent runtime. Your sessions can call tools, consult knowledge sources, and continue work across the main learning workspace.
Knowledge Bases for Files, GitHub Repositories, and Documentation Sites: DeepTutor can index uploaded learning materials and register GitHub repositories or documentation URLs as knowledge sources. GitHub and web sources support on-demand synchronization, and documentation crawls use explicit depth and page-count limits.
Multiple Retrieval and Parsing Options: Knowledge bases support LlamaIndex, first-party LightRAG, GraphRAG, PageIndex, LightRAG Server, Obsidian, and other configured engines. Parsing options include MinerU, Docling, markitdown, PyMuPDF4LLM, Apache Tika, LiteParse, and text extraction. MinerU can process PDF, common image formats, DOCX, PPTX, and XLSX.
Immersive PDF and EPUB Reading: Open a PDF or EPUB beside the tutor, keep your reading position, create anchored highlights and annotations, and ask questions against the visible material. Reading sessions appear in the same conversation history as other study sessions.
Courses, Little Tutor, and Ask Questions: Learning Space can organize conversations into Courses. You can open a Little Tutor thread from selected text for a focused explanation, or use Ask Questions when the tutor needs clarification before completing the original request.
Immersive YouTube Learning: Paste a YouTube URL to study beside synchronized playback. DeepTutor can bind transcript evidence to timestamps, explain the current cue, and save viewing progress. Public-caption tutoring uses the optional video-learning extra.
My Agents and Live Agent Consultation: DeepTutor can consult local agents during a chat turn. Current integrations include Claude Code, Codex, Antigravity, Kimi, opencode, MiMo Code, Hermes Agent, OpenClaw, and DeepSeek Harness, plus DeepTutor Partners.
Partners with Private Conversations: Each user can create and manage personal Partners with their own persona, memory, model settings, tools, and supported chat channels. Multi-user deployments keep each person’s Partner conversations tied to that account.
Inspectable Memory: DeepTutor uses three memory layers for event traces, curated facts, and cross-workspace synthesis. The Memory Graph exposes the evidence chain behind saved profile information.
Research, Quizzes, and Mastery Practice: Deep Research can produce structured reports with citations. The question tools generate quizzes and new practice problems from your materials, while Mastery Path tracks learning objectives and schedules reviews after an objective is mastered.
Books, Notebooks, and Visualizers: Notebooks collect useful output from study sessions. Books can compile longer learning material and support controlled sharing in multi-user deployments. The visualizer catalog supports SVG, Mermaid, Chart.js, interactive HTML, Manim, and optional GeoGebra output.
Extensible Tools, MCP Servers, and Skills: The runtime supports built-in tools, MCP servers, CLI apps, third-party tool and capability plugins, and community skills from EduHub and ClawHub.
Use Cases
Study Course Materials: Build a knowledge base from lecture notes, textbooks, slides, papers, or documentation, then use grounded tutoring and quizzes for the topics you are working through.
Read Long PDFs and EPUBs: Use Immersive Reading for source-linked questions, annotations, saved reading position, and conversations connected to the material you have open.
Learn Technical Documentation and Codebases: Register documentation sites or GitHub repositories as knowledge sources. You can ask implementation questions, inspect cited material, and consult a connected coding agent during the session.
Analyze Research Literature: Build a collection from academic papers and use Deep Research to investigate a topic, compare material across sources, and produce a structured report with references.
Create Course-Based Study Sessions: Group related conversations into Courses, open Little Tutor threads for difficult passages, and use Mastery Path when you want tracked objectives and review scheduling.
Study From YouTube: Open supported YouTube material beside the tutor, follow timestamped transcript evidence, request an explanation for the current cue, and return to saved progress later.
Run a Multi-User Learning Server: Administrators can manage shared resources and Book access while each user keeps an isolated learning workspace, personal progress, private Partner conversations, and account-bound model credentials where supported.
How to Install and Use DeepTutor
Installation Options
Option 1: PyPI (recommended for most users):
deeptutor 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.
mkdir -p my-deeptutor && cd my-deeptutor
pip install -U deeptutor
deeptutor init
deeptutor startOption 2: Docker (single container, single port):
Only 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.
docker run --rm --name deeptutor \
-p 127.0.0.1:3782:3782 \
-v deeptutor-data:/app/data \
ghcr.io/hkuds/deeptutor:latestOption 3: From Source (for development or customization):
Optional source-install extras include .[rag-lightrag] for first-party LightRAG, .[graphrag] for Microsoft GraphRAG, .[partners] for Partner channel SDKs, .[video-learning] for public-caption YouTube tutoring, and .[math-animator] for Manim support.
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 startOption 4: CLI Only (no web UI):
The 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.
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 chatConfiguration
Runtime settings live under data/user/settings/ for the current workspace. You can manage them through the Settings area or edit the underlying JSON and YAML files when needed.
For a basic configuration check, run:
deeptutor doctorThis command checks workspace settings, providers, dependencies, and ports. You can use deeptutor doctor --online to send a small request to the configured model provider, or deeptutor doctor --format json for machine-readable output. deeptutor config show is useful when you need the resolved configuration values.
Using the Workspace
Home is the main chat UI for ordinary tutoring, reading, mastery work, and video study. The sidebar keeps conversations, Courses, Books, knowledge resources, Partners, and connected agents accessible from the same workspace.
Knowledge Base Management: Create a knowledge base, choose a retrieval engine and parser, then upload supported files or register a GitHub repository or documentation URL. GitHub and web sources can be synchronized later, and DeepTutor detects source changes before re-indexing.
Immersive Reading: Open a PDF or EPUB beside the tutor. Your position, highlights, annotations, and linked conversations can persist with the material, while questions can stay grounded in the visible text or your current selection.
Courses and Little Tutor: Organize related conversations inside a Course. When a passage needs extra explanation, select it and open a Little Tutor thread under the parent conversation. Ask Questions can collect clarification before the tutor completes a request.
YouTube Learning: Paste a YouTube URL to open synchronized playback beside the tutor. Transcript-grounded explanations use the optional public-caption adapter, while playback itself can work through the supported YouTube or configured Invidious setup.
My Agents: Connect a supported local coding or agent CLI and select it during a chat. DeepTutor can run the external agent mid-turn and use its result as context for the tutoring session.
Deep Research: Start a research session, select the desired research depth, and let the agent gather and synthesize material with citations. Search support depends on the provider configured in Settings.
Questions and Mastery: Generate questions from your materials or use Mastery Path for tracked learning objectives. Mastered objectives can enter the review schedule for later practice.
Books and Notebooks: Save useful session output to notebooks or compile longer material as a Book. Multi-user administrators can grant read or collaborative edit access to shared Books while each learner keeps private progress and learning activity.
Visualize: The current visualizer catalog can render SVG, Mermaid, Chart.js, interactive HTML, Manim, and optional GeoGebra output. Browser-only visualizer packages run inside sandboxed frames.
Remote Access and Multi-User Setup
Docker deployments normally publish the web app on port 3782. Multi-user mode can isolate each account’s workspace and personal learning state while administrators manage shared resources, permissions, and Book access. OpenAI Codex OAuth is account-bound in current releases, so each supported user signs in with their own account.
Pros
- Open Source: Apache 2.0 licensing supports self-hosting and code inspection.
- Source-Grounded Study: Knowledge bases, reading, research, and quizzes can work from your own material.
- Multiple Study Modes: Courses, reading, mastery work, research, video study, and question generation share one workspace.
- Local Model Support: DeepTutor works with local model servers as well as cloud providers.
- Extensible Runtime: MCP servers, skills, plugins, CLI apps, and connected agents expand the available tools.
Cons
- Technical Setup: Local installation expects basic terminal, Python, provider, or Docker knowledge.
- Provider Costs: Cloud models, hosted search, parsing services, and media APIs can create usage charges.
- Local Hardware Needs: Local models and larger indexing jobs can require substantial RAM, VRAM, and CPU capacity.
Alternatives & Related Resources
- OpenMAIC: Free AI Multi-Agent Interactive Classroom Generator
- DeepTutor Documentation: Setup guides for installation, configuration, Partner channels, and API usage.
- 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 do I check whether DeepTutor is configured correctly?
A: Run deeptutor doctor to check settings, providers, dependencies, and ports. Use deeptutor doctor --online for a small provider request or deeptutor doctor --format json for structured output. deeptutor config show prints the resolved configuration.
Q: What learning sources can DeepTutor use?
A: DeepTutor can work with uploaded files and configured knowledge sources such as GitHub repositories and documentation sites. Current releases also support PDF and EPUB reading. YouTube study is available through the video-learning workflow, with transcript-grounded explanations when the optional caption adapter is installed.
Q: Does DeepTutor work offline?
A: The app can run locally with a local model server after the required models and dependencies are installed. Features that use cloud LLMs, online search, remote parsers, GitHub synchronization, documentation crawling, or YouTube need network access.
Q: What happens to my uploaded documents and study data?
A: DeepTutor stores workspace data under its local data/ directory. External providers receive requests when you use cloud models, hosted search, remote parsing, or other online integrations. Review the providers you configure if local-only processing is important to you.
Q: Can DeepTutor use my coding agents?
A: Yes. My Agents can connect supported local agents such as Claude Code, Codex, Antigravity, Kimi, opencode, MiMo Code, Hermes Agent, OpenClaw, and DeepSeek Harness. DeepTutor can consult a selected agent during a chat turn.
Q: Can I use DeepTutor for a class or team?
A: Multi-user deployments support isolated user workspaces and administrator-managed shared resources. Shared Books can use per-user read or edit access, while each learner keeps private progress and study activity.
Q: How do I update DeepTutor?
A: PyPI users can run pip install -U deeptutor. Docker users can pull the current ghcr.io/hkuds/deeptutor:latest image. DeepTutor v1.6.2 also adds update checks and eligible PyPI updates under Settings → About.
Last Updated: Aug 30, 2026
