Skat: Agent-Native Personalized Tutoring

Features Â· Get Started Â· Explore Â· TutorBot Â· CLI Â· Multi-User Â· Community

ðŸ¤� 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

Past releases (more than 2 weeks ago)

ðŸ“° News

âœ?Key Features

Work surfaces

Chat â€?Chat, Solve, Quiz, Research, and Visualize share one session, knowledge base, and citation history, so you can escalate mid-conversation without losing context.
Co-Writer â€?split-view Markdown workspace where any selection can be rewritten, expanded, or shortened, optionally grounded by your KB or the web. Drafts save straight to notebooks.
Book Engine â€?a multi-agent pipeline compiles your materials into interactive "living books" with 13 block types: quizzes, flash cards, timelines, concept graphs, an embedded GeoGebra viewer, animations, and more. Pages are KB-fingerprinted, so drift is detectable.

Your library

Knowledge Bases â€?versioned RAG-ready collections, end-to-end on LlamaIndex. Every (re-)index is tracked, comparable, and rollback-able.
Space â€?a personal review library bundling chat history, notebooks, question bank, and user-authored skills (SKILL.md) that switch Skat's persona.
Three-layer memory â€?append-only L1 traces, L2 per-surface curated facts with citations, and L3 cross-surface synthesis. An inspectable workbench and a memory graph let you audit why Skat knows what it knows.

Extensibility & control

