Klee

An AI-Powered Knowledge Management Desktop Application

License: MIT (https://img.shields.io/badge/License-MIT-yellow.svg) Electron (https://img.shields.io/badge/Electron-33.4.11-blue) React (https://img.shields.io/badge/React-18.3.1-blue) TypeScript (https://img.shields.io/badge/TypeScript-5.4.2-blue)

Features • Architecture • Getting Started • Documentation • Contributing

Overview

Klee is a modern desktop application that combines AI-powered chat, knowledge base management, and note-taking capabilities. It offers both Cloud Mode for seamless synchronization and Private Mode for complete offline functionality.

Key Highlights

• 🤖 AI-Powered Conversations: Integrated with OpenAI and local Ollama models
• 📚 Knowledge Base Management: Organize and search through your documents with RAG (Retrieval-Augmented Generation)
• 📝 Rich Note-Taking: Tiptap-based collaborative editor with Markdown support
• 🔒 Privacy-First: Complete offline mode with local AI and data storage
• ☁️ Cloud Sync: Optional cloud synchronization via Supabase
• 🎨 Modern UI: Built with React, TailwindCSS, and shadcn/ui components

Features

🌩️ Cloud Mode

• Authentication: Google OAuth and email/password via Supabase
• Data Sync: PostgreSQL database with real-time updates
• File Storage: Supabase Storage for documents and attachments
• Collaboration: Share knowledge bases and chat configurations

🔐 Private Mode

• Local AI: Powered by Ollama (embedded or system-installed)
• Local Storage: SQLite for structured data
• Vector Search: LanceDB for semantic search (planned)
• Complete Offline: No internet connection required

🛠️ Core Capabilities

• Multi-Model Support: Switch between cloud (OpenAI) and local (Ollama) models
• Knowledge Base: Upload documents, extract text, and query with RAG
• Note Management: Create, edit, and organize notes with a rich editor
• Marketplace: Browse and install community-shared agents and knowledge bases
• Search: Full-text and semantic search across all content

Architecture

Tech Stack

Frontend

• Framework: React 18.3 + TypeScript
• Desktop: Electron 33.4
• Routing: TanStack Router
• State Management: TanStack Query (React Query)
• UI Components: Radix UI + shadcn/ui
• Styling: TailwindCSS
• Editor: Tiptap (collaborative rich text)

Backend

• Framework: Hono (type-safe RPC)
• Database (Cloud): PostgreSQL via Drizzle ORM
• Database (Private): SQLite via Drizzle ORM
• Authentication: Supabase Auth
• Storage: Supabase Storage
• AI: AI SDK (Vercel) with OpenAI + Ollama providers

Infrastructure

• Deployment: AWS Elastic Beanstalk (backend)
• Vector Store: LanceDB (private mode, planned)
• Local AI: electron-ollama

Project Structure

klee/
├── client/                 # Electron + React app
│   ├── src/
│   │   ├── main/          # Electron main process
│   │   │   ├── ipc/       # IPC handlers
│   │   │   └── local/     # Private mode services
│   │   └── renderer/      # React app
│   │       ├── components/
│   │       ├── hooks/     # TanStack Query hooks
│   │       ├── routes/    # TanStack Router routes
│   │       └── lib/       # Utilities and clients
├── server/                 # Hono API server
│   ├── src/
│   │   ├── routes/        # API routes
│   │   └── db/            # Database schemas and queries
├── docs/                   # Documentation
└── specs/                  # Feature specifications

Getting Started

Prerequisites

• Node.js: 20.x or higher
• npm: 9.x or higher
• Docker: For local PostgreSQL (optional, cloud mode only)
• Ollama: For local AI (optional, private mode only)

Installation

1. Clone the repository

   git clone https://github.com/signerlabs/Klee.git
   cd klee
   

2. Configure Tiptap Pro (Required)

   Klee uses Tiptap Pro for advanced editor features. You'll need a Tiptap Pro account:

   # Copy the .npmrc template
   cp .npmrc.example .npmrc
   
   # Edit .npmrc and replace YOUR_TIPTAP_PRO_TOKEN_HERE with your actual token
   # Get your token from https://cloud.tiptap.dev/
   

3. Install dependencies

   npm install
   

4. Set up environment variables

   Copy .env.example files and configure:

   cp .env.example .env
   cp server/.env.example server/.env
   cp client/.env.example client/.env
   

   See Environment Configuration for details.

5. Set up Ollama for Private Mode (Optional)

   Private Mode requires Ollama binaries and models. You have two options:

   Option A: Use System Ollama (Recommended for Development)

   # Install Ollama on your system
   brew install ollama  # macOS
   # or download from https://ollama.ai/
   
   # Start Ollama service
   ollama serve
   

   Option B: Use Embedded Ollama (For Distribution)

   For bundled distributions, copy the offline Ollama resources:

   # The structure should be:
   # client/resources/ollama/
   # ├── binaries/v0.9.0/darwin/arm64/ollama
   # └── models/nomic-embed-text/...
   
   # You can obtain these from:
   # 1. Download from https://github.com/ollama/ollama/releases
   # 2. Export models: ollama export nomic-embed-text
   # 3. Follow client/resources/ollama/README.md for structure
   

   Note: The embedded Ollama binaries (~56MB) are not included in the repository. See client/resources/ollama/README.md for detailed setup instructions.

6. Start the development server

   npm run dev
   

   This will start:

   • Backend API server on http://localhost:3000
   • Electron app with hot reload

Environment Configuration

Root .env (for macOS builds)

# Apple Developer credentials (only needed for signed builds)
[email protected]
APPLE_APP_SPECIFIC_PASSWORD=your_app_specific_password
APPLE_TEAM_ID=YOUR_TEAM_ID
CODESIGN_IDENTITY="Developer ID Application: Your Company Name (TEAMID)"

server/.env

# OpenAI Configuration
OPENAI_API_KEY=your_openai_api_key

# Database (Cloud Mode)
DATABASE_URL=postgresql://user:pass@localhost:5432/klee

# Supabase Configuration
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

client/.env

# Supabase Configuration
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key

Database Setup (Cloud Mode)

1. Start PostgreSQL

   npm run db:up
   

2. Run migrations

   npm run db:push
   

3. Configure Supabase

   • Create a new project at supabase.com (https://supabase.com)
   • Copy your project URL and anon key to .env files
   • Configure OAuth providers in Supabase dashboard
   • Add redirect URL: klee://auth/callback

Development

Available Scripts

# Development
npm run dev              # Start both client and server in dev mode
npm run client:dev       # Start Electron app only
npm run server:dev       # Start API server only

# Building
npm run build            # Build for production
npm run client:build     # Build Electron app
npm run server:build     # Build API server
npm run build:mac        # Build signed macOS .dmg

# Database
npm run db:up            # Start PostgreSQL with Docker
npm run db:push          # Push schema changes
npm run db:generate      # Generate migrations
npm run db:migrate       # Run migrations

# Deployment
npm run server:deploy    # Deploy backend to AWS EB