urbanwafflezz/gilbertcodex

Gilbert Codex

A local-first desktop AI agent workspace with MCP servers, Skills, plugins, connected apps, workspace tools, image creation, research, review, and release work.

v0.8.2 release notes | Download v0.8.2 | MCP setup | Roadmap | Contributing | Support

v0.8.2 Is The Connected Platform Build

Gilbert Codex v0.8.2 is the build where the v0.8 platform work becomes much more usable day to day. It keeps the MCP, Skills, plugin, connected-app, thinking, tool, and cross-platform release foundation from v0.8.0/v0.8.1, then deepens the real runtime paths: richer Apps and MCP setup, reusable non-model keys, stronger connected-tool evidence, provider cache accounting, and better native command discovery on Windows, macOS, and Linux.

This is still alpha software, but the v0.8.x line is a major line in the sand: Gilbert now has the pieces for connected tools, reusable workflows, plugin-powered capability growth, and cross-platform desktop distribution. v0.8.2 is the build new testers should start from.

High-impact local actions, destructive operations, credential access, publishing, terminal commands, and outside-scope paths are still guarded by explicit review/permission flows. Provider keys, local accounts, OAuth credentials, logs, databases, private tool overlays, generated build output, and release signing secrets stay out of public Git.

Known alpha issue: ChatGPT GPT-5.3 Spark is currently read-only for workspace work. It can inspect files, but write/edit tool calls are not completing reliably on that route yet. Use the other available Codex/ChatGPT, OpenRouter, or local routes for file changes until this is fixed.

What Shipped

Download

The v0.8.2 desktop alpha is the current build on GitHub Releases.

The release workflow builds Windows, macOS arm64, macOS x64, and Linux x64 on GitHub-hosted native runners.

macOS and Linux packages are built on GitHub-hosted native runners and are now part of the release workflow, but they still need real-device launch smoke tests before those platforms should be called fully verified. The workflow builds ad-hoc signed, unnotarized macOS artifacts when Apple Developer signing and notarization secrets are not configured; local macOS inspection builds use the same ad-hoc signing path.

Screenshots

MCP, Skills, And Plugins

MCP Servers

Gilbert Codex now treats MCP as a first-class app feature instead of a hidden config file.

• Add remote HTTP endpoints, localhost development endpoints, or stdio command servers from Apps > MCP.
• Store bearer tokens and stdio environment values through OS-backed secure storage.
• Search the MCP Registry and install normalized server definitions into the same save/test/chat path.
• Start from 20 curated presets: Firebase, Figma, Supabase, AWS, GitLab, GitHub MCP, Linear, Stripe, Atlassian, Vercel, Notion, Cloudflare, Context7, Redis, MongoDB, Sentry, Kubernetes, and more.
• Run Test all to refresh cached tool schemas and surface per-server failures.
• Let chat list configured servers, list tool schemas, and call MCP tools when MCP is enabled in tool settings.
• Keep OAuth callback codes, state values, bearer tokens, and env values out of visible chat/tool output.

See MCP Support for setup details, transport notes, Firebase auth guidance, and protocol behavior.

Skills

Skills are reusable instruction bundles that Gilbert can inject only when they match the turn.

• Premade skills include $coding, $frontend, $review, $research, $skill-creator, and $release.
• Apps > Skills can install presets, import a folder containing SKILL.md, create a new custom skill, edit skill metadata/instructions, enable or disable skills, and copy triggers.
• The composer has a skill mention picker, so a user can type $review or $research and select an installed skill directly.
• The runtime can also match enabled skills by description when the prompt clearly fits the workflow.
• Skill instructions are capped for prompt budget so large skill files do not swallow the whole context window.

Plugins

Plugins now have a real directory experience.

• Browse the local first-party plugins plus the upstream marketplace-backed catalog across coding, code intelligence, apps/data, research, design, security, testing, delivery, and authoring.
• Track installed plugins separately from discoverable plugins.
• Inspect components such as Skills, MCP, Agents, Hooks, LSP, and Monitors with permission sensitivity labels.
• Preview a plugin manifest while creating a workspace-local plugin.
• Use OpenAI/Codex marketplace metadata to route plugins toward native app connectors, MCP presets/search, or bundled skill import where supported.
• Default installed plugin concepts include GitHub, Playwright browser automation, Figma, Stripe, and CodeRabbit.

