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, a 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.

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 AgentClient available for other integration levels;
  • a familiar, conversation-oriented API built around uniform Message history 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
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.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.2.22)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for baptor from gravatar.com baptor

Credits

Author: Baptiste

License expression

MIT
View SPDX License List

Requires

Python >=3.11

Provides Extra

dev

Tags

agent ai codex openai tools

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

codex_agent_framework-0.2.3.tar.gz (3.3 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

codex_agent_framework-0.2.3-py3-none-any.whl (3.2 MB view details)

Uploaded Python 3

File details

Details for the file codex_agent_framework-0.2.3.tar.gz.

File metadata

  • Download URL: codex_agent_framework-0.2.3.tar.gz
  • Upload date:
  • Size: 3.3 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.12.13

File hashes

Hashes for codex_agent_framework-0.2.3.tar.gz
Algorithm Hash digest
SHA256 56817df88f031f5edf38dd1243a9e2add90ca57999ee5317915c2f426dc65470
MD5 9ff55c8dadaf1c462fbf7890a76df78b
BLAKE2b-256 f258a73af364526935fc76a7eaa8b3425c30c09e6fc59d5d20a357a9be98c82a

See more details on using hashes here.

File details

Details for the file codex_agent_framework-0.2.3-py3-none-any.whl.

File metadata

File hashes

Hashes for codex_agent_framework-0.2.3-py3-none-any.whl
Algorithm Hash digest
SHA256 b752737424f16deadf783a1c9a8efb2d9a267796d240581aa9ca1f8beb89e852
MD5 df4bed9b068bf6d2d4da533c5cb055fe
BLAKE2b-256 e7dc0436a99f1959923f3f846d5df20cdd1f9fdea982d2750a07721f6a908874

See more details on using hashes here.

Release history Release notifications | RSS feed

0.2.22

2 files

0.2.21

2 files

0.2.20

2 files

0.2.19

2 files

0.2.18

2 files

0.2.17

2 files

0.2.16

2 files

0.2.15

2 files

0.2.14

2 files

0.2.13

2 files

0.2.12

2 files

0.2.11

2 files

0.2.10

2 files

0.2.9

2 files

0.2.8

2 files

0.2.7

2 files

0.2.6

2 files

0.2.5

2 files

0.2.4

2 files

This release

0.2.3 This release

2 files

0.2.2

2 files

0.2.1

2 files

0.2.0

2 files

0.1.99

2 files

0.1.98

2 files

0.1.97

2 files

0.1.96

2 files

0.1.95

2 files

0.1.94

2 files

0.1.93

2 files

0.1.92

2 files

0.1.91

2 files

0.1.90

2 files

0.1.89

2 files

0.1.88

2 files

0.1.87

2 files

0.1.86

1 file

0.1.84

1 file

0.1.83

2 files

0.1.82

2 files

0.1.81

2 files

0.1.80

2 files

0.1.79

2 files

0.1.78

2 files

0.1.77

2 files

0.1.76

2 files

0.1.75

2 files

0.1.74

2 files

0.1.73

2 files

0.1.72

2 files

0.1.71

2 files

0.1.70

2 files

0.1.69

2 files

0.1.68

2 files

0.1.67

2 files

0.1.66

2 files

0.1.65

2 files

0.1.64

2 files

0.1.63

2 files

0.1.62

2 files

0.1.61

2 files

0.1.60

2 files

0.1.59

2 files

0.1.58

2 files

0.1.57

2 files

0.1.56

2 files

0.1.55

2 files

0.1.54

2 files

0.1.53

2 files

0.1.52

2 files

0.1.51

2 files

0.1.50

2 files

0.1.49

2 files

0.1.48

2 files

0.1.47

2 files

0.1.46

2 files

0.1.45

2 files

0.1.44

2 files

0.1.43

2 files

0.1.42

2 files

0.1.41

2 files

0.1.40

2 files

0.1.39

2 files

0.1.38

2 files

0.1.37

2 files

0.1.36

2 files

0.1.35

2 files

0.1.34

2 files

0.1.33

2 files

0.1.32

2 files

0.1.31

2 files

0.1.30

2 files

0.1.29

2 files

0.1.28

2 files

0.1.27

2 files

0.1.26

2 files

0.1.25

2 files

0.1.24

2 files

0.1.23

2 files

0.1.22

2 files

0.1.21

2 files

0.1.20

2 files

0.1.19

2 files

0.1.18

2 files

0.1.17

2 files

0.1.16

2 files

0.1.15

2 files

0.1.14

2 files

0.1.13

2 files

0.1.12

2 files

0.1.11

2 files

0.1.10

2 files

0.1.9

2 files

0.1.8

2 files

0.1.6

2 files

0.1.5

2 files

0.1.4

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page