In ancient Egyptian mythology, Thoth (𓁟) was the god of wisdom, writing, and knowledge — the divine scribe who recorded all human understanding. Like its namesake, this tool is built to gather, organize, and faithfully retrieve knowledge — while keeping everything under your control.

Full subsystem details live in docs/ARCHITECTURE.md.

Thoth stores durable knowledge as entities and typed relationships, not just chat snippets. It can save, search, link, explore, visualize, and export your knowledge graph as an Obsidian-compatible wiki vault, while background extraction and Dream Cycle refine duplicates, stale confidence, missing relationships, and actionable insights.

Designer Studio creates decks, documents, landing pages, app mockups, and storyboards with a sandboxed interactive runtime, critique-repair loop, editable exports, and shareable HTML. The same media layer supports image generation/editing with OpenAI, Google, and xAI, plus video generation through Google Veo and xAI Grok Imagine Video.

The LangGraph ReAct agent has 30 core tool modules plus auto-generated channel tools. It can browse in a visible Chromium window, use the shell, manage files, search the web, read documents, send email, manage calendar events, create charts, inspect system status, and call external MCP tools. Destructive actions are approval-gated, shell commands are safety-classified, the filesystem is sandboxed, and tools can be disabled individually.

Advanced workflows add schedules, webhook triggers, condition branches, approval steps, subtasks, notification-only runs, concurrency groups, per-workflow model/tool/skill overrides, and background safety modes. The Workflow Console shows running jobs, approvals, recent history, and insights without leaving chat.

Thoth ships as a desktop app for Windows and macOS with one-click installers, tray integration, setup wizard, voice input, local Kokoro TTS, desktop notifications, and 5 bundled messaging channels: Telegram, WhatsApp, Discord, Slack, and SMS. Channels share media handling, streaming, approvals, health checks, and optional tunnel support.

Plugins add tools and skills through a sandboxed marketplace; MCP servers add external tools with per-server and per-tool review; Claude Code Delegation can coordinate Claude Code CLI as an approval-gated external coding worker; the migration wizard imports selected Hermes/OpenClaw data with backups and redacted reports. Core and plugin API keys use the OS credential store when available, with metadata-only files in Thoth's data directory.

Detailed architecture and subsystem reference →

OpenClaw is a popular open-source personal AI assistant. It's a powerful multi-channel gateway built for developers comfortable in the terminal. Here's how the two compare:

In short: OpenClaw is a powerful gateway for developers who want their AI assistant on every messaging platform. Thoth is built for people who want personal AI sovereignty — local-first intelligence, a structured knowledge graph that grows with you, one-click setup, and tools that work without touching a terminal. Different philosophies, both open source.

For comparisons with ChatGPT and other cloud assistants, see docs/ARCHITECTURE.md.

Thoth's agent has access to 30 core tool modules. Many of them expose multiple operations, and running messaging channels add extra send/photo/document tools automatically. Tools can be enabled or disabled from the Settings panel.

• Destructive operations require confirmation: workspace_file_delete, workspace_move_file, run_command (moderate-risk), send_gmail_message, move_calendar_event, delete_calendar_event, delete_memory, tracker_delete, task_delete
• Filesystem is sandboxed: only the configured workspace folder is accessible (defaults to ~/Documents/Thoth, auto-created on first use)
• Shell commands are safety-classified: safe (auto), moderate (confirm), blocked (rejected); high-risk commands like shutdown, reboot, mkfs are blocked outright; moderate commands in background tasks require per-task command prefix allowlists
• Browser tabs are isolated per thread: each chat or background task gets its own browser tab; tabs are cleaned up on task completion or thread deletion
• Background task permissions are configurable per-task: shell command prefixes and email recipients can be allowlisted in the task editor
• Gmail/Calendar operations are tiered: read, compose/write, and destructive tiers can be toggled independently
• MCP tools are opt-in and isolated: imported servers stay disabled until tested, external tools are namespaced, destructive MCP tools require approval, and broken MCP servers degrade to diagnostics instead of startup failure
• Prompt-injection defence — 5-layer scanning protects against injection attacks in tool outputs and user inputs: instruction override detection, role impersonation, data exfiltration, encoding evasion, and social engineering patterns
• Tools can be individually disabled from Settings to reduce model decision complexity

