codex-agent-framework 0.1.4

A lightweight event-driven Codex agent runtime.

codex-agent

codex-agent-framework is a lightweight Python runtime for building interactive, tool-using AI agents.

It provides a reusable Agent abstraction with persistent sessions, local tools, slash commands, contextual providers, voice hooks, image handling, and document-reading helpers. The package can be used as a CLI assistant or embedded as a library in your own application.

Status: early alpha. APIs are still evolving.

Highlights

• Interactive terminal agent exposed as codex-agent.
• Persistent JSON sessions with latest, explicit session IDs, and session navigation commands.
• Built-in local tools for reading, writing, editing, showing, observing, Bash, and Python execution.
• Extensible tool, command, and provider decorators.
• Event-driven internals for UI, streaming, voice, and automation integrations.
• Document extraction helpers for folders, text files, URLs, PDFs, DOCX, XLSX, ODT, HTML, and more.
• Optional image generation, image observation, voice, LaTeX, and Streamlit-oriented integration points.
• Packaged prompt assets and runtime defaults.

Requirements

• Python 3.10 or newer.
• A working model backend configuration compatible with codex-backend-sdk / OpenAI usage.
• Firefox / GeckoDriver may be needed for Selenium-backed web extraction paths.

Installation

From a local checkout:

python -m pip install -e .

For development:

python -m pip install -e '.[dev]'

Optional Streamlit support:

python -m pip install -e '.[streamlit]'

Quick start

Run the bundled terminal assistant:

codex-agent

Or use the agent from Python:

from codex_agent import Agent

agent = Agent(
    session="new",
    username="Baptiste",
    voice_enabled=False,
)

agent("Summarize this project in three bullet points.")

For an interactive Python-driven session:

from codex_agent import Agent

agent = Agent(session="latest", voice_enabled=False)
agent.interact()

Runtime directory and sessions

By default, local runtime state is stored in:

~/.agent_runtime

This directory contains, among other things:

sessions/      persisted conversation histories as JSON
workfolder/    generated or uploaded files
tools/         user runtime tools
providers/     user runtime context providers
commands/      user runtime slash commands
images/        generated or persisted image outputs

You can override the runtime location with:

AGENT_RUNTIME_DIR=/tmp/my-agent-runtime codex-agent

Session behavior:

• Agent(session="new") starts a fresh session.
• Agent(session="latest") resumes the newest saved session.
• Agent(session="<session_id>") loads a specific saved session.
• Agent(session="/path/to/session.json") loads a session file directly.

Session IDs are timestamp-based and lexicographically sortable.

Built-in slash commands

Inside the interactive agent, commands start with /.

Common commands:

/help                         list available commands
/sessions                     list saved sessions
/new_session                  create a new session
/load_session latest          load latest session
/load_session <session_id>    load a specific session
/delete_session <session_id>  delete a session
/next_session                 move to the next/newer session
/previous_session             move to the previous/older session
/compact                      compact completed history turns
/config                       show model-related config
/config model=gpt-test verbosity=low
/model                        show current model
/model gpt-test               update model
/reasoning high               update reasoning effort
/verbosity low                update verbosity

Built-in tools

The default agent registers local tools that can be exposed to the model:

Tool	Purpose
read	Extract text from files, folders, URLs, and common document formats.
write	Write or overwrite one or more complete UTF-8 text files.
edit	Apply exact-string replacements to local text files.
python	Execute Python in a persistent interactive shell.
bash	Execute shell commands.
observe	Load an image into the conversation for visual analysis.
show	Open a file, folder, or URL with the system default app/browser.

Use these with care: Bash, Python, write, and edit run with the current user's privileges.

Extending the agent

Define a tool

from codex_agent import Agent, tool

@tool
def add(a: int, b: int) -> int:
    """Return the sum of two integers."""
    return a + b

agent = Agent(session="new", voice_enabled=False)
agent.add_tool(add)

Define a slash command

from codex_agent import Agent, command, get_agent

@command
def hello(name="world"):
    return f"Hello, {name}! Current session: {get_agent().current_session_id}"

agent = Agent(session="new", voice_enabled=False)
agent.add_command(hello)
print(agent("/hello Baptiste"))

Define a context provider

Providers inject ephemeral context into each model call. Their output is not persisted in the session.

from codex_agent import Agent, provider

@provider
def app_context():
    return "The user is working on the codex-agent repository."

agent = Agent(session="new", voice_enabled=False)
agent.add_provider(app_context)

Runtime extensions

The agent also loads Python modules from the runtime directory:

~/.agent_runtime/tools/*.py
~/.agent_runtime/providers/*.py
~/.agent_runtime/commands/*.py

Decorated functions in those files are registered automatically when the agent starts.

Events

Agent exposes an event bus for UI and automation integrations.

Example:

from codex_agent import Agent, MessageAddedEvent

agent = Agent(session="new", voice_enabled=False)

@agent.on(MessageAddedEvent)
def log_message(event):
    print(event.message.type)

Useful exported events include:

• MessageAddedEvent
• ResponseStartEvent
• ResponseContentDeltaEvent
• ResponseDoneEvent
• ToolCallStartEvent
• ToolCallDoneEvent
• AgentInterruptedEvent
• AudioPlaybackEvent

Configuration

Agent accepts configuration through keyword arguments:

agent = Agent(
    session="latest",
    model="gpt-5.4",
    reasoning_effort="medium",
    verbosity="medium",
    input_token_limit=128000,
    auto_compact=True,
    web_search_enabled=False,
    image_generation_enabled=False,
    voice_enabled=False,
)

Configuration is persisted to agent_config.json in the runtime directory when updated through agent helpers or slash commands.

Project layout

codex_agent/                    Python package
codex_agent/agent.py            Agent, AgentConfig, AgentSession
codex_agent/builtin_tools.py    Built-in local tools
codex_agent/builtin_commands.py Built-in slash commands
codex_agent/builtin_providers.py Built-in context providers
codex_agent/prompts/            Packaged prompt templates
codex_agent/get_text/           Document extraction helpers
tests/                          Test suite
pyproject.toml                  Package metadata and build config
MANIFEST.in                     Source distribution includes

Testing

Run the full suite:

python -m pytest

The tests isolate AGENT_RUNTIME_DIR automatically, so they should not create or resume sessions from your real ~/.agent_runtime.

Current baseline:

102 passed

Packaging

Build source and wheel distributions with:

python -m pip install build
python -m build

The distribution includes prompt text files and codex_agent/get_text/default_gitignore through package data and MANIFEST.in.

Recent changes

• 0.1.4: make the Textual REPL UI the default, add multiline input, assistant turn/step events, cleaner tool-call rendering, and /voice configuration.
• 0.1.3: pass the current session id as prompt_cache_key to the Codex backend for prompt cache reuse.
• 0.1.2: add /clear in the terminal chat to clear the screen without changing session history.
• 0.1.1: image observations are now validated before session persistence, preventing broken ImageMessage entries from poisoning later turns.

Safety notes

This project is designed to let an AI assistant act on the local machine. That is powerful and potentially risky.

Recommended practices:

• Use a dedicated runtime directory for experiments.
• Review tool calls before enabling autonomous workflows.
• Avoid running the agent with elevated privileges.
• Keep secrets out of prompts, logs, and committed runtime files.
• Prefer temporary workfolders in tests and demos.

License

MIT. See LICENSE.