Codex

Codex CLI gives you AI-powered code code generation and reasoning straight from the terminal. Pair it with SpecStory to preserve every AI-powered coding session and intent as Markdown.

Run Codex CLI with SpecStory

Tip

Install SpecStory first: see the Terminal Coding Agents overview.

specstory run codex

Note

For the full SpecStory CLI command and flag reference, see Configuration.

You can continue to use Codex CLI features such as multi-file diffs, auto PRs, and test runs while SpecStory records the conversation and shell context.

List existing Codex CLI sessions

List all the Codex CLI sessions SpecStory can see and sync for the current project directory.

specstory list codex

Sync existing Codex CLI sessions

Forgot to launch with specstory run codex? Convert prior sessions with specstory sync.

# Convert every stored Codex CLI session
specstory sync codex

# Convert a single session by UUID
specstory sync codex -s <session-uuid>

# Watch the sync progress
specstory sync codex --console

Session sources: Reads from ~/.codex/history.

The resulting Markdown files live under .specstory/history/ with timestamps and metadata for easy sharing.

Watch for Codex CLI activity

Prefer to run the Codex CLI directly or via another tool? Use specstory watch to watch the current project directory for any new agent activity and auto-save it to markdown.

# Watch for only activity from any supported coding agent
specstory watch

# Watch for only new Codex CLI agent activity
specstory watch codex

Run specstory watch without an agent name to capture activity from any supported provider.

Best Practices

Segment workstreams: Use Codex CLI’s commands to start fresh sessions per task so transcripts stay focused.
Document custom tooling: Add notes about bespoke scripts or workflows to the Markdown files for teammate handoff.
Archive transcripts: Commit .specstory/history/ alongside your code to preserve design intent.

Troubleshooting

codex command missing: Confirm installation by running codex --version outside SpecStory.
No Markdown output: Run inside a project directory that contains .specstory/ and allows writing.
Sync returns nothing: Ensure Codex CLI has existing session logs in the current workspace.
Need assistance? Contact support@specstory.com or open a ticket on GitHub.