Skip to main content

pycodex

中文 · 0.7.0 release notes

pycodex is a Python implementation of the Codex coding agent. Use it in a terminal, in a browser, or from your own Python code. It supports file editing, command execution, multiple agents and saved sessions. See upstream alignment for the supported scope and differences.

Install

Package Includes Python
python-codex CLI and Python API 3.6.2+
pycodex-ws Core plus browser workspace and optional Feishu integration 3.7+

For the CLI and Python API:

python3 -m pip install --upgrade python-codex

For the browser workspace, install pycodex-ws; it includes the matching core version:

python3 -m pip install --upgrade pycodex-ws

Configure a model

Start with config_examples/ for Responses, StepFun, Chat Completions, Claude Messages or Gemini. Give an agent your endpoint and key (StepFun Coding Plan includes its endpoint) and ask it to follow that guide to install and verify a config or profile.

Create ~/.codex/config.toml. For example, with OpenAI:

model = "gpt-5.4"
model_provider = "openai"

Supply the API key through the environment or ~/.codex/.env:

export OPENAI_API_KEY="your-api-key"

For another provider, configure its base_url and env_key. Select the API with compat_api in the profile or provider table:

compat_api API
"none" (default) Responses
"chat_completions" Chat Completions, including Step
"messages" Claude Messages
"gemini" Gemini API

Legacy use_chat_completion = true/false remains supported as chat_completions/none.

Use --profile NAME to select NAME.config.toml beside the base config or an embedded [profiles.NAME] table. Use --config PATH for a different config file, and pycodex doctor to check configuration and connectivity. The browser workspace picks up profile changes for new sessions without a restart.

See configuration and the Gemini setup example. Gemini 4 Argon and Carbon include prompts adapted from Antigravity's coding guidance. Gemini tool arguments stream as they are generated; tools run after the complete call is received. Gemini tool results use response.output; returned images stay in the matching functionResponse.parts. Gemini continuation omits unsigned empty text parts while preserving thought signatures, including when resuming recorded sessions.

Use the CLI

Run these commands from your project directory:

pycodex
pycodex "Summarize this repository."
pycodex --profile my_profile "Review the latest changes."
pycodex --json "Summarize this repository."

The first command starts an interactive session; the others run a single task. Web skill completion is an optional frontend feature. Apply skill-completion through Customize to enable @/$ prefix suggestions. The agent can edit files and run commands with your user account's permissions.

Command Purpose
/model, /effort View or change the model and reasoning effort
/cd <directory> Change directory while idle
/title, /history Manage the title and inspect conversation history
/resume List or resume saved sessions
/retry Retry the last failed model request
/compact Summarize history to free context
/queue <message> Submit a task after the current one finishes

Use /retry 429|502 to retry either error code indefinitely, or /retry * to retry every model request error, including disconnects. /retry off disables infinite retries.

Manual and automatic compaction preserve the tool declarations, instruction prefix and ordinary tool choice. The Agent can use its live tools while preparing the summary in memory. Success writes one summary checkpoint. On failure, completed tool exchanges are saved so the Agent can use their results on retry.

Send a message while the agent is working to redirect it, or use /queue to wait. Sessions are saved under ~/.codex/sessions by default. Ctrl+C or Ctrl+D closes the session after issued operations finish. Run pycodex --help for all options.

For a local vLLM server:

pycodex --vllm-endpoint http://127.0.0.1:18000

Use the browser workspace

After installing pycodex-ws, create workspaces.json:

{
  "workspaces": [
    {"id": "demo", "work_dir": ".", "state_path": "demo", "enable_board": true}
  ]
}

Start the server and keep the terminal open:

pycodex-ws --listen 127.0.0.1:6007 --workspace-config workspaces.json

Open http://127.0.0.1:6007. The workspace uses the same model configuration as the CLI and provides conversations, a live HTML Canvas, and file/diff viewers. Chat updates arrive through two-second polling; completed replies render as Markdown. When opening or switching conversations, a loading indicator above the input stays visible until the latest session snapshot arrives, including when cached messages are shown immediately. Click the × beside a session and confirm to remove it from the workspace. Each entry shows the time since the session's last activity. Click file links to inspect code, then select text and use Insert into chat to include it in your next message. Local HTML links such as report.html#results open the preview at the named section. Each input displays its author and creation time, including separate messages in a steer batch. Recorded messages keep that metadata when the session resumes. Restoring a tab reads the rollout tail needed for its latest 80 display rows; Agent resume still restores the complete active context after the last checkpoint.

Settings → Customize Agent opens the optional feature catalog. Browse the descriptions and send a feature name, ID or custom request in chat to start the Agent. Settings also provides password-protected sharing and External Call sessions that connect an external client to a Web conversation. See the workspace guide for session controls, storage and Feishu setup. A separate VS Code extension connects to the same backend, including over Remote SSH.

Use the Python API

Save this as example.py and run python3 example.py. It uses the model configuration above and the standard tools:

from contextlib import closing

from pycodex import AgentsManager, CodexConfig
from pycodex.bootstrap import build_model
from pycodex.utils.async_bridge import run_async


async def main():
    config = CodexConfig.from_env()
    with closing(build_model(config.provider)) as model:
        runtime = AgentsManager(
            model.client, config.context,
        ).create_root_runtime()
        try:
            await runtime.start()
            receipt = await runtime.submit_input("Summarize this repository.")
            print((await receipt.future).output_text)
        finally:
            await runtime.close()


run_async(main())

AgentsManager creates the runtime; submit_input submits work. Await receipt.future for the result. Models and tools import EventScope from pycodex.events and call EventScope.emit(event) to notify the session’s observers. Each observer receives its own copy. During a turn the event loop reports observer errors and the Agent continues. Custom model clients return token counts in ModelResponse.usage for goal accounting and automatic compaction. The example closes the runtime and any local compatibility server when finished. See runtime contracts for custom models, tools and integrations.

More features

Development

From the repository root:

env -u VIRTUAL_ENV uv sync --dev
env -u VIRTUAL_ENV uv run --dev pytest

See the development guide, test guide, runtime architecture and workspace API.

Metadata

Release files for python-codex 0.7.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for python-codex 0.7.0
File Size Uploaded Provenance Actions
python_codex-0.7.0.tar.gz 369.1 kB With provenance Details for python_codex-0.7.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for python-codex 0.7.0
File Interpreter ABI Platform Actions
python_codex-0.7.0-py3-none-any.whl Python 3 none any Details for python_codex-0.7.0-py3-none-any.whl

Total release size: 775.8 kB

Release files / python_codex-0.7.0.tar.gz

Download URL python_codex-0.7.0.tar.gz
Size 369.1 kB
Tags Source
SHA-256 checksum
How to use checksums
add2335d62f56dfa3221faebc7ef77755f8e3b61462937dd3e400f87aafb9c6f
BLAKE2b-256 checksum
How to use checksums
979b814790a1ab51fc998d38d63473d19b1a4a804be8a9bebb140706a8416768
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Release files / python_codex-0.7.0-py3-none-any.whl

Download URL python_codex-0.7.0-py3-none-any.whl
Size 406.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
413db91cb79c6fe4483c32d6ad430336518ac0657ebfe85f7259c089da658ebd
BLAKE2b-256 checksum
How to use checksums
7c8e43c204d9d490932a1047cd71110fa11fbbe9844633dc3e31edfae3b6b5a1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Security for python-codex 0.7.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for python_codex-0.7.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.7.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page