Codexia: a Tauri desktop and headless workspace for Codex CLI and Claude Code

What Codexia is for, and who ends up using it

The README calls Codexia a "Lightweight Agent Workstation for Codex CLI + Claude Code + any Agent Client Protocol (ACP) agent". That framing is accurate about the target user: someone who already has Codex CLI or Claude Code installed and runs it in a terminal, and who now wants the surrounding chores handled in the same window.

The chores are named in the feature list. A task scheduler for recurring jobs. Git worktree management. A project file tree and an IDE-like editor. A prompt notepad. A local web preview. PDF, XLSX and CSV preview. An MCP server marketplace and an agent skills marketplace. Usage analytics.

None of those replace the agent. Codexia is the shell around it. If your work is one prompt in one repository and you close the terminal afterwards, the shell has nothing to hold. The project earns its place when you are juggling several repositories, several long-running sessions, or a job that has to run again tomorrow without you typing the prompt again.

How Codexia talks to Codex, Claude Code and ACP agents

The architecture section of the README is explicit about the layers. The frontend is React, TypeScript, Zustand and shadcn/ui under src/. The desktop backend is Tauri v2 with Rust under src-tauri/src/. A separate headless backend is an Axum web server under web/.

The agent runtime is the interesting part. For Codex, Codexia integrates with the Codex app-server over JSON-RPC to drive session and turn lifecycle. For Claude, it uses a Rust SDK (claude-agent-sdk-rs, pinned to tag v0.8.0 in the workspace Cargo.toml). For anything else, it acts as an ACP client, and the README states that those sessions persist across restarts and that tool calls render live in the thread.

Real-time updates reach browser clients over a WebSocket broadcast stream at /ws. The named entry points are src-tauri/src/lib.rs for desktop commands and state, web/src/server_web.rs for headless startup, src-tauri/src/web/router.rs for the HTTP route surface, and src/services/tauri/ for the frontend invoke layer. The workspace is split into crates: acp, automation, cc, codex, db, shared and git. That split is a reasonable signal that the agent integrations are meant to be separable rather than tangled into the Tauri shell, though the README does not document a stable crate-level API for third parties.

Installing Codexia and starting a first session

Codex CLI and Claude Code CLI are prerequisites, not bundled dependencies. Install at least one before Codexia.

On macOS, the README gives a Homebrew cask:

brew install --cask codexia

On Windows, the README documents a Scoop bucket and package:

scoop bucket add milisp https://github.com/milisp/scoop-bucket
scoop install codexia

Windows also ships a portable archive named codexia_<version>_x64_portable.zip that runs without installing. For macOS and Linux without a package manager, the README points at GitHub Releases.

The quick start is four steps: launch Codexia, add your project directory, enter a prompt and start your agent session, then create an Agent Task Scheduler job for recurring workflows. No configuration file is required for that path.

If you want the headless server instead of the desktop app, the justfile shows how the maintainer runs it locally. The backend listens on port 7420 by default, and the Vite frontend on 1420 proxies API and WebSocket traffic to it.

just dev-web

The justfile prints the API base and the /ws route, waits for http://localhost:7420/health to answer, then opens the frontend. The same port is configurable through VITE_WEB_PORT, which appears in .env.example alongside VITE_SUPABASE_URL and VITE_ENABLE_AUTH. The example file sets VITE_ENABLE_AUTH=false and notes that setting it to true forces login. If you run the headless server outside the justfile, the binary is codexia-web and takes a --port flag.

The headless HTTP API is the part to think hardest about

