Codex
Write the work in One Horizon first. Codex can start from an initiative, bug, or todo with the goal and context already included, so the prompt does not have to start from a blank chat.
Send one item to Codex when you want to stay hands-on, or set up a local Codex agent when you want Codex to run assigned work on your machine from Desktop, the CLI, or Workflows.
Choose how to use Codex
| Path | Best for | What happens |
|---|---|---|
| Send to Codex | Starting one task now. | Codex opens with a generated prompt based on the initiative, bug, or todo. |
| Local Codex agent | Letting Codex work from assigned One Horizon tasks. | One Horizon starts Codex on your machine, prepares the code workspace, and records progress on the run. |
| Open in Codex | Reviewing a local Codex run later. | The run opens the recorded Codex thread when a thread ID is available. |
Unlike the ChatGPT integration, this page covers Codex app launch and local agent setup. ChatGPT setup is MCP-based.
Start with the work item
Make the initiative, bug, or todo readable before sending it to Codex. Add the outcome, important links, known constraints, and what counts as done. That work item becomes the prompt source for Send to Codex and local agent runs.
For planned implementation work, spec-driven development gives Codex a tighter brief: the task explains the expected change before any code is written.
Send one work item to Codex
Enable Codex before it appears in Send to…:
- Open Settings → Preferences → Coding tools.
- Enable Codex.
- Open an initiative, bug, or todo and choose Send to… → Codex.
- Codex opens with a structured prompt that includes the work item context.
The generated prompt can use mode-specific instructions such as plan, build, or review.
The work item detail page is where the Send to… action starts.
Preferences control whether Codex appears in that menu.
Codex receives the One Horizon work item as a structured prompt.
Run Codex as a local agent
When a local Codex agent runs through Desktop or the CLI, the agent session stores a Codex thread ID. Open in Codex opens that thread with codex://threads/....
Desktop gives the guided setup path. Open Workflows, go to the agents page, select Add agent, and choose Codex. Pick a runtime preset, set Agent access, choose the repository folder, and decide whether One Horizon should create PRs or MRs after successful runs. The same setup modal is available from an agent step in the workflow designer.
Start from the terminal when you want scriptable control:
one agent createone agent doctorone agent watch
A workflow can target the same local agent. The saved runtime uses codex app-server; Local Agents covers setup, run modes, worktrees, pull requests, artifacts, and safety boundaries.
Local agents are experimental. Keep tasks small and review code, tests, and pull requests before you merge.
Agent Sessions covers the run lifecycle.
Open a Codex thread
When a local Codex agent runs through Desktop or the CLI, the run stores a Codex thread ID. Open in Codex opens that thread with codex://threads/....
Open the run from Agents or Work queue. On run details for a Codex local agent run with a thread ID, Open in Codex is the primary action. In run lists, the same action can appear in the actions menu.
Send to Codex launches codex://new?prompt=.... Open in Codex launches codex://threads/....
If Codex does not open, see Why does Codex not open?.
The local agent records token usage from Codex app-server events while the session is active. For when session details show token counts, see Agent Sessions.
Session lifecycle and the Work queue panel are described in the same page.
Codex agent with the CLI
The CLI includes a Codex agent: a long-running command that connects queued agent sessions to Codex. The agent registers as your local Codex agent, sends heartbeats, polls sessions, claims one before execution, prepares a repo workspace, runs Codex, reports progress, and advances finished work when your workflow allows it.
It fits queues of well-scoped work and sessions that should follow the same repo prep, branch, check, and handoff steps.
The agent is experimental. Use it for small, well-bounded tasks and bug fixes, not large refactors or major redesigns. Review diffs, tests, and pull requests before you merge or ship.
Install the CLI, sign in, and pick a workspace as described on the CLI page. After one agent create, run one agent doctor to check auth, workspace, workflow file, local agent registration, and the Codex command. Read Local agents for the agent execution model.
Run one agent create before one agent watch or one agent start. Agent creation registers a new local agent, writes the local agent settings, and creates a starter workflow file when needed. Skipping it leaves automatic pickup without a saved configuration.
Codex and ChatGPT
Both are OpenAI products, but they are used differently here:
- Codex: Send to… from a work item, Open in Codex from an agent session with a thread ID, or queued sessions through the CLI Codex agent.
- ChatGPT: MCP connector setup in ChatGPT Developer Mode for broader tool calling.
If you want MCP connector setup in ChatGPT, see ChatGPT.