pycodex
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 includes a prompt adapted from Antigravity.
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 |
/compact |
Summarize history to free context |
/queue <message> |
Submit a task after the current one finishes |
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.
Click file links to inspect code, then select text and use Insert into chat
to include it in your next message.
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.
The settings menu provides interface customization, password-protected workspace sharing, and One-line Agent: an Agent that runs directly in most shells without installation, for bootstrapping an Agent environment or simple debugging. 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. The example closes the runtime and any
local compatibility server when finished. See runtime contracts for
custom models, tools and integrations.
More features
- Portable configuration: transfer encrypted configuration, instructions and skills to another machine.
- Frontend customization: change the workspace through an Agent conversation or your own CSS/JavaScript.
- Responses compatibility server: expose a supported backend through the Responses API.
- Retries and fallback models: configure recovery from model failures.
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.6.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| python_codex-0.6.3.tar.gz | 364.4 kB | With provenance | Details for python_codex-0.6.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| python_codex-0.6.3-py3-none-any.whl | Python 3 | none | any | Details for python_codex-0.6.3-py3-none-any.whl |
Total release size: 767.6 kB
Release files / python_codex-0.6.3.tar.gz
| Download URL | python_codex-0.6.3.tar.gz |
|---|---|
| Size | 364.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e561fd0f4836d4b680e813482c083b8c18a2395f5b74b87678b3c246615ad53b
|
|
BLAKE2b-256 checksum How to use checksums |
ab53090ba64d23ab3ad59fad9581bf51dfbefaefc0394a90a47d7b441248b2d7
|
| 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 18, 2026.
Transparency logRelease files / python_codex-0.6.3-py3-none-any.whl
| Download URL | python_codex-0.6.3-py3-none-any.whl |
|---|---|
| Size | 403.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b72736cd646a718903a4468ff4e099528978b90dff3a240cb8e9d86e141c62e4
|
|
BLAKE2b-256 checksum How to use checksums |
caa34d6484b7909cc5758def54e6e77f6e4b5326e73f625a52737c588ff130ed
|
| 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 18, 2026.
Transparency logSecurity for python-codex 0.6.3
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.
Attestation for python_codex-0.6.3.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 18, 2026.
Transparency logA 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.