┌──────────────────────────────────────────────────────────────────────┐
│                    NiceGUI Frontend (app.py + ui/ package)              │
│  ┌────────────┐  ┌──────────────────────┐  ┌───────────────────┐   │
│  │  Sidebar   │  │   Chat Interface     │  │   Settings Dialog │   │
│  │  Threads   │  │   Streaming Tokens   │  │   14 Tabs         │   │
│  │  Controls  │  │   Tool Status        │  │   Tool Config     │   │
│  │ Knowledge  │  │ Knowledge Graph View │  │ Provider Settings │   │
│  │ Approvals  │  │   Approval Gates     │  │                   │   │
│  └────────────┘  └──────────────────────┘  └───────────────────┘   │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │  Status Monitor — Avatar · 17 Health Pills · Diagnosis Btn  │   │
│  └──────────────────────────────────────────────────────────────┘   │
└──────────────────────────┬───────────────────────────────────────────┘
                           │
                           ▼
┌──────────────────────────────────────────────────────────────────────┐
│               LangGraph ReAct Agent (agent.py)                       │
│                                                                      │
│   create_react_agent() with pre-model message trimming              │
│   System prompt with TOOL USE, MEMORY, SELF-KNOWLEDGE, and CITATION │
│   guidelines                                                        │
│   Interrupt mechanism for destructive action confirmation            │
│   Graph-enhanced auto-recall (semantic + 1-hop expansion)           │
│   Per-thread model override (local or cloud)                        │
│                                                                      │
│   30 core tool modules + plugin tools + external MCP tools +        │
│   auto-generated channel tools                                      │
└───────┬──────────┬──────────┬──────────┬──────────┬─────────────────┘
        │          │          │          │          │
        ▼          ▼          ▼          ▼          ▼
  ┌──────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
  │   LLMs   │ │Knowledge│ │ SQLite │ │ FAISS  │ │External│
  │  Ollama  │ │ Graph  │ │Threads │ │ Vector │ │  APIs  │
   │+Providers│ │(SQLite+│ │(local) │ │ Store  │ │(opt-in)│
  │ (opt-in) │ │NetworkX)│ │        │ │        │ │        │
  └──────────┘ └────────┘ └────────┘ └────────┘ └────────┘

📖 Module descriptions, data storage layout, and full system internals → docs/ARCHITECTURE.md

Note: The default local model (qwen3:14b, ~9 GB) runs well on CPU with 16 GB RAM, but a GPU makes responses significantly faster. Smaller models like qwen3:8b (~5 GB) work on 8 GB RAM machines.

You still need an API key from OpenAI, Anthropic, Google AI, xAI, or OpenRouter, or an in-app ChatGPT sign-in for ChatGPT / Codex. API providers are billed per-token by the upstream provider; ChatGPT / Codex uses your ChatGPT subscription access.

1. Download the latest Windows installer (.exe)
2. Run the installer — it installs Python, Ollama, and all dependencies automatically
3. Launch Thoth from the Start Menu or Desktop shortcut

1. Download the latest macOS DMG
2. Open the DMG and drag Thoth.app into the Applications folder
3. Launch Thoth from Applications or Launchpad
   • First run may prompt "Thoth is an app downloaded from the internet" → click Open
   • First run installs Homebrew (if needed), Python, Ollama, and all dependencies automatically
   • Subsequent launches skip installation and start in ~3 seconds

Works on Apple Silicon (M1/M2/M3/M4) and Intel Macs (macOS 12+). No terminal, no manual setup — just double-click and go.

Using provider models only? The installer still sets up Ollama by default, but you can skip model downloads. On first launch, choose the Providers setup path, enter your API key, and start chatting — no GPU required.

Prefer a manual install? A few commands from source:

1. Install Ollama (required for local models — skip if using provider models only)

2. Clone the repository

   git clone https://github.com/siddsachar/Thoth.git
   cd Thoth

3. Create and activate a virtual environment

   python -m venv .venv
   # Windows
   .venv\Scripts\activate
   # macOS / Linux
   source .venv/bin/activate

4. Install dependencies

   pip install -r requirements.txt

5. Start Ollama (if using local models)

6. Launch Thoth

   This starts the system tray icon and opens the app at http://localhost:8080.

   Alternatively, run directly without the tray:

