Claude Code

Claude Code gives you an AI pair-programmer directly in the terminal. Run it through SpecStory to capture every step of the conversation and reasoning as Markdown that ships with your repo.

Run Claude Code with SpecStory

specstory run claude

While the wrapper is active you can use the full Claude Code feature set, including multi-file edits, /init, /clear, and slash commands. SpecStory records both sides of the chat plus terminal output generated by ! commands.

List existing Claude Code sessions

List all the Claude Code sessions SpecStory can see and sync for the current project directory.

specstory list claude

Sync existing Claude Code sessions

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

# Convert everything Claude Code has stored locally
specstory sync claude

# Export a single session by ID
specstory sync claude -s <session-uuid>

# Inspect sync logs in your terminal
specstory sync claude --console

• Session sources: Read from ~/.claude/projects/ (JSONL files).

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

Watch for Claude Code activity

Prefer to run Claude Code 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 Claude Code agent activity
specstory watch claude

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

Best Practices

• Segment workstreams: Sstart fresh sessions per task so transcripts stay focused.
• Create CLAUDE.md: Seed the assistant with project docs once, and re-use those instructions automatically.
• Keep sessions focused: Use /clear between tasks so transcripts stay tight and portable.
• Archive transcripts: Commit .specstory/history/ alongside your code to preserve design intent.

Troubleshooting

• claude command missing: Run claude --version outside SpecStory to verify installing Anthropic's CLI.
• No Markdown output: Make sure you start specstory run claude inside a writable project folder.
• specstory sync finds nothing: Claude Code must have an existing session database in the current directory.
• Need help? Reach out at support@specstory.com or open an issue on GitHub.