CodexGui

Native Avalonia desktop client for the Codex app-server protocol.

CodexGui brings a Codex-style workspace to a desktop-native .NET application. The repository combines a typed app-server transport, an interactive Avalonia shell, and a modular markdown rendering stack for rich conversation, diff, and document surfaces.

Status: active development. The current codebase already supports interactive sessions, turn authoring, pending approvals, rich item detail panes, and both local stdio and remote WebSocket app-server connections.

Highlights

• Native Avalonia shell with a left navigation rail, thread sidebar, center conversation stream, right detail pane, and bottom terminal strip.
• Local process transport using codex app-server, plus remote ws:// and wss:// app-server endpoint support.
• Strict initialize / initialized lifecycle handling with typed protocol models generated from OpenAPI via NSwag.
• Live workspace snapshots for accounts, models, threads, skills, apps, and runtime requirements.
• Turn workflows built on thread/start, thread/resume, turn/start, and turn/interrupt.
• Interactive approval and user-input surfaces for commands, file changes, and dynamic tool calls.
• Rich markdown-based detail rendering backed by a reusable plugin ecosystem for alerts, figures, footers, math, Mermaid diagrams, syntax highlighting, and more.

Solution map

| Project | Responsibility | | --- | --- | | src/CodexGui.App | Main Avalonia desktop application, shell layout, MVVM view models, and session orchestration. | | src/CodexGui.AppServer | Typed JSON-RPC transport layer for local process and remote WebSocket connections. | | src/CodexGui.Markdown | Core markdown rendering and editing services built on Avalonia and Markdig. | | src/CodexGui.Markdown.Plugin.* | Feature plugins for alerts, custom containers, definition lists, figures, footers, math, Mermaid, syntax highlighting, and TextMate integration. | | src/CodexGui.Markdown.Sample | Standalone sample application for exploring the markdown stack in isolation. |

NuGet packages

| Package | Version | Downloads | Notes | | --- | --- | --- | --- | | CodexGui.App | | | .NET tool package for launching the Avalonia desktop client via codexgui. | | CodexGui.AppServer | | | Typed client transport and protocol models for Codex app-server connections. | | CodexGui.Markdown | | | Core Avalonia markdown rendering and editing package. | | CodexGui.Markdown.Plugin.Alerts | | | Alert block support for the markdown stack. | | CodexGui.Markdown.Plugin.CustomContainers | | | Generic custom-container parsing and rendering support. | | CodexGui.Markdown.Plugin.DefinitionLists | | | Definition list support for the markdown stack. | | CodexGui.Markdown.Plugin.Figures | | | Figure block parsing and rendering support. | | CodexGui.Markdown.Plugin.Footers | | | Footer block support for reusable markdown surfaces. | | CodexGui.Markdown.Plugin.Math | | | Inline and block math support. | | CodexGui.Markdown.Plugin.Mermaid | | | Mermaid diagram support for markdown documents. | | CodexGui.Markdown.Plugin.SyntaxHighlighting | | | Built-in code syntax highlighting support. | | CodexGui.Markdown.Plugin.TextMate | | | TextMate-backed highlighting and editor integration. |

Tech stack

• .NET 10
• Avalonia 11
• CommunityToolkit.Mvvm
• NSwag-generated protocol DTOs
• Markdig-based markdown pipeline

Getting started

Prerequisites

• .NET 10 SDK
• A local codex executable on your PATH if you want to use the default process transport

Build the solution

dotnet build CodexGui.slnx

Run the desktop app

dotnet run --project src/CodexGui.App/CodexGui.App.csproj

When the app opens, the default connection settings target a local codex app-server process. You can also point the connection panel at a remote ws:// or wss:// endpoint if you already have an app-server running elsewhere.

Run the markdown sample

dotnet run --project src/CodexGui.Markdown.Sample/CodexGui.Markdown.Sample.csproj

Use the sample app to inspect the reusable markdown editor and preview pipeline outside the main Codex workspace shell.

Documentation

Project documentation now lives under site/ and is built with Lunet for GitHub Pages deployment.

Build docs locally

dotnet tool restore
bash ./check-docs.sh

Serve docs locally

bash ./serve-docs.sh

The repository also includes PowerShell equivalents: ./build-docs.ps1, ./check-docs.ps1, and ./serve-docs.ps1.

GitHub Actions

• .github/workflows/build.yml validates the solution build, test baseline, Lunet docs generation, and NuGet package creation.
• .github/workflows/docs.yml deploys the site/ output to GitHub Pages.
• .github/workflows/release.yml builds tagged releases, packs the reusable libraries, publishes NuGet packages, and creates the GitHub release entry.

What ships today

• Codex-style desktop workspace chrome and thread inspection flows
• Live protocol notification rendering and transport activity feed
• Rich center-pane cards for commands, diffs, plans, reasoning, and tool-call items
• Right-pane detail rendering driven by the selected conversation item
• Pending approval cards for command execution, file changes, and dynamic tool interactions
• Modular markdown rendering infrastructure that can be reused independently of the main app

Roadmap

CodexGui is currently in the parity-building phase. The implemented shell and transport foundations are in place, while the remaining work is focused on deeper Codex app parity.

Current gaps called out in the repository include:

• review mode workflows
• thread forking and rollback polish
• auth management and ChatGPT token refresh handling
• broader app and skill administration surfaces
• full parity for remaining server-request types

For the active roadmap and design direction, see docs/implementation-plan.md. The docs/ directory also contains detailed markdown subsystem plans and feature notes.

License

MIT. See LICENSE.