codex-python-kagent 0.1.3

Async Codex-backed coding agent SDK.

kagent

Async Python SDK for running Codex-backed coding-agent tasks with a small, memorable thread API.

The PyPI distribution is codex-python-kagent; the import package is kagent.

import asyncio

from kagent import kagent


async def main() -> None:
    agent = kagent()
    run = await agent.thread("main").run("Create hello.txt with exactly: hello")
    print(run.text)


asyncio.run(main())

Status

kagent is experimental. It wraps the local Codex CLI/app-server flow and currently depends on the experimental OpenAI Codex Python SDK for runner="sdk".

The package itself has no required runtime dependencies so it can be built and published cleanly. The default runner uses the Codex CLI. The experimental Codex Python SDK is kept in a local uv dependency group instead of PyPI metadata.

Install

In a uv project:

uv add codex-python-kagent
kagent login

For API-key auth instead of ChatGPT subscription auth:

export OPENAI_API_KEY="sk-..."
kagent login --api-key-env OPENAI_API_KEY

For local development in this repo:

uv sync --group dev --group codex --group examples

The local machine must also have the Codex CLI installed and authenticated:

codex login status

API

Use kagent(...) when you already authenticated with kagent login or codex login.

from kagent import kagent

agent = kagent(workspace=".", model="gpt-5.5")
thread = agent.thread("refactor-auth")
await thread.run("Refactor auth.py without changing behavior.")
await thread.run("Now run the tests and fix any failures.")

Stream events while still getting the final result:

from typing import Any


def show_event(event: dict[str, Any]) -> None:
    print(event.get("type") or event.get("method"))


run = await agent.thread("refactor-auth").run(
    "Run the tests and fix failures.",
    on_event=show_event,
)

print(run.text)
print(run.events)

Or trigger Codex auth from Python, inspired by OpenHands-style login constructors:

import os

from kagent import kagent

agent = kagent.login(model="gpt-5.5")
api_agent = kagent.login(model="gpt-5.5", api_key=os.environ["OPENAI_API_KEY"])

Options:

kagent(
    workspace=".",
    model="gpt-5.5",
    runner="cli",
    ask_for_approval="never",
    sandbox="danger-full-access",
    skip_git_repo_check=True,
    yolo=True,
    codex_bin=None,
    store_path=None,
)

agent.thread(id, ...) requires a human-readable id. kagent maps that id to Codex's generated session id using a local shelve store at .kagent/threads inside the workspace.

runner="cli" uses codex exec through an async subprocess. It stores Codex's generated session id in .kagent/threads, then uses codex exec resume on later runs with the same human-readable Thread id.

runner="sdk" uses the experimental Codex app-server SDK and persistent threads. It requires the local development codex dependency group.

agent = kagent(model="gpt-5.5", runner="cli", yolo=True)

await agent.thread("goal-test").run(
    "Create hello.txt with exactly the text hello.",
    goal=True,
)

There is no native codex exec --goal flag. goal=True translates to a prompt beginning with /goal ..., which is the behavior verified locally. Goal runs use the CLI runner, not app-server SDK thread persistence.

yolo=True maps to Codex's --dangerously-bypass-approvals-and-sandbox flag.

Examples

Already logged in with kagent login or codex login:

uv run python examples/01_already_logged_in.py

Trigger ChatGPT/Codex subscription login from Python:

uv run python examples/02_subscription_login.py

Log in with an OpenAI API key from Python:

export OPENAI_API_KEY="sk-..."
uv run python examples/03_api_key_login.py

Stream events in real time:

uv run python examples/04_stream_events.py

Run the OpenHands comparison example:

uv run --group examples python examples/openhands_thread.py

OpenHands may require interactive ChatGPT subscription login on first run.

Development

uv sync --group dev --group codex --group examples
uv run pytest
uv run ruff check .
uv run mypy
uv build

Publish:

export UV_PUBLISH_TOKEN="pypi-..."
uv build
uv publish

The package uses:

• src/ layout
• hatchling build backend
• MIT license
• py.typed for typed package consumers
• uv.lock committed for reproducible local development
• pytest, ruff, and mypy for validation

License

MIT