Codex

Codex is OpenAI's coding agent that edits files, runs commands, and ships changes from your terminal. In LobeHub, you can delegate Codex from the desktop app — keep the chat UX you already use, while Codex does the work locally with full access to your project.

Send a prompt and Codex opens files, makes edits, runs tests, and reports back. File changes, todos, and command output stream into the chat as the agent moves; sessions resume across turns so a long task can span many messages.

What Is Codex in LobeHub?

A bridge between LobeHub's chat UI and the Codex CLI running on your machine. LobeHub spawns the Codex CLI as a local subprocess, streams its events into a chat conversation, and renders Codex's tool output — file changes, todo lists, command runs — as first-class chat blocks. You drive the agent in natural language; Codex executes locally with your environment, credentials, and project context.

Requirements

LobeHub desktop app — Codex agents only work in the desktop build. The web app cannot spawn local processes.
Codex CLI installed — the codex command must be available on your PATH.
Signed in — you must run codex once in a terminal to authenticate before LobeHub can drive it.

Install the Codex CLI

Pick one of the install paths:

Recommended (npm)

bash

npm install -g @openai/codex

Homebrew (macOS)

bash

brew install --cask codex

After installing, run codex once in a terminal to sign in. See the Codex installation guide for details.

If LobeHub can't find the CLI, it shows an Install Codex CLI prompt with the same commands and an Open System Tools button — click it after installing to re-detect the CLI.

Add Codex in LobeHub

When LobeHub detects the Codex CLI on your machine, an Add Codex recommendation card appears on the home page tagged "Coding Agent". Click it to create a Codex agent in one step.

You can also create one manually from the Create Agent menu and pick Codex as the type.

Each agent is independent, so you can keep multiple Codex agents pinned to different projects or workflows.

Working Directory

Every Codex session is pinned to a working directory — the folder Codex sees as the project root. Set it from the chat input bar before sending your first message. Switching the working directory mid-conversation starts a new Codex session for the topic; chat history stays, but the previous session context cannot be resumed.

If you change folders and the saved Codex thread can't be resumed safely, LobeHub shows: "The saved Codex thread could not be resumed safely, so a new conversation has started for this topic."

What Gets Rendered in Chat

LobeHub renders Codex's tool calls with purpose-built blocks instead of raw JSON:

File changes — Codex's edits show up as an expandable list with the operation kind (added, deleted, modified, renamed), the file path, and a per-file line count delta (+/−). Click to see what changed.

Todo lists — When Codex plans a multi-step task, the plan renders as a progress card with completed / in-progress / pending items and a running count (e.g. "3/5 completed"). Watch tasks tick off as Codex finishes them.

Command execution — Shell commands Codex runs show the command, exit code, and stdout / stderr output. Success and failure states are clearly marked.

Subagents — Codex can spawn subagents to work in parallel. Their work appears in isolated threads inside the conversation without leaking into the main bubble.

Sessions and Resume

Codex sessions persist across messages in the same topic. You can send a follow-up like "now also update the tests" and Codex picks up where it left off — same files, same context, same plan.

A session can't be resumed if:

The working directory changed since the saved thread was created
The original Codex thread no longer exists
The CLI returns a "no conversation found" or "thread not found" error

In any of these cases, LobeHub starts a fresh conversation automatically.

Where It Can Run

The Execution Device selector lets you pick where the Codex agent runs:

This device — runs Codex as a local process inside the desktop app. Default.
Cloud sandbox — runs Codex in an ephemeral cloud sandbox. Useful when you don't want the agent touching your local filesystem.
Remote device — drives a remote machine you've connected with lh connect. Useful when the project lives on a different machine.

Limitations

Desktop only — the Codex agent runs in the LobeHub desktop app. The web app cannot spawn the CLI.
One sign-in per machine — Codex shares its authentication with the global CLI. If codex works in your terminal, it works in LobeHub.
Working-directory-bound — sessions don't follow you across folders or machines.

Tips

Run codex once in a terminal first — sign-in happens at the CLI level, not in LobeHub.
Pick the working directory before your first message — switching it later starts a new session.
Watch the todo card — it's the fastest read on what Codex thinks it still has to do.
Use one Codex agent per project — pinning each agent to a specific repo keeps sessions tidy and resumable.