DeepCode Desktop is the Tauri 2 workbench for DeepCode. It opens the same local Projects, canonical Sessions, Agent runtime, models, Skills, Goals, Automations, permissions, and evidence as the CLI. Desktop is a visual client, not a second implementation of Agent behavior.

The workbench combines conversation history with structured tool progress, approvals, Git review, files, terminals, tests, Artifacts, and provider settings. Work started in one interface can be resumed in the other without converting or copying its Session.

Install the platform dependencies from the Tauri 2 prerequisite guide before preparing the repository.

Tauri development on Windows requires Microsoft Edge WebView2 and the Visual Studio 2022 Build Tools workload Desktop development with C++. Rust must use the MSVC host toolchain; Rustup alone does not install Microsoft's link.exe.

Run the following commands in PowerShell. Accept the UAC prompt raised by the Build Tools installer:

winget install --id astral-sh.uv --exact
winget install --id OpenJS.NodeJS.LTS --exact
winget install --id Rustlang.Rustup --exact
winget install --id Microsoft.VisualStudio.2022.BuildTools --exact `
  --override "--wait --passive --norestart --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"

WebView2 is normally already installed on supported Windows 10 and Windows 11 systems. If it is missing, install the Evergreen Runtime from the Microsoft download page linked by the Tauri prerequisite guide.

Close all existing PowerShell windows after the installers finish. Open a new PowerShell window so the updated user PATH is loaded, then run:

uv --version
node --version
rustup default stable-msvc
rustc --version
cargo --version

Run these commands from the repository root:

uv venv --python 3.12
uv pip install --python .venv\Scripts\python.exe -e .
Set-Location desktop
npm ci
$env:DEEPCODE_PYTHON = (Resolve-Path ..\.venv\Scripts\python.exe)
npm run setup:sidecar
npm run build:sidecar

The explicit interpreter path prevents an active Conda or other environment from receiving the editable DeepCode installation.

From the same desktop directory and PowerShell window:

npm run tauri -- dev

Keep the terminal open while Desktop is running. Press Ctrl+C in that terminal to stop the development application. On later launches, set DEEPCODE_PYTHON again if using a new PowerShell window:

Set-Location desktop
$env:DEEPCODE_PYTHON = (Resolve-Path ..\.venv\Scripts\python.exe)
npm run tauri -- dev

After installing the platform dependencies from the Tauri prerequisite guide, run the following commands from the repository root:

uv venv --python 3.12
uv pip install --python .venv/bin/python -e .
cd desktop
npm ci
npm run setup:sidecar
npm run build:sidecar
cd ..
./scripts/deepcode-desktop

To use deepcode-desktop from any working directory, link the launcher into a directory on PATH once:

mkdir -p ~/.local/bin
ln -sf "$(pwd)/scripts/deepcode-desktop" ~/.local/bin/deepcode-desktop

The first build:sidecar creates the resource directory declared in tauri.conf.json, which Tauri validates during development as well as release builds. Debug runtime launch still prefers the repository .venv, so ordinary Python and React edits do not require rebuilding the PyInstaller sidecar. Rebuild it only after removing desktop/build/sidecar or changing packaged runtime dependencies.

1. Open Settings → AI providers and select Add provider.
2. Choose a provider. Its normal endpoint and protocol are filled in for you.
3. Paste an API key, or choose an environment variable. Custom gateways and local servers without a universal endpoint also ask for their base URL; optional endpoint overrides remain under Advanced connection settings.
4. Select Save and check. DeepCode checks credential availability and model discovery without sending repository or Session content.
5. Under Agent model, choose an exact model ID and select Save and verify model. This final step sends one tiny reply OK inference request so a public model catalog cannot be mistaken for usable model access.
6. Open a Session to inherit the default, or use its composer picker to switch the connection/model for future Turns.

API keys are written to ~/.deepcode/credentials.json in user-private storage. Desktop receives only configured/missing status and never reads a stored key back. The same named connections and defaults are used by CLI and Desktop.

The composer model picker changes the connection, model, and model-advertised Thinking effort for future Turns in the current Session. Existing history stays attached to the same canonical Session under ~/.deepcode/sessions/. A switch made while work is active leaves the current Turn's immutable execution profile unchanged and applies to the next Turn. Raw chain-of-thought is never shown as assistant text. Provider-designated summaries and reasoning details are kept in a separate typed timeline item, while opaque continuation state remains private.

The transcript picker beside the composer controls presentation independently of model effort:

• Normal shows a compact completed reasoning preview and keeps provider details behind a disclosure.
• Verbose expands returned reasoning details and ordinary execution activity.
• Summary keeps the final answer and important outcomes while hiding reasoning and routine tool activity.

Ctrl+O cycles the same three modes. The preference is local UI state; changing it never changes the Session, model request, Goal, tools, or stored evidence.

Every accepted Turn stores an immutable, secret-free execution profile. Later changes to defaults or credentials cannot silently change queued or historical work. Paper2Code captures both its planning and implementation profiles at admission; an explicit Session connection/model applies to both phases, while Sessions without an override inherit the corresponding advanced phase default.

The first time a Project is used for Agent execution, review and trust its canonical folder. Trust remembers which workspace DeepCode may execute in; it does not grant unrestricted tool access.

The composer access picker controls future Turns in the current Session:

• Ask keeps workspace protections and requests approval for sensitive actions.
• Read only allows inspection while denying mutating tools.
• Full access removes approvals and filesystem sandbox boundaries after an explicit warning. Use it only for a workspace you are prepared to expose to unrestricted local execution.

An active or queued Turn keeps the access profile captured when it was accepted. Changing the picker applies to later submissions and is immediately visible to the CLI because both clients edit the same Session setting.

The Session menu separates Archive from Delete permanently. Archive preserves the canonical transcript. Permanent deletion removes the transcript, Goal ledger, and rebuildable application records but never deletes repository files. The backend rejects deletion when another CLI/terminal still owns the Session, work is active, a managed worktree is attached, or an Automation must be removed first.

The equivalent CLI workflow uses the same connection and Session backend:

deepcode provider list
deepcode provider set personal-openrouter --template openrouter --api-key
deepcode provider models personal-openrouter --refresh
deepcode provider test personal-openrouter --model <model-id>
deepcode -c personal-openrouter -m <model-id> --effort auto

Use Set a Goal above the Session composer to define one natural-language outcome and optional Skills. While it runs, the composer steers the current Turn; if that Turn has already ended, the same submission starts the next Turn with the same idempotency key. Queue next is the only way to request next-Turn delivery, and Desktop reports whether an input was started, steered, or queued. Edit Goal updates the same durable Goal identity and delivers the new objective to its active Turn when possible. Completed Goals can be reopened for new work without erasing the Session history.

The compact Goal rail shows the current objective, status, token usage, and pause/resume controls. Tests, builds, diagnostics, diffs, and independent review remain visible evidence for the working Agent's completion decision. Goals are not a Desktop-only workflow: the same ledger and ordinary Turn execution are available from the interactive CLI with /goal.

Open Automations after selecting a trusted Project. A definition may be manual or interval-based and owns one canonical Goal Thread. Run now creates an idempotent Run; Runs shows its durable history; Open Thread opens the same conversation, tools, approvals, evidence, and continuation controls used by interactive work.

Pause/resume controls only an interval schedule. Manual definitions are always enabled, and Run now remains available while an interval is paused.

Desktop loads one bounded page of definitions and one bounded page of expanded Run history at a time. Load more automations and Load more runs append the next explicit page with stable ID deduplication. Live notifications refresh the first page; an overflow warning also resets the visible pages safely rather than presenting a partial cache as complete.

Interval schedules execute while a scheduler-enabled Desktop or App Server is active. If several compatible processes share the database, one holds the scheduler leader lease and the others remain available for takeover. Agent and Workflow Turns still use the shared cross-process capacity and workspace fences, so another Session cannot mutate the same canonical checkout at the same time.

Automation instructions never grant trust or elevated permissions. Each Turn captures the workspace's explicit permission setting or the safe default, and an approval can be answered from another connected DeepCode client. The same definitions and Run history are available through deepcode automation. See the Automation architecture for lifecycle, idempotency, and recovery details.

Desktop packaging uses an isolated Python 3.12 environment installed from sidecar-requirements.lock; it does not depend on optional packages installed in the repository virtualenv.

Run the complete validation sequence before opening a pull request:

npm run setup:sidecar
npm run build:sidecar
npm run audit:licenses
npm run lint
npm run test
npm run check:protocol
npm run build
cd src-tauri
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test --all-targets

setup:sidecar is idempotent. It creates build/sidecar/.venv and installs the locked runtime plus PyInstaller. Regenerate sidecar-requirements.lock from sidecar-requirements.in only when packaged runtime dependencies intentionally change.

The packaged sidecar supports PDF, Markdown, text, HTML, and DOCX without Docling or a system Office installation. CLI users who need Docling's advanced layout/image conversion can install deepcode-hku[advanced-documents]; it is deliberately excluded from the Desktop bundle.

Regenerate Desktop protocol types only after changing the canonical schema:

npm run generate:protocol

Build the application bundle:

npm run tauri:build

Before bundling, Tauri builds a PyInstaller onedir App Server, verifies every lazy runtime import, and performs an isolated initialize → shutdown RPC smoke. The complete directory is embedded under the app resource directory as app-server/; release builds never fall back to source paths or a system Python.

Useful runtime overrides for tests and diagnostics:

• DEEPCODE_APP_SERVER_PATH: explicit sidecar executable.
• DEEPCODE_DATABASE_PATH: explicit SQLite path passed to the App Server.
• DEEPCODE_SIDECAR_PYTHON: Python interpreter used by the sidecar build.
• DEEPCODE_SIDECAR_BOOTSTRAP_PYTHON: Python 3.12 used to create the isolated packaging environment.
• DEEPCODE_TARGET_TRIPLE: target name used by the sidecar build.

Local macOS bundles use ad-hoc signing so nested Python resources and the app resource seal can be verified with codesign --verify --deep --strict. release-desktop.yml provides architecture-native macOS arm64/x64, Windows x64, and Linux x64 release jobs, signed updater artifacts, macOS notarization, Windows Authenticode, Linux AppImage signing, and draft release uploads. It fails closed until the protected release environment contains every required credential. See the release runbook and privacy/diagnostics contract.