Metadata-Version: 2.1
Name: codexapi
Version: 0.1.1
Summary: Minimal Python API for running the Codex CLI.
License: MIT
Keywords: codex,agent,cli,openai
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE

# CodexAPI

Use codex from python as easily as calling a function with your codex credits instead of the API.

## Requirements

- Codex CLI installed and authenticated (`codex` must be on your PATH).
- Python 3.8+.

## Install

```bash
pip install codexapi
```

## Quickstart

```python
from codexapi import agent, Agent

# Run one-shot tasks as a function call
print(agent("Say hello"))

# Run a multi-turn conversation as a session
session = Agent(cwd="/path/to/project")
print(session("Summarize this repo."))
print(session("Now list any risks."))
```

## API

### `agent(prompt, cwd=None, *, yolo=False, agent="codex") -> str`

Runs a single Codex turn and returns only the agent's message. Any reasoning
items are filtered out.

- `prompt` (str): prompt to send to Codex.
- `cwd` (str | PathLike | None): working directory for the Codex session.
- `yolo` (bool): pass `--yolo` to Codex when true.
- `agent` (str): agent backend to use (only `"codex"` is supported).

### `Agent(cwd=None, *, yolo=False, agent="codex", trace_id=None)`

Creates a stateful session wrapper. Calling the instance sends the prompt into
the same conversation and returns only the agent's message.

- `__call__(prompt) -> str`: send a prompt to Codex and return the message.
- `thread_id -> str | None`: expose the underlying session id once created.
- `trace_id` (str | None): Codex thread id to resume from the first call.
- `yolo` (bool): pass `--yolo` to Codex when true.
- `agent` (str): agent backend to use (only `"codex"` is supported).

## Behavior notes

- Uses `codex exec --json` and parses JSONL events for `agent_message` items.
- Automatically passes `--skip-git-repo-check` so it can run outside a git repo.
- Passes `--yolo` when enabled (use with care).
- Raises `RuntimeError` if Codex exits non-zero or returns no agent message.

## Configuration

Set `CODEX_BIN` to point at a non-default Codex binary:

```bash
export CODEX_BIN=/path/to/codex
```