The plugin marketplace is still being polished, but the v0.8.x line moves it out of “idea” territory and into a working foundation for real capability packs.

Product Shape

• Desktop shell: Tauri 2 window, custom chrome, local app metadata, Rust commands, branded installer assets, updater-ready release config, host-aware build/release dispatch, and Windows/macOS/Linux bundle outputs.
• Local users: local account creation and sign-in for namespaced chat, project, settings, Skills, MCP, app-connector, and workspace state.
• Chat workspace: searchable history, pinned chats, generated chat titles, project grouping, markdown rendering, image/file attachments, regeneration, queued sends, targeted stop controls, bulk delete review, 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, empty-response retry handling, and malformed-tool retry guidance.
• Subscription routing: optional local subscription routing for Codex / ChatGPT, Claude Code, Gemini CLI / Cloud Code, GitHub Copilot, and other supported provider accounts, with account sign-in, sign-out, usage visibility, model catalogs, and OpenRouter fallback.
• Skills and plugins: local skill registry, premade/custom/imported skills, plugin catalog, installed-state tracking, OpenAI/Codex marketplace import routes, plugin manifest preview, and component-aware permission language.
• MCP and connected tools: MCP server registry/presets/custom setup, secret headers/query params/env values, credential reuse from Settings > Keys, Gmail, Google Calendar, GitHub, Discord, browser preview, web search, local terminal, local Git, and workspace file actions.
• Image generation: chat can attach generated image artifacts through subscription image routes, with composer controls, progress, image grids, lightbox preview, and downloads.
• Voice input: offline Whisper dictation for desktop builds, bundled model resources, configurable dictation hotkeys, and dictionary entries.
• Source context: DuckDuckGo/Brave-backed source cards, thinking/planning support, browser preview capture, citation-aware web context, and clearer fallback messaging.
• Review posture: destructive chat deletion confirmation, explicit local workspace permission modes, source-write guardrails, connected-tool evidence checks, desktop notification permission checks, Tauri CSP, least-privilege notification capabilities, and visible activity/progress cards.
• Settings: provider key/base URL entry, non-model Keys vault presets for MCP, skills, apps, and services, subscription account setup, subscription model catalogs without a required local API key, GitHub browser login, Google OAuth setup, Discord bridge setup/runtime controls, optional support links, connection validation, appearance mode, UI/chat/composer sizing, motion, voice dictation, model, generation, thinking, workspace, app, plugin, and MCP controls.

Support

Gilbert Codex stays open source and usable without payment. Optional project funding is available through the app’s Fund project page, GitHub’s Sponsor button, and Cash App $kobeelijahh. See Funding Gilbert Codex for the safety rules and hosted-link setup notes.

Coming Next

v0.8.2 keeps hardening the extensible platform. The next work is about making that platform smoother, deeper, and more trustworthy in real daily use.

• Polish the Apps, Skills, and Plugins hub so installed, available, imported, and coming-soon capabilities are easier to scan.
• Deepen the plugin install path beyond the current native/MCP/skill-import routes.
• Improve activity cards so tools, files, approvals, sources, retries, artifacts, and long-running jobs read cleanly.
• Expand provider compatibility tests for subscription routes, image generation, tool schemas, tool-result replay, malformed-call recovery, and streaming edge cases.
• Improve GitHub/source-control UI with richer review cards, diff review, PR handoff, release workflow visibility, and CI status.
• Add stronger model/provider UX: capability badges, context hints, local/cloud filters, provider profiles, and task presets.
• Continue macOS and Linux launch verification, signing/notarization work, installer diagnostics, and public alpha validation notes.

See the full roadmap for the active direction.

Repository Layout

