Gemini CLI

Gemini CLI is Google's terminal agent for code generation and multi-modal reasoning straight from the terminal. Pair it with SpecStory to turn every session into reusable Markdown notes.

Run Gemini CLI with SpecStory

specstory run gemini

You use Gemini CLI normally while SpecStory records the entire conversation and context.

List existing Gemini CLI sessions

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

specstory list gemini

Sync existing Gemini CLI sessions

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

# Convert every stored Gemini CLI session
specstory sync gemini

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

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

• Session sources: Read from ~/.gemini/tmp/<project_hash>/chats.

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

Watch for Gemini CLI activity

Prefer to run the Gemini 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 Gemini CLI agent activity
specstory watch gemini

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

Best Practices

• Segment workstreams: Use Gemini 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

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