feat: Session Replay & Templates

[Aki-07]

What feature would you like to see?

Status: RFC (Request for Comments)
Proposer: @Aki-07
Target: Codex CLI v0.3.0+

Problem Statement

Current State:
Every Codex session is ephemeral. When developers find a successful workflow (e.g., "set up React + TypeScript + Tailwind"), they cannot easily:

• Reproduce it across projects
• Share it with team members
• Version control the workflow
• Apply it with different parameters

Pain Points:

• Developers repeatedly type similar prompts across projects
• Successful patterns are lost after the session ends
• No way to create "standard playbooks" for common tasks
• Onboarding new developers requires manual guidance

Overview

This feature would allow developers to:

1. Record a successful Codex session (prompts, commands, file diffs, responses).
2. Convert it into a reusable, parameterized template (YAML-based).
3. Replay it anytime using codex replay <template-name>.
4. Share templates via Git, enabling collaborative and version-controlled workflows.
5. Discover community or official templates via a built-in template marketplace.

Why it matters

Currently, every Codex session is transient, developers can’t easily reproduce or share a working flow.
This feature would:

1. Improve reproducibility (no more retyping successful prompts).
2. Boost team collaboration (shared org templates via Git).
3. Simplify onboarding (run codex replay org/setup-react-app).
4. Encourage community-driven patterns (React setup, Auth, CI/CD, etc.).
5. In short, it elevates Codex from a conversational tool to a reproducible automation assistant.

Metrics

User Impact:

• 50% reduction in time for repetitive tasks
• 3x increase in workflow reuse across projects
• Easier team onboarding (shared templates)
• Community template library growth

Technical Metrics:

• Template execution success rate > 90%
• Replay performance within 10% of original session
• Zero security incidents from template execution

Key Components (high-level)

1. Recorder: Logs prompts, commands, file diffs, and outputs.
2. Template Engine: Converts sessions into editable templates with parameters.
3. Replay CLI: Deterministic execution with preconditions, approvals, rollback.
4. Registry/Marketplace: Git-based registry for installing and sharing templates.

Implementation Plan

I’ve already drafted a detailed build plan and schema design for this feature including CLI structure, template YAML spec, security policy, and roadmap
Happy to contribute this implementation end-to-end once approved.

Additional information

Example CLI workflow:

codex record start
# Developer interacts with Codex
codex record stop --out session.jsonl
codex template init --from session.jsonl
codex replay react-app-setup --set project_name=my-app

Duplicate Check & Relationship to Existing Issues

While #4932 touches the surface of reusable “task templates,” this RFC introduces a broader, higher-level system enabling developers to record, parameterize, replay, and share entire Codex sessions, not just single prompts or scripts.
Therefore, this is not a duplicate, but an evolution of that concept into a structured replay and workflow automation framework for Codex CLI + IDE.

[github-actions]

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

• codex web: task library to store tasks #4932
• Dynamic Expressions, Command Substitution, and Context Variables in Custom Prompts #5019
• Symlinking prompts to ~/codex/prompts does not work #5040
• Namespacing custom prompts #4735
• Look for custom prompts in {project root}/.codex/prompts/ first #4734

Powered by Codex Action

[Aki-07]

@codex-maintainers Any opinions on this?

[0xdevalias]

Recorder: Logs prompts, commands, file diffs, and outputs.

Are the session transcripts that are already logged in ~/.codex/sessions/ sufficient for this part?

---

Template Engine: Converts sessions into editable templates with parameters.

This is the main part I personally see value in; though even without something built in, you could probably already point codex or another agent / LLM at a session file and ask it to post-process it into a reusable custom prompt (in ~/.codex/prompts/) or similar:

• https://github.com/openai/codex/blob/main/docs/prompts.md

  • Custom Prompts

    Save frequently used prompts as Markdown files and reuse them quickly from the slash menu.

---

Replay CLI: Deterministic execution with preconditions, approvals, rollback.

While it's not a deterministic execution, preconditions, approvals, rollback, etc; if a previous session transcript is transformed into a custom prompt; then it can just be called directly:

• https://github.com/openai/codex/blob/main/docs/prompts.md

  • • How to use:
      • Start a new session (Codex loads custom prompts on session start).
      • In the composer, type / to open the slash popup and begin typing your prompt name.
      • Use Up/Down to select it. Press Enter to submit its contents, or Tab to autocomplete the name.

---

Registry/Marketplace: Git-based registry for installing and sharing templates.

Something like this could definitely be interesting; but I wonder if a decentralised pattern for finding these (eg. GitHub repo prefix / tag / similar) might be better than a centralised registry repository.

[Aki-07]

@0xdevalias, thanks for the thoughtful feedback 🙏
Let me clarify a few design intentions behind each component:

Recorder vs Existing Session Logs
You’re absolutely right that Codex already stores transcripts in ~/.codex/sessions/.
However, the Recorder proposed here is semantic, it doesn’t just log raw events but normalizes them into structured JSON (prompt, command, file diff, response, timestamp).
This structure makes replay and parameter injection deterministic and auditable, closer to a “codex.jsonl schema” than plain history logs.

