WAIT — Single-maintainer risk — review before adopting

• Last commit 6w ago
• 13 active contributors
• AGPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 85% of recent commits
• ⚠ AGPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Khoj is a self-hostable personal AI second brain that lets you chat with local or cloud LLMs (GPT, Claude, Llama, Qwen, Mistral) and retrieve answers from your documents and the web via semantic search. It spans multiple interfaces (web, Obsidian plugin, Emacs, desktop, mobile) and includes agent creation, automation scheduling, and multi-source RAG with support for PDFs, Markdown, Org-mode, Notion, and images. Monorepo with Python backend (inferred from ~1.6M lines Python) and TypeScript/React frontend (~1.2M lines TypeScript). Multiple client implementations: .devcontainer/ for development, .github/workflows/ for CI/CD, documentation/ folder uses Docusaurus, Dockerfile + docker-compose.yml for containerization. Separate build pipelines for Emacs Lisp plugin (build_khoj_el.yml), desktop app (desktop.yml), and telemetry server.

Individual knowledge workers, researchers, and organizations who want a self-hosted alternative to proprietary AI assistants; developers integrating local LLMs into their workflows; teams needing document-based RAG without vendor lock-in; users of Emacs, Obsidian, or desktop environments seeking AI augmentation.

Production-ready with active development. The codebase shows ~2.8M lines across Python/TypeScript, extensive CI/CD via GitHub Actions (test.yml, dockerize.yml, pypi.yml workflows), Docker support, PyPI distribution, and a Discord community of 1000+ members. Recent activity evident from release workflows and desktop/browser client builds.

Moderate risk: monorepo spanning Python backend + TypeScript frontend requires coordinating dependency updates across ecosystems. No visible lock files in file list suggests potential reproducibility issues. Reliance on external LLM APIs (OpenAI, Anthropic) for cloud features. Self-hosting requirement means users inherit infrastructure ops burden. Telemetry server presence (dockerize_telemetry_server.yml) may face privacy concerns despite open-source claims.

Active work on agents feature (agents_page_full.png in docs), automation/email integration (khoj_automation_email.png), multi-client support (khoj_chat_on_emacs.png, khoj_chat_on_obsidian.png, khoj_chat_on_web.png), and performance benchmarking (run_evals.yml workflow, blog post on retrieval/reasoning benchmarks). Desktop and web deployment pipelines are actively maintained.

git clone https://github.com/khoj-ai/khoj.git
cd khoj
# For Python backend: pip install -e .
# For TypeScript frontend: npm install (if package.json exists in project root)
# Using Docker: docker-compose up

See docs at https://docs.khoj.dev/get-started/setup for detailed instructions.

Daily commands: Development: npm start (documentation folder runs Docusaurus on port 3000). Backend likely uses python manage.py runserver or similar (see documentation/README.md and root README for full setup). Docker: docker-compose up. Desktop/Emacs: separate build workflows (desktop.yml, build_khoj_el.yml) produce platform-specific binaries.

• README.md — Entry point describing Khoj as an AI second brain with links to docs, web app, and community; essential for understanding project scope and architecture.
• documentation/docs/features/all-features.md — Comprehensive feature overview covering chat, agents, automations, and integrations; required reading for understanding what Khoj can do.
• .github/workflows/test.yml — Defines the CI/CD pipeline and test execution strategy; critical for understanding how contributions are validated.
• docker-compose.yml — Orchestrates multi-service deployment (web, API, databases); essential for understanding runtime architecture and dependencies.
• Dockerfile — Primary container image definition for the main Khoj application; required for understanding production deployment.
• .devcontainer/devcontainer.json — Development environment configuration with required extensions and startup scripts; critical for onboarding new contributors.
• documentation/docs/contributing/development.mdx — Development setup guide and contribution guidelines; mandatory reading before submitting PRs.

Add a new integration data source (e.g., new cloud storage provider)

1. Create integration documentation in the data-sources folder (documentation/docs/data-sources/your_integration.md)
2. Add the integration to the feature matrix in all-features.md (documentation/docs/features/all-features.md)
3. Update the datasources SVG diagram if adding a new category (documentation/assets/img/khoj_datasources.svg)
4. Add tests to the test workflow to validate the integration (.github/workflows/test.yml)

Add a new client (e.g., Slack bot, mobile app)

