Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ The global engineering instructions in `~/.codex/AGENTS.md` apply in full.

## Required reading: native interactive qualification

[Canonical interactive Xvfb test suite and visual approval matrix](docs/qualification/native-test-suite.md).
[Canonical interactive Xvfb test suite and visual approval matrix](docs/qualification/native-test-suite.md#banner).

## Markdown formatting

Expand Down
33 changes: 17 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<a id="banner"></a>
<!-- snodec:begin header -->
<a name="project-overview"></a>

Expand All @@ -9,7 +10,7 @@
</p>

<!-- snodec:begin organization -->
<p><a href="https://github.com/SNodeC" title="SNode.C organization"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/media/nav/organization-dark.svg"><img align="right" src="docs/media/nav/organization-light.svg" alt="SNode.C organization" title="SNode.C organization" width="160" height="28"></picture></a><br clear="all"></p>
<p><a href="https://github.com/VolkerChristian#banner" title="Volker Christian account"><picture><source media="(max-width: 640px) and (prefers-color-scheme: dark)" srcset="docs/media/nav/account-icon-dark.svg"><source media="(max-width: 640px)" srcset="docs/media/nav/account-icon-light.svg"><source media="(prefers-color-scheme: dark)" srcset="docs/media/nav/account-dark.svg"><img align="right" src="docs/media/nav/account-light.svg" alt="Volker Christian account" title="Volker Christian account"></picture></a><a href="https://github.com/SNodeC#banner" title="SNode.C organization"><picture><source media="(max-width: 640px) and (prefers-color-scheme: dark)" srcset="docs/media/nav/organization-icon-dark.svg"><source media="(max-width: 640px)" srcset="docs/media/nav/organization-icon-light.svg"><source media="(prefers-color-scheme: dark)" srcset="docs/media/nav/organization-dark.svg"><img align="right" src="docs/media/nav/organization-light.svg" alt="SNode.C organization" title="SNode.C organization"></picture></a><a href="#banner" title="CodexUI repository"><picture><source media="(max-width: 640px) and (prefers-color-scheme: dark)" srcset="docs/media/nav/repository-icon-dark.svg"><source media="(max-width: 640px)" srcset="docs/media/nav/repository-icon-light.svg"><source media="(prefers-color-scheme: dark)" srcset="docs/media/nav/repository-dark.svg"><img align="right" src="docs/media/nav/repository-light.svg" alt="CodexUI repository" title="CodexUI repository"></picture></a><br clear="all"></p>
<!-- snodec:end organization -->

# Codex(W)UI
Expand All @@ -26,13 +27,13 @@

**Follow the work, not just the final answer.** Codex(W)UI offers two frontends: **CodexUI**, a native Qt desktop application, and **CodexWUI**, a browser application connecting over WebSocket. They bring conversations, commands, plans, approvals and file changes into a visual coding workspace.

Built on [AISuite](https://github.com/SNodeC/AISuite#project-overview) and [SNode.C](https://github.com/SNodeC/snode.c#project-overview), both frontends connect through AISuite's `codex-bridge`. Codex app-server remains responsible for agent execution and persistent history; both applications give you the controls and visibility around it.
Built on [AISuite](https://github.com/SNodeC/AISuite#banner) and [SNode.C](https://github.com/SNodeC/snode.c#banner), both frontends connect through AISuite's `codex-bridge`. Codex app-server remains responsible for agent execution and persistent history; both applications give you the controls and visibility around it.

<!-- snodec:begin menu -->
<p>
<a href="#quick-start" title="Start"><img src="docs/media/menu/start.svg" alt="Start" width="160" height="28"></a>
<a href="#install" title="Install"><img src="docs/media/menu/install.svg" alt="Install" width="160" height="28"></a>
<a href="docs/guides/build-from-source.md#page-overview" title="Build"><img src="docs/media/menu/build.svg" alt="Build" width="160" height="28"></a>
<a href="docs/guides/build-from-source.md#banner" title="Build"><img src="docs/media/menu/build.svg" alt="Build" width="160" height="28"></a>
<a href="#first-run" title="Use"><img src="docs/media/menu/use.svg" alt="Use" width="160" height="28"></a>
<a href="#configuration" title="Configure"><img src="docs/media/menu/configure.svg" alt="Configure" width="160" height="28"></a>
<a href="#architecture" title="Architecture"><img src="docs/media/menu/architecture.svg" alt="Architecture" width="160" height="28"></a>
Expand Down Expand Up @@ -72,7 +73,7 @@ In the native threads panel, **projects contain the visual grouping; sections or

To create a project or section, click the current grouping label—**Projects**, **Sections** or **Ungrouped**—above the thread list. Use a thread's context menu to assign its project and section. Creation and assignment require controller access and server support.

Next: [read the grouping and lifecycle guide](docs/guides/thread-projects.md#page-overview).
Next: [read the grouping and lifecycle guide](docs/guides/thread-projects.md#banner).

### Choose your frontend

Expand All @@ -98,7 +99,7 @@ Build [native Qt desktop](docs/guides/build-from-source.md#native-desktop) or [b

### Native desktop

**You need:** the native build, a configured Codex executable available to the bridge user, and AISuite's `codex-bridge`. The bridge's generated protocol targets Codex 0.162.1; use the [AISuite entry page](https://github.com/SNodeC/AISuite#project-overview) to check compatibility before changing Codex versions.
**You need:** the native build, a configured Codex executable available to the bridge user, and AISuite's `codex-bridge`. The bridge's generated protocol targets Codex 0.162.1; use the [AISuite entry page](https://github.com/SNodeC/AISuite#banner) to check compatibility before changing Codex versions.

Start `codex-bridge --config-file /dev/null` as your own user in one terminal. In a second terminal, run from this checkout:

Expand Down Expand Up @@ -144,30 +145,30 @@ The bridge allows multiple frontends to follow the same app-server session, with

On the native side, a SNode.C worker owns protocol processing and writes one shared `NodeGraph`; Qt projects that state into widgets. The browser uses AISuite's TypeScript SDK and its own presentation state. Neither frontend replaces app-server's persistent history or tool execution.

For the detailed state, threading and protocol boundaries, see the [architecture guide](docs/architecture/overview.md#page-overview).
For the detailed state, threading and protocol boundaries, see the [architecture guide](docs/architecture/overview.md#banner).

## Documentation

Manual CI builds and qualifies the desktop and browser editions, including shared verification and frontend SDK checks. See the organization [workflow graph](https://github.com/SNodeC/.github/blob/main/docs/workflow-graph.md#page-overview) for triggers and artifact boundaries.
Manual CI builds and qualifies the desktop and browser editions, including shared verification and frontend SDK checks. See the organization [workflow graph](https://github.com/SNodeC/.github/blob/main/docs/workflow-graph.md#banner) for triggers and artifact boundaries.

[Documentation index](docs/README.md#page-overview): guides, architecture, qualification and engineering records for CodexUI.
[Documentation index](docs/README.md#banner): guides, architecture, qualification and engineering records for CodexUI.

| Start here | Go deeper |
| --- | --- |
| [Using CodexUI](docs/guides/interaction-guide.md#page-overview) | [Native state and threading](docs/architecture/shared-node-graph.md#page-overview) |
| [Projects and sections](docs/guides/thread-projects.md#page-overview) | [Architecture overview](docs/architecture/overview.md#page-overview) |
| [Timestamps and durations](docs/architecture/timestamp-presentation.md#page-overview) | [Browser contract](docs/web/contract-1.0.md#page-overview) |
| [Browser build and deployment](web/README.md#page-overview) | [Web qualification](docs/web/qualification.md#page-overview) · [Release process](docs/web/release-process.md#page-overview) |
| [Using CodexUI](docs/guides/interaction-guide.md#banner) | [Native state and threading](docs/architecture/shared-node-graph.md#banner) |
| [Projects and sections](docs/guides/thread-projects.md#banner) | [Architecture overview](docs/architecture/overview.md#banner) |
| [Timestamps and durations](docs/architecture/timestamp-presentation.md#banner) | [Browser contract](docs/web/contract-1.0.md#banner) |
| [Browser build and deployment](web/README.md#banner) | [Web qualification](docs/web/qualification.md#banner) · [Release process](docs/web/release-process.md#banner) |

For bug reports, include the revision, Qt version, connection type and the smallest reproducible sequence. Remove credentials and private conversation content from logs and screenshots.

## Platforms

The documented native platform is Linux with Qt 6.6+ Widgets. Browser frontend scope, coverage and limitations are defined by the [browser contract](docs/web/contract-1.0.md#page-overview); they are not a promise of native/browser feature parity. Review the [known limitations](docs/guides/interaction-guide.md#known-limitations) before relying on approval handling or native performance.
The documented native platform is Linux with Qt 6.6+ Widgets. Browser frontend scope, coverage and limitations are defined by the [browser contract](docs/web/contract-1.0.md#banner); they are not a promise of native/browser feature parity. Review the [known limitations](docs/guides/interaction-guide.md#known-limitations) before relying on approval handling or native performance.

## Releases

No GitHub release or shared binary-package distribution is published yet; the documented installation routes build from source. Future release notes belong on the [releases page](https://github.com/SNodeC/CodexUI/releases). The [web release process](docs/web/release-process.md#page-overview) describes development qualification, not a downloadable product release.
No GitHub release or shared binary-package distribution is published yet; the documented installation routes build from source. Future release notes belong on the [releases page](https://github.com/SNodeC/CodexUI/releases). The [web release process](docs/web/release-process.md#banner) describes development qualification, not a downloadable product release.

## Contributing

Expand All @@ -178,13 +179,13 @@ No GitHub release or shared binary-package distribution is published yet; the do
<!-- snodec:begin ecosystem -->
## Ecosystem

Depends on [AISuite](https://github.com/SNodeC/AISuite#project-overview) and [SNode.C](https://github.com/SNodeC/snode.c#project-overview)
Depends on [AISuite](https://github.com/SNodeC/AISuite#banner) and [SNode.C](https://github.com/SNodeC/snode.c#banner)
<!-- snodec:end ecosystem -->

<!-- snodec:begin footer -->
Choose either [MIT](LICENSE-MIT) or [LGPL-3.0-or-later](LICENSE-LGPL-3.0-or-later).

Built with [Qt](https://www.qt.io/). Codex(W)UI is an independent project; neither frontend is an official OpenAI application.

Maintainer: [Volker Christian](https://github.com/VolkerChristian). [Organization](https://github.com/SNodeC) · [Contributing](#contributing) · [Security](https://github.com/SNodeC/.github/blob/main/SECURITY.md)
Maintainer: [Volker Christian](https://github.com/VolkerChristian#banner). [Organization](https://github.com/SNodeC#banner) · [Contributing](#contributing) · [Security](https://github.com/SNodeC/.github/blob/main/SECURITY.md)
<!-- snodec:end footer -->
56 changes: 28 additions & 28 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<!-- snodec:begin page-header -->
<a id="page-overview"></a>
<a id="banner"></a><a id="page-overview"></a>
<p><picture><source media="(max-width: 640px)" srcset="media/nav/banner-documentation-compact.svg"><img src="media/nav/banner-documentation.svg" alt="CodexUI — Documentation" width="100%"></picture></p>
<p><a href="../README.md#project-overview" title="Up to CodexUI"><picture><source media="(prefers-color-scheme: dark)" srcset="media/nav/up-codexui-dark.svg"><img src="media/nav/up-codexui-light.svg" alt="Up to CodexUI" title="Up to CodexUI" width="160" height="28"></picture></a><a href="https://github.com/SNodeC" title="SNode.C organization"><picture><source media="(max-width: 640px) and (prefers-color-scheme: dark)" srcset="media/nav/organization-icon-dark.svg"><source media="(max-width: 640px)" srcset="media/nav/organization-icon-light.svg"><source media="(prefers-color-scheme: dark)" srcset="media/nav/organization-dark.svg"><img align="right" src="media/nav/organization-light.svg" alt="SNode.C organization" title="SNode.C organization"></picture></a><a href="../README.md#project-overview" title="CodexUI repository"><picture><source media="(max-width: 640px) and (prefers-color-scheme: dark)" srcset="media/nav/repository-icon-dark.svg"><source media="(max-width: 640px)" srcset="media/nav/repository-icon-light.svg"><source media="(prefers-color-scheme: dark)" srcset="media/nav/repository-dark.svg"><img align="right" src="media/nav/repository-light.svg" alt="CodexUI repository" title="CodexUI repository"></picture></a><br clear="all"></p>
<p><a href="../README.md#banner" title="Up to CodexUI"><picture><source media="(prefers-color-scheme: dark)" srcset="media/nav/up-codexui-dark.svg"><img src="media/nav/up-codexui-light.svg" alt="Up to CodexUI" title="Up to CodexUI" width="160" height="28"></picture></a><a href="https://github.com/VolkerChristian#banner" title="Volker Christian account"><picture><source media="(max-width: 640px) and (prefers-color-scheme: dark)" srcset="media/nav/account-icon-dark.svg"><source media="(max-width: 640px)" srcset="media/nav/account-icon-light.svg"><source media="(prefers-color-scheme: dark)" srcset="media/nav/account-dark.svg"><img align="right" src="media/nav/account-light.svg" alt="Volker Christian account" title="Volker Christian account"></picture></a><a href="https://github.com/SNodeC#banner" title="SNode.C organization"><picture><source media="(max-width: 640px) and (prefers-color-scheme: dark)" srcset="media/nav/organization-icon-dark.svg"><source media="(max-width: 640px)" srcset="media/nav/organization-icon-light.svg"><source media="(prefers-color-scheme: dark)" srcset="media/nav/organization-dark.svg"><img align="right" src="media/nav/organization-light.svg" alt="SNode.C organization" title="SNode.C organization"></picture></a><a href="../README.md#banner" title="CodexUI repository"><picture><source media="(max-width: 640px) and (prefers-color-scheme: dark)" srcset="media/nav/repository-icon-dark.svg"><source media="(max-width: 640px)" srcset="media/nav/repository-icon-light.svg"><source media="(prefers-color-scheme: dark)" srcset="media/nav/repository-dark.svg"><img align="right" src="media/nav/repository-light.svg" alt="CodexUI repository" title="CodexUI repository"></picture></a><br clear="all"></p>
<!-- snodec:end page-header -->

# Codex(W)UI documentation
Expand All @@ -10,7 +10,7 @@
<p>
<a href="../README.md#quick-start" title="Start"><img src="media/menu/start.svg" alt="Start" width="160" height="28"></a>
<a href="../README.md#install" title="Install"><img src="media/menu/install.svg" alt="Install" width="160" height="28"></a>
<a href="guides/build-from-source.md#page-overview" title="Build"><img src="media/menu/build.svg" alt="Build" width="160" height="28"></a>
<a href="guides/build-from-source.md#banner" title="Build"><img src="media/menu/build.svg" alt="Build" width="160" height="28"></a>
<a href="../README.md#first-run" title="Use"><img src="media/menu/use.svg" alt="Use" width="160" height="28"></a>
<a href="../README.md#configuration" title="Configure"><img src="media/menu/configure.svg" alt="Configure" width="160" height="28"></a>
<a href="../README.md#architecture" title="Architecture"><img src="media/menu/architecture.svg" alt="Architecture" width="160" height="28"></a>
Expand All @@ -24,39 +24,39 @@ Start with the [repository README](../README.md#quick-start) for a first working
## Sections

<!-- snodec:begin section-pages -->
- [Architecture](architecture/README.md#page-overview)
- [Guides](guides/README.md#page-overview)
- [Qualification](qualification/README.md#page-overview)
- [Records](records/README.md#page-overview)
- [UI review](ui-review/README.md#page-overview)
- [Web UI](web/README.md#page-overview)
- [Architecture](architecture/README.md#banner)
- [Guides](guides/README.md#banner)
- [Qualification](qualification/README.md#banner)
- [Records](records/README.md#banner)
- [UI review](ui-review/README.md#banner)
- [Web UI](web/README.md#banner)
<!-- snodec:end section-pages -->

## User guides and references

- [Build and install from source](guides/build-from-source.md#page-overview)
- [Using CodexUI](guides/interaction-guide.md#page-overview)
- [Projects and sections](guides/thread-projects.md#page-overview)
- [Architecture overview](architecture/overview.md#page-overview)
- [Timestamp presentation](architecture/timestamp-presentation.md#page-overview)
- [Browser contract](web/contract-1.0.md#page-overview)
- [Browser build and deployment](../web/README.md#page-overview)
- [Web release process](web/release-process.md#page-overview)
- [Build and install from source](guides/build-from-source.md#banner)
- [Using CodexUI](guides/interaction-guide.md#banner)
- [Projects and sections](guides/thread-projects.md#banner)
- [Architecture overview](architecture/overview.md#banner)
- [Timestamp presentation](architecture/timestamp-presentation.md#banner)
- [Browser contract](web/contract-1.0.md#banner)
- [Browser build and deployment](../web/README.md#banner)
- [Web release process](web/release-process.md#banner)

## Design and engineering records

These documents describe implementation decisions, qualification scope or historical evidence; they are not prerequisites for first use and do not establish that current builds passed every check.

- [Native state and threading](architecture/shared-node-graph.md#page-overview)
- [Web qualification](web/qualification.md#page-overview)
- [Interactive qualification inventory](qualification/native-test-suite.md#page-overview)
- [Qualification execution record](qualification/native-results-2026-09-27.md#page-overview)
- [Native architecture audit](architecture/qt-ui-audit.md#page-overview)
- [Virtualized conversation view](architecture/qt-virtualized-conversation-view.md#page-overview)
- [Internal UI APIs](architecture/ui-internal-api.md#page-overview)
- [Thread projects verification](records/thread-projects-verification.md#page-overview)
- [Timestamp verification](records/timestamp-verification.md#page-overview)
- [Codex 0.162.1 migration inventory](records/codex-0.162.1-migration-inventory.md#page-overview)
- [Codex 0.162.1 local migration results](records/codex-0.162.1-migration-results.md#page-overview)
- [Native state and threading](architecture/shared-node-graph.md#banner)
- [Web qualification](web/qualification.md#banner)
- [Interactive qualification inventory](qualification/native-test-suite.md#banner)
- [Qualification execution record](qualification/native-results-2026-09-27.md#banner)
- [Native architecture audit](architecture/qt-ui-audit.md#banner)
- [Virtualized conversation view](architecture/qt-virtualized-conversation-view.md#banner)
- [Internal UI APIs](architecture/ui-internal-api.md#banner)
- [Thread projects verification](records/thread-projects-verification.md#banner)
- [Timestamp verification](records/timestamp-verification.md#banner)
- [Codex 0.162.1 migration inventory](records/codex-0.162.1-migration-inventory.md#banner)
- [Codex 0.162.1 local migration results](records/codex-0.162.1-migration-results.md#banner)

[Media assets](media/README.md).
Loading