Skip to content
/
Tier A A16 Cross-vendor router

Codexia

codexia · milisp/codexia · ★ 690 · last commit 2026-05-23

Primitive shape
No installable primitives
00

Summary

codexia — Summary

Elevator pitch: A Tauri v2 desktop application (macOS/Linux/Windows) that acts as an integrated workstation for Codex CLI and Claude Code, providing a visual IDE-like interface, task scheduler, git worktree management, remote-control web server, and agent skills marketplace in a single binary. Built with React + TypeScript + shadcn/ui frontend and Rust (Axum) backend, it exposes a REST API + WebSocket stream that enables headless/remote operation from browsers or scripts. Codex plays the worker role (session/turn lifecycle controlled via codex app-server JSON-RPC integration); Claude Code is integrated via the claude-agent-sdk-rs Rust binding. AGPL-3.0 licensed with a commercial dual-license option. Compared to seeds: unlike any seed framework (which are all CLI/plugin installations), codexia is the only desktop GUI application in this batch and among the most ambitious in the full corpus — it adds a local browser-accessible API that makes Codex and Claude Code remotely drivable.

01

Overview

codexia — Overview

Origin

By milisp. Version 0.33.0. AGPL-3.0 (open source) with commercial dual-license. 690 stars, 68 forks. Active: last commit 2026-05-23. 6 contributors.

Philosophy

"Agent Workstation for Codex CLI + Claude Code — with task scheduler, git worktree & remote control, skills management"

The project positions itself as a workstation layer above both CLIs — providing the visual control plane, scheduling, and remote-access that neither CLI offers natively.

Core Features

  • Agent workflows: Task Scheduler for recurring jobs, remote control via headless web server
  • Workspace: Git worktree management, project file tree, IDE-like editor, prompt notepad, local web preview
  • Data tools: One-click PDF / XLSX / CSV preview
  • Ecosystem: MCP server marketplace, agent skills marketplace
  • Personalization: Theme and accent customization, usage analytics dashboard

Key Architectural Claim

"Codex app-server integration" — Codexia connects to Codex via the app-server JSON-RPC protocol, giving it programmatic access to session and turn lifecycle events, not just CLI invocation.

"Claude agent rust sdk integration" — Direct integration via claude-agent-sdk-rs for Claude Code control.

Security Model (verbatim)

"Process isolation: Agents run in separate processes. Permission control: Configure file and network access per agent. Local storage: All data stays on your machine."

Commercial Licensing

AGPL-3.0 for open source use; commercial license required for closed-source or SaaS deployments. This is the only framework in this batch with a dual-license model.

02

Architecture

codexia — Architecture

Distribution

  • Type: Desktop application (Tauri v2)
  • Binary: Homebrew cask or prebuilt release
  • Version: 0.33.0
  • License: AGPL-3.0 + Commercial dual-license

Install

# macOS via Homebrew:
brew tap milisp/codexia
brew install --cask codexia

# Prebuilt releases: GitHub Releases (macOS/Linux/Windows)

Required Runtime

  • Codex CLI (codex app-server support required)
  • Claude Code CLI (claude)
  • macOS / Linux / Windows (macOS primary)

Technology Stack

Layer Technology
Desktop backend Tauri v2 + Rust
Web backend Axum (HTTP web server, part of Tauri app)
Frontend React + TypeScript + Zustand + shadcn/ui
Build Bun + Vite
State management Zustand with persistence
Agent runtimes codex app-server (JSON-RPC) + claude-agent-sdk-rs

Core Entry Points

  • src-tauri/src/lib.rs — desktop commands and state
  • src-tauri/src/web/server.rs — headless server startup
  • src-tauri/src/web/router.rs — HTTP API route surface (~80+ routes)
  • src/services/tauri/ — frontend invoke layer

API Surface (when running in headless/web mode)

