Desktop & CLI

Run Kendr locally with the desktop app, CLI, and shared API runtime.

The agent-research-deep repository already ships a working local-first runtime: an Electron desktop shell, a Typer CLI, and a FastAPI backend that share the same SQLite-backed, event-driven run model.

Source setup Desktop UI CLI workflows
Desktop UI CLI FastAPI MCP and KBs

What the local runtime already ships

Kendr in this repository is more than a hosted API client. The local runtime already supports the full research workspace loop.

Workflows
Chat, agentic, and deep research
Chat threads, tool-driven execution, and approval-gated report workflows all run on the same controller.
Persistence
SQLite, events, and exports
Runs, evidence, model catalogs, KB metadata, connector state, and artifact metadata are persisted locally.
Extensions
MCP, connectors, and skill packs
The desktop app and API already manage Cursor-style MCP configs, OAuth connectors, API-key connectors, and external skill packs.
Outputs
Reports and follow-up assets
Deep research exports markdown, HTML, PDF, and DOCX. Completed reports can also spawn slide and spreadsheet follow-up runs.

Surface matrix

The local runtime is shared, but each surface exposes a different amount of control.

Capability Desktop UI CLI HTTP API
Configure cloud or Ollama model connections Yes Yes Yes
Chat, agentic, and deep research runs Yes Yes Yes
Plan approval and action approval Yes Yes Yes
Knowledge-base management Yes Yes Yes
MCP registry Yes No Yes
OAuth connector setup Yes No Yes
Report regeneration and report follow-up Yes No Yes

Run Kendr from source

A normal local development session uses two processes: the FastAPI backend and the desktop shell. The CLI talks to the same runtime and can be used with or without the desktop app.

Backend

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e ".[dev]"
uvicorn kendr_api.app:app --reload --port 8765

Desktop shell

cd apps/desktop
npm ci
npm run dev

CLI help

kendr --help

Module entrypoint

PYTHONPATH=python python3 -m kendr_cli.main --help
Packaged behavior

The source-built Electron shell expects the backend to already be running. Packaged installer builds bootstrap runtime folders and start the bundled backend automatically.

Use the desktop UI

The desktop app is the richest local surface. It exposes the shell, the research rail, settings, knowledge bases, skills, and the full run-details workspace.

Shell
History rail, header, and composer
Start fresh runs, switch models from the header, attach files, and choose Chat, Agentic, or Deep Research at the composer.
Research rail
Depth and evidence strategy
Set depth, backend, source families, folders, links, OCR image verification, writing guide, citation style, date range, verification mode, and source limits.
Settings
Connectors, MCP, local LLMs, RAG, profile
Save provider keys, start OAuth flows, paste Cursor-style MCP JSON, browse Ollama models, configure vector stores, and store user profile preferences.
Run details
Progress, evidence, outline, drafts, trace
Approve plans, approve or reject side-effecting agent actions, inspect evidence, review section drafts, and download exported report artifacts.
  • Deep research runs pause after plan generation until a user approves the plan.
  • Agentic runs start immediately, but pause when a proposed tool is not read-only.
  • Knowledge bases can be created from uploaded files, web links, or YouTube URLs and then attached to the composer.
  • The Skills overlay shows both built-in skill health and installed external skill packs.
  • Completed deep research runs can regenerate report artifacts and spawn slide or spreadsheet follow-up runs from the UI.

Use the CLI

The CLI already covers the core day-to-day workflows: connection setup, runs, approvals, KBs, skills, vector-store settings, and local model management.

Connect and ask a chat question

kendr connection set --mode api --provider openai --credential "$OPENAI_API_KEY"
kendr models list
kendr chat ask "Summarize the architecture"

Run deep research with approval

kendr research start "Compare AI coding assistants for enterprise use" \
  --depth comprehensive \
  --web \
  --news \
  --papers

kendr runs approve <run-id>
kendr runs events <run-id> --follow
kendr runs artifacts <run-id>

Create and use a knowledge base

kendr kb create \
  --name "Quarterly sources" \
  --file ./docs/q1.pdf \
  --link https://example.com/brief \
  --algorithm hybrid \
  --wait

kendr chat ask "Use the KB to summarize the key risks" --kb <kb-id>

Run an agentic task

kendr agentic start "Inspect the docs MCP and summarize useful tools" \
  --folder ./docs \
  --link https://example.com/notes

kendr runs action-approve <run-id> <step-id>
kendr runs action-reject <run-id> <step-id> --reason "Do not modify anything"
CLI boundaries

The CLI does not currently manage MCP server configs, OAuth connector setup, report regeneration, or report follow-up creation. Use the desktop UI or direct API routes for those flows.

Shared API runtime and event stream

The desktop app uses a FastAPI service that you can call directly. Route groups are organized around settings, runs, uploads, knowledge bases, and the shared event stream.

Area Route examples Notes
Connection and models /api/settings/connection, /api/models, /api/models/lane Used by both the desktop and CLI connection flows.
Connectors and MCP /api/settings/connectors/*, /api/settings/mcp OAuth starts and finishes here, and MCP discovery logs are exposed here.
Knowledge bases and uploads /api/uploads, /api/knowledge-bases Knowledge bases can index attachments, links, and YouTube sources.
Runs /api/runs, /approve, /revise, /messages, /regenerate-report Run creation, approval, threaded chat replies, report regeneration, and follow-up actions all flow through the run routes.
Event stream /api/stream/events Server-sent events power live timelines and status updates in the desktop app.

Create a deep research run

curl http://127.0.0.1:8765/api/runs \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Compare local OCR model options for desktop research workflows",
    "mode": "research",
    "composer_mode": "deep-research",
    "depth": "Standard",
    "search_backend": "DuckDuckGo",
    "output_formats": ["md", "html", "pdf", "docx"]
  }'

Approve the run

curl http://127.0.0.1:8765/api/runs/<run-id>/approve \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"actor":"api-user"}'

Current boundaries

Scheduling
One active run at a time
The controller rejects a new queued or running workflow when another run is still active or waiting on an action approval.
Desktop source mode
Backend must already be up
The source-built Electron shell is a client. Only packaged builds auto-start the bundled backend.
CLI scope
Not every UI flow is mirrored
MCP registry, OAuth connector setup, report regeneration, and report follow-up creation remain desktop or direct-API tasks.
Planned scope
Developer Mode is still future work
The product plan mentions a separate Developer Mode, but the current shipped local surface is the Studio-style workspace only.