introduction.md

Python Client Introduction

Purpose

The codex-manager Python client is a control-plane SDK for codex-manager APIs and websocket events.

Use it when you need Python workflows to:

• create/read/update chats and projects
• control turns, approvals, and tool-input decisions
• read/write per-session settings used by UI and extensions
• subscribe to realtime events and app-server signal pass-through
• synchronize async/sync workflows with generic and session-aware wait helpers
• orchestrate queue/supervisor automation
• handle dynamic item/tool/call requests with Python remote-skill handlers through codex-manager routes

Practical workflow categories

• script repeatable session tasks (create, message, inspect transcript)
• run approval/tool-input queues from service workers
• apply and read session settings used by UI and extensions
• host long-running stream listeners for automation triggers

Install

From repository root:

pip install -e packages/python-client

First use

from codex_manager import CodexManager

cm = CodexManager.from_profile("local")
health = cm.system.health()
print(health["status"])
cm.close()

Client types

• CodexManager: sync workflows
• AsyncCodexManager: async workflows, high-throughput event handling, long-running services

Both clients expose the same domain structure.

Both clients also expose polling-based wait helpers for synchronization:

• cm.wait.until(...) / await acm.wait.until(...) for generic conditions
• cm.wait.turn_status(...) / await acm.wait.turn_status(...) for turn-status reads and expected-status waits
• cm.wait.send_message_and_wait_reply(...) / await acm.wait.send_message_and_wait_reply(...) for request/reply flows
• default polling cadence is latency-oriented (interval_seconds=0.25) and can be overridden per call when slower polling is preferred

Typed OpenAPI facade

Both clients also expose a typed facade:

• cm.typed for sync
• acm.typed for async

Typed methods use generated Pydantic models from OpenAPI and return typed responses for supported operations while keeping all existing dict-based domains unchanged.

Advanced extension points

Both clients now support protocol-based dependency injection for advanced integrations:

• custom request executors (request_executor)
• dynamic header providers (header_provider)
• explicit retry policies (retry_policy, retryable_operations)
• custom hook registries (hook_registry)
• injectable stream routers (stream_router)
• deterministic client plugins (plugins)

Hook middleware objects can be registered directly with use_middleware(...) in addition to decorator hooks.

Documentation map

• Quickstart: quickstart.md
• Practical recipes: practical-recipes.md
• Team mesh example (no orchestrator jobs): team-mesh.md
• API domain map: api-surface.md
• Streaming + decorators + handlers: streaming-and-handlers.md
• Streaming event routing reference: streaming-event-routing-reference.md
• Streaming reliability patterns: streaming-reliability-patterns.md
• Remote-skill bridge: remote-skills.md
• Remote-skill lifecycle/catalog: remote-skills-lifecycle-and-catalog.md
• Remote-skill dispatch/reliability: remote-skills-dispatch-and-reliability.md
• Session settings + automation patterns: settings-and-automation.md
• Protocol-oriented implementation contract: protocol-interfaces.md
• Typed model/facade + boundary validation implementation: typed-models.md
• Development and packaging details: development-and-packaging.md

Recommended paths by use case

• "I want to automate chats quickly":
  • quickstart.md
• "I want copy-paste production recipes":
  • practical-recipes.md
• "I need event-driven workflows":
  • streaming-and-handlers.md
• "I need dynamic tool calls backed by Python handlers":
  • remote-skills.md
• "I want a multi-agent team workflow without server orchestrator jobs":
  • team-mesh.md
• "I need settings-driven supervisor automation":
  • settings-and-automation.md
• "I want stronger typed request/response handling":
  • typed-models.md
• "I want to tune typed/dict boundary validation behavior":
  • typed-models.md