1. Create client documentation file (documentation/docs/clients/your_client.md)
2. Add to clients category index (documentation/docs/clients/_category_.json)
3. Update the khoj_clients.svg diagram with new client type (documentation/assets/img/khoj_clients.svg)
4. Add client build workflow if platform-specific (e.g., iOS build) (.github/workflows/your_client_build.yml)

Add a new advanced deployment guide (e.g., Kubernetes, AWS)

1. Create deployment guide in advanced folder (documentation/docs/advanced/your_deployment.md)
2. Document environment variables and configuration options (documentation/docs/advanced/your_deployment.md)
3. Add Dockerfile variant if needed (existing: computer.Dockerfile, main Dockerfile) (computer.Dockerfile)
4. Update docker-compose.yml with new service definitions if applicable (docker-compose.yml)

Set up development environment for first-time contributor

1. Read the main README and features overview to understand scope (README.md)
2. Follow development setup instructions (documentation/docs/contributing/development.mdx)
3. Open project in VS Code with devcontainer for consistent setup (.devcontainer/devcontainer.json)
4. Review pre-commit hooks to understand code quality requirements (.pre-commit-config.yaml)
5. Check test workflow to understand CI validation (.github/workflows/test.yml)

• Docker + Docker Compose — Ensures consistent deployment across development, testing, and production environments; enables multi-service orchestration (web, API, databases, optional services like telemetry).
• Docusaurus 3.9.2 — Static site generation for documentation with React components (MDX); fast, SEO-friendly, and integrates with GitHub Pages for automated deployment.
• GitHub Actions — Native CI/CD automation for testing on every commit, building Docker images, publishing to PyPI and registries, and deploying documentation.
• Multiple LLM support (OpenAI, Claude, Ollama, LMStudio, Vertex AI) — Enables self-hosting and flexibility; users can choose their LLM provider (paid SaaS or open-source).
• Vector embeddings + semantic search — Core to the RAG (Retrieval-Augmented Generation) architecture; enables search across diverse data sources by semantic similarity rather than keyword matching.

• Self-hosted architecture with multi-provider LLM support

  • Why: Maximizes flexibility and reduces vendor lock-in; users can deploy on-premise or choose their LLM.
  • Consequence: Increased operational complexity for self-hosted deployments; requires users to manage dependencies, secrets, and infrastructure.

• Support for many data source integrations (GitHub, Notion, local files, web, etc.)

  • Why: Broad appeal to diverse user workflows (developers, researchers, knowledge workers).
  • Consequence: Requires maintaining multiple integration libraries and keeping them up-to-date with API changes; increases surface area for bugs.

• Build documentation as static site (Docusaurus) rather than embedded wiki

  • Why: Decouples documentation from application; enables version control, collaborative PRs, and fast deployment.
  • Consequence: Documentation updates require separate deployment workflow; separate from in-app help.

• Real-time collaborative editing (not a collaborative document editor like Google Docs)
• Mobile native apps (supports PWA/web only for cross-platform reach)
• End-to-end encrypted messaging (not a privacy-focused messenger)
• Windows-only deployment (designed for Linux/Docker-first, cross-platform via containers)

1. Multi-ecosystem coordination: Python backend + TypeScript frontend mean dependency updates must be synced; breaking changes in one can cascade. 2. LLM API credentials: Cloud features (OpenAI, Anthropic, Gemini) require API keys in environment; self-hosted still needs model server setup (Ollama, local inference). 3. Vector database requirement: Semantic search implies dependency on embeddings DB (Postgres+pgvector, Milvus, Pinecone, etc.) — this must be running for RAG to work. 4. Telemetry server: .github/workflows/dockerize_telemetry_server.yml suggests optional telemetry collection; understand what data flows where for privacy compliance. 5. DevContainer expects Docker: .devcontainer/ setup assumes Docker is installed and running. 6. File indexing overhead: Document ingestion (PDF, Notion, Org) can be I/O and compute intensive; no obvious queue system visible (may use Celery, RQ, or similar).

