Skip to main content
SpecStory complements Claude Code, Cursor CLI, and Codex CLI, terminal-first AI coding agents that automate edits, testing, and PR workflows. SpecStory wraps these agents so every command, response, and decision becomes Markdown you can review and share.

Claude Code

Launch Claude Code through SpecStory to capture end-to-end terminal conversations as Markdown.

Cursor CLI

Mirror Cursor’s agent in your terminal and archive collaborative reasoning with SpecStory.

Codex CLI

Pair Codex CLI with SpecStory to preserve GPT-powered coding sessions for later review.

​
Why wrap terminal agents with SpecStory?

  • Portable reasoning: Markdown transcripts travel with your repository, not a volatile terminal scrollback.
  • Retroactive capture: specstory sync converts past Claude, Cursor, or Codex sessions even if you forgot to wrap them.
  • Team-friendly context: Share the “why” behind automation-driven edits in pull requests and docs.
  • CLI-first flexibility: Keep your existing commands, aliases, and automations while SpecStory observes in the background.
Prefer a macOS-native experience? BearClaude ships with SpecStory support and Claude Code built in.

​
Universal workflow

# 1. Install or update the SpecStory CLI
brew tap specstoryai/tap
brew update
brew install specstory

# 2. Run your preferred agent through SpecStory (choose one)
specstory run claude   # or cursor / claude

# 3. Export past sessions (pick the agent you used)
specstory sync claude  # or cursor / claude
Transcripts land in .specstory/history/ with timestamps and metadata ready for code review or knowledge sharing.

​
Understand specstory sync

specstory sync retroactively exports chat history, making it useful when you forget to start with specstory run or want to convert older work.
  • specstory sync: export every available session (Claude, Cursor, Codex) for the current project.
  • specstory sync claude -s <session-uuid>: convert a specific Claude session by its UUID.
  • specstory sync cursor --console: watch verbose logging while exporting Cursor CLI sessions.
  • specstory sync codex: capture all stored Codex CLI conversations.
All generated Markdown ends up in .specstory/history/*.md, grouped by timestamp and agent.

​
Tips for every agent

  • Use /clear (or the agent’s reset command) between tasks to keep transcripts scoped.
  • Feed shell context with ! commands so SpecStory captures inputs and outputs together.
  • Commit .specstory/history/ alongside code to preserve design intent and debugging rationale.
  • Store persistent project notes (e.g., CLAUDE.md) so agents stay aligned across sessions.

​
Troubleshooting

  • specstory run shows nothing: confirm the agent binary (claude, cursor-agent, or codex) is installed and in your PATH.
  • No Markdown written: ensure you are inside a writable project folder when launching the wrapper.
  • Sync exports zero files: verify the agent has stored session history in the current working directory.
  • Need help? Email support@specstory.com or open an issue on GitHub.
⌘I