Gilbert Codex

Gilbert Codex is a GUI-first local desktop agent workspace for building, reviewing, and steering code from one focused surface. The app combines React, TypeScript, Tauri 2, and a Rust command layer so agent workflows can run close to the local workspace without requiring a hosted backend for the first public milestone.

Preview

Focused chat workspace	Live activity, tools, and sources

Tool registry	Local settings

Current Status

Gilbert Codex is in an early public alpha desktop foundation phase. The app currently includes local account sign-in, a chat workspace, project-scoped local state, multi-provider model streaming, planning mode, web search, local computer file context, local Git source control, GitHub source control, Discord slash-command bridge setup/runtime, terminal sessions, browser preview, tool toggles, settings, desktop notifications, and a Tauri command bridge.

Platform status: Windows x64 is the verified alpha target. macOS and Linux now have partial source support, but they still need contributors on those operating systems to run the app, package it, and finish any native port issues. See Platform Support And Porting Notes.

The repository is kept open-source ready by default: dependencies, build output, local logs, generated targets, local databases, and secrets stay out of Git. Source files are grouped by product surface so contributors can find the UI, runtime clients, tools, types, and Rust commands without reverse-engineering the whole app.

Download

The latest Windows public alpha is available from GitHub Releases.

Download the Windows x64 setup executable, run it, and configure provider keys or local endpoints in Settings. The customer installer uses Tauri's NSIS packaging, branded light/dark-safe setup artwork, a license page, Start menu metadata, and a WebView2 runtime check. This alpha is unsigned, so Windows SmartScreen may show an extra confirmation prompt.

macOS and Linux release artifacts are not official yet. The repo has partial source support for both platforms, and contributors with those operating systems are needed to test and complete the port.

See v0.2.2 release notes for the Stability Pack 1 milestone, updater status, setup notes, known limitations, and checksum details.

Product Shape

• Desktop shell: Tauri 2 window, custom chrome, local app metadata, and Rust commands.
• Local identity: local account creation and sign-in for namespaced chat, project, settings, and workspace state.
• Chat workspace: searchable history, pinned chats, generated chat titles, project grouping, markdown rendering, image/file attachments, regeneration, targeted stop controls, and local persistence.
• Model runtime: OpenRouter, OpenAI, Anthropic, Google Gemini, xAI, LM Studio, Ollama, Groq, Mistral, and DeepSeek chat streaming with live model catalogs where available, provider usage tracking, thinking controls, planning mode, and empty-response retry handling.
• Tools: web search, local Git status/diff/stage/commit/push/pull/branch tools, review-panel Git commit/push actions, GitHub repository/release/workflow tools, local file indexing, file read/write/delete helpers, duplicate-safe typed TXT/Markdown/code/React/HTML/PDF file creation, batch file creation, vector helpers, testing, TypeScript, SQL, React Native, PDF, browser folder fallback, interactive PTY terminal sessions, browser preview, and Toolbox feature toggles.
• Review posture: destructive chat deletion confirmation, explicit local workspace permission modes, desktop notification permission checks, a configured Tauri CSP, least-privilege notification capabilities, and visible activity/progress cards.
• Settings: provider key/base URL entry, GitHub browser login, Discord bridge setup/runtime controls, connection validation, appearance mode, model, generation, thinking, and web-search controls.

Coming Next

• Stability Pack follow-ups: more provider/runtime tests, safer local tool recovery, durable long-running jobs, and clearer update/install diagnostics.
• Model selector revamp: provider profiles, model capability badges, context-window hints, local/cloud filtering, and faster switching between coding, planning, reasoning, and multimodal models.
• Multimodal creation tools: image generation/editing, image-to-code workflows, video generation job tracking, thumbnails, and saved media artifacts.
• Messaging integrations: WhatsApp support research focused on compliant Business Platform flows, plus stronger Discord/GitHub notification routing.
• Collaboration polish: richer source-control review cards, PR handoff helpers, issue templates, roadmap labels, and contributor-friendly first tasks.

Repository Layout

