Imported from hemantvirmani/DeskGenie (AGENTS.md). Install upstream with npx skills add hemantvirmani/DeskGenie. Copyright stays with the author.

AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

Commands

Backend

# Activate virtual environment (Windows)
venv\Scripts\activate

# Run backend / web server (no window)
python deskgenie.py --server

# Run a single query (CLI)
python deskgenie.py --query "your query here"

# Check all Python files compile
python -m compileall . -q

Frontend

cd frontend
npm install       # install deps
npm run dev       # dev server (port 5173, proxies API to port 8000)
npm run build     # production build → frontend/dist

Desktop App (dev)

# GUI mode — native window with system tray
python deskgenie.py

# CLI mode — query via desktop entry point
python deskgenie.py --query "your query here"

# Enable DevTools (Edge inspector alongside the window)
DESKGENIE_DEBUG=1 python deskgenie.py

Production Build (exe)

# Builds frontend + packages everything into dist/windows/DeskGenie/DeskGenie.exe
python windows/build.py

Production (web server only)

Build frontend first (npm run build), then python deskgenie.py --server serves both API and static files on port 8000.

Architecture

DeskGenie is a desktop AI assistant. The user sends natural language commands via a React UI or CLI. A LangGraph agent backed by Google Gemini processes the request using 25+ tools (file ops, PDF, images, media, web search, HTTP requests, Python execution, classical ciphers), streaming logs back to the UI in real time.

React UI / CLI
    ↓
FastAPI (app/genie_api.py)  ←→  SSE log streaming
    ↓
DeskGenieAgent (agents/agents.py)
    ↓
LangGraphAgent (agents/langgraphagent.py)  ←  Google Gemini
    ↓
Tools (tools/desktop_tools.py, tools/custom_tools.py)

Key flows

• Async chat: POST /api/chat → returns task_id → frontend polls /api/task/{id} for result, streams logs via SSE at /api/task/{id}/logs/stream.
• Agent loop: LangGraphAgent builds a LangGraph state machine. State tracks question, messages, answer, step_count, file_name. Max 25 steps per iteration, recursion limit 100.

Important files

Coding Conventions (from .clinerules)

• No hardcoded strings — all user-facing strings go in resources/ui_strings.py (backend) or frontend/src/uiStrings.js / frontend/src/consoleStrings.js (frontend).
• All function signatures must have type hints (Optional[], List[], Dict[], Tuple[]).
• Private methods prefixed with _underscore. Constants in UPPER_SNAKE_CASE. Classes in PascalCase.
• Public functions get Google-style docstrings (Args, Returns, Raises). Private functions get a one-liner.
• All agents implement the __call__(question, file_name) interface.
• Internal engine constants (timeouts, retry limits, ports) live in app/config.py. User-facing settings (LLM provider/keys, MCP servers, agent tuning, observability) live in config.json.

Configuration

All user-facing settings live in config.json (platform config dir — Windows: %LOCALAPPDATA%\DeskGenie\config.json). See config.json.example at the repo root for the full schema. Key sections:

• llm — active provider, API keys, model names, temperature, timeout
• mcpServers — MCP server definitions (same schema as Codex settings.json)
• agent — maxSteps, maxRetries, search result limits
• observability.langfuse — Langfuse tracing keys
• logging.level — Python log level (DEBUG/INFO/WARNING/ERROR)
• folder_aliases — short names resolved in natural language commands
• preferences — default output dir, image quality, PDF DPI

Multi-Model Architecture

DeskGenie deliberately routes different workloads to different models:

• Agent reasoning / orchestration — controlled by llm.activeProvider in config.json. Supports google, anthropic, ollama, huggingface.
• Vision workloads (image analysis, video understanding, YouTube Q&A) — always Google Gemini (genai.Client in tools/custom_tools.py), regardless of active provider.

The two layers are independent: switching the primary LLM has no effect on vision tool behaviour.

LLM Configuration

Set via config.json → llm. Google provider has three model slots: agentModel (main loop), visionModel (image/video tools), advisorModel (hard-problem escalation). Temperature defaults to 0 (deterministic). LLM call timeout: 300s. Retry logic: 3 retries, 2s initial delay, 2× backoff (handles 504 DEADLINE_EXCEEDED).

CLI Tool Usage — Always Verify Before Suggesting

Never suggest CLI commands for third-party tools (fastmcp, uvx, npx, etc.) from memory. CLI APIs change between versions and remembered syntax is frequently wrong or outdated.

Before suggesting any CLI command for an installed tool:

1. Run <tool> --help or <tool> <subcommand> --help first
2. Read the actual output to confirm flags and syntax
3. Only then suggest the command

This applies to: fastmcp, uvx, npx, pyinstaller, langchain-cli, and any other tool where the installed version may differ from training data.