Category Endpoints
Health/stream GET /health, GET /ws (WebSocket)
Codex lifecycle /api/codex/thread/*, /api/codex/turn/*, /api/codex/model/*, /api/codex/approval/*
Automation /api/automation/* (CRUD + run/pause)
Files/git/terminal /api/filesystem/*, /api/git/*, /api/terminal/*
Claude integration /api/cc/*
Notes /api/notes/*

Target AI Tools

  • Primary: Codex CLI (via app-server JSON-RPC)
  • Integrated: Claude Code (via claude-agent-sdk-rs)
  • Optional: P2P/STUN for mobile-to-desktop remote control
03

Components

codexia — Components

Desktop Application Views

View Purpose
Agent Command Center Main control plane — session management, prompt input, output display
Task Scheduler Create/edit/run/pause recurring automation jobs
Git Worktree Manager Create, switch, apply changes across worktrees
IDE-like Editor Project file tree + edit capabilities
Prompt Notepad Save and reuse prompts
MCP Marketplace Browse and install MCP servers
Skills Marketplace Browse and install agent skills
Usage Analytics Token usage and session analytics dashboard
Data Viewer PDF, XLSX, CSV one-click preview

HTTP API Endpoint Groups (~80+ routes)

Group Key Endpoints
Codex Threads api_start_thread, api_resume_thread, api_rollback_thread, api_fork_thread, api_list_threads
Codex Turns api_turn_start, api_turn_interrupt
Codex Approvals api_respond_command_execution_approval, api_respond_file_change_approval, api_respond_user_input
Claude CC Sessions api_cc_new_session, api_cc_resume_session, api_cc_send_message, api_cc_interrupt
Automation api_create_automation, api_run_automation_now, api_set_automation_paused
Git api_git_create_worktree, api_git_apply_worktree_changes, api_git_commit, api_git_push
Skills api_skills_list, api_skills_install_marketplace, api_skills_link_to_agent

Subagents

None in the framework itself. Codex and Claude Code run as external processes.

Hooks

None (framework-level). The Tauri app manages lifecycle via OS events.

Chat Integration

  • Discord (bots/discord/)
  • Telegram (bots/telegram/)

These provide persistent multi-device chat access to the CAR-like control plane.

P2P Support

iOS-to-desktop remote control via STUN (src-tauri/src/p2p/).

05

Prompts

codexia — Prompts

Codexia is a GUI/runtime harness, not a prompt framework. It does not ship prompt files, skills, or behavioral instructions for the AI agent. The prompts are entirely user-provided through the Prompt Notepad or the Agent Command Center input field.

AGENTS.md (verbatim — developer context, not user prompts)

Source: AGENTS.md (project development guidance for contributors)

## Project Info
- Agent os for `codex cli` and `claude code cli` - agent
- use `codex app-server` and `claude-agent-sdk-rs` to connect Codexia

### Project tech
- Package manager: bun
- Framework: React + shadcn + tailwindcss + TypeScript + Tauri v2
- Don't use emit_all
- UI: use shadcn UI components first, Button, Input, etc.
- code comment language: English-only
- Zustand: for state management with persistence

Prompting technique: This is developer documentation, not user prompt content. The AGENTS.md is used to guide AI coding assistants working on Codexia itself, not to control what Codexia does during agent sessions.

Prompt Notepad

The Prompt Notepad feature allows users to save and reuse custom prompts. These are stored locally (no templates shipped by the framework).

Key Observation

Codexia's value proposition is the runtime harness (scheduling, remote control, worktree management, approval UX) rather than behavioral prompt engineering. It delegates all AI behavior decisions to the underlying Codex and Claude Code CLIs.

09

Uniqueness

codexia — Uniqueness

differs_from_seeds

No seed framework is a desktop GUI application. The closest seed is claude-flow (most feature-complete framework with SQLite, multiple agents, CLI), but claude-flow is an npm package with a CLI interface. Codexia is the only framework in this batch and the seeds that ships a Tauri-based native application. The app-server JSON-RPC integration for Codex (giving programmatic control over session/turn lifecycle rather than just spawning CLI subprocesses) is architecturally novel. The headless REST+WebSocket API surface (~80 routes) enabling remote automation from any HTTP client is unique across the entire corpus.

Positioning

An "agent OS" layer above both Codex CLI and Claude Code CLI — providing visual control, scheduling, isolation, and remote access without owning the AI reasoning itself. Unlike all other frameworks in this batch (which are prompt/skill/plugin frameworks), Codexia is a runtime harness.

Most Unusual Features

  1. codex app-server JSON-RPC integration: Instead of spawning codex exec as a subprocess, Codexia connects to Codex's app-server JSON-RPC interface, getting structured session/turn events, approval callbacks, and model state.
  2. Headless HTTP API for agent control: The Axum web server exposes agent sessions as REST resources, making Codex + Claude Code drivable from curl, CI/CD pipelines, or mobile devices.
  3. Thread fork: api_fork_thread — ability to branch a Codex conversation at an arbitrary point, similar to git branching for agent sessions.

Observable Failure Modes

  1. Codex app-server instability: app-server is a less-documented Codex feature; API changes can break Codexia's core integration.
  2. Dual-license complexity: AGPL-3.0 requires open-sourcing any SaaS deployment; teams building internal tools may need the commercial license without realizing it.
  3. Rust SDK fragility: claude-agent-sdk-rs is an unofficial Rust binding for the Claude Code CLI; changes to the Claude Code CLI protocol can break it.
  4. Scope creep: At 0.33.0 with 80+ API routes, the surface area is large for a project with 6 contributors — maintenance burden is high.
04

Workflow

codexia — Workflow

Basic Usage

  1. Launch Codexia
  2. Add project directory
  3. Enter prompt in the Agent Command Center
  4. Start agent session (Codex CLI or Claude Code)
  5. Monitor output in real-time via WebSocket stream
  6. Respond to approval prompts (file changes, command execution)

Task Scheduler Workflow

1. Create Automation job (cron schedule + repo + prompt)
2. Job runs: /api/automation/run
3. Agent session spawned with configured args
4. Output captured and stored
5. Notification (optional: Discord/Telegram)

Git Worktree Workflow

1. Create worktree: api_git_create_worktree
2. Switch to worktree context
3. Run agent session in worktree
4. Apply/stage changes: api_git_apply_worktree_changes
5. Commit: api_git_commit
6. Remove worktree: api_git_remove_worktree

Phases + Artifacts

Phase Entry Point Artifact
Session Start GUI or /api/codex/thread/start Thread ID
Turn Execution GUI or /api/codex/turn/start Turn output stream
Approval GUI dialog or /api/codex/approval/* Approval decision
Commit GUI or /api/git/commit Git commit
Automation Cron or /api/automation/run Scheduled run log

Approval Gates

All Codex approval prompts are surfaced through the UI and the REST API:

  • api_respond_command_execution_approval — approve/deny Codex commands
  • api_respond_file_change_approval — approve/deny file changes
  • api_respond_user_input — provide text input to Codex session
06

Memory Context

codexia — Memory and Context

State Storage

  • Zustand + persistence: Frontend state (projects, sessions, preferences) persisted via Zustand persistence middleware
  • Tauri state: Desktop application state in src-tauri/src/state.rs
  • Thread history: api_list_archived_threads suggests thread history is stored server-side
  • Notes: /api/notes/* endpoints (create/read/update/delete/sync) indicate notes are persisted
  • Automation runs: /api/automation/list-runs suggests run history is stored

Session Continuity

  • Codex session resume: api_resume_thread wraps codex resume
  • Claude session resume: api_cc_resume_session wraps claude --resume
  • Thread rollback: api_rollback_thread — can roll back a Codex thread to prior state
  • Thread fork: api_fork_thread — create a branched version of a thread

Git Worktree as Memory Isolation

Each worktree represents an isolated working context. Codexia's worktree management (api_git_create_worktree, api_git_apply_worktree_changes) enables parallel agent sessions in isolated filesystem contexts.

Compaction

Not explicitly documented. The Codex CLI handles its own session compaction; Codexia provides the control plane but not context management.

Remote Notes Sync

api_mark_notes_synced and api_get_unsynced_notes suggest a notes sync mechanism (possibly to external service or cloud storage).

Memory Type

Hybrid — Zustand (frontend persistence) + Tauri state (desktop) + Codex/Claude native session state.

07

Orchestration

codexia — Orchestration

Multi-Agent

Yes — Codexia can run multiple Codex and Claude Code sessions across different worktrees simultaneously (via the git worktree management + parallel session tracking).

Orchestration Pattern

Event-driven (scheduled via Task Scheduler) and interactive (manual via GUI or API). Codexia is a control plane, not an orchestration engine — it launches and monitors agent processes but does not coordinate between them.

Isolation Mechanism

Git worktree per task — Codexia provides explicit worktree create/switch/apply APIs, enabling Codex and Claude Code to run in isolated filesystem contexts.

Multi-Model

Yes — Codexia integrates both Codex CLI and Claude Code CLI as separate agent backends. The user can choose which to use per session. No automatic multi-model routing.

Codex Role

Worker (primary agent). Codex runs via codex app-server JSON-RPC with Codexia controlling the session/turn lifecycle. Claude Code is an alternative worker accessible via the same GUI.

Execution Mode

  • Interactive: user-initiated sessions via GUI
  • Scheduled: recurring jobs via Task Scheduler (cron-based)
  • Event-driven: automation triggers via API

Remote Control

Headless mode: Codexia's Axum web server enables remote HTTP/WebSocket control of both agent runtimes. This allows:

  • Scripted CI/CD integration (curl the API)
  • Mobile remote control via P2P/STUN
  • Discord/Telegram chat-based control

Consensus Mechanism

None. Codexia does not implement multi-agent consensus; it manages independent sessions.

08

Ui Cli Surface

codexia — UI and CLI Surface

Local UI

Yes — full desktop application (Tauri v2).

  • Type: Desktop app (native binary)
  • Tech stack: React + TypeScript + Zustand + shadcn/ui (frontend) + Tauri v2 + Rust + Axum (backend)
  • Platform: macOS (primary), Linux, Windows
  • Port: Not exposed in desktop mode; in headless mode the Axum server listens on a configurable port

Key UI Features

  • Agent Command Center (main session interface)
  • Task Scheduler (create/edit/run/pause recurring jobs)
  • Git Worktree Manager (create, switch, apply changes)
  • IDE-like editor (project file tree + edit)
  • Prompt Notepad (save/reuse prompts)
  • MCP Server Marketplace
  • Agent Skills Marketplace
  • Usage Analytics Dashboard (token usage, session heatmaps)
  • Data Viewer (PDF, XLSX, CSV)
  • AGENTS.md editor view

Headless / Web Mode

When running in headless mode, Codexia exposes a browser-accessible HTTP API:

  • REST endpoints: ~80+ routes covering all features
  • WebSocket stream: /ws for real-time agent output
  • Health check: GET /health

This enables CI/CD integration, scripted workflows, and remote access from any HTTP client.

Chat Integration

  • Discord bot (bots/discord/)
  • Telegram bot (bots/telegram/)

Both provide chat-based remote control of agent sessions.

P2P Remote Control

iOS-to-desktop remote control via STUN protocol (src-tauri/src/p2p/).

Dedicated CLI Binary

None for users. The Tauri app is the primary interface. The car-style control is through the web API.

Cross-Tool Portability

High — Codexia works with both Codex CLI and Claude Code CLI as agent backends. Users can switch between them per session.

Related frameworks

same archetype · same primary tool · same memory type

CodeMachine CLI ★ 2.5k
A16 Cross-vendor router

JavaScript-DSL workflow orchestration engine that captures repeatable AI coding agent workflows with tracks, condition groups,…

Kagan ★ 88
A16 Cross-vendor router

Kanban TUI for AI coding agents with a structurally enforced human review gate (REVIEW → DONE cannot be automated) — one git…

oh-my-claudecode (Yeachan-Heo) ★ 35k
A16 Cross-vendor router

Zero-learning-curve teams-first multi-agent orchestration for Claude Code with autopilot (6-phase lifecycle), ralph (PRD-driven…

Paseo ★ 6.8k
A16 Cross-vendor router

Multi-provider AI coding agent orchestration daemon with cross-device access (phone/desktop/CLI) and git worktree isolation.

CCG Workflow ★ 5.4k
A16 Cross-vendor router

Routes Claude + Codex + Gemini to task-appropriate collaboration strategies (direct-fix through full-collaborate) with hook-based…

CCS (Claude Code Switch) ★ 2.4k
A16 Cross-vendor router

Routes Claude Code tasks to the optimal AI agent (Codex, Factory Droid, Ollama, Claude) based on configurable cost/capability…