codex-agent

codex-agent-framework is a local-first Python framework for building and running tool-using AI agents.

It is designed as an open-source, hackable Codex-style harness for people who want local control over sessions, tools, plugins, runtime state, and UI surfaces instead of a sealed assistant runtime. Use it as a ready-to-run terminal assistant, or import Agent when you want to build your own agentic workflow in Python.

Early alpha: APIs are still evolving and breaking changes are expected while the architecture settles.

For the project's broader intent and architecture in plain language, read What is codex-agent?.

Why codex-agent?

codex-agent is meant to be a transparent, hackable local harness for power users and developers:

  • Local-first runtime: sessions, memory, config, plugins, logs, and work files live under your local runtime directory.
  • Multiple entry points: TUI, headless CLI, Python SDK, and local FastAPI server.
  • Plugin-first design: tools, providers, slash commands, hooks, events, prompt sections, and stream processors are extension points.
  • Observable agent loop: turns return structured results and emit events that UIs and integrations can stream.
  • Built-in practical tools: files, shell, Python, context, memory, planner, scheduler, browser/desktop automation, and subagents.

Quick start

Install the package:

python -m pip install codex-agent-framework

For the recommended local setup, run:

codex-agent bootstrap -- -y

bootstrap installs desktop/browser/tray dependencies, installs the user services, and starts them. It is currently aimed mostly at Debian-like Linux systems. Use an X11 session for the best desktop automation support; Wayland is fine if you do not use the desktop plugin.

Open the assistant:

codex-agent

If a local agent server is already running, the TUI connects to it. Otherwise codex-agent starts a temporary server for that TUI session and shuts it down when the TUI exits. New sessions are anchored to the directory where you launch codex-agent; see CLI and runtime.

Inside the TUI, start with:

/help
/sessions
/new_session
/load_session latest
/compact
/config

Use /compact when a long session needs to reduce its active context. It keeps a backend summary and prunes older raw history from the active session file.

Python in 30 seconds

from codex_agent import Agent

agent = Agent(session="new")
turn = agent("Summarize this repository in three practical bullet points.")

print(turn.result)

Stream live events when building your own UI or integration:

from codex_agent import Agent, ResponseContentDeltaEvent

agent = Agent(session="new")
stream = agent.stream("Explain what this project does.")

for event in stream:
    if isinstance(event, ResponseContentDeltaEvent):
        print(event.delta, end="", flush=True)

turn = stream.turn
print("\ncompleted:", turn.completed)

The built-in TUI uses the same streamed event model and is designed to stay responsive during heavier tool activity by decoupling event intake from UI rendering.

Add a small tool:

import subprocess
from codex_agent import Agent, tool

@tool
def list_changed_files() -> list[str]:
    """Return modified or untracked files in the current git repository."""
    output = subprocess.check_output(["git", "status", "--short"], text=True)
    return [line[3:] for line in output.splitlines() if line.strip()]

agent = Agent(session="latest")
agent.add_tool(list_changed_files)
agent("What changed locally?")

Main ways to use it

Mode Entry point Best for
Interactive TUI codex-agent Daily local assistant usage.
Python SDK Agent(...) Scripts, notebooks, tests, custom applications.
Headless CLI codex-agent run ... Automation and shell pipelines.
Persistent server codex-agent start server Long-lived local service used by UIs or scripts.
Runtime plugins ~/.codex-agent/plugins/*.py Local customization without forking the project.

Useful CLI commands:

codex-agent status --json
codex-agent tools
codex-agent plugins list
codex-agent sessions list
codex-agent config get
codex-agent run "Run a quick repository health check."
git diff -- README.md | codex-agent run --stdin "Review this documentation diff."

Built-in capability map

Area Examples Purpose
Files/content read, view, write, edit Strict text reads, broad extraction, exact-string edits.
Shell/Python bash, python Local command execution and persistent Python work.
Context/status context_status, context_compact Inspect and manage the active context window.
Memory/planner memory_add, planner_create Durable semantic memory and persistent named todos.
Scheduler scheduler_schedule Future turns and post-restart continuation.
Browser/desktop browser and desktop tools Persistent Chromium and Linux desktop automation.
Subagents subagents_run Focused child agents such as the read-only explorer profile.

Select built-ins explicitly when you want a smaller agent:

agent = Agent(
    session="latest",
    builtin_plugins=["files", "content", "bash", "python", "environment", "context"],
)

By default, the agent starts with a minimal built-in surface: files, environment, memory, planner, scheduler, and context. Pass builtin_plugins=None to load all built-ins, [] to load none, or an explicit list to select plugin module names.

Project health

The repository includes a GitHub Actions CI workflow that runs an explicit offline/headless test subset on Python 3.11 and 3.12, then builds the package and validates distributions with twine check. You can run the same subset locally with scripts/run-ci-tests.sh; use python -m pytest for broader local sweeps that may include machine- or backend-dependent tests. Dependabot is configured for weekly GitHub Actions and pip dependency updates.

Documentation

The README is intentionally a façade and quick-start guide. Advanced usage lives in docs/:

  • What is codex-agent?: project intent, continuity model, interfaces, and the local-first philosophy.
  • Python SDK: Agent, turns, streaming, events, config, and interactive sessions.
  • Plugins and extensions: tools, providers, commands, runtime plugins, stateful plugins, hooks, events, and stream processors.
  • CLI and runtime: TUI, server, headless CLI, sessions, config, runtime files, and service setup.
  • Built-in capabilities: bundled plugins and common usage patterns.
  • Safety and trust: local trust model, runtime plugins, server binding, secrets, and risky actions.
  • Development: project layout, tests, build, and release checks.

See CHANGELOG.md for release history.

Safety notes

This project lets an AI assistant act on the local machine. That is useful, but risky.

Recommended practices:

  • Avoid running the agent with elevated privileges.
  • Review tools and runtime plugins before enabling autonomous workflows.
  • Keep secrets out of prompts, logs, committed runtime files, and shared session exports.
  • Treat browser, desktop, shell, file-write, and edit operations as real user actions.
  • Keep important runtime plugins under version control.

License

MIT. 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.1.96.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.1.96-py3-none-any.whl (3.2 MB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: codex_agent_framework-0.1.96.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.1.96.tar.gz
Algorithm Hash digest
SHA256 d95a38b9a4a9b3bddd61b653f3319a5269be90d2ce33f05686127ff6425f2a02
MD5 bee49a59e051a38c279887880e774c8b
BLAKE2b-256 8cfafcdfa6d40f9ad05e4fc8a69f23d4b1246e4945b4565388601af64affa512

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for codex_agent_framework-0.1.96-py3-none-any.whl
Algorithm Hash digest
SHA256 1c34e59944c699447df9b4725651484534d461c003a0332cbef6ba5f6ac171f3
MD5 dda4820d94c912b0e1bfa5b8457ab7f0
BLAKE2b-256 1ac536d0daa544bac5a4892966873e919d28ddf982cdd6a3d91af8ad04ec44eb

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

0.2.3

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

This release

0.1.96 This release

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