Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
241 lines (174 loc) · 5.45 KB

GETTING_STARTED.md

File metadata and controls

241 lines (174 loc) · 5.45 KB
Raw

Getting Started with Octocode

This guide will help you get up and running with Octocode quickly.

Prerequisites

Before you start, make sure you have:

First Steps

1. Navigate to Your Project

cd /path/to/your/project

2. Index Your Codebase

# Index current directory
octocode index

# Watch for progress
octocode index --verbose

What happens during indexing:

  • Scans all supported files in your project
  • Extracts code symbols and structure
  • Generates embeddings for semantic search
  • Builds knowledge graph relationships
  • Stores everything in local database

3. Try Your First Search

# Basic semantic search
octocode search "user authentication"

# Search specific content types
octocode search "database connection" --mode code
octocode search "API documentation" --mode docs

4. Explore Multi-Query Search

# Combine related terms for comprehensive results
octocode search "authentication" "middleware"
octocode search "jwt" "token" "validation"
octocode search "database" "connection" "pool"

Basic Workflow

Daily Development Cycle

# 1. Start watching for changes (optional)
octocode watch &

# 2. Work on your code...
# Files are automatically indexed as you work

# 3. Search for relevant code
octocode search "error handling patterns"

# 4. Use AI-powered git workflow
git add .
octocode commit  # Generates intelligent commit message

# 5. Review your changes
octocode review --focus security

Configuration Basics

View Current Configuration

octocode config --show

Essential Configuration

# Use faster local models (requires fastembed feature)
octocode config \
  --code-embedding-model "fastembed:BAAI/bge-small-en-v1.5" \
  --text-embedding-model "fastembed:multilingual-e5-small"

# Or use current cloud defaults (recommended)
octocode config \
  --code-embedding-model "voyage:voyage-code-3" \
  --text-embedding-model "voyage:voyage-3.5-lite"

Enable GraphRAG for relationship analysis

octocode config --graphrag-enabled true

Set search preferences

octocode config --max-results 20 --similarity-threshold 0.65


## MCP Server for AI Assistants

### Basic MCP Setup

1. **Start the server:**
   ```bash
   octocode mcp --path /path/to/your/project

  1. Configure in Claude Desktop:

    {
  "mcpServers": {
    "octocode": {
      "command": "octocode",
      "args": ["mcp", "--path", "/path/to/your/project"]
    }
  }
}

  2. Use with AI assistant:

    • Ask: "Search for authentication functions in my codebase"
    • Ask: "What are the main components in this project?"
    • Ask: "Remember this bug fix for future reference"

With LSP Integration

# Start with language server support
octocode mcp --path /path/to/rust/project --with-lsp "rust-analyzer"
octocode mcp --path /path/to/python/project --with-lsp "pylsp"

Common Use Cases

Code Exploration

# Understand new codebase
octocode view "**/*.rs" --md > project-overview.md
octocode graphrag overview --md > architecture.md

# Find similar patterns
octocode search "error handling" --expand

Structural Code Search

# Find code patterns by AST structure
octocode grep '$FUNC.unwrap()' --lang rust
octocode grep 'new $CLASS($$$ARGS)' --lang javascript
octocode grep 'return nil' --lang go

Debugging and Maintenance

# Find related code
octocode search "authentication" "session" "login"

# Search for specific patterns
octocode search "TODO" "FIXME" --mode all

# Review recent changes
git add .
octocode review --severity high

Documentation Generation

# Generate API documentation
octocode view "src/**/*.rs" --json > api-docs.json

# Create project structure overview
octocode graphrag overview --md > STRUCTURE.md

Troubleshooting

Slow Indexing

# Use faster embedding models
octocode config --code-embedding-model "fastembed:all-MiniLM-L6-v2"

# Disable GraphRAG temporarily
octocode config --graphrag-enabled false

Poor Search Results

# Adjust similarity threshold
octocode config --similarity-threshold 0.4  # More results
octocode config --similarity-threshold 0.7  # Fewer, more relevant results

# Try different search modes
octocode search "your query" --mode code     # Only code
octocode search "your query" --mode docs     # Only documentation

# Use multi-query search
octocode search "authentication" "login" "security"

# Check available models
octocode models list

API Rate Limits

# Switch to local models (requires fastembed feature)
octocode config \
  --code-embedding-model "fastembed:Xenova/all-MiniLM-L6-v2" \
  --text-embedding-model "fastembed:intfloat/multilingual-e5-small"

Next Steps

Once you're comfortable with the basics:

  1. Explore Advanced Features - See Advanced Usage
  2. Optimize Performance - See Performance Guide
  3. Set Up MCP Integration - See MCP Integration
  4. Configure for Your Workflow - See Configuration Guide

Getting Help