hkuds/deeptutor

---

🤝 We welcome any kinds of contributing! Vote on roadmap items or propose new ones at Roadmap, and see our Contributing Guide for branching strategy, coding standards, and how to get started.

📦 Releases

[2026.10.28] v1.7.0 — Modular installation, a refreshed learning workspace, block notebooks with Dito, narrated video lessons, resumable embedding checkpoints, and more reliable tutoring.

✨ v1.7.0 is live. pip install -U "deeptutor[full]" installs the full Web app and CLI; bare deeptutor installs core only. See the upgrade steps below for legacy CLI installations.

📰 News

• 2026-09-20 🎉 40k stars in 9 months! We’ll keep expanding DeepTutor’s learning ecosystem.
• 2026-05-22 🌐 Official docs site live at deeptutor.info — guides, references, and capability tours in one place.
• 2026-04-19 🎉 20k stars in 111 days! Thank you for the support toward truly personalized, intelligent tutoring.
• 2026-04-10 📄 Our paper is live on arXiv — read the preprint for the design and ideas behind DeepTutor.
• 2026-02-06 🚀 10k stars in just 39 days! A huge thank you to our incredible community.
• 2026-01-01 🎊 Happy New Year! Join our Discord, WeChat, or Discussions — let’s shape DeepTutor together.
• 2025-12-29 🎓 DeepTutor is officially released!

✨ Key Features

DeepTutor is an agent-native learning workspace that connects tutoring, problem solving, quiz generation, research, visualization, and mastery practice in one extensible system.

• One runtime for every mode — Chat, Ask Questions, Quiz, Research, Visualize, Solve, Mastery Path, Immersive Reading, and Audio Overview share one capability runtime and session context while keeping purpose-built loops and pipelines.
• Task Board — Track study tasks in To do, In progress, and Done, with notes, drag-and-drop or keyboard-accessible move buttons, and an archive you can restore from. Cards stay in the current workspace and follow the existing appearance and language settings; no model configuration is required.
• Connected learning context — Knowledge bases, books, Learning notebook pages, Favorites, question banks, personas, and Memory can be reused across the workflows that support them, subject to account grants and learning policies.
• Immersive video learning — add YouTube or Bilibili links to Reading for native playback, transcript search, timestamp-grounded tutoring, saved notes, and resumable progress; YouTube captions and browsing can use an administrator-configured Invidious instance.
• Subagents and Partners — from Chat, consult a live agent harness (Claude Code, Codex, Grok CLI, Antigravity, Kimi, opencode, MiMo, Hermes, OpenClaw, or DeepSeek) or a Partner, import past conversations, and run persistent IM companions on the same brain.
• Multi-engine knowledge — versioned RAG libraries across LlamaIndex, PageIndex, GraphRAG, LightRAG, a remote LightRAG Server, a self-hosted WeKnora knowledge base, a Tencent IMA or MarginNote 4 library, a connected Kiwix ZIM archive, or a linked Obsidian vault, with pluggable document parsing. See native LightRAG role models for independent extraction, query and vision settings, default-only creation and confirmed rebuilds.
• Extensible tools and skills — built-in tools, MCP servers, CLI apps, image / video / voice generation models, and installable community skills from EduHub.
• Inspectable memory — L1 traces, L2 surface summaries, and L3 synthesis make personalization visible and editable; the Memory Graph links L2 facts to L1 evidence and L3 synthesis to contributing surfaces.

---

🚀 Get Started

Let Your Agent Set Up DeepTutor

Copy this prompt into your terminal-capable AI agent (such as Codex or Claude Code):

Help me install and configure the current dev version of DeepTutor from https://github.com/HKUDS/DeepTutor.
Clone the dev branch, or inspect and reuse my existing checkout. Start at
docs-for-dev/README.md, then read docs-for-dev/AGENT_SETUP.md and SKILL.md.
Follow the setup guide to prepare the environment,
configure my model provider, verify the setup, and start the Web app.
Ask me for any missing provider, model, or credential-source information;
do not print API keys. Preserve my existing files and settings, and finish
with the access URL and the results of your checks.

The developer and agent handbook is the documentation entry point for setup, architecture, extension development, testing, and troubleshooting. Its Agent Setup guide covers the full installation flow, including non-interactive CLI configuration. To install it yourself, choose one of the paths below.

DeepTutor ships four installation paths. They all share one runtime-home layout: private settings live in data/user/settings/ under the directory you launch from (or under DEEPTUTOR_HOME / deeptutor start --home if you set one explicitly). See Local Data Persistence for the complete storage layout, database support, and backup notes. For the full app, the recommended flow is pick a runtime-home directory → install → deeptutor init → deeptutor start.

