Developer Quick Start Guide

Welcome to the Oboyu development quick start! This guide assumes you already have Oboyu installed and covers development-specific workflows.

Prerequisites

Before following this guide, make sure you have:

• Oboyu installed on your system (see installation guide)
• Basic familiarity with command-line tools
• Understanding of semantic search concepts

Development Environment Prerequisites

For development work, ensure you have:

• Python 3.13+ (3.11+ supported)
• UV package manager (recommended) or pip
• Git
• System build dependencies (see below if needed)

System Dependencies for Development

If you plan to build from source or work with native dependencies:

Linux (Ubuntu/Debian):

sudo apt-get update && sudo apt-get install -y \
    git \
    curl \
    build-essential \
    cmake \
    pkg-config \
    libssl-dev \
    python3-dev \
    libfreetype6-dev \
    libfontconfig1-dev \
    libjpeg-dev \
    libpng-dev \
    zlib1g-dev

macOS:

# Install Xcode Command Line Tools
xcode-select --install

# Install additional dependencies via Homebrew
brew install cmake pkg-config uv

Development-Specific Setup

For development work with Oboyu, you may want to install the development version:

# Install development version with all dependencies
pip install oboyu[dev]

Or for contributing to Oboyu:

# Clone and install from source
git clone https://github.com/sonesuke/oboyu.git
cd oboyu
uv sync
uv run oboyu --version

Your First Search - 3 Simple Steps

Step 1: Index Your Documents

Index a directory of documents (supports text-based formats: .txt, .md, .html, .py, .java, and other plain text files):

oboyu index /path/to/your/documents

Example - index your notes directory:

oboyu index ~/Documents/notes

You'll see progress like:

Indexing documents...
Processed 150 files in 45 seconds
Index created successfully!

Step 2: Search Your Documents

Search using natural language:

oboyu query --query "how to configure Python logging"

Step 3: Interactive Search (Recommended)

For the best experience, use interactive mode:

oboyu query --interactive

This opens a search interface where you can:

• Type queries and see instant results
• Navigate results with arrow keys
• Press Enter to view full content
• Use /mode to switch search modes
• Type /help for all commands

Common Use Cases

1. Search Technical Documentation

# Index your project documentation
oboyu index ~/projects/myapp/docs

# Find specific implementation details
oboyu query --query "authentication flow"

2. Research Notes and Documentation

# Index research notes
oboyu index ~/research/notes --include "*.md"

# Find related concepts
oboyu query --query "machine learning optimization techniques"

3. Code Documentation Search

# Index only markdown files
oboyu index ~/projects --include "*.md"

# Search for API usage
oboyu query --query "API authentication examples"

4. Japanese Document Search

# Index Japanese documents (encoding auto-detected)
oboyu index ~/documents/japanese

# Search in Japanese
oboyu query --query "機械学習の最適化"

Search Modes

Oboyu offers three search modes for different needs:

1. Hybrid (default): Combines keyword and semantic search

   oboyu query --query "Python logging" --mode hybrid

2. Semantic: Finds conceptually related content

   oboyu query --query "how to debug applications" --mode semantic

3. Keyword: Traditional keyword matching

   oboyu query --query "ERROR FileNotFoundError" --mode keyword

Pro Tips

1. Use Filters for Targeted Search

# Search only in specific files
oboyu query --query "configuration" --filter "*.yaml"

# Search in a specific directory
oboyu query --query "testing" --filter "tests/"

2. Rerank for Better Accuracy

Enable reranking for more accurate results (slower but better):

oboyu query --query "complex technical concept" --rerank

3. Index Incrementally

Update your index with only new or modified files:

oboyu index /path/to/documents --incremental

4. Clear Index When Needed

Start fresh with a new index:

oboyu index --clear

What's Next?

Now that you're up and running:

1. Explore Interactive Mode: Try oboyu query -i for the full experience
2. Read Configuration Guide: Learn about customization options
3. Check CLI Reference: See all available commands and options
4. Learn About Architecture: Understand how Oboyu works

Need Help?

• Run oboyu --help for command help
• Check Troubleshooting Guide for common issues
• Visit our GitHub repository for support

Quick Command Reference

Task	Command
Install Oboyu	uv tool install oboyu
Index documents	oboyu index /path/to/docs
Search	oboyu query --query "your search"
Interactive mode	oboyu query --interactive
Update index	oboyu index /path --incremental
Clear index	oboyu index --clear
Show version	oboyu --version

Happy searching! 🔍