DOCSEARCHbyAlgolia
Submit Docs

codexapp Documentation

repository·main·Indexed 20 days ago

https://github.com/friuns2/codex-mobile

A lightweight web interface and bridge for Codex app-server workflows, enabling remote access to the Codex desktop experience via a browser on Linux, Windows, and Android (via Termux). It includes features for Cloudflare tunneling, Tailscale integration, a Telegram bot bridge for thread management, and project import/export via ZIP files. The documentation also covers the App Server protocol schemas and the LLM Wiki pattern for building persistent knowledge bases.

Tokens
41.6K
Snippets
45
Records
123
Agent score
72%

What's inside codexapp

  3. Project Structure and Module Organization

    main

    The project is organized into several key directories:

    • src/api/: Contains the backend communication layer, including codexGateway.ts (high-level API for threads, turns, and models), codexRpcClient.ts (HTTP/SSE transport), and DTO normalizers.
    • src/components/: UI components categorized by content/ (conversation and composer), sidebar/ (thread trees), layout/ (desktop layout), and icons/.
    • src/composables/: Contains useDesktopState.ts, the central reactive state manager.
    • src/server/: The Node.js server implementation, including the codexAppServerBridge.ts (spawns/proxies the app-server), httpServer.ts, and authMiddleware.ts.
    • src/cli/: The CLI entry point using Commander.
    • documentation/: Contains the full APP_SERVER_DOCUMENTATION.md protocol reference and materialized JSON/TypeScript schemas for the app-server protocol.

  4. How the realtime sync model manages updates

    main

    The application uses a tiered update strategy to prevent full thread refreshes from competing with realtime rendering:

    • item/* events: Used for high-frequency updates to live assistant text, command output, reasoning, file changes, or plan state. These update the UI locally without a full refresh.
    • Message refresh: Reserved for structural lifecycle events: turn/started, turn/completed, and error.
    • Thread list refresh: Reserved for thread/* events and turn/completed.
    • Background thread pagination: Automatically pauses while turns are active and resumes once the turn is complete.

  5. Architecture of codex-web-local

    main

    The codex-web-local project is a browser-based web UI for OpenAI Codex that enables remote access to a local Codex instance. It follows a three-tier architecture:

    1. Browser (Vue 3 SPA): A single-page application using Vue 3, Vue Router, and Tailwind CSS. It communicates with the server via an API layer (codexGateway and codexRpcClient) and manages state through a central composable (useDesktopState).
    2. Node.js Server: An Express-based server that acts as a bridge. It handles authentication (password/cookie) and hosts the Codex Bridge at the /codex-api/* endpoint.
    3. Codex app-server: A child process spawned by the Node.js server. Communication between the Node.js bridge and the app-server occurs via JSON-RPC over newline-delimited I/O (stdin/stdout).

    Realtime Transport: The client uses WebSockets on /codex-api/ws for server-to-client notifications, with an automatic fallback to SSE (EventSource) on /codex-api/events. Client-to-server RPC calls are performed via HTTP POST.

    ┌──────────────────────────────────────────────────────────┐
│  Browser (Vue 3 SPA)                                     │
│  ┌────────────┐  ┌──────────────┐  ┌──────────────────┐ │
│  │ App.vue     │  │ Composables  │  │ API Layer        │ │
│  │ (Router)    │──│ useDesktop   │──│ codexGateway     │ │
│  │             │  │ State        │  │ codexRpcClient   │ │
│  └─────────────┘  └──────────────┘  └────────┬─────────┘ │
└─────────────────────────────────────────────┼───────────┘
                                              │ HTTP/SSE
┌─────────────────────────────────────────────┼───────────┐
│  Node.js Server                             │           │
│  ┌──────────────────────────────────────────┼─────────┐ │
│  │ Express / Vite Middleware               │         │ │
│  │  ┌───────────────────┐  ┌───────────────┴───────┐ │ │
│  │  │ Auth Middleware    │  │ Codex Bridge          │ │ │
│  │  │ (password, cookie) │  │ /codex-api/*          │ │ │
│  │  └───────────────────┘  └───────────┬───────────┘ │ │
│  └─────────────────────────────────────┼─────────────┘ │
│                                        │ stdin/stdout    │
│  ┌─────────────────────────────────────┼─────────────┐ │
│  │ codex app-server (child process)   │             │ │
│  │ JSON-RPC over newline-delimited I/O │           │ │
│  └───────────────────────────────────┴─────────────┘ │
└──────────────────────────────────────────────────────────┘

  6. Follow the Merge-to-main workflow for feature integration

    main

    The project uses a disciplined merge-to-main workflow to integrate feature branches into the local main branch. This pattern ensures explicit integration points and prevents silent regressions through manual conflict resolution and verification.

    To follow this workflow:

    1. Use explicit merges: Use the --no-ff flag when merging feature branches into main to create a merge commit, providing a clear integration point in the history.
    2. Resolve conflicts manually: When conflicts arise, resolve them on a per-file basis. Avoid using blanket strategies like ours or theirs which can lead to data loss or regressions.
    3. Verify the build: Before finalizing the merge, run focused verification commands to ensure the integration hasn't broken the project:
      • build:frontend (for frontend changes)
      • build:cli (for CLI changes)
    4. Push to remote: Only push the main branch to the remote repository after all verification steps have passed successfully.
    # Example workflow steps
git checkout main
git merge --no-ff feature-branch-name
# ... resolve conflicts manually ...
npm run build:frontend
npm run build:cli
git push origin main

  7. Understand Thread Heartbeat Automations

    main

    Thread heartbeat automations are local Codex automation records that allow automated tasks to be attached to specific chat threads. Each automation is stored as a local record under $CODEX_HOME/automations/<automation-id>/automation.toml and is linked to a chat thread via the target_thread_id field.

    Key characteristics:

    • Multiple Automations: A single thread can have multiple heartbeat automations attached to it. The backend manages these as an ordered array mapped to the thread ID.
    • Independent Management: Because operations (edit/delete) require both threadId and automationId, you can manage or remove one automation without affecting others on the same thread.
    • UI Integration: The sidebar thread menu displays a Manage automations... option whenever at least one automation is attached to the current thread.

  8. Optimize Realtime Chat Rendering Performance

    main

    To prevent expensive re-evaluations of markdown parsing, inline parsing, and syntax highlighting during streaming assistant text updates, ThreadConversation.vue implements a multi-layered caching strategy.

    Key caching mechanisms include:

    • Message Blocks: Cached by message id, text, and cwd.
    • Inline Segments: Cached by source text.
    • Rendered Markdown HTML: Cached by cwd, text, and highlighter version.
    • Highlighted Code HTML: Cached by highlighter version, language, and code.

    Additionally, normal message text flow utilizes Vue v-memo keyed by message id, message text, cwd, highlighter version, and markdown-image failure version to minimize re-renders.

  9. How the Unified Proxy Flow works

    main

    The proxy acts as a compatibility adapter to ensure Codex always receives Responses-shaped responses. The high-level flow is:

    1. Receive: The proxy reads an incoming Responses request from Codex.
    2. Authenticate: It loads the real provider bearer token and the selected wireApi (Responses or Chat).
    3. Translate (Request):
      • If in Responses mode, it sends the payload as-is.
      • If in Completions mode, it converts the payload to Chat Completions format.
    4. Upstream Call: Sends the request to the provider.
    5. Translate (Response): If the upstream used Chat Completions, the proxy converts the response back to the Responses format (mapping choices[].message.content to output[].type = "message", etc.).
    6. Return: Returns the status, body, and errors to Codex.

  10. Understand the Skills route UI structure

    main

    The application's directory-related navigation has been rebranded to Skills.

    UI Components:

    • Sidebar Link: Now a prominent destination card featuring an accent icon, the primary title Skills, and the subtitle Plugins, apps, MCPs.
    • Route Header: Displays a large Skills title with a matching accent icon.
    • Internal Page Title: The DirectoryHub component still uses the title Skills & Apps internally.

    This change consolidates Plugins, Apps, and MCPs (Model Context Protocol) under a single unified 'Skills' concept.

  11. Navigating the Wiki with index.md and Git

    main

    As the wiki grows, use these two mechanisms for navigation and history:

    • index.md: A content-oriented catalog. It lists every page with a link, a one-line summary, and optional metadata (date, source count). The LLM updates this on every ingest and uses it as the primary way to find relevant pages before drilling into them.
    • Git history: A chronological record. Commit all wiki changes with clear messages. The Git history serves as the timeline for all ingests, queries, and maintenance tasks, replacing the need for an internal changelog.