.
|-- .github/               Issue forms, PR template, CODEOWNERS, CI, and Dependabot
|-- public/                 Static app assets
|-- docs/                   Project docs, tool contracts, and publishing checklists
|   |-- INSTALLER.md        Windows customer installer build and release checklist
|   |-- platform/           Platform support matrix and macOS/Linux port checklist
|-- src/                    React frontend
|   |-- app/                App composition, auth, runtime helpers, Tauri clients
|   |-- components/         Reusable UI grouped by product area
|   |-- lib/                Storage, chat helpers, model metadata, context windows
|   |-- pages/              Top-level app surfaces
|   |-- services/           Provider, planning, usage, and web-search clients
|   |-- styles/             CSS split by surface
|   |-- tools/              Browser, GitHub, and local-computer tool executors
|   `-- types/              Shared TypeScript contracts
|-- src-tauri/              Tauri 2 and Rust host layer
|   |-- capabilities/       Window and runtime permissions
|   |-- icons/              App icon assets generated from the project logo
|   |-- windows/            Branded NSIS installer artwork
|   |-- src/commands/       Auth, app info, computer, Discord, GitHub, terminal, and web commands
|   |-- src/core/           Rust provider, job, storage, and agent scaffolding
|   `-- tauri.conf.json     Desktop app configuration
|-- CONTRIBUTING.md         Local setup and contribution rules
|-- PROGRESS.md             Current phase history and roadmap
|-- SECURITY.md             Responsible disclosure and local-data notes
`-- README.md              Project overview

Getting Started

For platform-specific status and porting work, start with docs/platform/README.md. Windows is verified; macOS and Linux are partial until tested on real machines.

Prerequisites:

• Node.js 18 or newer.
• Rust and Cargo.
• Microsoft WebView2 Runtime on Windows.
• WebKitGTK runtime/development packages on Linux when running or building the Tauri desktop shell.

Install dependencies:

npm install

Run the frontend preview:

npm run dev

Run the full desktop app:

npm run app:dev

Run the full repository check:

npm run check

Optional production dependency audit:

npm run audit:prod

Individual checks:

npm run build
npm run rust:fmt:check
npm run rust:check

On Windows PowerShell, npm.cmd is also supported if local script execution policy blocks the npm shim.

Build the Windows customer installer:

npm.cmd run app:installer

See Windows Installer for what is bundled, what stays local, and the release checklist.

Local Data And Secrets

Gilbert Codex is local-first. Provider keys and local endpoint URLs are entered through Settings and treated as local user data, not repository configuration. Desktop local accounts are stored in the app data area; the browser preview uses localStorage as a development fallback. Do not commit real API keys, local databases, logs, terminal output, private workspace data, or build artifacts.

GitHub browser login uses OAuth device flow. For local development, create a GitHub OAuth App with device flow enabled, copy .env.example to .env, set VITE_GITHUB_OAUTH_CLIENT_ID to the public client ID, and sign in from Settings. No client secret belongs in the desktop app. The app requests a broad GitHub OAuth scope bundle at sign-in so source-control, workflow-file, package, gist, organization, and repository-admin tools can work when the signed-in account is allowed to perform those actions.

Discord bridge settings are local setup data for the desktop Discord runtime. Slash-command chat uses a signed local Interactions receiver and can start ngrok in the background to produce a public HTTPS endpoint. /gilbert continues the latest Discord-linked chat, while /gilbertnewchat intentionally starts a fresh chat. Incoming Discord webhooks are one-way posting URLs; GitHub repository events can use Discord's GitHub-compatible webhook payload URL for channel notifications. Bot gateway chat is still future runtime work.

See SECURITY.md before sharing bug reports that include logs, screenshots, workspace paths, terminal output, or provider errors.

Integration Setup

• Platform support and porting notes: Windows verification status, macOS/Linux partial support, and the native testing checklist.
• Discord integration setup: Discord application setup, one-click ngrok-backed slash-command bridge setup, bot gateway notes, incoming webhooks, and GitHub-to-Discord notifications.
• GitHub integration setup: GitHub OAuth App device-flow setup, requested scopes, Settings sign-in, repository tools, and webhook troubleshooting.

Collaboration

Before opening a pull request, run:

npm run check
npm run audit:prod
git diff --check

Use CONTRIBUTING.md for coding and review standards, docs/CODE_DOCUMENTATION.md for source comment expectations, and PROGRESS.md for the current roadmap.

Branch and contribution flow:

• Normal contributor work targets develop.
• QA batches promote from develop to testing.
• Release-ready work promotes from testing to main.
• The detailed workflow lives in docs/BRANCHING.md and docs/CONTRIBUTION_PROCESS.md.

License

Gilbert Codex is released under the MIT License.