Heimgeist/AGENTS.md

AGENTS.md

Project Overview

Heimgeist is a local desktop chat app for Ollama. It uses a React/Vite renderer, a Tauri desktop shell, a FastAPI backend, SQLite chat storage, Whisper transcription, optional SearXNG web search, and local RAG libraries under the backend.

Important Directories and Entry Points

• src/ - React renderer code.
  • src/main.jsx mounts the app.
  • src/App.jsx owns most chat UI state, session flow, model startup checks, and library/sidebar orchestration.
  • src/chatApi.js, src/chatGeneration.js, and src/backendApi.js contain backend request and streaming helpers.
  • src/desktop/desktopApi.js is the renderer platform abstraction for desktop APIs.
  • src/styles.css contains the main UI styling.
• src-tauri/ - Tauri desktop shell.
  • src-tauri/src/main.rs owns Tauri commands for the renderer desktopApi surface, settings persistence, dialogs, path opening, external links, focus events, and update placeholders.
  • src-tauri/tauri.conf.json points Tauri at the existing Vite renderer.
  • src-tauri/capabilities/ contains Tauri permission grants for enabled plugins.
• backend/ - FastAPI backend and local processing.
  • backend/main.py defines chat, session, model, audio, Ollama, and web search routes.
  • backend/sidecar_main.py is the PyInstaller entrypoint used by packaged Tauri builds to start backend.main:app.
  • backend/local_rag.py defines library, file registration, job, and local context routes.
  • backend/paths.py centralizes backend runtime data paths for SQLite and local RAG libraries.
  • backend/schemas.py and backend/models.py define API and database data shapes.
  • backend/rag/ contains corpus, enrichment, embedding, indexing, and retrieval helpers.
  • backend/database.py gets the SQLite path from backend/paths.py.
• scripts/ - development wrappers used by npm scripts.
  • scripts/run-backend.cjs starts Uvicorn from backend/.venv.
  • scripts/run-tauri-dev.cjs starts or reuses FastAPI, then launches the Tauri dev shell.
  • scripts/build-backend-sidecar.cjs builds the PyInstaller backend sidecar and helper binaries for Tauri packaging.
• run.sh - bootstrap script for local development dependencies and dev startup.
• vite.config.js - Vite dev/build configuration. Tauri dev uses the strict Vite port 127.0.0.1:5174.

Run and Build Commands

• ./run.sh - bootstrap/update Python and npm dependencies, then start the full dev stack.
• npm run dev - start or reuse FastAPI on 127.0.0.1:8000, start the Vite renderer on 127.0.0.1:5174, then launch Tauri.
• npm run dev:tauri - alias for the primary Tauri development workflow.
• npm run dev:backend - start FastAPI on 127.0.0.1:8000 with reload. Requires backend/.venv.
• npm run dev:renderer - start Vite on 127.0.0.1:5174 for Tauri.
• npm run dev:tauri:shell - launch the raw Tauri shell when backend lifecycle is managed separately.
• npm run build - build the renderer into dist/.
• npm run build:sidecar - build the PyInstaller backend sidecar and helper binaries into src-tauri/binaries/.
• npm run package:mac - build the sidecar and produce src-tauri/target/release/bundle/macos/Heimgeist.app.
• npm run build:app - alias for npm run package:mac.
• npm start - alias for npm run dev.

There are currently no npm test or lint scripts in package.json.

Architectural Boundaries

• Renderer code should remain platform-neutral where practical. It may call backend HTTP APIs and may call desktopApi, but it should not import or call Tauri APIs directly.
• src/desktop/desktopApi.js is the renderer's platform abstraction. Add desktop capabilities there first, then back them with Tauri commands/events.
• src-tauri/src/main.rs owns desktop concerns: windows, menus, dialogs, shell opening, settings persistence, update placeholders, focus events, and Tauri command implementations.
• src-tauri/src/main.rs also starts the packaged backend sidecar in release builds, waits for /health, passes app-managed data-path environment, and shuts the sidecar down when the app exits.
• backend/paths.py owns backend runtime path resolution. Default development paths must remain backend/app.db and backend/libraries; packaged launchers pass app-managed paths through internal environment hooks.
• Backend code owns chat/session persistence, Ollama integration, Whisper transcription, web search enrichment, and RAG library processing.
• Backend API contracts should stay stable unless intentionally coordinated with renderer changes. If a response/request shape changes in backend/schemas.py or route handlers, update the renderer callers in the same change.
• Keep local RAG job orchestration and generated library state in the backend. Renderer code should use backend endpoints rather than reading library files directly.

Generated and Runtime Data

Do not edit or commit generated/runtime data unless the task explicitly requires it:

