Skip to main content
Codex CLI gives you GPT-powered code edits and reasoning straight from the terminal. Pair it with SpecStory to convert every session into reusable Markdown notes.

​
Install SpecStory CLI

Install the SpecStory CLI once to wrap Codex and manage your transcripts. 
brew tap specstoryai/tap
brew update
brew install specstory
specstory version
specstory check
Need Linux or WSL binaries or installing manually? Download the archive that matches your OS and architecture (for example SpecStoryCLI_Linux_x86_64.tar.gz or SpecStoryCLI_Darwin_arm64.zip) from the latest release, make them executable, and move them into your PATH.
tar -xzf SpecStoryCLI_Linux_x86_64.tar.gz   # unzip the Darwin archive on macOS
sudo mv specstory /usr/local/bin/
sudo chmod +x /usr/local/bin/specstory
specstory version
Swap the archive name for the asset you downloaded and repeat when upgrading.

​
Run Codex CLI with auto-save

Launch Codex through SpecStory to capture a Markdown history in .specstory/history/. 
specstory run codex
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.

​
Sync older Codex sessions

If you used Codex before installing SpecStory, retroactively export existing sessions. 
# 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
The resulting Markdown files live under .specstory/history/ with timestamps and metadata for easy sharing.

​
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 has existing session logs in the current workspace.
  • Need assistance? Contact support@specstory.com or open a ticket on GitHub.
⌘I