This is the one-level-deeper product foundation for Codex Manager.
It starts where README.md leaves off: the README explains what exists; this PRD explains what the product must achieve, what quality bar applies, and what is intentionally out of scope.
Use this as the product source of truth before implementing or reviewing behavior changes.
Codex Manager
A local-first control plane for Codex sessions that provides web/CLI/Python interfaces over one API surface, while keeping codex app-server as runtime authority.
Primary:
- local operators and developers running Codex-driven workflows.
Secondary:
- extension authors building automation workflows without modifying API core.
- reliable session/project lifecycle operations.
- stream-correct turn UX with clear completion/failure states.
- safe approval/tool-input/tool-call handling.
- reproducible operations through API, CLI, and Python SDK parity.
- extension-driven queue automation for higher-level workflows.
- deterministic state transitions under reconnect/restart windows.
- idempotent behavior for repeated user/operator actions.
- operational observability for queue/extension/runtime failures.
- documentation parity with real implementation behavior.
- multi-tenant SaaS identity/permissions platform.
- replacing app-server runtime semantics with custom execution engine.
- fully distributed orchestration federation in core product.
- IDE-grade file/project management replacing chat-first workflow.
The expected baseline user journey:
- create/select a chat.
- send a request and observe progressive stream output.
- resolve approvals/tool-input prompts when required.
- inspect summarized thought/tool activity when needed.
- continue, switch chats, and resume reliably later.
The expected baseline operator journey:
- validate API health/auth/runtime readiness.
- operate flows through CLI/API/Python with route parity.
- inspect queue and extension lifecycle states deterministically.
- recover from failures through documented runbooks.
- Web UI (
apps/web) for primary transcript and control workflow. - API control plane (
apps/api) for lifecycle + runtime bridging. - CLI (
apps/cli) for scriptable operational parity. - Python SDK (
packages/python-client) for programmable automation. - Extension runtime (
agents/*+ runtime SDK contracts) for workflow semantics.
A product change is complete only when:
- behavior is implemented and validated.
- external workflow/API/config impacts are documented in the same change.
- architecture/operations/protocol docs still match real behavior.
- release-gate and conformance checks remain green.
- Start here for scope and decision boundaries.
- Use level-2 PRD docs for full requirements and delivery/risk details.
- Use architecture/implementation docs for “how it works today.”
- Detailed requirements:
product/core-prd-requirements.md - Delivery, metrics, and risk:
product/core-prd-delivery-and-risk.md - Agent platform requirement set:
product/agent-platform-requirements.md
- Architecture and invariants:
architecture.md - Setup and operations:
operations/setup-and-run.md - Protocol index:
codex-app-server.md - Current implementation snapshot:
implementation-status.md