• Semantic Search / Vector Embeddings — Core capability of Khoj — converts documents and queries into dense vectors for similarity matching, enabling retrieval of relevant docs without keyword matching
• Retrieval-Augmented Generation (RAG) — Khoj's architecture pattern — retrieves relevant documents, then feeds them to LLM as context to ground answers in your data, reducing hallucinations
• Agents / Tool Use — Khoj agents feature (visible in agents_page_full.png) — LLM-driven task automation that chains multiple tools and APIs, not just static prompts
• Self-Hosting / Privacy-First Architecture — Core value prop — users deploy Khoj on their own infrastructure to avoid data leaving their control, critical for enterprises and privacy-conscious users
• Multi-Client / Adapter Pattern — Khoj serves Emacs, Obsidian, web, desktop, mobile from one backend — adapter pattern keeps backend agnostic to client implementation, reducing code duplication
• Progressive Web App (PWA) — Khoj web client is PWA-capable (chrome_pwa_alt.png visible) — offline support, installation to home screen, native-like UX without app store distribution
• Monorepo Polyglot Development — Khoj manages Python backend and TypeScript frontend in one repo with shared CI/CD — requires careful dependency management and coordinated testing across ecosystems

• jina-ai/reader — Web content extraction and processing library — used or could be integrated into Khoj's web scraping pipeline for RAG
• langchain-ai/langchain — Orchestration framework for LLM chains and RAG — Khoj likely uses or should consider using LangChain for agent and tool composition
• chroma-core/chroma — Open-source vector database — direct alternative/complement for embeddings storage if Khoj uses it for semantic search
• ollama/ollama — Local LLM runtime — primary way users run models locally without cloud dependencies, core to Khoj's self-hosting value prop
• khoj-ai/pipali — Sister project mentioned in README — AI coworker built on Khoj; users of Khoj may want to explore Pipali for agentic use cases

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add GitHub Actions workflow for documentation build validation

The repo has a Docusaurus documentation setup (documentation/package.json with @docusaurus/core ^3.9.2) but no dedicated CI workflow to validate documentation builds. The .github/workflows directory has test.yml, dockerize.yml, and other workflows, but no github_pages_deploy.yml implementation visible. Adding a workflow to validate npm run build succeeds in the documentation folder prevents broken deployments and catches MDX/markdown syntax errors early.

• [ ] Create .github/workflows/docs-validate.yml to run cd documentation && npm install && npm run build on pull requests
• [ ] Add step to validate no broken internal links using a tool like linkinator or muffet
• [ ] Configure workflow to fail the PR check if documentation build fails, preventing broken docs from being merged

Add integration tests for desktop client build workflow

The repo has .github/workflows/desktop.yml for building desktop clients, but no corresponding integration test workflow. The .devcontainer/Dockerfile and computer.Dockerfile suggest desktop/local installation capabilities. Adding tests ensures desktop builds don't break across Python/Node dependencies and that the desktop client integrates properly with the backend.

• [ ] Create .github/workflows/test-desktop-build.yml to test desktop client build steps on Windows, macOS, and Linux matrices
• [ ] Add validation that desktop client can start and connect to a test Khoj backend instance
• [ ] Include smoke tests for desktop-specific features (system tray integration, offline mode if supported)

Add pre-commit hook validations for Python type hints and linting

The repo has .pre-commit-config.yaml configured but the specifics are not shown. Given this is a mature Python + Node.js project with multiple entry points (CLI, web, desktop), adding stricter pre-commit hooks (mypy, pylint, black formatting) would catch bugs early. The test.yml workflow likely runs these, but enforcing them pre-commit improves developer experience and code quality.

• [ ] Update .pre-commit-config.yaml to add mypy for Python type checking with strict mode enabled
• [ ] Add pylint and black hooks to enforce code formatting standards across the codebase
• [ ] Document the pre-commit setup in README.md or CONTRIBUTING.md so new contributors know to run pre-commit install

• Add end-to-end tests for the agents feature visible in agents_page_full.png — no test files for agent creation/execution logic are visible in the file list, making this a high-impact gap.
• Improve documentation for self-hosting with local LLMs (Ollama, LM Studio) in the documentation/ folder — currently docs emphasize cloud APIs; a 'local-only setup' guide would help users avoid vendor lock-in perception.
• Add TypeScript type safety to the web client's API layer — 1.2M lines of TypeScript with what may be any types or loose API contracts; audit and add strict types for fetch calls to backend.