• backend/app.db and any *.db files - local SQLite runtime data.
• backend/libraries/ - local RAG library metadata, corpora, enrichment outputs, embeddings, indexes, and job state.
• backend/.venv/ and .venv/ - Python virtual environments.
• node_modules/ - npm dependencies.
• dist/ - Vite build output.
• __pycache__/, *.pyc, .DS_Store, and similar machine-generated files.
• Local app settings files under the Tauri app config directory or HEIMGEIST_SETTINGS_FILE.
• Packaged-build backend data directories supplied through internal deployment hooks such as HEIMGEIST_DATA_DIR, HEIMGEIST_DB_PATH, or HEIMGEIST_LIB_ROOT.
• Tauri-generated src-tauri/target/, src-tauri/gen/, and local src-tauri/Cargo.lock if generated by local verification.
• Generated sidecar binaries in src-tauri/binaries/ except src-tauri/binaries/.gitignore.

Avoid broad file operations that traverse these directories. Use ignore patterns with search tools when inspecting the repo.

Verification Expectations

• Frontend changes: run npm run build at minimum. For UI or interaction changes, also run the dev stack and exercise the affected flow in Tauri.
• Backend changes: run a targeted syntax/import check such as backend/.venv/bin/python -m py_compile backend/main.py backend/local_rag.py for touched modules, then start npm run dev:backend or the full dev stack and check GET /health.
• Desktop bridge/Tauri changes: run cargo check --manifest-path src-tauri/Cargo.toml with a temp CARGO_TARGET_DIR when useful, run npm run build, and if practical run npm run dev. Use a temporary HEIMGEIST_SETTINGS_FILE when testing ordinary shared settings behavior; use a temporary HOME with a fake legacy settings file when testing first-run import, because HEIMGEIST_SETTINGS_FILE intentionally bypasses import.
• Tauri packaging changes: run npm run build:sidecar, then npm run package:mac on macOS. Verify src-tauri/target/release/bundle/macos/Heimgeist.app exists, launches, starts or reuses a compatible backend on 127.0.0.1:8000, uses app-managed data outside the app bundle, and stops its sidecar processes on quit.
• API contract changes: verify both sides together. Update backend schemas/routes and renderer callers in the same change, then exercise the affected request path.
• RAG, Whisper, Ollama, or SearXNG changes: note any external services or local models required for verification, and test graceful failure paths when those services are unavailable.

Tauri Guidance

• Keep renderer desktop calls behind src/desktop/desktopApi.js; do not import Tauri APIs directly in React components.
• When adding desktop capabilities, prefer method names and payloads that stay stable for renderer callers.
• Preserve HEIMGEIST_SETTINGS_FILE as an explicit shared settings override.
• Keep first-run legacy settings import available when Tauri settings do not already exist.
• Do not move or rewrite backend/app.db or backend/libraries; the development backend must keep using the existing backend working directory.
• Treat HEIMGEIST_DATA_DIR, HEIMGEIST_DB_PATH, and HEIMGEIST_LIB_ROOT as internal app/sidecar deployment hooks only. Do not expose them in the UI or document them as normal user configuration.
• Packaged Tauri builds use backend/sidecar_main.py and scripts/build-backend-sidecar.cjs to bundle the FastAPI backend. Do not move or migrate development data into the packaged app data directory as part of packaging.
• Production-release work still needs signed updater/changelog parity, final bundle metadata, signing/notarization, full Windows/Linux packaging scripts, and installer behavior.
• Avoid refactors that mix migration prep with unrelated feature work. Migration work should be explicit and reviewable.

Coding and Refactor Guidelines

• Keep changes scoped to the request. Do not refactor large files such as src/App.jsx, src/styles.css, backend/main.py, or backend/local_rag.py unless the task needs it.
• Prefer existing helper modules and patterns over new abstractions.
• Preserve stable backend contracts and persisted data compatibility. Add small migration helpers when changing database-backed fields.
• Keep settings keys backward compatible where possible. Existing settings migrations live in Tauri and backend settings helpers.
• Use structured JSON/schema changes rather than ad hoc string parsing for API payloads.
• Add comments only where they explain non-obvious control flow, concurrency, migration, or integration behavior.
• Do not silently swallow errors in user-facing flows; surface useful messages while preserving graceful degradation for optional services.
• Do not mix formatting churn with behavior changes.

Known Fragile Areas

• The Tauri bridge is intentionally narrow. Direct window.__TAURI__ use outside src/desktop/desktopApi.js makes desktop behavior harder to reason about.
• src/App.jsx, src/chatGeneration.js, and backend chat routes share assumptions about streaming, regeneration, attachments, source metadata, and session state.
• backend/main.py creates/migrates SQLite tables at import/startup. Schema changes need care because they run against local user data.
• backend/paths.py controls where chat and local RAG data are stored. Preserve development defaults unless the task explicitly concerns packaged app data paths.
• backend/local_rag.py coordinates asynchronous jobs, file registration, generated artifacts, and per-library locks. Avoid changes that can start duplicate jobs or corrupt backend/libraries/.
• RAG builders under backend/rag/ run heavier file processing and subprocess/threaded work. Test with small inputs before broader runs.
• Whisper depends on ffmpeg/ffprobe paths supplied by the Node backend runner when available.
• Web search depends on an optional SearXNG instance, usually http://127.0.0.1:8888; features should fail gracefully when it is absent.
• Ollama availability, model names, embedding model choices, and vision capability checks are runtime-dependent. Keep related UI and backend paths tolerant of missing models.