codex-agent
codex-agent-framework is a local-first Python framework for building and running a persistent, tool-using AI agent.
It is an open-source, hackable Codex-style harness for Linux developers and power users 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 assistant with TUI, tray, and dock, 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.
New here? Start with Your first day with codex-agent. For prerequisites, installation choices, and common repairs, read Installation and troubleshooting. For the project's broader intent 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 the normal user service setup and can install desktop/browser/tray dependencies plus the dock. 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. See Installation and troubleshooting for prerequisites, variants, and repair steps.
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
/session
/session new
/session load 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 local service | codex-agent bootstrap -- -y |
User service used by UIs, tray, and 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"],
)
A bare Python Agent() uses builtin_plugins=None, which loads every available built-in. Pass [] to load none, or an explicit list to keep an embedded agent deliberately small. The persistent local service restores its saved plugin selection instead; manage that selection from the dock or plugin controls.
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/:
- Your first day with codex-agent: shortest path from install to a useful daily agent session.
- Installation and troubleshooting: prerequisites, bootstrap variants, service setup, isolated experiments, and common repairs.
- 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.
- Dock and shared workspace: tray, dock, shared Chromium, integrated Monaco editor, and responsive controls during agent work.
- 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.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file codex_agent_framework-0.1.99.tar.gz.
File metadata
- Download URL: codex_agent_framework-0.1.99.tar.gz
- Upload date:
- Size: 3.3 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.12.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
7e332dd79bb56ce2ca30ef1c731d2b4644aa8a7fd314872fe215681f8eaee9c6
|
|
| MD5 |
0971e04f0a6bd219138bfff8649dfc7b
|
|
| BLAKE2b-256 |
b2d8efddfec9ca639add57dae42ad6871e11e83c08286e32a300d96738f2058a
|
File details
Details for the file codex_agent_framework-0.1.99-py3-none-any.whl.
File metadata
- Download URL: codex_agent_framework-0.1.99-py3-none-any.whl
- Upload date:
- Size: 3.2 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.12.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
e5b5f5991b3a4cbc9a696a8c2ce0c29aef63d192c0b22cc45f2e87809f4a09f8
|
|
| MD5 |
fd395006ba71645b1090f262ee1bde50
|
|
| BLAKE2b-256 |
94cba0a2d9ec4a77e42590d212dc84fa9f61597a8d320a708e2621f6fc9be100
|
