Metadata-Version: 2.4
Name: codex-agent-framework
Version: 0.1.30
Summary: A lightweight event-driven Codex agent runtime.
Author: Baptiste
License-Expression: MIT
Keywords: agent,ai,codex,openai,tools
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: audioop-lts; python_version >= "3.13"
Requires-Dist: beautifulsoup4
Requires-Dist: codex-backend-sdk>=0.3.1
Requires-Dist: fastapi
Requires-Dist: filetype
Requires-Dist: modict
Requires-Dist: mss
Requires-Dist: numpy
Requires-Dist: odfpy
Requires-Dist: openai
Requires-Dist: openpyxl
Requires-Dist: pathspec
Requires-Dist: pillow
Requires-Dist: playwright
Requires-Dist: pydub
Requires-Dist: pypdf
Requires-Dist: pynteract>=0.1.4
Requires-Dist: pywinctl
Requires-Dist: python-docx
Requires-Dist: PyYAML
Requires-Dist: regex
Requires-Dist: requests
Requires-Dist: rich
Requires-Dist: textual
Requires-Dist: tiktoken
Requires-Dist: trafilatura
Requires-Dist: uvicorn
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# codex-agent

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

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:

```bash
python -m pip install codex-agent-framework
```

For the recommended local setup, run:

```bash
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:

```bash
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](docs/cli-and-runtime.md#session-root-and-working-directory).

Inside the TUI, start with:

```text
/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

```python
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:

```python
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:

```python
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:

```bash
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:

```python
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.

## Documentation

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

- [Python SDK](docs/python-sdk.md): `Agent`, turns, streaming, events, config, and interactive sessions.
- [Plugins and extensions](docs/plugins.md): tools, providers, commands, runtime plugins, stateful plugins, hooks, events, and stream processors.
- [CLI and runtime](docs/cli-and-runtime.md): TUI, server, headless CLI, sessions, config, runtime files, and service setup.
- [Built-in capabilities](docs/built-in-capabilities.md): bundled plugins and common usage patterns.
- [Safety and trust](docs/safety-and-trust.md): local trust model, runtime plugins, server binding, secrets, and risky actions.
- [Development](docs/development.md): project layout, tests, build, and release checks.

See [CHANGELOG.md](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](LICENSE).