When Codexia runs in headless mode it exposes a browser-accessible API, and the route list in the README is wide. Health and stream: GET /health and GET /ws. Codex lifecycle: /api/codex/thread/*, /api/codex/turn/*, /api/codex/model/*, /api/codex/approval/*. Automation scheduler: /api/automation/* with create, update, list, run, pause and delete. Files, git and terminal: /api/filesystem/*, /api/git/*, /api/terminal/*. Claude integration under /api/cc/*. Notes and token usage under /api/notes/* and /api/codex/usage/token.

That is a remote-control surface for a coding agent. It is also a filesystem, git and terminal API reachable over HTTP. The README's security section lists process isolation, per-agent permission control for file and network access, local storage, and open source transparency. It does not describe authentication on the headless routes, and the only auth switch visible anywhere in the repository is VITE_ENABLE_AUTH in .env.example, which the comment ties to forcing login. The README does not state whether that flag gates the HTTP API or only the frontend. Treat the headless server as something to bind to localhost or put behind your own access control until you have read docs/WEB_SERVER.md, which the README links but does not summarise.

Where Codexia is the wrong tool

Codexia assumes Codex CLI or Claude Code is already installed and working. If neither is present, there is nothing for it to drive, and the ACP path only helps if you have a third-party agent that already speaks the protocol.

The desktop app is built on Tauri v2, so it is a native binary per platform rather than a browser tab. That is a deliberate trade: you get process isolation and local storage, and you give up the ability to run the same UI on a machine where you cannot install a desktop application. The headless server covers part of that gap, but it is the API surface, not the full desktop feature set.

There is also a scope question. The feature list includes a prompt notepad, a theme customiser, a usage analytics dashboard, a data-file previewer, an editor and a file tree. Each of those is a thing you probably already have. A team that only wants scheduled agent runs is carrying a lot of UI for one cron-like feature. The README does not offer a way to disable panels, so the lighter path is to run the headless server and call /api/automation/* directly.

Finally, the versioning is fast. Three releases landed between 2026-09-07 and 2026-09-09, taking the project from v0.50.0 to v0.50.2. The last push to master was on 2026-09-10. Frequent patch releases at that cadence suggest an interface that still moves, and the README does not document a compatibility policy for the HTTP routes.

Alternatives and the real difference in approach

The README itself points at two community forks, and the difference between them and upstream is architectural rather than cosmetic. jeremiahodom/codex-ui is described as a Node.js backend with API/SSE, where Codexia uses a Rust Axum server with a WebSocket broadcast at /ws. nuno5645/codexia is described as adding reasoning and token count events, which in upstream terms means changes around the /api/codex/usage/token surface. If you want a Node runtime you can extend in JavaScript, the fork is the closer fit; if you want the Tauri desktop shell, upstream is.

The README also recommends keke, described as a local terminal coding agent with zero vendor lock-in that works with subscriptions, API keys or self-hosted models and speaks ACP for editor and client integration. That is a different category: keke is an agent, Codexia is a workstation that hosts agents. They are complementary rather than substitutes, and the ACP support in Codexia is what makes keke a plausible agent to plug in.

Against a plain terminal, the difference is state. A terminal session ends when you close it. Codexia's ACP sessions persist across restarts, and the scheduler keeps jobs defined between runs. Against a full IDE with an agent plugin, the difference is that Codexia drives Codex and Claude Code as external processes instead of embedding a model client, so your existing CLI configuration and credentials stay where they are.

Licence, maintenance and the cost of upgrading

Codexia is MIT licensed, and the repository carries a LICENSE file at the top level. MIT is permissive: you can fork, modify and redistribute, including commercially, provided the copyright notice and permission notice are preserved. That is a description of the licence text, not legal advice; if you are redistributing a modified build, read the file yourself.

One licence detail worth noticing is the dependency list. The workspace Cargo.toml pulls claude-agent-sdk-rs from a git URL pinned to tag v0.8.0, and codex-finder from a git repository rather than crates.io. The licence terms of those dependencies are separate from Codexia's MIT licence, and the README does not state what they are. If your organisation has a dependency-review process, those two entries are the ones to check before adopting.

The upgrade cost is mostly the release cadence. Codexia went from v0.50.0 to v0.50.2 in three days, and package.json carries the same version string as the workspace, so frontend and backend version together. The README does not document a migration path for the HTTP API between versions, and there is no deprecation policy in the repository. If you build against /api/automation/* or /api/codex/*, pin the release you tested and read CHANGELOG.md before moving. The repository ships a changelogs/ directory and a bump-version script, which suggests version bumps are scripted rather than hand-edited.

On maintenance: the last push to master was on 2026-09-10, and the repository is not archived. The README names a single maintainer, @milisp, and lists sponsorship and custom work as available. That is a bus-factor of one, which is worth weighing if you plan to depend on the headless API.

Editorial conclusion

Adopt Codexia if you already run Codex CLI or Claude Code from a terminal and want sessions that survive restarts, recurring scheduler jobs and remote control from a browser or phone. Skip it if you only need a single interactive agent session, or if you cannot accept that the headless server exposes filesystem, git and terminal routes over HTTP. Before installing, read docs/WEB_SERVER.md and confirm which approval settings the desktop app applies to the agents it launches, because the README does not spell that out.

Frequently asked questions

Official sources

1. License: MIT
2. milisp/codexia on GitHub
3. Project website
4. README
5. Releases