"DeepTutor: Agent-Native Personalized Learning Assistant"

DeepTutor: Agent-Native Personalized Tutoring

Features · Get Started · Explore · TutorBot · CLI · Community

🇨🇳 中文 · 🇯🇵 日本語 · 🇪🇸 Español · 🇫🇷 Français · 🇸🇦 العربية · 🇷🇺 Русский · 🇮🇳 हिन्दी · 🇵🇹 Português

[2026.4.4] Long time no see! ✨ DeepTutor v1.0.0 is finally here — an agent-native evolution featuring a ground-up architecture rewrite, TutorBot, and flexible mode switching under the Apache-2.0 license. A new chapter begins, and our story continues!

[2026.2.6] 🚀 We've reached 10k stars in just 39 days! A huge thank you to our incredible community for the support!

[2026.1.1] Happy New Year! Join our Discord, WeChat, or Discussions — let's shape the future of DeepTutor together!

[2025.12.29] DeepTutor is officially released!

[2026.4.7] v1.0.0-beta.2 — Runtime cache invalidation for hot settings reload, MinerU nested output support, mimic WebSocket fix, Python 3.11+ minimum, and CI improvements.

[2026.4.4] v1.0.0-beta.1 — Agent-native architecture rewrite (DeepTutor 2.0) with two-layer plugin model (Tools + Capabilities), CLI & SDK entry points, TutorBot multi-channel bot agent, Co-Writer, Guided Learning, and persistent memory.

• Unified Chat Workspace — Five modes, one thread. Chat, Deep Solve, Quiz Generation, Deep Research, and Math Animator share the same context — start a conversation, escalate to multi-agent problem solving, generate quizzes, then deep-dive into research, all without losing a single message.
• Personal TutorBots — Not chatbots — autonomous tutors. Each TutorBot lives in its own workspace with its own memory, personality, and skill set. They set reminders, learn new abilities, and evolve as you grow. Powered by nanobot.
• AI Co-Writer — A Markdown editor where AI is a first-class collaborator. Select text, rewrite, expand, or summarize — drawing from your knowledge base and the web. Every piece feeds back into your learning ecosystem.
• Guided Learning — Turn your materials into structured, visual learning journeys. DeepTutor designs multi-step plans, generates interactive pages for each knowledge point, and lets you discuss alongside each step.
• Knowledge Hub — Upload PDFs, Markdown, and text files to build RAG-ready knowledge bases. Organize insights across sessions in color-coded notebooks. Your documents don't just sit there — they actively power every conversation.
• Persistent Memory — DeepTutor builds a living profile of you: what you've studied, how you learn, and where you're heading. Shared across all features and TutorBots, it gets sharper with every interaction.
• Agent-Native CLI — Every capability, knowledge base, session, and TutorBot is one command away. Rich terminal output for humans, structured JSON for AI agents and pipelines. Hand DeepTutor a SKILL.md and your agents can operate it autonomously.

A single interactive script that walks you through everything: dependency installation, environment configuration, live connection testing, and launch. No manual .env editing needed.

git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor

# Create a Python environment
conda create -n deeptutor python=3.11 && conda activate deeptutor
# Or: python -m venv .venv && source .venv/bin/activate

# Launch the guided tour
python scripts/start_tour.py

The tour asks how you'd like to use DeepTutor:

• Web mode (recommended) — Picks a dependency profile, installs everything (pip + npm), then spins up a temporary server and opens the Settings page in your browser. A four-step guided tour walks you through LLM, Embedding, and Search provider setup with live connection testing. Once complete, DeepTutor restarts automatically with your configuration.
• CLI mode — A fully interactive terminal flow: choose a dependency profile, install dependencies, configure providers, verify connections, and apply — all without leaving the shell.

Either way, you end up with a running DeepTutor at http://localhost:3782.

If you prefer full control, install and configure everything yourself.

1. Install dependencies

git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor

conda create -n deeptutor python=3.11 && conda activate deeptutor
pip install -e ".[server]"

# Frontend
cd web && npm install && cd ..

2. Configure environment

cp .env.example .env

Edit .env and fill in at least the required fields:

