codex-agent-framework 0.1.49

A lightweight event-driven Codex agent runtime.

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.

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)

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 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"],
)

None loads all built-ins, [] loads none, and an explicit list selects 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/:

• 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.