Composable tools â€?RAG, web search, code execution, reasoning, brainstorming, paper search, GeoGebra analysis, and chat helpers (ask_user, web_fetch, write_note, list_notebook, github_query). MCP servers plug in alongside built-ins.
Personal TutorBots â€?persistent, autonomous tutors, each with its own workspace, soul, skills, and channels (Telegram, Discord, Slack, Matrix, Zulip, â€?. Built on nanobot.
Unified settings â€?one draft / Apply workbench for appearance, models, embeddings, search, capabilities, memory, MCP servers, and tools, with shared per-call cost tracking.
Agent-native CLI â€?every capability, KB, session, and TutorBot is one command away; rich output for humans, structured JSON for agents. Hand any tool-using LLM the SKILL.md and it can drive Skat on its own.
Optional authentication â€?off by default; opt in for multi-user deployments with bcrypt + JWT, an admin dashboard, and an optional PocketBase / OAuth sidecar.

ðŸš€ Get Started

Skat ships four installation paths. They all share one workspace layout: settings live in data/user/settings/ under the directory you launch from (or under SKAT_HOME / skat start --home if you set one explicitly). For the full app, the recommended flow is pick a workspace directory â†?install â†?skat init â†?skat start.

âœ?v1.4.2 is live. pip install -U skat picks up the latest stable. Pre-releases (when available) opt in with pip install --pre -U skat.

Option 1 â€?Install From PyPI

Full local Web app + CLI, no clone required. Needs Python 3.11+ and a Node.js 20+ runtime on PATH (the packaged Next.js standalone server is spawned by skat start).

mkdir -p my-skat && cd my-skat
pip install -U skat
skat init     # prompts for ports + LLM provider + optional embedding
skat start    # starts backend + frontend; keep the terminal open

skat init prompts for backend port (default 8001), frontend port (default 3782), LLM provider / base URL / API key / model, and an optional embedding provider for Knowledge Base / RAG.

After skat start, open the frontend URL printed in the terminal â€?by default http://127.0.0.1:3782. Press Ctrl+C in that terminal to stop both backend and frontend. Skipping skat init is fine for a quick trial; the app boots with default ports and empty model settings, configure them later in Settings â†?Models.

Option 2 â€?Install From Source

For development against a checkout. Use Python 3.11+ and Node.js 22 LTS to match CI and Docker.

git clone https://github.com/ldcr6/Skat.git
cd Skat

# Create a venv (macOS/Linux). Windows PowerShell:
#   py -3.11 -m venv .venv ; .\.venv\Scripts\Activate.ps1
python3 -m venv .venv && source .venv/bin/activate
python -m pip install --upgrade pip

# Install backend + frontend deps
python -m pip install -e .
( cd web && npm ci --legacy-peer-deps )

skat init
skat start

Source installs run Next.js in dev mode against the local web/ directory; everything else (config layout, ports, stop with Ctrl+C) matches Option 1.

Conda environment (instead of venv)

conda create -n skat python=3.11
conda activate skat
python -m pip install --upgrade pip

Optional install extras â€?dev / tutorbot / matrix / math-animator

pip install -e ".[dev]"             # tests/lint tools
pip install -e ".[tutorbot]"        # TutorBot engine + channel SDKs
pip install -e ".[matrix]"          # Matrix channel without E2EE/libolm
pip install -e ".[matrix-e2e]"      # Matrix E2EE; requires libolm
pip install -e ".[math-animator]"   # Manim addon; requires LaTeX/ffmpeg/system libs

Frontend dependency tweaks & dev-server troubleshooting

Changing frontend dependencies: run npm install --legacy-peer-deps to refresh web/package-lock.json, then commit both web/package.json and web/package-lock.json.

Stuck dev server: if skat start reports an existing frontend that isn't responding, stop the PID it prints. If no Next.js process is actually running, the lock files are stale â€?remove them and retry:

rm -f web/.next/dev/lock web/.next/lock
skat start

Option 3 â€?Docker

One container for the full Web app. Images on GitHub Container Registry:

ghcr.io/ldcr6/skat:latest â€?stable release
ghcr.io/ldcr6/skat:pre â€?pre-release, when available

docker run --rm --name skat \
  -p 127.0.0.1:3782:3782 \
  -p 127.0.0.1:8001:8001 \
  -v skat-data:/app/data \
  ghcr.io/ldcr6/skat:latest

âš ï¸� Map both 3782 and 8001. 3782 serves the web UI; 8001 is the FastAPI backend that your browser calls directly â€?there is no in-container proxy. Skip the 8001 mapping and the page still loads, but Settings shows "Backend unreachable" and stays unusable.

Open http://127.0.0.1:3782. The container creates /app/data/user/settings/*.json on first boot; configure model providers from the Web Settings page. Config, API keys, logs, workspace files, memory, and knowledge bases persist in the skat-data volume.

Different host ports: change the left side of each -p host:container mapping (e.g. -p 127.0.0.1:8088:3782). If you change container-side ports in /app/data/user/settings/system.json, restart and update the right side of each mapping to match.
Detached: add -d, then docker logs -f skat to follow, docker stop skat to stop, docker rm skat before reusing the name. The skat-data volume keeps your settings and workspace across restarts.

Remote Docker / reverse proxy: the Web UI runs in the browser, so the browser needs a backend URL it can reach. For remote servers, open Settings -> Network or edit data/user/settings/system.json:

{
  "next_public_api_base_external": "https://skat.example.com"
}

public_api_base is accepted as a compatibility alias and is normalized into next_public_api_base_external on save. CORS uses frontend origins, not API URLs. With auth disabled, Skat permits normal HTTP/HTTPS browser origins by default. With auth enabled, add exact frontend origins:

{
  "cors_origins": ["https://skat.example.com"]
}

Connecting to Ollama / LM Studio / llama.cpp / vLLM / Lemonade on the host

Inside Docker, localhost is the container itself, not your host machine. To reach a model service running on the host, use the host gateway (recommended):

docker run --rm --name skat \
  -p 127.0.0.1:3782:3782 -p 127.0.0.1:8001:8001 \
  --add-host=host.docker.internal:host-gateway \
  -v skat-data:/app/data \
  ghcr.io/ldcr6/skat:latest

Then in Settings â†?Models, point the provider Base URL at host.docker.internal:

Ollama LLM: http://host.docker.internal:11434/v1
Ollama embedding: http://host.docker.internal:11434/api/embed
LM Studio: http://host.docker.internal:1234/v1
llama.cpp: http://host.docker.internal:8080/v1
Lemonade: http://host.docker.internal:13305/api/v1

Docker Desktop (macOS/Windows) usually resolves host.docker.internal without --add-host. On Linux, the flag is the portable way to create that hostname on modern Docker Engine.

Linux alternative â€?host networking: add --network=host and drop the -p flags. The container shares the host network directly, so open http://127.0.0.1:3782 (or the frontend_port in system.json), and host services can be reached with normal localhost URLs like http://127.0.0.1:11434/v1. Note that host networking exposes container ports directly on the host and may conflict with existing services.

Option 4 â€?CLI Only

When you don't need the Web UI. The CLI-only package is installed from a source checkout, not from PyPI.

git clone https://github.com/ldcr6/Skat.git
cd Skat

# Create a venv (macOS/Linux). Windows PowerShell:
#   py -3.11 -m venv .venv-cli ; .\.venv-cli\Scripts\Activate.ps1
python3 -m venv .venv-cli && source .venv-cli/bin/activate
python -m pip install --upgrade pip

python -m pip install -e ./packaging/skat-cli
skat init --cli
skat chat

skat init --cli shares the same data/user/settings/ layout as the full app but skips the backend/frontend port prompts and defaults embeddings to off (choose Yes if you plan to use skat kb â€¦ or RAG tools). It still writes a complete runtime layout (system.json, auth.json, integrations.json, model_catalog.json, main.yaml, agents.yaml) and still prompts for the active LLM provider and model.

Common commands

skat chat                                          # interactive REPL
skat chat --capability deep_solve --tool rag --kb my-kb
skat run chat "Explain Fourier transform"
skat run deep_solve "Solve x^2 = 4" --tool rag --kb my-kb
skat kb create my-kb --doc textbook.pdf
skat memory show
skat config show

The local skat-cli install ships no Web assets or server dependencies. Keep the source checkout around â€?the editable install points to it. To add the Web app later, install the PyPI package (Option 1) and run skat init + skat start from the same workspace.

Configuration Reference

Config files under data/user/settings/ â€?JSON/YAML reference

Everything under data/user/settings/ is plain JSON/YAML. The Settings page in the browser is the recommended editor.

File	Purpose
`model_catalog.json`	LLM, embedding, and search provider profiles; API keys; active models
`system.json`	Backend/frontend ports, public API base, CORS, SSL verification, attachment directory
`auth.json`	Optional auth toggle, username, password hash, token/cookie settings
`integrations.json`	Optional PocketBase and sidecar integration settings
`interface.json`	UI language / theme / sidebar preferences
`main.yaml`	Runtime behavior defaults and path injection
`agents.yaml`	Capability/tool temperature and token settings

Project-root .env is not read as an application config file. For a minimal model setup, open Settings â†?Models, add an LLM profile (Base URL / API key / model name), and save. Add an embedding profile only if you plan to use Knowledge Base / RAG features.

ðŸ“– Explore Skat

The v1.4.0-beta refactor reorganises Skat around five core surfaces â€?Chat, Co-Writer, Book, Knowledge, Space â€?plus a three-layer Memory that sits underneath all of them and a unified Settings workbench that exposes every knob. Capabilities (Solve / Quiz / Research / Visualize) and tools (RAG, web, code, reason, brainstorm, paper search, ask_user, web_fetch, write_note, list_notebook, github_query) compose freely on top.

ðŸ’¬ Chat â€?Unified Intelligent Workspace

One thread, five modes, any tool. The capability picker lives in the composer; the same session, knowledge base, attachments, and references travel with you across modes â€?switch from a casual question into multi-agent solving, into a quiz, into a full research report, without losing context.

What each mode does & what it's built on

Mode	What it does	Built on
Chat	Flexible conversation with any tool; pick from RAG, web search, code execution, deep reasoning, brainstorming, paper search, GeoGebra analysis.	LlamaIndex-backed RAG + tool registry
Solve	Multi-step plan â†?investigate â†?solve â†?verify, with precise source citations.	Agentic engine (`deep_solve`)
Quiz	Auto-validated question generation grounded in your KB; spawns a follow-up chat composer per question.	Agentic engine (`deep_question`)
Research	Decomposes a topic into subtopics, dispatches parallel agents across RAG / web / arXiv, and produces a cited report with iterative append-mode revisions.	Rebuilt `pipeline.py` (~45% smaller, citations + iterative reporting preserved)
Visualize	Generate SVG diagrams, Chart.js charts, Mermaid graphs, interactive HTML pages, or Manim videos / storyboards â€?the analyzer picks the right `render_type`.	Visualize pipeline (Animator merged in)

New chat tools shipped with the refactor: ask_user (asks a structured clarifying question mid-turn), web_fetch (pulls a specific URL into context), write_note / list_notebook (saves and lists notebook records from the chat surface), and github_query (issue / PR / repo lookups). Tools stay decoupled from workflows â€?every mode lets you opt tools in or out per turn.

A session also carries a cumulative source inventory across turns, so citations from earlier RAG / web hits remain reusable later in the same conversation.

âœ�ï¸� Co-Writer â€?Multi-Document AI Writing Workspace

Co-Writer is a split-view Markdown workbench (raw editor on the left, live preview on the right) for notes, reports, tutorials, and AI-assisted drafts. Each document lives in its own workspace with autosave, downloadable Markdown, and one-click Save to Notebook.

Select any text and choose Rewrite, Expand, or Shorten â€?every action runs as a tracked agent edit that can optionally pull from a knowledge base or the web. Co-Writer renders standard Markdown / CommonMark / GFM (tables, code, math, flowcharts, sequence diagrams), supports a HTML tag escape hatch (<sub>, <sup>, <abbr>, <mark>), and ships a starter template tuned for Skat product docs and learning notes.

ðŸ“– Book Engine â€?Interactive "Living Books"

Give Skat a topic, point it at your knowledge base, and it produces a structured, interactive book â€?not a static export, but a living document you can read, quiz yourself on, and discuss in context.

Behind the scenes, a multi-agent pipeline handles the heavy lifting: proposing an outline, retrieving relevant sources from your KB, synthesising a chapter tree, planning each page, and compiling every block. You stay in control â€?review the proposal, reorder chapters, and chat alongside any page.

Pages are assembled from 13 block types â€?text, callout, quiz, flash cards, code, figure, deep dive, animation, interactive demo (now including a GeoGebra viewer), timeline, concept graph, section, and user note â€?each rendered with its own interactive component. Book pages are fingerprinted against their source KB; skat book health reports drift and skat book refresh-fingerprints clears stale pages when sources change.

ðŸ“š Knowledge Bases â€?RAG-Ready Document Libraries

A dedicated workspace for the document collections that power RAG. Each knowledge base has four tabs:

Files â€?Browse uploaded sources, preview PDFs inline, and see per-file size / status.
Add documents â€?Drop in PDFs, Office files (DOCX / XLSX / PPTX), Markdown, plain text, and a wide range of code / data file types. Documents are routed through the appropriate extractor automatically.
Index versions â€?Every (re-)index is a tracked version. Roll back to an earlier index, compare embedding models, or inspect chunking stats without losing the previous build.
Settings â€?Pick the embedding provider / model, chunking parameters, and reranker for the KB. Defaults are inherited from your global LLM and embedding profiles.

Indexing is built on LlamaIndex end-to-end (the previous dual-pipeline split was consolidated in the v1.4 refactor), with retry-safe re-index, embedding-mismatch detection, and resilient handling of corrupt persisted vectors.

ðŸŒ� Space â€?Your Personal Learning Library

Space is the read / review counterpart to the active surfaces. Where Chat / Co-Writer / Book are where you produce, Space is where everything you produce lives, searchable and replayable.

Chat History â€?Every conversation across every mode, with title-rename, delete, and resume; deleting individual turns is supported on every entry point.
Notebooks â€?Save outputs from Chat, Research, and Co-Writer into categorised, colour-coded notebooks; each record links back to the originating session and surface.
Question Bank â€?Every auto-generated quiz question, bookmarkable and @-mention-able in chat to reason over past performance.
Skills â€?User-authored SKILL.md files that define teaching personas (name, description, triggers, body). When active, a skill is injected into the chat system prompt â€?turning Skat into a Socratic tutor, a research assistant, or any role you design.

ðŸ§ Memory â€?Three-Layer Architecture

Skat's memory is now a three-layer pipeline with an inspectable workbench at /memory. The two-file v1 SUMMARY.md / PROFILE.md model is gone; everything is migrated into the new layout on first boot.

L1 / L2 / L3 â€?role and on-disk layout

Layer	Role	Storage
L1 Â· Workspace mirror (LIVE)	Append-only trace of every interaction, per surface, per day. The lossless record of what actually happened.	`trace/<surface>/<YYYY-MM-DD>.jsonl`
L2 Â· Per-surface summaries (CURATED)	Surface-specific facts extracted by the consolidator. Each fact carries footnote citations back to L1 traces. Supports per-doc Update / Audit / Dedup runs.	`L2/<surface>.md`
L3 Â· Cross-surface knowledge (SYNTHESIS)	Cross-surface synthesis: your `profile`, `recent` timeline, `scope` of knowledge, and `preferences`. Hedged claims, each backed by L2 evidence.	`L3/<recent\|profile\|scope\|preferences>.md`

Seven surfaces feed the pipeline: chat, notebook, quiz, kb, book, tutorbot, cowriter. The consolidator is LLM-driven and runs asynchronously (POST /memory/runs/start) â€?you can fire it from the workbench, watch L1 â†?L2 â†?L3 propagate, and edit any layer by hand.

The Memory Graph (/memory/graph) renders all three layers at once: L3 synthesis at the centre, L2 facts in the middle ring, L1 traces on the outside, grouped by surface. Hover any node for an inline preview; click to lock the highlight and trace the L3 â†?L2 â†?L1 references inward, so you can audit why Skat "knows" something about you.

âš™ï¸� Settings â€?Unified Control Center

The settings surface was unified in v1.4 and split by concern, with a draft / Apply model so changes are atomic and can be reverted before save:

Appearance â€?UI language and theme (Cream, Snow, Dark, Glass).
Status â€?Live health probe across LLM, embedding, search, and storage backends.
LLM, Embedding, Search â€?Provider catalog, base URLs, API keys, and active model selection. Active models are picked from the catalog so every surface stays in sync.
Capabilities â€?Per-capability tunables (chunking, LLM budget, dedup and reference policies, max iterations) for Chat, Solve, Quiz, Research, Visualize, and Co-Writer. Backed by a unified emit_capability_result envelope and a shared UsageTracker that surfaces per-call cost.
Memory â€?Toggle consolidator runs, configure cadence and budget, and jump into the memory workbench.
MCP servers â€?Register external Model Context Protocol servers; their tools are surfaced alongside built-in tools.
Tools â€?Inspect every built-in tool, its parameters, status (enabled / coming-soon), and i18n status copy.

A "Tour" launcher walks new users through the page, and every capability ships a canonical capabilities/prompts/{en,zh}/<name>.yaml so status messages stay consistent in both English and ä¸æ–‡.

ðŸ¦ž TutorBot â€?Persistent, Autonomous AI Tutors

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 Skat'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 Skat'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, Matrix, QQ, WhatsApp, 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.

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

âŒ¨ï¸� Skat CLI â€?Agent-Native Interface

Skat 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 Skat autonomously.

Example commands â€?one-shot run, REPL, KB lifecycle, JSON output, session resume

One-shot execution â€?Run any capability directly from the terminal:

skat run chat "Explain the Fourier transform" -t rag --kb textbook
skat run deep_solve "Prove that âˆ? is irrational" -t reason
skat run deep_question "Linear algebra" --config num_questions=5
skat run deep_research "Attention mechanisms in transformers"
skat run visualize "Draw the architecture of a transformer"

Interactive REPL â€?A persistent chat session with live mode switching:

skat 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:

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

Dual output mode â€?Rich rendering for humans, structured JSON for pipelines:

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

Session continuity â€?Resume any conversation right where you left off:

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

Full CLI command reference

Top-level

Command	Description
`skat run <capability> <message>`	Run any capability in a single turn (`chat`, `deep_solve`, `deep_question`, `deep_research`, `math_animator`, `visualize`)
`skat chat`	Interactive REPL with optional `--capability`, `--tool`, `--kb`, `--language`
`skat serve`	Start the Skat API server

skat bot

Command	Description
`skat bot list`	List all TutorBot instances
`skat bot create <id>`	Create and start a new bot (`--name`, `--persona`, `--model`)
`skat bot start <id>`	Start a bot
`skat bot stop <id>`	Stop a bot

skat kb

Command	Description
`skat kb list`	List all knowledge bases
`skat kb info <name>`	Show knowledge base details
`skat kb create <name>`	Create from documents (`--doc`, `--docs-dir`)
`skat kb add <name>`	Add documents incrementally
`skat kb search <name> <query>`	Search a knowledge base
`skat kb set-default <name>`	Set as default KB
`skat kb delete <name>`	Delete a knowledge base (`--force`)

skat memory

Command	Description
`skat memory show [file]`	View memory (`summary`, `profile`, or `all`)
`skat memory clear [file]`	Clear memory (`--force`)

skat session

Command	Description
`skat session list`	List sessions (`--limit`)
`skat session show <id>`	View session messages
`skat session open <id>`	Resume session in REPL
`skat session rename <id>`	Rename a session (`--title`)
`skat session delete <id>`	Delete a session

skat notebook

Command	Description
`skat notebook list`	List notebooks
`skat notebook create <name>`	Create a notebook (`--description`)
`skat notebook show <id>`	View notebook records
`skat notebook add-md <id> <path>`	Import markdown as record
`skat notebook replace-md <id> <rec> <path>`	Replace a markdown record
`skat notebook remove-record <id> <rec>`	Remove a record

skat book

Command	Description
`skat book list`	List all books in the workspace
`skat book health <book_id>`	Check KB drift and book health
`skat book refresh-fingerprints <book_id>`	Refresh KB fingerprints and clear stale pages

skat config / plugin / provider

Command	Description
`skat config show`	Print current configuration summary
`skat plugin list`	List registered tools and capabilities
`skat plugin info <name>`	Show tool or capability details
`skat provider login <provider>`	Provider auth (`openai-codex` OAuth login; `github-copilot` validates an existing Copilot auth session)

ðŸ‘¥ Multi-User â€?Shared Deployments with Per-User Workspaces

Flip on authentication and Skat turns into a multi-tenant deployment with per-user isolated workspaces and admin-curated resources. The first person to register becomes the admin and configures models, API keys, and knowledge bases on behalf of everyone else. Subsequent accounts are created by the admin (invite-only), each gets their own scoped chat history / memory / notebooks / knowledge bases, and they only see the LLMs, KBs, and skills the admin assigned to them.

Quick start (5 steps):

# 1. Enable auth in data/user/settings/auth.json:
#    {"enabled": true, "token_expire_hours": 24, "cookie_secure": false}
#    Use cookie_secure=true for HTTPS deployments where Web and API are cross-site.

# 2. Restart the web stack.
skat start

# 3. Open http://localhost:3782/register and create the first account.
#    The first registration is the only public one; that user becomes admin
#    and the /register endpoint is closed automatically afterward.

# 4. As admin, navigate to /admin/users â†?"Add user" to provision teammates.

# 5. For each user, click the slider icon â†?assign LLM profiles, knowledge
#    bases, and skills. Save. The user can now sign in and start working.

What the admin sees:

Full Settings page at /settings â€?manage LLM / embedding / search providers, API keys, model catalogs, and runtime "Apply".
User management at /admin/users â€?create, promote, demote, and delete accounts. The public /register endpoint is automatically closed once the first admin exists; further accounts go through POST /api/v1/auth/users (admin-only).
Grant editor â€?for each non-admin user, pick the model profiles, knowledge bases, and skills they may use. Grants carry logical IDs only; API keys never cross the grant boundary.
Audit trail â€?every grant change and assigned-resource access is appended to multi-user/_system/audit/usage.jsonl.

What ordinary users get:

Isolated workspace under multi-user/<uid>/ â€?their own chat history (chat_history.db), memory (SUMMARY.md / PROFILE.md), notebooks, and personal knowledge bases. Nothing is shared by default.
Read-only access to admin-assigned knowledge bases and skills, surfaced inline next to their own resources with an "Assigned by admin" badge.
Redacted Settings page â€?only theme, language, and a summary of granted models. API keys, base URLs, and provider endpoints are never returned for non-admin requests.
Scoped LLM â€?chat turns are routed through the admin-assigned model. If no LLM is granted, the turn is rejected up-front (no silent fallback to the admin's keys).

Workspace layout:

multi-user/
â”œâ”€â”€ _system/
â”?  â”œâ”€â”€ auth/users.json          # Hashed credentials, roles
â”?  â”œâ”€â”€ auth/auth_secret         # JWT signing secret (auto-generated)
â”?  â”œâ”€â”€ grants/<uid>.json        # Per-user resource grants (admin-managed)
â”?  â””â”€â”€ audit/usage.jsonl        # Audit trail
â””â”€â”€ <uid>/
    â”œâ”€â”€ user/
    â”?  â”œâ”€â”€ chat_history.db
    â”?  â”œâ”€â”€ settings/interface.json
    â”?  â””â”€â”€ workspace/{chat,co-writer,book,...}
    â”œâ”€â”€ memory/{SUMMARY.md,PROFILE.md}
    â””â”€â”€ knowledge_bases/...

Configuration reference:

Setting	Required	Description
`data/user/settings/auth.json: enabled`	Yes	Set to `true` to enable multi-user auth. Default `false` (single-user mode â€?admin paths everywhere).
`multi-user/_system/auth/auth_secret`	Recommended	JWT signing secret. Auto-generated on first authenticated boot if missing.
`data/user/settings/auth.json: token_expire_hours`	No	JWT lifetime; defaults to `24`.
`data/user/settings/auth.json: cookie_secure`	HTTPS / cross-site auth	Set `true` for HTTPS deployments that need `SameSite=None` cookies. Keep `false` for local HTTP.
`data/user/settings/auth.json: username/password_hash`	No	Optional headless single-user bootstrap credential. Leave blank when using browser registration.
`data/user/settings/system.json`	No	`skat start` derives frontend auth flags, public API base, and CORS origins from runtime settings.

âš ï¸� PocketBase mode (integrations.pocketbase_url set) is single-user only. The default PocketBase schema has no role field on users (every login resolves to role=user, no admin can be created), and sessions / messages / turns queries are not filtered by user_id. Multi-user deployments must keep integrations.pocketbase_url blank and use the default JSON/SQLite backend.

âš ï¸� Single-process recommendation. The first-user-becomes-admin promotion is protected by an in-process threading.Lock. Multi-worker deployments should provision the first admin offline (start with auth.json.enabled=false, register the admin via the bootstrap flow, then set auth.json.enabled=true) or back the user store with an external system.

ðŸŒ� Community & Ecosystem

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

Project	Role in Skat
nanobot	Ultra-lightweight agent engine powering TutorBot
LlamaIndex	RAG pipeline and document indexing backbone
ManimCat	AI-driven math animation generation for Math Animator

From the ldcr6 ecosystem:

âš?LightRAG	ðŸ¤– AutoAgent	ðŸ”¬ AI-Researcher	ðŸ§¬ nanobot
Simple & Fast RAG	Zero-Code Agent Framework	Automated Research	Ultra-Lightweight AI Agent

ðŸ¤� Contributing

We hope Skat becomes a gift for the community. ðŸŽ�

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

â?Star History

Skat

â?Star us Â· ðŸ�› Report a bug Â· ðŸ’¬ Discussions

Licensed under the Apache License 2.0.

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.github		.github
assets		assets
packaging/skat-cli		packaging/skat-cli
requirements		requirements
scripts		scripts
skat		skat
skat_cli		skat_cli
skat_web		skat_web
tests		tests
web		web
.dockerignore		.dockerignore
.gitattributes		.gitattributes
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.secrets.baseline		.secrets.baseline
AGENTS.md		AGENTS.md
CONTRIBUTING.md		CONTRIBUTING.md
Communication.md		Communication.md
Dockerfile		Dockerfile
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
SKILL.md		SKILL.md
SYSTEM_DESIGN.md		SYSTEM_DESIGN.md
_t_agents.py		_t_agents.py
_t_agents2.py		_t_agents2.py
_t_final.py		_t_final.py
_t_gh.py		_t_gh.py
_t_gh2.py		_t_gh2.py
_t_lp_gh.py		_t_lp_gh.py
_t_planner.py		_t_planner.py
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.ghcr.yml		docker-compose.ghcr.yml
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
start_backend.bat		start_backend.bat
start_frontend.bat		start_frontend.bat

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Skat: Agent-Native Personalized Tutoring

ðŸ“¦ Releases

ðŸ“° News

âœ?Key Features

ðŸš€ Get Started

Option 1 â€?Install From PyPI

Option 2 â€?Install From Source

Option 3 â€?Docker

Option 4 â€?CLI Only

Configuration Reference

ðŸ“– Explore Skat

ðŸ’¬ Chat â€?Unified Intelligent Workspace

âœ�ï¸� Co-Writer â€?Multi-Document AI Writing Workspace

ðŸ“– Book Engine â€?Interactive "Living Books"

ðŸ“š Knowledge Bases â€?RAG-Ready Document Libraries

ðŸŒ� Space â€?Your Personal Learning Library

ðŸ§ Memory â€?Three-Layer Architecture

âš™ï¸� Settings â€?Unified Control Center

ðŸ¦ž TutorBot â€?Persistent, Autonomous AI Tutors

âŒ¨ï¸� Skat CLI â€?Agent-Native Interface

ðŸ‘¥ Multi-User â€?Shared Deployments with Per-User Workspaces

ðŸŒ� Community & Ecosystem

ðŸ¤� Contributing

â?Star History

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Skat: Agent-Native Personalized Tutoring

ðŸ“¦ Releases

ðŸ“° News

âœ?Key Features

ðŸš€ Get Started

Option 1 â€?Install From PyPI

Option 2 â€?Install From Source

Option 3 â€?Docker

Option 4 â€?CLI Only

Configuration Reference

ðŸ“– Explore Skat

ðŸ’¬ Chat â€?Unified Intelligent Workspace

âœ�ï¸� Co-Writer â€?Multi-Document AI Writing Workspace

ðŸ“– Book Engine â€?Interactive "Living Books"

ðŸ“š Knowledge Bases â€?RAG-Ready Document Libraries

ðŸŒ� Space â€?Your Personal Learning Library

ðŸ§ Memory â€?Three-Layer Architecture

âš™ï¸� Settings â€?Unified Control Center

ðŸ¦ž TutorBot â€?Persistent, Autonomous AI Tutors

âŒ¨ï¸� Skat CLI â€?Agent-Native Interface

ðŸ‘¥ Multi-User â€?Shared Deployments with Per-User Workspaces

ðŸŒ� Community & Ecosystem

ðŸ¤� Contributing

â­?Star History

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

â?Star History

Packages