@claude-vector/cli/README.md

CLI for Claude-integrated vector search

# @claude-vector/cli

Command-line interface for Claude-integrated vector search. Provides powerful AI-assisted development tools right from your terminal.

## Features

- 🔍 **Semantic Code Search**: Find code using natural language queries
- 🎯 **Smart Project Detection**: Automatically detects project root from any directory
- 📝 **Auto Environment Loading**: Finds and loads .env files automatically
- 🚀 **Simple Installation**: Just `npm install @claude-vector/cli`
- 💡 **Dual Command Support**: Both `ccvector` (simple) and `claude-search` (advanced)
- 🔧 **Flexible Configuration**: Supports multiple index directory formats
- 🔄 **Dynamic Threshold Adjustment**: Automatically adjusts search sensitivity for better results
- 🎸 **Query Optimization**: Optional abbreviation expansion for better search results

## Installation

```bash
# Install in your project (recommended)
npm install @claude-vector/cli

# Or install globally
npm install -g @claude-vector/cli
```

## Quick Start

### Option 1: ccvector (Simple & Recommended)

```bash
# 1. Set up your environment
echo "OPENAI_API_KEY=your-api-key" >> .env.local

# 2. Create index (if needed)
npx ccvector index

# 3. Start searching from any directory
npx ccvector search "authentication function"
cd src/components  # Works from any subdirectory
npx ccvector search "user login"
```

### Option 2: claude-search (Advanced Features)

```bash
# Initialize your project
claude-search init

# Search for code
claude-search search "authentication function"

# Start an AI development session
claude-search start "implement user login"

# View session status
claude-search status
```

## Commands

### ccvector Commands (Simple & Recommended)

#### `ccvector search`

Search for code using semantic similarity.

```bash
ccvector search <query> [options]

Options:
  --limit <number>      Maximum number of results (default: 20)
  --threshold <number>  Similarity threshold 0-1 (default: 0.4)
  -h, --help           Display help

Examples:
  ccvector search "user authentication"
  ccvector search "database connection" --limit 10
  ccvector search "error handling" --threshold 0.2
```

#### `ccvector index`

Create or update the search index.

```bash
ccvector index [options]

Options:
  -f, --force          Force recreate existing index
  -h, --help           Display help

Examples:
  ccvector index
  ccvector index --force
```

#### `ccvector info`

Show project and index information.

```bash
ccvector info

Examples:
  ccvector info
```

#### `ccvector help`

Show help information.

```bash
ccvector help
ccvector --help
ccvector -h
```

### claude-search Commands (Advanced Features)

### `claude-search init`

Initialize vector search for your project.

```bash
claude-search init [options]

Options:
  -p, --project-path <path>  Path to project directory (default: current directory)
  -f, --force               Force re-initialization
  -h, --help                Display help
```

### `claude-search search`

Search for code using semantic similarity.

```bash
claude-search search <query> [options]

Options:
  -l, --limit <number>      Maximum number of results (default: 10)
  -t, --threshold <number>  Similarity threshold 0-1 (default: 0.4)
  -f, --format <format>     Output format: json, table, detailed (default: table)
  --optimize                Enable query optimization (expand abbreviations)
  --no-optimize             Disable query optimization
  --auto                    Automatically add results to context and optimize query
  -h, --help                Display help

Examples:
  claude-search search "user authentication"
  claude-search search "database connection" --limit 5
  claude-search search "error handling" --format json
  claude-search search "auth" --optimize  # Expands to "auth authentication"
  claude-search search "auth" --no-optimize  # Searches for exact term
```

### `claude-search start`

Start an AI-assisted development session.

```bash
claude-search start <task> [options]

Options:
  -c, --context <items>     Maximum context items (default: 20)
  -t, --type <type>         Session type: development, debugging, research (default: development)
  -h, --help                Display help

Examples:
  claude-search start "implement user registration"
  claude-search start "debug authentication issue" --type debugging
```

### `claude-search status`

View current session status and statistics.

```bash
claude-search status [options]

Options:
  -d, --detailed            Show detailed session information
  -h, --help                Display help
```

### `claude-search context`

Manage development context and view session information.

```bash
claude-search context [options]

Options:
  -d, --detailed            Show detailed context information
  -a, --activities          Show recent activities
  -h, --help                Display help
```

### `claude-search config`

View and manage configuration.

```bash
claude-search config [options]

Options:
  -s, --show                Show current configuration
  -h, --help                Display help
```

## Configuration

The CLI uses configuration files to customize behavior:

### Global Configuration

Create `~/.claude-search.config.js`:

```javascript
export default {
  openaiApiKey: process.env.OPENAI_API_KEY,
  defaultProjectPath: '.',
  search: {
    threshold: 0.4,  // Lowered for better results
    maxResults: 10
  },
  session: {
    maxContextItems: 20,
    autoSave: true
  }
};
```

### Project Configuration

Create `.claude-search.config.js` in your project root:

```javascript
export default {
  patterns: {
    include: ['src/**/*.{js,ts}', 'docs/**/*.md'],
    exclude: ['**/*.test.js', '**/__tests__/**', 'node_modules/**']
  },
  chunks: {
    maxSize: 1500,
    overlap: 300
  },
  search: {
    threshold: 0.8
  }
};
```

## Environment Variables

- `OPENAI_API_KEY`: Your OpenAI API key (required)
- `CLAUDE_SESSION_DIR`: Directory for session files (default: ~/.claude-sessions)
- `CLAUDE_CACHE_DIR`: Directory for cache files (default: .claude-vector-cache)

## Examples

### Basic Workflow

```bash
# 1. Initialize project
cd my-project
claude-search init

# 2. Search for relevant code
claude-search search "user authentication logic"

# 3. Start development session
claude-search start "add two-factor authentication"

# 4. Check session status
claude-search status --detailed
```

### Advanced Usage

```bash
# High-precision search
claude-search search "JWT token validation" --threshold 0.9 --limit 3

# Debugging session with detailed context
claude-search start "fix login bug" --type debugging --context 30

# Export search results
claude-search search "API endpoints" --format json > api-search.json
```

## Available Commands Summary

The CLI provides multiple command interfaces:

### ccvector (Recommended for simple use)
```bash
# Simple, auto-detecting, works from any directory
npx ccvector search "function definition"
npx ccvector index
npx ccvector info
```

### claude-search (Full featured)
```bash
# Advanced AI-powered development
claude-search search "function definition"
claude-search start "implement feature"
claude-search status
```

### cs (Shorthand for claude-search)
```bash
# Short alias for claude-search
cs search "function definition"
cs start "implement feature"
cs status
```

## Integration

### VS Code Integration

Add these tasks to your `.vscode/tasks.json`:

```json
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Claude Search",
      "type": "shell",
      "command": "claude-search",
      "args": ["search", "${input:searchQuery}"],
      "group": "build",
      "presentation": {
        "reveal": "always",
        "panel": "new"
      }
    }
  ],
  "inputs": [
    {
      "id": "searchQuery",
      "description": "Search query",
      "default": "",
      "type": "promptString"
    }
  ]
}
```

### Git Hooks

Add to `.git/hooks/pre-commit`:

```bash
#!/bin/sh
# Update search index before commit
claude-search init --force
```

## Performance

- **Caching**: Results are cached for faster subsequent searches
- **Incremental Updates**: Only changed files are reprocessed
- **Batch Processing**: Efficient handling of large codebases
- **Memory Management**: Optimized memory usage for large projects

## Requirements

- Node.js 18+
- OpenAI API key
- Git repository (optional, for enhanced project analysis)

## License

MIT