Claude Code Integration Guide

This guide covers how to integrate SuperSmall with Claude Code for enhanced AI-assisted development.

Overview

Claude Code integration provides: - Optimized context generation for Claude's models - Automatic file relationship detection - Token-efficient formatting - Seamless workflow integration

Installation & Setup

Prerequisites

- SuperSmall installed and in PATH - Claude Code access - Repository initialized with SuperSmall

Initial Setup

1. Install SuperSmall

git clone [repository-url].git
cd supersmall-cli-osx-alpha
swift build -c release
sudo cp .build/release/supersmall /usr/local/bin/



2. Initialize Your Repository

cd /path/to/your/project
supersmall init --languages typescript,javascript,python



3. Verify Installation

supersmall claude-code --help



Basic Usage


File Analysis


Analyze a specific file with related context:



Basic file analysis
supersmall claude-code src/auth/login.ts


Include related files
supersmall claude-code src/auth/login.ts --include-related


Custom token limit
supersmall claude-code src/api/users.js --max-tokens 50000



Query-Based Analysis


Find relevant code for natural language queries:



Ask about functionality
supersmall claude-code "How does the authentication system work?"


Search for specific patterns
supersmall claude-code "database connection handling" --type query


Include file contents
supersmall claude-code "payment processing logic" --include-contents



Advanced Workflows


Interactive Development


Create an alias for quick access:

Add to ~/.bashrc or ~/.zshrc
alias scc='supersmall claude-code'


Usage
scc src/main.ts
scc "explain the caching strategy"



Context Generation Script


Create a script for common patterns:

#!/bin/bash
claude-context.sh


FILE=$1
QUERY=$2


if [ -f "$FILE" ]; then
    echo "Analyzing file: $FILE"
    supersmall claude-code "$FILE" --include-related
elif [ -n "$QUERY" ]; then
    echo "Searching for: $QUERY"
    supersmall claude-code "$QUERY" --type query --include-contents
else
    echo "Usage: $0  or $0 "
fi



Integration with Claude Code CLI


When Claude Code CLI supports external context:

Future integration
claude-code analyze src/main.ts --context-provider supersmall


Or with environment variable
export CLAUDE_CODE_CONTEXT_PROVIDER=supersmall
claude-code analyze src/main.ts



Output Formats


Standard Claude Format


SuperSmall generates Claude-optimized output:









File: src/auth/login.ts


Symbols:
- function: authenticate
- function: validateCredentials  
- class: LoginManager
- interface: Credentials



import { User } from '../models/user';
import { encrypt } from '../utils/crypto';


export class LoginManager {
  async authenticate(credentials: Credentials): Promise {
    // Implementation
  }
}



Dependencies
- src/auth/login.ts → src/models/user.ts
- src/auth/login.ts → src/utils/crypto.ts



JSON Output


For programmatic use:

supersmall claude-code src/main.ts --output-format json




{
  "query": "src/main.ts",
  "type": "file",
  "context": {
    "files": [
      {
        "path": "src/main.ts",
        "language": "typescript",
        "relevance": 1.0,
        "content": "...",
        "symbols": [...]
      }
    ],
    "dependencies": [...],
    "tokenCount": 15234,
    "optimizationRatio": 0.72
  }
}



Best Practices


1. File Analysis Strategy


Start Narrow, Expand as Needed

Start with single file
supersmall claude-code src/feature.ts


Add related files if needed
supersmall claude-code src/feature.ts --include-related


Increase token limit for complex features
supersmall claude-code src/feature.ts --include-related --max-tokens 150000



2. Query Optimization


Use Specific Technical Terms

Good: Specific and technical
supersmall claude-code "Redux store authentication middleware"


Less effective: Too general
supersmall claude-code "login stuff"



3. Token Management


Monitor and Adjust

Check token usage
supersmall claude-code src/main.ts --verbose


Adjust limits based on Claude's capacity
Claude-3 Opus: up to 200k tokens
Claude-3 Sonnet: up to 200k tokens
supersmall claude-code complex_feature.ts --max-tokens 180000



Common Use Cases


Code Review Preparation



Get context for code review
git diff main..feature-branch --name-only | while read file; do
  supersmall claude-code "$file" --include-related
done > review-context.txt



Bug Investigation



Understand error context
supersmall claude-code "ErrorClass handling and recovery" --type query


Analyze specific error file
supersmall claude-code src/errors/handlers.ts --include-related



Feature Implementation



Get examples of similar features
supersmall claude-code "user registration flow" --type query


Analyze existing patterns
supersmall claude-code src/auth/register.ts --include-related



Documentation Generation



Get comprehensive file context
supersmall claude-code src/api/endpoints.ts --include-related --max-tokens 100000


Then ask Claude to generate docs



Automation


Git Hooks


Add to .git/hooks/pre-commit:

#!/bin/bash
Generate context for changed files


CHANGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(ts|js|py)$')


if [ -n "$CHANGED_FILES" ]; then
  echo "Generating Claude context for changed files..."
  for file in $CHANGED_FILES; do
    supersmall claude-code "$file" > ".claude-context/${file}.context"
  done
fi



VS Code Task


Add to .vscode/tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Generate Claude Context",
      "type": "shell",
      "command": "supersmall claude-code ${file} --include-related",
      "presentation": {
        "reveal": "always",
        "panel": "new"
      },
      "problemMatcher": []
    }
  ]
}



Troubleshooting


Issue: No Context Generated


Solution: Ensure repository is indexed

supersmall init
supersmall stats  # Verify index exists



Issue: Too Many Tokens


Solution: Adjust parameters

Reduce token limit
supersmall claude-code "query" --max-tokens 50000


Increase relevance threshold
supersmall claude-code "query" --threshold 0.7


Exclude file contents
supersmall claude-code "query"  # Without --include-contents



Issue: Missing Related Files


Solution: Update index and use flags

Update index
supersmall update --incremental


Force include related
supersmall claude-code file.ts --include-related


Lower relevance threshold
supersmall claude-code file.ts --threshold 0.3



Tips & Tricks


1. Create Context Templates



Save common queries
echo "authentication flow" > ~/.supersmall-queries/auth.txt
echo "database operations" > ~/.supersmall-queries/db.txt


Use with
supersmall claude-code "$(cat ~/.supersmall-queries/auth.txt)"



2. Combine with Other Tools



With ripgrep
rg "TODO|FIXME" --json | supersmall claude-code "technical debt areas"


With git
git log --oneline -10 | supersmall claude-code "recent changes context"



3. Context Caching



Cache frequently used contexts
CACHE_DIR=~/.supersmall-cache
mkdir -p $CACHE_DIR


Generate and cache
supersmall claude-code src/main.ts > $CACHE_DIR/main-context.txt


Reuse
cat $CACHE_DIR/main-context.txt | pbcopy



Future Enhancements


Planned Features
- Direct Claude API integration
- Real-time context updates
- Context history tracking
- Custom relevance algorithms


Community Requests
- Browser extension
- IDE plugins
- Context sharing platform
- Team collaboration features


Next Steps


1. Initialize your repository: supersmall init
2. Try basic file analysis: supersmall claude-code 
3. Experiment with queries: supersmall claude-code "your question"
4. Set up automation: Create scripts and aliases
5. Share feedback: Help improve the integration