Codex Agent
A local, persistent and extensible AI agent built around the Codex backend.
Codex Agent turns a ChatGPT/Codex account into an agent that can live on your machine: keep long-running sessions, use local tools, schedule work, expose multiple interfaces, and evolve through Python plugins.
It is primarily designed for Linux developers and AI enthusiasts who want more than a coding task runner: a general-purpose local assistant whose harness remains open, inspectable and adaptable.
Codex Agent is an independent open-source project. It is not a fork of the official Codex application and is not affiliated with OpenAI.
What you get
- A persistent local agent backed by Codex and authenticated through ChatGPT.
- Long-lived sessions with context compaction and selective memory.
- A terminal UI, an adaptive desktop dock and a system tray connected to the same agent.
- Local file, shell, Python, browser, scheduler and other capabilities through plugins.
- A Python SDK for direct, embedded or process-isolated integrations.
- A local REST/SSE server for custom clients and user interfaces.
- A plugin model that can contribute tools, context, commands, hooks and events.
Codex Agent deliberately favors power and adaptability over consumer-grade sandboxing. It is intended for technically confident users who understand that enabled plugins can act on their machine.
The desktop experience adapts to the task: a minimal always-on-top composer for working directly on the desktop, a focused chat column, or a Files/Editor/Chat workspace. The persistent tray can also show temporary Markdown notifications and compact tool activity while the dock is collapsed—or even closed—so scheduled and background work remains observable without taking over the screen.
Why not just use Codex?
Official Codex is the simpler choice for a polished, supported coding-agent experience. Its CLI works on Linux, but the official desktop app currently targets macOS and Windows.
Codex Agent is for developers who want to own and evolve the harness itself:
- a fully open-source, Linux-first workspace, with a persistent service, TUI, tray and native desktop dock;
- a Python-first Agent SDK exposing the engine itself—not just a client—with runtimes and
AgentClientavailable for other integration levels; - a familiar, conversation-oriented API built around uniform
Messagehistory and typed dictionary payloads; - extension points throughout the agentic loop, including tools, context, commands, hooks, events and stream processing;
- a live workflow where the agent can modify, test and reload its own runtime, interfaces and plugins without discontinuing the ongoing session.
Use official Codex when its product experience already fits your workflow. Use Codex Agent when building and evolving your own local agent platform is part of the goal.
Independent, not adversarial. Codex Agent is not affiliated with OpenAI and does not seek to replace or bypass Codex. It is an independent interpretation of a harness compatible with the Codex backend, using the normal authentication flow and usage quota of a paid ChatGPT account. Its authentication support follows the protocol documented by OpenAI's open-source Codex client; it does not circumvent access controls. The project exists to explore different—sometimes subtle, but consequential—design choices around the same service.
Quick start
Requirements
- Linux is the primary supported desktop platform.
- Python 3.11 or newer.
- A ChatGPT account with Codex access and enough usage quota for sustained agent work.
- Git and common build tools.
- Node.js, pnpm, Rust and Tauri system dependencies are needed only when building the desktop dock from source.
Install
pip install codex-agent-framework
# Optional local microphone/speaker support:
pip install "codex-agent-framework[realtime]"
codex-agent bootstrap
bootstrap installs the background services and, when desktop sources and dependencies are available, builds and installs the dock.
Then open the default terminal interface:
codex-agent
Or submit one headless task:
codex-agent run "Summarize this repository"
The first Codex request may open the ChatGPT authentication flow.
Choose your path
Use Codex Agent
| I want to… | Read |
|---|---|
| Install, bootstrap or repair the application | Installation |
| Start a session and understand the daily workflow | Getting started |
| Run tasks or administer the local agent from a terminal | CLI reference |
Integrate or extend it
| I want to… | Read |
|---|---|
| Embed an agent directly in Python | Python SDK |
| Choose in-process, isolated or server execution | Runtimes |
| Build an HTTP/SSE client | Server API and events |
| Add tools, context or other capabilities | Plugins |
| Build an interactive client | Interfaces and UI integration |
The complete documentation map is available in docs/README.md.
Core model
Codex Agent separates four concerns:
Agent owns sessions, context, tools and the agentic loop
Runtime exposes that Agent in-process or through an isolated worker
Server maps one long-lived Runtime to REST and SSE
Interfaces consume the same server state and event stream
Plugins are the canonical extension surface. A plugin may add model-callable tools, context providers, slash commands, hooks, stream processors, event handlers and system-prompt sections.
The server normally binds to 127.0.0.1. Treat runtime plugins and any interface connected to the server as trusted local code unless you add your own security boundary.
Project status
Codex Agent is already usable as a daily personal harness, but remains intentionally evolving. Public entry points are kept small and predictable; implementation details may continue to change as the project becomes clearer and more capable.
Contributions, experiments and personal forks are welcome—especially from developers interested in designing the environment around an AI agent rather than consuming a fixed assistant.
License
See LICENSE.
1 maintainer
Metadata
1 maintainer
Release files for codex-agent-framework 0.2.22
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| codex_agent_framework-0.2.22.tar.gz | 3.4 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| codex_agent_framework-0.2.22-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 6.6 MB
Release files / codex_agent_framework-0.2.22.tar.gz
| Download URL | codex_agent_framework-0.2.22.tar.gz |
|---|---|
| Size | 3.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
655633765949ee9564cd71cbc723707f4d61cabc1355c23e2f6407d002eb5356
|
|
BLAKE2b-256 checksum How to use checksums |
62ef94382240742de1382676cfcc79c767facc39fb9ef6bffc9e7502d821d4a1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Release files / codex_agent_framework-0.2.22-py3-none-any.whl
| Download URL | codex_agent_framework-0.2.22-py3-none-any.whl |
|---|---|
| Size | 3.3 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2ac479344acae3acc8981f11ac19b5e8aa5fa809efbbe561bad5e8fedd7a1fbb
|
|
BLAKE2b-256 checksum How to use checksums |
4892615357ca5a66ab286a33b8426cee605142402cf00c1ade79a81aed75a8fc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