# LLM (Required)
LLM_BINDING=openai
LLM_MODEL=gpt-4o-mini
LLM_API_KEY=sk-xxx
LLM_HOST=https://api.openai.com/v1

# Embedding (Required for Knowledge Base)
EMBEDDING_BINDING=openai
EMBEDDING_MODEL=text-embedding-3-large
EMBEDDING_API_KEY=sk-xxx
EMBEDDING_HOST=https://api.openai.com/v1
EMBEDDING_DIMENSION=3072

3. Start services

# Backend (FastAPI)
python -m deeptutor.api.run_server

# Frontend (Next.js) — in a separate terminal
cd web && npm run dev -- -p 3782

Open http://localhost:3782 and you're ready to go.

Docker wraps the backend and frontend into a single container — no local Python or Node.js required. Two options depending on your preference:

1. Configure environment variables (required for both options)

git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor
cp .env.example .env

Edit .env and fill in at least the required fields (same as Option B above).

2a. Pull official image (recommended)

Official images are published to GitHub Container Registry on every release, built for linux/amd64 and linux/arm64.

docker compose -f docker-compose.ghcr.yml up -d

To pin a specific version, edit the image tag in docker-compose.ghcr.yml:

image: ghcr.io/hkuds/deeptutor:1.0.0  # or :latest

2b. Build from source

docker compose up -d

This builds the image locally from Dockerfile and starts the container.

3. Verify & manage

Open http://localhost:3782 once the container is healthy.

docker compose logs -f   # tail logs
docker compose down       # stop and remove container

# Set to the public URL where the backend is reachable
NEXT_PUBLIC_API_BASE_EXTERNAL=https://your-server.com:8001

docker compose -f docker-compose.yml -f docker-compose.dev.yml up

BACKEND_PORT=9001
FRONTEND_PORT=4000

docker compose up -d     # or docker compose -f docker-compose.ghcr.yml up -d

If you just want the CLI without the web frontend:

pip install -e ".[cli]"
deeptutor chat                                   # Interactive REPL
deeptutor run chat "Explain Fourier transform"   # One-shot capability
deeptutor run deep_solve "Solve x^2 = 4"         # Multi-agent problem solving
deeptutor kb create my-kb --doc textbook.pdf     # Build a knowledge base

See DeepTutor CLI for the full feature guide and command reference.

Five distinct modes coexist in a single workspace, bound by a unified context management system. Conversation history, knowledge bases, and references persist across modes — switch between them freely within the same topic, whenever the moment calls for it.

Tools are decoupled from workflows — in every mode, you decide which tools to enable, how many to use, or whether to use any at all. The workflow orchestrates the reasoning; the tools are yours to compose.

Start with a quick chat question, escalate to Deep Solve when it gets hard, generate quiz questions to test yourself, then launch a Deep Research to go deeper — all in one continuous thread.

Co-Writer brings the intelligence of Chat directly into a writing surface. It is a full-featured Markdown editor where AI is a first-class collaborator — not a sidebar, not an afterthought.

Select any text and choose Rewrite, Expand, or Shorten — optionally drawing context from your knowledge base or the web. The editing flow is non-destructive with full undo/redo, and every piece you write can be saved straight to your notebooks, feeding back into your learning ecosystem.

Guided Learning turns your personal materials into structured, multi-step learning journeys. Provide a topic, optionally link notebook records, and DeepTutor will:

1. Design a learning plan — Identify 3–5 progressive knowledge points from your materials.
2. Generate interactive pages — Each point becomes a rich visual HTML page with explanations, diagrams, and examples.
3. Enable contextual Q&A — Chat alongside each step for deeper exploration.
4. Summarize your progress — Upon completion, receive a learning summary of everything you've covered.

Sessions are persistent — pause, resume, or revisit any step at any time.

Knowledge is where you build and manage the document collections that power everything else in DeepTutor.

• Knowledge Bases — Upload PDF, TXT, or Markdown files to create searchable, RAG-ready collections. Add documents incrementally as your library grows.
• Notebooks — Organize learning records across sessions. Save insights from Chat, Guided Learning, Co-Writer, or Deep Research into categorized, color-coded notebooks.