Template Engine
Agreed! an LLM could already post-process transcripts into a prompt.
The goal here is to formalize that process into a first-class CLI workflow:

codex template init --from session.jsonl  
codex replay react-app-setup --set project_name=my-app

Think of it as codifying “what users are already doing manually” into a reproducible workflow language.

Replay CLI
While /prompts covers one-shot inserts, replay aims to manage multi-turn sessions, carrying context, injecting parameters, and verifying file changes deterministically.
It’s more like a hybrid between “prompt macro” and “agent script,” designed for CI/CD-style reproducibility.

Registry / Marketplace
100% agree on decentralization! I propose leveraging GitHub-discoverable repos tagged with codex-template or similar (à la Homebrew tap model).
Codex CLI could simply support:

codex template install github:org/repo

That avoids central infra and keeps it open.
Happy to incorporate these refinements into the RFC spec if that direction sounds aligned

[0xdevalias]

Recorder vs Existing Session Logs
You’re absolutely right that Codex already stores transcripts in ~/.codex/sessions/.
However, the Recorder proposed here is semantic, it doesn’t just log raw events but normalizes them into structured JSON (prompt, command, file diff, response, timestamp).

@Aki-07 nods I understand that, though I guess my point was more that I believe there is sufficient details in those session logs to be able to extract the prompt, command, file diff, response, timestamp, etc.

Like skimming through one of my recent sessions' .jsonl I see:

• timestamp
• type: event_msg, payload.type: user_message
• type: response_item, payload.type: message
• type: response_item, payload.type: function_call
• type: response_item, payload.type: function_call_output
• type: response_item, payload.type: custom_tool_call
• type: response_item, payload.type: custom_tool_call_output
• etc

So, my point was more that an explicit 'record' mode may not really be needed, as all of the 'primitives' that would be recorded anyway might already be present in the session logs in a structured format.

So, instead of focussing on recording; the tool could instead just transform the existing session log directly into the 'template engine' format.

---

Template Engine
Agreed! an LLM could already post-process transcripts into a prompt.
The goal here is to formalize that process into a first-class CLI workflow:

Think of it as codifying “what users are already doing manually” into a reproducible workflow language.

@Aki-07 Yeah, makes sense; and having a single 'well known/supported' way of achieving it definitely has its merits; though I guess this also wouldn't necessarily need to be built into codex directly (as based on the state of a lot of issues/PRs here, I suspect the codex team is likely more focussed on other areas for now; so might take a long time to actually be considered/etc).

Particularly if there are already enough primitives in the session logs that a separate 'recorder' isn't needed, then this could probably be built as an external helper tool; which would likely allow it to exist / become useful quicker.

---

Replay CLI
While /prompts covers one-shot inserts, replay aims to manage multi-turn sessions, carrying context, injecting parameters, and verifying file changes deterministically.
It’s more like a hybrid between “prompt macro” and “agent script,” designed for CI/CD-style reproducibility.

@Aki-07 Yeah ok, that makes sense; thanks for explaining how it differs from the 'one-shot' custom prompts that are currently supported.

Continuing similar 'this could potentially be built as an external tool right now' line of thinking; the two parts that come to mind for this Replay CLI aspect are:

• Structured multi-turn sessions, particularly with some logic/validation/etc kind of feels like it might align well with the recently announced Agent Builder / Agents SDK functionality
  • https://platform.openai.com/docs/guides/agent-builder

    • Agent Builder

    • Visually assemble, debug, and export multi-step agent workflows from the playground.

    • https://platform.openai.com/agent-builder
  • https://platform.openai.com/docs/guides/agents-sdk

    • Agents SDK

    • This library makes it straightforward to build agentic applications—where a model can use additional context and tools, hand off to other specialized agents, stream partial results, and keep a full trace of what happened.

• And then that might be able to be combined with the also recently announced Codex SDK
  • https://developers.openai.com/codex/sdk/

    • Codex SDK

    • Programmatically control local Codex agents

Like I wonder if the 'template engine' aspect might be able to just be a sort of automated translation of a raw session log into an Agent Builder workflow / similar; that could then be run with Agents SDK / Codex SDK / similar?

I haven't looked too deeply into these to see what is currently supported for them within Codex itself; or what the team might have in mind for future; but perhaps a more generic feature request for Codex that would then enable more complex custom things (like the proposal in this issue) to be built more easily would be having 'native' support for running an Agent Builder style workflow within a codex session directly.

---

Registry / Marketplace
100% agree on decentralization! I propose leveraging GitHub-discoverable repos tagged with codex-template or similar (à la Homebrew tap model).

@Aki-07 Agreed; that's seemed to work well for other projects I've used (eg. from memory it's how the GitHub gh CLI extensions work).

[Aki-07]

@rakesh-oai @dedrisian-oai requesting for your opinions