Skip to main content

Documentation Index

Fetch the complete documentation index at: https://repr.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

The generate command is the core of repr. It analyzes your git history and uses an LLM to write stories—turning raw commits into professional narratives.

​
Usage

repr generate [OPTIONS]

​
Options

OptionDescriptionDefault
--local, -lUse local LLM (Ollama/LocalAI)Auto (if not signed in)
--cloudUse cloud LLM (requires login)Auto (if signed in)
--template <name>, -tTemplate: resume, changelog, narrative, interviewresume
--repo <path>Only generate for specific repositoryAll tracked repos
--commits <shas>Comma-separated commit SHAs to generate fromRecent commits
--since <date>Generate from commits since date (e.g., 2024-01-01, monday, 2 weeks ago)-
--days <n>Generate from commits in the last N days90
--batch-size <n>Number of commits to group into one story5
--dry-runPreview what would be sent without saving-
--prompt <text>, -pAppend custom instructions to the LLM-

​
How It Works

  1. Selects commits - From specific SHAs (--commits), a timeframe (--since, --days), or defaults to last 90 days
  2. Analyzes changes - Reads diffs to understand what actually changed
  3. Generates narrative - LLM writes a story using your chosen template
  4. Saves locally - Story saved to ~/.repr/stories/<id>.md
All generation happens locally by default. Diffs never leave your machine unless you use --cloud.

​
Examples

​
Basic Generation

Generate using local LLM: 
repr generate --local
Output: 
Generating stories (local LLM)...

myproject
  • Built OAuth2 integration with Google and GitHub providers
  • Implemented Redis caching layer for session management
  • Fixed race condition in authentication flow

Generated 3 stories
Stories saved to: ~/.repr/stories

​
Use a Specific Template

Generate interview-ready stories with STAR format: 
repr generate --template interview --local
This creates stories structured as:
  • Situation: Context and problem
  • Task: What needed to be done
  • Action: How you solved it
  • Result: Measurable impact
Perfect for behavioral interviews.

​
Generate from a Specific Timeframe

Control the time range for commit selection: 
# Last 30 days
repr generate --days 30 --local

# Since a specific date
repr generate --since 2024-01-01 --local

# Natural language dates
repr generate --since "2 weeks ago" --local
repr generate --since monday --local
repr generate --since "last month" --local
Supported date formats:
  • ISO dates: 2024-01-01, 2024-06-15
  • Day names: monday, tuesday, etc. (previous occurrence)
  • Relative: 3 days ago, 2 weeks ago, 1 month ago
  • Keywords: yesterday, today, last week, last month

​
Generate from Specific Commits

Target exact commits instead of using recent history: 
# List commits to find SHAs
repr commits --limit 20

# Generate from selected commits
repr generate --commits abc1234,def5678,ghi9012 --local

​
Generate for One Project

Focus on a single repository: 
repr generate --repo ~/code/important-project --template resume

​
Add Custom Context

Guide the LLM with additional instructions: 
repr generate --local --prompt "Focus on performance optimizations and scalability improvements"
This appends your instructions to the system prompt, influencing how the LLM writes your stories.

​
Preview Before Generating

See what would be sent to the LLM without actually generating: 
repr generate --dry-run
Output: 
Dry Run Preview
Commits to analyze: 23
Template: resume

Estimated tokens: ~45,000

Sample commits:
  • abc1234 Implement user authentication
  • def5678 Add Redis caching
  • ghi9012 Fix session timeout bug
  ... and 20 more
Useful for checking token limits before expensive cloud generation.

​
Templates Comparison

TemplateBest ForStyleExample
resumePortfolios, performance reviewsAction verbs, impact-focused”Optimized database queries by 40%…”
changelogRelease notes, sprint summariesCategorized bullets (Added/Fixed/Changed)“Fixed: Race condition in auth flow”
narrativeBlog posts, case studiesStorytelling, problem-solving journey”We started by identifying a bottleneck…”
interviewJob interviews, promotionsSTAR format (Situation/Task/Action/Result)“Result: Reduced failures by 60%“

​
Batch Sizes

The --batch-size option controls how many commits are grouped into one story:
  • Small (3-5): More stories, focused scope. Good for daily/weekly reviews.
  • Medium (5-10): Balanced. Good for feature work.
  • Large (10-20): Comprehensive stories. Good for project summaries.
# Daily micro-stories
repr generate --batch-size 3 --local

# Big-picture project narrative
repr generate --batch-size 15 --template narrative --local

​
Privacy Modes

​
Local-Only (Maximum Privacy)

repr generate --local
  • ✅ Diffs processed by local LLM (Ollama/LocalAI)
  • ✅ Zero data leaves your machine
  • ✅ Works in air-gapped environments
  • ✅ Free, no API costs

​
Cloud (Managed)

repr generate --cloud
  • ⚠️ Requires repr login
  • ⚠️ Diffs sent to repr.dev for processing
  • ✅ No local LLM needed
  • ✅ Fast, optimized models

​
BYOK (Bring Your Own Key)

repr llm add openai
repr generate
  • ✅ Diffs sent directly to your API provider (OpenAI, Anthropic, etc.)
  • ✅ repr.dev never sees your data
  • ✅ Your API key, your costs
  • ✅ Keys stored in OS keychain

​
Token Limits

For cloud generation, repr enforces limits to control costs:
  • Max commits per batch: 50 (configurable)
  • Token limit: ~100k tokens per batch
If you exceed limits, repr will:
  1. Show you the split plan
  2. Ask for confirmation
  3. Process in multiple batches
repr generate --cloud
Output: 
⚠ 87 commits exceeds 50-commit limit

Will split into 2 batches:
  Batch 1: commits 1-50 (est. 45k tokens)
  Batch 2: commits 51-87 (est. 32k tokens)

Continue with generation? [Y/n]

​
Troubleshooting

​
”Local LLM not found”

Install Ollama and pull a model: 
brew install ollama
ollama pull llama3.2
repr llm test

​
“No repositories tracked”

Initialize repr first: 
repr init ~/code

​
Generation is slow

  • Use --batch-size 3 for smaller stories
  • Try a lighter model: ollama pull phi3
  • Use cloud generation instead

​
Stories are too technical/brief

Add a custom prompt: 
repr generate --local --prompt "Write in accessible language for non-technical stakeholders. Focus on business impact."
  • repr stories - View generated stories
  • repr story view <id> - Read a specific story
  • repr review - Interactive review workflow
  • repr push - Publish stories to repr.dev