• High · Hardcoded Database Credentials in docker-compose.yml — docker-compose.yml - database service environment variables. The docker-compose.yml file contains hardcoded PostgreSQL credentials (POSTGRES_USER: postgres, POSTGRES_PASSWORD: postgres) in plain text. These default credentials are a significant security risk, especially if this file is committed to version control and exposed. Fix: Use environment variables or secrets management tools. Move credentials to a .env file (add to .gitignore), use Docker secrets, or implement proper credential rotation. Example: use ${POSTGRES_PASSWORD} and populate via .env file or CI/CD secrets.
• High · Missing POSTGRES_PASSWORD in database Service — docker-compose.yml - database service. The PostgreSQL container uses a default weak password 'postgres'. Combined with default username 'postgres', this creates an easily guessable credential pair that could allow unauthorized database access. Fix: Generate a strong, randomly generated password and inject it via secrets management (Docker secrets, environment variables from external files, or CI/CD pipeline secrets).
• Medium · Outdated or Unverified Container Images — docker-compose.yml - multiple service image definitions. The docker-compose.yml uses several external container images (pgvector, ghcr.io/khoj-ai/terrarium, searxng, khoj-computer) without specifying pinned versions. Using 'latest' tags or unpinned versions can lead to unexpected breaking changes or security vulnerabilities from image updates. Fix: Pin all container images to specific versions (e.g., 'pgvector:pg15-v0.5.1' instead of 'pgvector:pg15'). Regularly update and audit pinned versions for security patches.
• Medium · Permissive Volume Mounts Without Read-Only Protection — docker-compose.yml - volumes section in database and search services. The docker-compose.yml mounts volumes (khoj_db, khoj_search) without specifying mount options. These volumes could potentially be written to or accessed by any container without read-only restrictions. Fix: Use read-only mount options where appropriate (e.g., 'readonly: true' for volume mounts that should not be modified by the container). Implement proper volume permissions.
• Medium · Missing Network Isolation in docker-compose.yml — docker-compose.yml - overall service configuration. The docker-compose services communicate on the default network without explicit network segmentation or access control policies. This could allow unauthorized inter-service communication. Fix: Define explicit networks in docker-compose.yml with services only connected to networks they require. Implement network policies and restrict inter-service communication.
• Medium · Unvalidated External Package Dependencies — documentation/package.json - dependencies and resolutions. The Node.js package.json includes resolutions that override package versions (serialize-javascript, picomatch), but there's no evidence of security audit processes or dependency scanning in the provided files. Fix: Implement automated dependency scanning (npm audit, Snyk, Dependabot). Regularly update dependencies and monitor for CVEs. Use lockfiles (package-lock.json) and commit them to version control.
• Medium · Potential Vulnerable Package: webpack-dev-server — documentation/package.json - dependencies and resolutions. webpack-dev-server ^5.2.1 is included as both a dependency and resolution. While it's a development tool, it could pose risks if accidentally deployed to production or used in insecure configurations. Fix: Move webpack-dev-server to devDependencies only if not needed at runtime. Ensure it's never deployed to production environments. Verify the pinned version has no known vulnerabilities.
• Low · Missing Security Headers Configuration — Docusaurus configuration and web server setup. No explicit security header configuration (CSP, X-Frame-Options, HSTS, etc.) is visible in the Docusaurus configuration or Docker setup. Fix: Configure security headers in docusaurus.config.js or reverse proxy. Implement Content-Security-Policy, X-Frame-Options: DENY, Strict-Transport-Security, and other appropriate headers.
• Low · Missing .gitignore Entries for Sensitive — undefined. undefined Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/khoj-ai/khoj shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live khoj-ai/khoj repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/khoj-ai/khoj.

What it runs against: a local clone of khoj-ai/khoj — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in khoj-ai/khoj | Confirms the artifact applies here, not a fork | | 2 | License is still AGPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 74 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of khoj-ai/khoj. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/khoj-ai/khoj.git
#   cd khoj
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of khoj-ai/khoj and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "khoj-ai/khoj(\\.git)?\\b" \\
  && ok "origin remote is khoj-ai/khoj" \\
  || miss "origin remote is not khoj-ai/khoj (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(AGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"AGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is AGPL-3.0" \\
  || miss "license drift — was AGPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "documentation/docs/features/all-features.md" \\
  && ok "documentation/docs/features/all-features.md" \\
  || miss "missing critical file: documentation/docs/features/all-features.md"
test -f ".github/workflows/test.yml" \\
  && ok ".github/workflows/test.yml" \\
  || miss "missing critical file: .github/workflows/test.yml"
test -f "docker-compose.yml" \\
  && ok "docker-compose.yml" \\
  || miss "missing critical file: docker-compose.yml"
test -f "Dockerfile" \\
  && ok "Dockerfile" \\
  || miss "missing critical file: Dockerfile"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 74 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~44d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/khoj-ai/khoj"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.