Overview

SpecStory complements Claude Code, Cursor CLI, Codex CLI, Droid CLI, and Gemini 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 auto-capture all your AI-conversations as Markdown.

Codex CLI

Pair OpenAI Codex CLI with SpecStory to preserve AI-powered coding sessions and intent.

Droid CLI

Capture Factory Droid CLI sessions with SpecStory and keep your prompts and reasoning intact.

Cursor CLI

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

Gemini CLI

Wrap Gemini CLI with SpecStory to log AI-driven terminal workflows as shareable Markdown.

Why use SpecStory with terminal agents?

• Portable reasoning: Markdown transcripts travel with your repository, not a volatile terminal scrollback.
• Retroactive capture: specstory sync converts past Claude, Cursor, Codex, Droid, or Gemini 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.

Universal workflow

Install SpecStory CLI

Install or update the SpecStory CLI once, then use it with any supported agent.

brew tap specstoryai/tap
brew update
brew install specstory
specstory version
specstory check

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

Run an agent through SpecStory

Choose one agent per session and launch it with specstory run.

# Run your preferred agent through SpecStory (choose one)
specstory run claude   # or cursor / codex / droid / gemini

# Export past sessions
specstory sync

# Watch for any new agent activity
specstory watch

# List agent sessions for the current project directory
specstory list

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, Droid, Gemini) 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.
• specstory sync droid: capture all stored Droid 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.

Need to adjust defaults or review flags? Visit the Terminal Coding Agents settings.

Troubleshooting

• specstory run shows nothing: confirm the agent binary (claude, cursor-agent, codex, droid, or gemini) 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.