@claude-vector/claude-tools/README.md

Claude integration tools for AI-powered development assistance

# @claude-vector/claude-tools

Advanced Claude integration tools for AI-powered development assistance. Provides context management, session handling, and workflow automation.

## Features

- 🧠 **Context Management**: Intelligent context optimization with token estimation
- 📊 **Session Management**: Persistent development sessions with state management
- 🔍 **Query Optimization**: Learning-based query enhancement and expansion with feedback collection
- 🐛 **Error Analysis**: AI-powered error debugging and solution suggestions
- 📈 **Learning System**: Improves search accuracy based on user feedback patterns
- 🚀 **Performance**: Optimized for long-running sessions and large codebases
- 🔄 **Integration**: Seamless integration with @claude-vector/core

## Installation

```bash
npm install @claude-vector/claude-tools
```

## Quick Start

```javascript
import { ContextManager, SessionManager } from '@claude-vector/claude-tools';

// Initialize context manager
const contextManager = new ContextManager(150000); // 150k token limit

// Add context items
contextManager.addItem({
  type: 'code',
  content: 'function authenticate(user) { ... }',
  metadata: { file: 'auth.js' }
}, 0.8);

// Optimize for current context
const optimizedContext = contextManager.optimize();

// Session management
const sessionManager = new SessionManager();
await sessionManager.startSession('implement-auth', 'development');
```

## Core Components

### ContextManager

Manages development context with intelligent optimization and token management.

```javascript
import { ContextManager } from '@claude-vector/claude-tools';

const contextManager = new ContextManager(150000); // 150k token limit

// Add items with priority
contextManager.addItem({
  type: 'code',
  content: 'function login() { ... }',
  metadata: { file: 'auth.js', line: 45 }
}, 0.9);

// Smart merging with duplicate detection
contextManager.addItemSmart({
  type: 'code',
  content: 'function login() { ... }', // Will be merged if similar
  metadata: { file: 'auth.js', line: 45 }
}, 0.8);

// Optimize for token limits
const optimized = contextManager.optimize();
console.log(`Optimized to ${optimized.totalTokens} tokens`);

// Get performance metrics
const stats = contextManager.getStats();
console.log(stats);
```

#### Key Features

- **Token Estimation**: Accurate token counting for Japanese and English text
- **Smart Merging**: Automatic duplicate detection and content merging
- **Dynamic Prioritization**: Priority adjustment based on access patterns
- **Performance Optimization**: LRU caching and fast lookups
- **Context Integration**: Seamless search result integration

### SessionManager

Manages persistent development sessions with state preservation.

```javascript
import { SessionManager } from '@claude-vector/claude-tools';

const sessionManager = new SessionManager();

// Start new session
await sessionManager.startSession('feature-implementation', 'development');

// Add session context
await sessionManager.addContext({
  type: 'task',
  content: 'Implement user authentication',
  priority: 0.9
});

// Get session info
const session = await sessionManager.getCurrentSession();
console.log(session);

// Session activities
const activities = await sessionManager.getSessionActivities();
console.log(activities);
```

#### Session Types

- **development**: General development tasks
- **debugging**: Error analysis and debugging
- **research**: Code exploration and research
- **refactoring**: Code refactoring and optimization

### QueryOptimizer

Enhances search queries with learning and expansion capabilities.

```javascript
import { QueryOptimizer } from '@claude-vector/claude-tools';

const optimizer = new QueryOptimizer();

// Optimize query for search
const optimizedQuery = await optimizer.optimizeQuery('user login', {
  taskType: 'feature',
  previousSearches: [] // optional context
});

// Record user feedback
await optimizer.recordFeedback('user login', {
  useful: true,
  rating: 5,
  resultIds: [0, 2, 4], // indices of useful results
  taskType: 'feature'
});

// Get learning statistics
const history = await optimizer.getHistory();
console.log(history.successfulPatterns);
console.log(history.queries);

// Get query suggestions
const suggestions = optimizer.getQuerySuggestions('auth', {
  taskType: 'feature'
});
```

#### Features

- **Task-based Optimization**: Different optimization strategies per task type
- **Learning System**: Improves based on user feedback and successful patterns
- **Query Expansion**: Automatically adds relevant synonyms and terms
- **Feedback Collection**: Records explicit and implicit feedback
- **Statistics Tracking**: Monitors successful patterns and usage
- **Persistent Learning**: Saves learning data to `.claude-query-history.json`