One-Command Docker Trial

If Docker is not installed yet, install Docker first. Then try the full app without setting up Python or Node.js:

docker run --rm --name deeptutor \
  -p 127.0.0.1:3782:3782 \
  -v deeptutor-data:/app/data \
  ghcr.io/hkuds/deeptutor:latest

Open http://127.0.0.1:3782, configure model providers in Settings → Providers, and press Ctrl+C when you are done. The named deeptutor-data volume keeps settings and local data for the next run.

Content Workspace

The Content Workspace is separate from DeepTutor’s private runtime home. It is the folder agents may read, with generated files under outputs////. Custom workspaces isolate conversations, learning materials, progress, and caches in a private .deeptutor/data/ tree that file tools cannot browse. Settings, credentials, and Memory stay shared at the account level.

Without configuration, the content workspace is /data/user/workspace. Local PyPI, CLI, and source installs can choose folders in Settings → Workspaces; set the default folder with:

deeptutor workspace show
deeptutor workspace set /absolute/path/to/my-folder
deeptutor workspace reset

Capabilities inspect their selected workspace through the built-in workspace tools. The model only receives relative paths such as outputs/...; when it uses workspace_present, the UI renders an authenticated, openable snapshot. The same exact relative path also works in a normal Markdown link or image. Changing the source file later does not change an already presented snapshot.

Learning Space manages the resource library. In Settings → Workspaces, assign Skills, MCP services and knowledge bases to each workspace, or retain its existing access rules. Existing workspaces keep their current access until a selection is saved. Assignments reference the original resources without copying credentials or knowledge indexes; workspace-specific skills can override shared versions. See workspace resource assignments.

Execution is read-only outside outputs/. Copying a generated file elsewhere in the content workspace requires an explicit Allow once confirmation for that exact source and destination. A system sandbox or the Docker runner enforces this boundary when available; local restricted-subprocess fallback is shown as best effort in Workspace settings.

This source install includes server dependencies but skips frontend setup. Keep the checkout around — the editable install points to it. To add the Web UI later, install Node.js 22 LTS, run npm ci --legacy-peer-deps in web/, then run deeptutor init and deeptutor start from the project root.

📖 Explore DeepTutor

Start with a workspace for a subject or project. Its Home, Learning, and Resources hold your conversations, learning activities, and materials. Partners and Personalization stay with your account across workspaces. The tour below shows how these surfaces connect, followed by settings and multi-user deployment.

If an answer loses an earlier constraint, cites weak evidence, or disagrees with selected material, collect the diagnostics in REASONING_SAFETY_CHECKLIST.md before opening an issue.

⌨️ DeepTutor CLI — Agent-Native Interface

One deeptutor binary, two ways in: an interactive REPL for people who live in the terminal, and structured JSON for other agents that drive DeepTutor as a tool. Same capabilities, tools, and knowledge bases either way.

🧩 Ecosystem — EduHub & the Skills Community

DeepTutor skills use the open Agent-Skills format — a folder with a SKILL.md playbook (YAML frontmatter + Markdown) and optional reference files. Nothing about it is DeepTutor-specific, so any registry that speaks the format becomes a source for your library. DeepTutor ships with EduHub — our own education-focused skill registry — wired in as the default hub.

🤝 Open Source Partners

Using code: DEEPTUTOR20 — get $20 off for your first PageIndex subscription!

🌐 Community

🔗 Maintainers

📮 Contact

DeepTutor is an open-source project led by Bingxi Zhao within the HKUDS Group, and it iterates in a fully open-source form, built together with the community. So far, we DO NOT have paid online products of any form. Feel free to reach out at [email protected] for discussions, ideas, or collaboration.

🙏 Appreciation

Heartfelt thanks to Chao Huang, director of the Data Intelligence Lab @ HKU, and to our HKUDS labmates for their warm support — especially Jiahao Zhang, Zirui Guo, and Xubin Ren. We’re also deeply grateful to the open-source community: your stars, issues, pull requests, and discussions shape DeepTutor every single day.

DeepTutor also stands on the shoulders of outstanding open-source projects that gave us both tools and inspiration:

🗺️ Roadmap & Contribute

We want DeepTutor to keep iterating and improving — and ultimately to become a gift we give back to the open-source community. Our roadmap is updated continuously; vote on items there or propose new ones. If you’d like to contribute, see the Contributing Guide for branching strategy, coding standards, and how to get started.