Quick Start

First Run Experience

CommitStudio offers a seamless first-run experience with intelligent defaults and interactive setup:

commitstudio
Copy code

On your first run, CommitStudio will automatically:

1. Detect credentials: Check for existing GitHub token and OpenAI API key
2. Interactive setup: If credentials are missing, prompt for them interactively
3. Repository detection: Automatically identify your Git repository
4. GitHub integration: Connect to the corresponding GitHub repository
5. Configuration setup: Set up default AI model and tokens (gpt-4.1-mini)
6. Analysis: Begin analyzing your code immediately after setup
7. Caching: Store your credentials securely for future use

You'll see a series of interactive prompts similar to:

✓ Welcome to CommitStudio!
? GitHub token not found. Enter your GitHub personal access token: [hidden]
✓ GitHub token validated!
? OpenAI API key not found. Enter your OpenAI API key: [hidden]
✓ OpenAI API key validated!
✓ Repository detected: user/repo-name
✓ Analyzing commits...
Copy code

Basic Usage

After the initial setup, using CommitStudio is straightforward:

# In your Git repository
commitstudio
Copy code

By default, CommitStudio will:

1. Analyze recent commits in your current branch
2. Use AI to generate insightful comments on code changes
3. Post these comments to GitHub (if not in dry-run mode)
4. Cache results to avoid duplicating work

You can also specify options:

# Analyze specific number of commits
commitstudio --commits 5

# Analyze specific branch
commitstudio --branch feature/new-feature

# Preview without posting to GitHub
commitstudio --dry-run
Copy code

YOLO Mode for Commit Messages

CommitStudio has a special "YOLO" mode that helps improve your commit messages:

commitstudio yolo
Copy code

This mode will:

1. Analyze your recent commit messages
2. Generate improved, more descriptive messages
3. Rewrite your Git history with the new messages
4. Optionally add emojis for better readability

Note: YOLO mode requires a clean working tree and rewrites Git history.

Configuration

You can easily customize CommitStudio:

# View current settings
commitstudio config --view

# Interactive configuration
commitstudio config

# Set specific model
commitstudio config --model gpt-4o
Copy code

Automatic Features

CommitStudio includes several automatic features to enhance your experience:

• Smart caching: Avoids reanalyzing the same commits
• Repository autodetection: Works in any Git repository
• GitHub integration: Automatically connects to the correct GitHub repo
• Interactive fallbacks: If autodetection fails, provides interactive selection
• Credential management: Securely stores tokens between sessions
• Parallel processing: Analyzes multiple commits simultaneously for speed
• Rate limit handling: Manages GitHub API limits automatically

Example Complete Workflow

Here's how CommitStudio fits into your development process:

1. Setup (one-time):

   Terminal

   npm install -g commitstudio
   cd your-project
   commitstudio  # First run with interactive setup
   Copy code

2. Daily Development:

   • Make code changes and commit them
   • Run commitstudio before submitting PRs
   • Review AI suggestions and fix issues
   • Use commitstudio yolo to clean up commit messages

3. Continuous Integration:

   • Add CommitStudio to your CI pipeline
   • Analyze PRs automatically
   • Get AI feedback directly in GitHub

Understanding the Output

CommitStudio's analysis includes:

• Summary: Overview of analyzed changes
• Issues: Potential bugs, security concerns, and code smells
• Improvements: Suggested code refactorings and optimizations
• Best practices: Recommendations for better coding standards
• Examples: Example code that demonstrates improvements

Example output:

✓ Found 3 commits to analyze
✓ Analyzing diffs with AI...
  ↪ Analyzing commit: Add user authentication (a1b2c3d)
  ↪ Analyzing commit: Fix pagination bug (e4f5g6h)
  ↪ Analyzing commit: Implement search (i7j8k9l)
✓ Analysis complete!

📊 Summary: 3 files changed with 250+ lines modified

🔍 Key findings:
  - Potential SQL injection in search input
  - Authentication lacks proper error handling
  - Pagination implementation could be optimized

💡 Posted 5 review comments to GitHub
Copy code

Troubleshooting First Run

If you encounter issues during first run:

• GitHub Token Issues: Ensure your token has 'repo' scope
• OpenAI API Key: Verify the key is valid in the OpenAI dashboard
• Repository Not Found: Make sure you're in a Git repository with a GitHub remote
• No Analysis Results: Check that you have commits to analyze

Next Steps

Now that you're up and running with CommitStudio, explore these additional features:

• Standard Mode - Learn about the main analysis mode
• Configuration Options - Customize AI models and settings
• Environment Variables - Configure via environment