### ErrorAssistant

Analyzes errors and provides debugging assistance.

```javascript
import { ErrorAssistant } from '@claude-vector/claude-tools';

const errorAssistant = new ErrorAssistant();

// Analyze error
const analysis = await errorAssistant.analyzeError(
  'TypeError: Cannot read property "name" of undefined',
  {
    file: 'user.js',
    line: 42,
    context: 'function getUser() { ... }'
  }
);

console.log(analysis.explanation);
console.log(analysis.suggestions);
```

## Configuration

### Environment Variables

```bash
# Required
OPENAI_API_KEY=sk-your-api-key-here

# Optional
CLAUDE_SESSION_DIR=~/.claude-sessions
CLAUDE_CACHE_DIR=.claude-vector-cache
CLAUDE_LOG_LEVEL=info
```

### Configuration File

Create `.claude-tools.config.js`:

```javascript
export default {
  context: {
    maxTokens: 150000,
    maxItems: 5000,
    cacheSize: 1000,
    mergeThreshold: 0.85
  },
  session: {
    autoSave: true,
    maxHistory: 100,
    cleanupInterval: 3600000 // 1 hour
  },
  query: {
    enableLearning: true,
    maxSuggestions: 5,
    expansionThreshold: 0.7
  }
};
```

## Integration Examples

### With @claude-vector/core

```javascript
import { VectorSearchEngine } from '@claude-vector/core';
import { ContextManager, QueryOptimizer } from '@claude-vector/claude-tools';

const searchEngine = new VectorSearchEngine(config);
const contextManager = new ContextManager();
const queryOptimizer = new QueryOptimizer();

// Set up integration
contextManager.setSearchEngine(searchEngine);

// Optimized search with context integration
const optimizedQuery = await queryOptimizer.optimizeQuery(
  'user authentication',
  'development'
);

const results = await searchEngine.search(optimizedQuery);
await contextManager.integrateSearchResults(results, optimizedQuery);
```

### With Express.js API

```javascript
import express from 'express';
import { SessionManager, ContextManager } from '@claude-vector/claude-tools';

const app = express();
const sessionManager = new SessionManager();

app.post('/api/sessions', async (req, res) => {
  const { task, type } = req.body;
  const session = await sessionManager.startSession(task, type);
  res.json(session);
});

app.get('/api/sessions/current', async (req, res) => {
  const session = await sessionManager.getCurrentSession();
  res.json(session);
});

app.listen(3000);
```

## Performance Optimization

### Memory Management

```javascript
// Configure memory limits
const contextManager = new ContextManager(150000, {
  maxContextItems: 5000,
  memoryLimit: '500MB',
  enableGC: true
});

// Monitor memory usage
const memoryStats = contextManager.getMemoryStats();
console.log(memoryStats);

// Cleanup when needed
contextManager.cleanup();
```

### Caching Strategy

```javascript
// Configure caching
const contextManager = new ContextManager(150000, {
  cacheSize: 1000,
  enableLRU: true,
  cacheCompression: true
});

// Cache hit statistics
const cacheStats = contextManager.getCacheStats();
console.log(`Cache hit rate: ${cacheStats.hitRate}%`);
```

## Advanced Usage

### Custom Context Types

```javascript
// Define custom context types
const customTypes = {
  'test-case': {
    priority: 0.7,
    tokenWeight: 1.2,
    category: 'testing'
  },
  'documentation': {
    priority: 0.5,
    tokenWeight: 0.8,
    category: 'docs'
  }
};

contextManager.registerCustomTypes(customTypes);
```

### Event Handling

```javascript
// Listen to context events
contextManager.on('itemAdded', (item) => {
  console.log(`Added item: ${item.type}`);
});

contextManager.on('optimized', (stats) => {
  console.log(`Optimized: ${stats.itemsRemoved} items removed`);
});

// Session events
sessionManager.on('sessionStarted', (session) => {
  console.log(`Started session: ${session.task}`);
});
```

## Testing

Run the test suite:

```bash
# Unit tests
npm test

# Integration tests
npm run test:integration

# Performance tests
npm run test:performance
```

## API Reference

Detailed API documentation is available in the source code with JSDoc comments.

## Requirements

- Node.js 18+
- OpenAI API key
- @claude-vector/core package

## License

MIT