First launch: A setup wizard lets you choose between Local (Ollama) and Providers (API key) setup paths. For local, the default brain model (qwen3:14b, ~9 GB) is recommended. For Providers, enter your API key (OpenAI, Anthropic, Google AI, xAI, or OpenRouter), pick a default model, and seed Quick Choices for everyday pickers. ChatGPT / Codex sign-in is available after launch in Settings → Providers.

Most tools work without any API keys. For provider models and enhanced functionality:

Configure provider keys and subscription accounts in Settings → Providers. Keys and in-app ChatGPT / Codex tokens are stored in your OS credential store (Windows Credential Manager, macOS Keychain, or Linux Secret Service/KWallet where available); ~/.thoth/api_keys.json and ~/.thoth/providers.json keep only local metadata such as saved-state, provider status, Quick Choices, and masked fingerprints. External Codex CLI login files are metadata/reference only: Thoth can show that a CLI login exists, but direct Codex runtime requires the in-app ChatGPT sign-in and does not copy runnable tokens from ~/.codex/auth.json.

ChatGPT / Codex uses ChatGPT's subscription/internal Codex backend rather than the public OpenAI API. That backend may change upstream, including endpoint behavior, catalog shape, auth requirements, rate limits, and model availability.

Configure channel keys in ⚙️ Settings → 📡 Channels and ⚙️ Settings → 🔗 Accounts tabs. Saved keys use the same local OS credential store when available.

For Gmail and Google Calendar, you'll need a Google Cloud OAuth credentials.json — setup instructions are provided in the respective Settings tabs.

1. Launch Thoth and wait for the default model to download (first time only)
2. Click "＋ New conversation" in the sidebar
3. Ask anything — the agent will automatically choose which tools to use:
   • "What's the weather in Tokyo?" → uses Weather tool
   • "Search for recent papers on transformer architectures" → uses Arxiv
   • "Remember that my mom's birthday is March 15" → saves to Memory
   • "Read the file report.pdf in my workspace" → uses Filesystem
   • "Run git status on my project" → uses Shell (safe, auto-executes)
   • "Install pandas with pip" → uses Shell (moderate, asks for approval)
   • "What's on my screen right now?" → uses Vision (screen capture)
   • "I took my Lexapro" → asks to log, then saves to Tracker
   • "Show my headache trends this month" → uses Tracker + Chart
   • "Remind me to call the dentist tomorrow at 9am" → uses Tasks with scheduling
   • "Create a 6-slide pitch deck for my startup" → uses Designer
   • "What did I ask about taxes last week?" → uses Conversation Search
4. Open ⚙️ Settings to configure models, enable/disable tools, and set up integrations

1. Launch Thoth → on the setup wizard, choose Providers
2. Enter your API key (OpenAI, Anthropic, Google AI, xAI, or OpenRouter) → Thoth validates and fetches available models
3. Pick a default model and add the models you actually use to Quick Choices — no downloads, no GPU needed
4. Optional: open Settings → Providers to sign in to ChatGPT / Codex for subscription-backed Codex models
5. Switch models per conversation anytime from the chat header dropdown; raw provider catalogs and pinning live in Settings → Models

Local models (default): All LLM inference runs on your machine via Ollama. Documents, memories, and conversations stored locally in ~/.thoth/. External network calls only when using online tools (web search, Gmail, Calendar) — each individually disableable. No telemetry, no tracking.

Provider models (opt-in): The current conversation plus model-visible tool context and tool results are sent to the selected LLM provider (OpenAI, Anthropic, Google AI, xAI, OpenRouter, or ChatGPT / Codex). Memories, knowledge graph, documents, files, and other conversations never leave your machine unless you explicitly include them in the active conversation or expose them through a tool result. API-key providers connect directly to the provider; ChatGPT / Codex uses your in-app ChatGPT sign-in and ChatGPT subscription/internal Codex backend. Thoth has no servers and no middleman.

Always: Core and plugin API keys are stored locally in your OS credential store when available, with only masked metadata in Thoth's data folder. No Thoth account required; no sign-up; no server to phone home to. Tools can be individually disabled to control what the agent can access.

Contributions are welcome. Start with CONTRIBUTING.md for the local setup, branch naming, commit format, PR process, and test expectations.

Useful project docs:

All changes should go through a pull request. main is intended to stay releasable.

Apache 2.0 — see LICENSE for details.

Built with NiceGUI, LangGraph, LangChain, Ollama, FAISS, Kokoro TTS, faster-whisper, HuggingFace, and tiktoken.