pycodex
pycodex brings the Codex agent loop to Python, with a CLI, reusable Agent API and browser workspace. It aims to follow upstream behavior; supported features and deliberate differences are documented in Alignment.
| Package | Provides | Python |
|---|---|---|
python-codex |
Agent, runtime, CLI, tools, Responses compatibility server and portable storage | 3.6.2+ |
pycodex-ws |
Browser workspace, Canvas, file/diff viewers and optional Feishu integration | 3.7+ |
The workspace package installs the matching core version. Python imports use
pycodex; the commands are pycodex and pycodex-ws.
Install and run
Install the core CLI:
python3 -m pip install python-codex
pycodex
Or install the browser workspace, which includes core:
python3 -m pip install pycodex-ws
pycodex-ws --help
Use python3 -m pip install --upgrade pycodex-ws to upgrade both packages
together. If a command is missing from PATH, use python3 -m pycodex or
python3 -m workspace_server with the interpreter used for installation.
Model configuration
pycodex reads ~/.codex/config.toml and the adjacent .env. Configure model,
model_provider, and the provider's base_url and env_key as needed.
The built-in openai provider uses OPENAI_API_KEY. Authentication uses API
keys; ChatGPT sign-in credentials from auth.json or the OS keychain are not
loaded.
pycodex --profile my_profile "Summarize this repository."
pycodex --config /path/to/config.toml
pycodex doctor
Models use the streaming Responses API. For a Chat Completions backend, set
use_chat_completion = true in its provider table. Other backend options include:
pycodex --vllm-endpoint http://127.0.0.1:18000
pycodex --profile my_profile --use-messages
See context and configuration and the Responses compatibility server.
CLI
Run pycodex without a prompt for an interactive session, or supply a prompt
for a single turn:
pycodex "Summarize this repository in one sentence."
printf 'Reply with exactly OK.' | pycodex
pycodex --json "Reply with exactly OK."
| Command | Purpose |
|---|---|
/model, /effort |
Show or change the model and reasoning effort |
/cd <directory> |
Change the session's working directory while idle |
/title, /history |
Manage the title and inspect conversation history |
/resume |
List saved sessions; pass an index or session UUID to resume |
/compact |
Summarize history to free context |
/fork |
Continue the current history under a new session ID |
/queue <message> |
Wait for the active turn to finish before submitting |
Ordinary input during a turn steers at the next safe sampling boundary.
Sessions are saved under CODEX_HOME/sessions. Set
model_auto_compact_token_limit in the configuration to compact automatically.
Ctrl+D or Ctrl+C closes the CLI after accepted work finishes. A second Ctrl+C
during closing exits immediately. Use pycodex --help for startup options.
Browser workspace
Create workspaces.json:
{
"workspaces": [
{"id": "demo", "work_dir": ".", "state_path": "demo", "enable_board": true}
]
}
pycodex-ws --listen 127.0.0.1:6007 --workspace-config workspaces.json
Open http://127.0.0.1:6007. The workspace combines conversations with a live
HTML Canvas and read-only file/diff viewers. Click file links in replies to open
them, and use Insert into chat to add selected code to an editable draft.
Keep the server's stdin open: EOF initiates shutdown.
The gear button starts an Agent conversation for customizing the interface
through files in ~/.pycodex/frontend/.
See the workspace guide for session controls, storage and Feishu setup. The separately distributed VS Code extension uses the same workspace backend, including on Remote SSH hosts.
Python API
Use the standard model and tool setup from Python:
from pycodex.bootstrap import build_agent, build_model
agent = build_agent(build_model())
try:
result = agent.ask("Summarize this repository in one sentence.")
print(result.output_text)
finally:
agent.shutdown()
For custom integrations, Agent accepts a model client, ToolRegistry and
ContextConfig. await agent.run_turn([...]) runs an asynchronous turn;
AgentRuntime adds input queues, commands and frontend subscriptions.
See runtime contracts and examples.
Portable configuration
Portable mode transfers an encrypted bundle of your configuration, instructions and skills to another machine. Start a storage service in a separate terminal:
python3 -m pycodex.portable.server --root .tmp/pycodex_storage --host 127.0.0.1 --port 5577
Upload the default Codex home, or specify another directory:
pycodex --put @127.0.0.1:5577
pycodex --put /path/to/.codex/@127.0.0.1:5577
After verifying a download round trip, the command prints a reusable
pycodex --call ... command. Run it on the target machine using a storage
address reachable from that machine.
Development and reference
uv sync --dev
uv run pycodex
uv run --dev pytest
- Test environments and coverage
- Architecture, package layout and runtime contracts
- Prompts, configuration and context
- Upstream alignment
- Responses compatibility server
Release notes and implementation details live in docs/.
1 maintainer
Metadata
1 maintainer
Release files for python-codex 0.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| python_codex-0.5.0.tar.gz | 235.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| python_codex-0.5.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 503.0 kB
Release files / python_codex-0.5.0.tar.gz
| Download URL | python_codex-0.5.0.tar.gz |
|---|---|
| Size | 235.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
792f10be5152aed192f80970ee2e51d59894cc9824192f0a3c2bc8008f24eac2
|
|
BLAKE2b-256 checksum How to use checksums |
1f9ab1d86caba124c8c1a49be85b4194ba597613df4158fb8afaf8f9da181e45
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 Oct 18, 2026.
Transparency logRelease files / python_codex-0.5.0-py3-none-any.whl
| Download URL | python_codex-0.5.0-py3-none-any.whl |
|---|---|
| Size | 267.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ae2ebb501c521c52dddc146df4a3c5ae03a53948078098f670c953b5f73fb9e0
|
|
BLAKE2b-256 checksum How to use checksums |
3e5102c0c8bb726b8a09ce8eac92f7f41c7f908a2f8848759ecabaf0884c580f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 Oct 18, 2026.
Transparency log