.
|-- .github/               Issue forms, PR template, CODEOWNERS, CI, release workflow, and Dependabot
|-- public/                 Static app assets
|-- docs/                   Project docs, release notes, and publishing checklists
|   |-- INSTALLER.md        Windows customer installer build and release checklist
|   |-- mcp/                MCP setup and protocol notes
|   |-- platform/           Platform support matrix and macOS/Linux port checklist
|   `-- ROADMAP.md          Upcoming product and contributor roadmap
|-- src/                    React frontend
|   |-- app/                App composition, auth, runtime helpers, Tauri clients
|   |-- components/         Reusable UI grouped by product area
|   |-- features/           Plugin catalog, skill mention, and capability feature helpers
|   |-- lib/                Storage, chat helpers, model metadata, context windows
|   |-- pages/              Top-level app surfaces, Apps, Settings, Tasks
|   |-- localWorkspace/     Host-provided workspace context helpers
|   |-- services/           Provider, planning, usage, skills, and web-search clients
|   |-- styles/             CSS split by surface
|   `-- 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, browser, Discord, GitHub, MCP, terminal, web, and workspace commands
|   |-- src/core/           Rust storage, secure-storage, and filesystem helpers
|   `-- 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.

Prerequisites:

• Node.js 18 or newer for the Gilbert app. Node.js 20 or newer is required when installing the local Subscriptions/9Router source runtime.
• Rust and Cargo.
• Microsoft WebView2 Runtime on Windows.
• WebKitGTK runtime/development packages on Linux when running or building the Tauri desktop shell.
• libsecret-tools and a Secret Service provider on Linux for OS-backed secrets.

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
npm test
git diff --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

Build native release bundles on the current host:

npm run app:release
npm run app:release:macos
npm run app:release:linux

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 local Gilbert Database, and 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. Create a GitHub OAuth App with device flow enabled, paste the public Client ID into Settings > GitHub, and sign in from there. No GitHub client secret belongs in the desktop app or release workflow. GitHub actions use the locally stored access token and should remain behind visible review or permission boundaries for high-impact actions.

Gmail and Google Calendar sign-in use Google OAuth for desktop apps. Each user adds their own Google Cloud desktop OAuth Client ID and Client secret in Settings > Google, then installs Gmail or Google Calendar from Apps and chooses a Google account in the browser. No shared Google OAuth client ID, Google access token, refresh token, or downloaded credential file belongs in the repository.

MCP bearer tokens and stdio environment values are stored through the app’s OS-backed secure storage. The React UI and chat tools only see whether a secret exists; they do not receive the secret values back.

Release-only app configuration stays out of the public source tree. The GitHub Release workflow restores private app-only runtime files from a private release overlay before building desktop artifacts, including the private tool bridge and optional plugin bundles. App-user OAuth values, provider keys, local accounts, and support links are not required as release secrets; users configure those inside the installed app.

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 for app updates and chat follow-ups. Bot gateway chat is still future runtime work.

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

Integration Setup

• MCP Support: MCP transports, stdio setup, registry discovery, featured presets, chat tools, and protocol notes.
• Platform support and porting notes: Windows verification status, macOS/Linux port readiness, and the native testing checklist.
• Discord integration setup: Discord application setup, one-click ngrok-backed slash-command bridge setup, bot gateway notes, and incoming webhooks.
• Gmail plugin setup: Google OAuth desktop setup, user connection flow, requested scopes, and Gmail confirmation rules.
• Google OAuth setup: Bring-your-own Google OAuth client setup and production verification notes.
• GitHub integration setup: GitHub OAuth App device-flow setup, requested scopes, Settings sign-in, repository actions, 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, docs/LICENSE_POLICY.md for the license boundary, 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 uses a split license. Implementation code and developer documentation are available under MIT except for Reserved Materials. The Gilbert Codex UI, UX visual design, product identity, brand assets, screenshots, installer artwork, promotional assets, product look and feel, and agent tool system are proprietary and all rights are reserved.

Do not copy, clone, substantially replicate, repackage, or externally integrate the Gilbert Codex UI, branding, or AI tool system without written permission. Gilbert Codex AI tools may be used only through authorized Gilbert Codex builds, authorized project workflows, or separate written permission. See LICENSE and License And UI Protection.