Your knowledge base is not passive storage — it actively participates in every conversation, every research session, and every learning path you create.

DeepTutor maintains a persistent, evolving understanding of you through two complementary dimensions:

• Summary — A running digest of your learning progress: what you've studied, which topics you've explored, and how your understanding has developed.
• Profile — Your learner identity: preferences, knowledge level, goals, and communication style — automatically refined through every interaction.

Memory is shared across all features and all your TutorBots. The more you use DeepTutor, the more personalized and effective it becomes.

TutorBot is not a chatbot — it is a persistent, multi-instance agent built on nanobot. Each TutorBot runs its own agent loop with independent workspace, memory, and personality. Create a Socratic math tutor, a patient writing coach, and a rigorous research advisor — all running simultaneously, each evolving with you.

• Soul Templates — Define your tutor's personality, tone, and teaching philosophy through editable Soul files. Choose from built-in archetypes (Socratic, encouraging, rigorous) or craft your own — the soul shapes every response.
• Independent Workspace — Each bot has its own directory with separate memory, sessions, skills, and configuration — fully isolated yet able to access DeepTutor's shared knowledge layer.
• Proactive Heartbeat — Bots don't just respond — they initiate. The built-in Heartbeat system enables recurring study check-ins, review reminders, and scheduled tasks. Your tutor shows up even when you don't.
• Full Tool Access — Every bot reaches into DeepTutor's complete toolkit: RAG retrieval, code execution, web search, academic paper search, deep reasoning, and brainstorming.
• Skill Learning — Teach your bot new abilities by adding skill files to its workspace. As your needs evolve, so does your tutor's capability.
• Multi-Channel Presence — Connect bots to Telegram, Discord, Slack, Feishu, WeChat Work, DingTalk, Email, and more. Your tutor meets you wherever you are.
• Team & Sub-Agents — Spawn background sub-agents or orchestrate multi-agent teams within a single bot for complex, long-running tasks.

deeptutor bot create math-tutor --persona "Socratic math teacher who uses probing questions"
deeptutor bot create writing-coach --persona "Patient, detail-oriented writing mentor"
deeptutor bot list                  # See all your active tutors

DeepTutor is fully CLI-native. Every capability, knowledge base, session, memory, and TutorBot is one command away — no browser required. The CLI serves both humans (with rich terminal rendering) and AI agents (with structured JSON output).

Hand the SKILL.md at the project root to any tool-using agent (nanobot, or any LLM with tool access), and it can configure and operate DeepTutor autonomously.

One-shot execution — Run any capability directly from the terminal:

deeptutor run chat "Explain the Fourier transform" -t rag --kb textbook
deeptutor run deep_solve "Prove that √2 is irrational" -t reason
deeptutor run deep_question "Linear algebra" --config num_questions=5
deeptutor run deep_research "Attention mechanisms in transformers"

Interactive REPL — A persistent chat session with live mode switching:

deeptutor chat --capability deep_solve --kb my-kb
# Inside the REPL: /cap, /tool, /kb, /history, /notebook, /config to switch on the fly

Knowledge base lifecycle — Build, query, and manage RAG-ready collections entirely from the terminal:

deeptutor kb create my-kb --doc textbook.pdf       # Create from document
deeptutor kb add my-kb --docs-dir ./papers/         # Add a folder of papers
deeptutor kb search my-kb "gradient descent"        # Search directly
deeptutor kb set-default my-kb                      # Set as default for all commands

Dual output mode — Rich rendering for humans, structured JSON for pipelines:

deeptutor run chat "Summarize chapter 3" -f rich    # Colored, formatted output
deeptutor run chat "Summarize chapter 3" -f json    # Line-delimited JSON events

Session continuity — Resume any conversation right where you left off:

deeptutor session list                              # List all sessions
deeptutor session open <id>                         # Resume in REPL

If you find DeepTutor useful, give us a star — it helps us keep going!

DeepTutor stands on the shoulders of outstanding open-source projects:

From the HKUDS ecosystem:

We hope DeepTutor becomes a gift for the community. 🎁

See CONTRIBUTING.md for guidelines on setting up your development environment, code standards, and pull request workflow.