@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

npm install @claude-vector/claude-tools

Quick Start

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.

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.

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.

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.

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

# 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:

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

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

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

// 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

// 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

// 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

// 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:

# 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