🚀 Startblock CLI

Automatic knowledge capture for codebases. Capture the "WHY" behind your code before it's lost.

Stop losing context when developers leave or switch projects. sb-cli integrates directly into your git workflow to automatically document your code changes, capture developer insights, and maintain a living knowledge base.

✨ Why Startblock?

• 🧠 Never Lose Context Again: Automatically generate documentation for every file you touch.
• ⚡ Zero Friction: Runs as a git hook. No context switching, no separate apps.
• 💬 Capture Insights: An optional, quick prompt asks for your "gotchas" and "tricky choices" right when they're fresh in your mind.
• 📁 Mirrored Structure: Knowledge files live right alongside your code in .startblock/knowledge/, mirroring your project structure.
• 🤖 AI-Powered: Uses OpenAI to analyze code changes, dependencies, and purpose automatically.

📦 Installation

Install the CLI globally using npm:

npm install -g @startblock-ai/cli

Note: If you encounter permission errors, check our Installation Guide.

Verify Installation

sb --help
sb --version  # Check installed version

🚀 Quick Start

Get up and running in seconds.

For New Repositories

1. Clone and install:

   git clone your-repo
   cd your-repo
   npm install

   If the repo has Startblock configured, onboarding runs automatically after npm install!

2. Or initialize manually:

   cd your-project
   sb init

   This sets up the git hooks and prompts you for your OpenAI API key.

For Existing Repositories

1. Run onboarding:

   sb onboard

   This analyzes key files and generates onboarding documentation.

2. Commit code as usual:

   git add .
   git commit -m "feat: added payment retry logic"

3. That's it!

   • The CLI will analyze your changes.
   • It will ask if you want to add any insights (optional).
   • Your knowledge files are generated and committed automatically! 🎉

🛠️ How It Works

Automatic Onboarding

When you clone a repository with Startblock enabled and run npm install, the postinstall script automatically invites you to run sb onboard. This:

1. Collects your goals - What are you trying to accomplish? What's your experience level?
2. AI selects best files - Intelligently chooses ~5 files most relevant to your goal
3. Analyzes and documents - Generates knowledge files for those selected files
4. Creates onboarding docs - Living documentation in .startblock/onboarding/ (INDEX.md, SETUP.md, ARCHITECTURE.md, etc.)
5. Saves session - Stores your onboarding context in .startblock/sessions/ (never committed)
6. Continue in Cursor - Use Startblock's MCP in Cursor chat for personalized, conversational onboarding

The onboarding experience:

• CLI: Run sb onboard to get started with personalized file selection and analysis
• Cursor Chat: Continue onboarding conversationally - Startblock uses your session data to guide you through the codebase
• Living Docs: Onboarding docs evolve as you learn - they're never overwritten, only refined

Commit-Time Analysis

1. You Commit: git commit -m "..."
2. Analysis: AI scans your staged files to understand purpose and dependencies.
3. Context: You see a summary of what's changing.
4. Insight (Optional): "Any gotchas or tricky choices?" -> You type a quick note.
5. Generation: AI combines its analysis with your notes to create detailed markdown docs.
6. Done: The docs are staged and committed with your code.

Ideally suited for:

• Teams with high turnover or rapid scaling.
• Complex codebases with "hidden knowledge".
• "Lazy" developers who hate writing documentation manually (we got you!).

🖥️ Visual Onboarding Server

Want a more interactive experience? Startblock includes a built-in visual server that turns your knowledge files into a rich, animated dashboard with AI voice guidance.

1. Run Server:

   sb serve

   Starts a local server at http://localhost:3939 with voice agent ready to guide you!

2. Features:

   • Interactive File Tree: Explore your project structure with knowledge status indicators.
   • 🎙️ AI Voice Agent: Real-time voice conversations about your codebase (powered by OpenAI + LiveKit).
   • Dynamic UI: Smooth animations, expandable dossiers, and "Dynamic Island" player controls.
   • Dark Mode: Optimized for developers with a sleek, high-contrast theme.

✨ No setup required! Voice agent credentials are provided automatically. Just run sb serve and start talking to your codebase.

📋 Commands

• sb init - Initialize Startblock in current repository
• sb onboard - Run personalized onboarding (collects your goals, AI-selects files, generates docs)
• sb onboard --postinstall - Non-blocking onboarding invitation after npm install (used automatically)
• sb serve - Start the visual onboarding server (interactive web UI)
• sb analyze-commit - Analyze staged files (used by Husky hook)
• sb setup-onboarding - Configure automatic onboarding for maintainers (adds postinstall script)
• sb --version or sb -v - Show CLI version
• sb --help or sb -h - Show help message

Onboarding Flow:

1. Run sb onboard - Answer a few questions about your goals and experience
2. CLI analyzes AI-selected files and generates knowledge docs
3. Continue in Cursor chat - Startblock's MCP uses your session to guide personalized onboarding
4. Docs evolve - Onboarding documentation improves with each session

⚙️ Configuration

After running sb init, you can customize behavior in .sb-config.json:

{
  "openai": {
    "apiKey": "sk-...", // Your OpenAI Key (required)
    "model": "gpt-4o-mini", // Recommend gpt-4o for best results
    "temperature": 0.3
  },
  "analysis": {
    "excludePatterns": ["*.test.ts", "dist/**"],
    "maxFilesPerAnalysis": 10
  }
  // Note: LiveKit config is NOT needed - credentials provided automatically!
}

🔒 Security: Your API keys are stored locally in .sb-config.json which is automatically added to .gitignore.

🎙️ Voice Agent

The AI voice agent works out of the box - no LiveKit configuration needed!

To use:

sb serve

Then open http://localhost:3939 and click the microphone button to start talking to your codebase.

How it works:

• Voice agent credentials are provided automatically by Startblock
• Your conversations stay private and secure
• Powered by OpenAI (for STT/LLM/TTS) + LiveKit (for real-time audio)

Self-hosting (optional):
Want to use your own LiveKit instance? See LIVEKIT_SETUP.md for advanced configuration.

📚 Resources

• Installation Troubleshooting: Fix permission issues.
• Testing Guide: Step-by-step walkthrough for newcomers.
• Contributing: Want to build sb-cli? Start here.

License

MIT © Startblock