CUSTOMIZATION.md

Customizing CodeWhisper

This guide explains how to customize CodeWhisper to fit your specific needs and workflow.

Table of Contents

• Custom Templates
• Template Variables
• Customizing AI Models
• Extending CodeWhisper
• Performance Tuning
• Integrating with Other Tools

Custom Templates

To create and use custom templates:

1. Export the built-in templates:

   codewhisper export-templates -d ./my-templates

2. Edit or create new template files in the ./my-templates directory.

3. Use your custom template:

   codewhisper generate --custom-template ./my-templates/my-custom-template.hbs

Example: Creating a Custom Template

Let's create a template that focuses on code statistics:

# Code Statistics for {{var_projectName}}

{{tableOfContents files}}

## Overall Statistics

Total Files: {{files.length}}
Total Lines of Code: {{sum files 'content.split("\n").length'}}

## File Breakdown

{{#each files}}

### {{relativePath this.path}}

- Language: {{this.language}}
- Lines of Code: {{this.content.split("\n").length}}
- Last Modified: {{this.modified}}

{{/each}}

## Project Description

{{multiline_projectDescription}}

Save this as code-stats.hbs in your templates directory and use it with:

codewhisper generate --custom-template ./my-templates/code-stats.hbs --custom-data '{"projectName": "My Project"}'

Best Practices for Template Creation

Best Practice	Description
Clear variable names	Use descriptive names for variables to enhance readability
Leverage helpers	Utilize Handlebars helpers for complex logic
Include comments	Add comments to explain template structure and logic
Modular design	Create reusable template components
Thorough testing	Test templates with various inputs to ensure robustness

Template Variables

CodeWhisper supports two types of special variable prefixes in templates to enable interactive prompting:

Prefix	Description	Example
var_	Single-line input prompts	{{var_projectName}}
multiline_	Multi-line input prompts (opens in default text editor)	{{multiline_projectDescription}}

Example usage in a template:

#
{{var_projectName}}

## Description

{{multiline_projectDescription}}

## Author

{{var_authorName}}

When using a template with these variables, CodeWhisper will automatically prompt the user for input if the values aren't provided via the --custom-data option. This feature makes it easier to create dynamic, interactive templates that can be reused across different projects.

Note: Variable values are cached to speed up repeated use of templates. The cache can be cleared by using a different cache path with the --cache-path option.

Advanced Variable Usage

You can also use computed values and conditional logic in your templates:

{{#if (gt files.length 10)}}
  This is a large project with
  {{files.length}}
  files.
{{else}}
  This is a small project with
  {{files.length}}
  files.
{{/if}}

Customizing AI Models

CodeWhisper allows you to specify which AI model to use for tasks. You can customize this in your commands:

codewhisper task -m claude-3-opus-20240229

To add support for new models:

1. Modify the MODEL_CONFIGS object in src/ai/model-config.ts
2. Update the generateAIResponse function in src/ai/generate-ai-response.ts to handle the new model

Example: Adding a New AI Model

// In src/ai/model-config.ts
export const MODEL_CONFIGS: ModelSpecs = {
  // ... existing models ...
  'new-model-name': {
    contextWindow: 100000,
    maxOutput: 4096,
    modelName: 'New Model',
    pricing: { inputCost: 1, outputCost: 2 },
  },
};

// In src/ai/generate-ai-response.ts
// Update the generateAIResponse function to handle the new model

Extending CodeWhisper

To add new features or modify existing ones:

1. Fork the CodeWhisper repository
2. Clone your fork and create a new branch
3. Make your changes, following the existing code style
4. Add tests for your new features
5. Update the documentation to reflect your changes
6. Submit a pull request with a clear description of your changes

Example: Adding a New Command

To add a new command, e.g., analyze:

1. Create a new file src/commands/analyze.ts:

   import { Command } from 'commander';
   import { processFiles } from '../core/file-processor';
   import { generateMarkdown } from '../core/markdown-generator';
   
   export function registerAnalyzeCommand(program: Command) {
     program
       .command('analyze')
       .description('Analyze code and generate a report')
       .option('-p, --path <path>', 'Path to analyze', '.')
       .action(async (options) => {
         const files = await processFiles(options);
         const template = `
   # Code Analysis Report
   
   {{#each files}}
   
   ## {{relativePath this.path}}
   
   {{fileInfo this}}
   
   {{/each}}
         `;
         const output = await generateMarkdown(files, template, options);
         console.log(output);
       });
   }

2. Update src/cli/index.ts to include your new command:

   import { registerAnalyzeCommand } from '../commands/analyze';
   
   // ... existing code ...
   
   registerAnalyzeCommand(program);
   
   // ... existing code ...

3. Add tests for your new command in tests/commands/analyze.test.ts

4. Update the documentation to include information about the new analyze command

Performance Tuning

To optimize CodeWhisper's performance:

Technique	Description	Example
Specific file filters	Reduce the number of processed files	--filter "src/**/*.js"
Consistent cache path	Leverage the caching mechanism	--cache-path /path/to/cache

Example:

codewhisper generate --filter "src/**/*.js" --cache-path /path/to/cache

Integrating with Other Tools

CodeWhisper can be easily integrated with other development tools:

Integration	Description	Example
Version Control	Use CodeWhisper in pre-commit hooks	Generate documentation or perform code analysis
CI/CD	Incorporate CodeWhisper in your pipeline	Automated code reviews or documentation generation
IDE Extensions	Create extensions using CodeWhisper's API	In-editor code analysis and AI assistance

Example Git pre-commit hook:

#!/bin/sh
codewhisper analyze --path ./src --output ./docs/analysis.md
git add ./docs/analysis.md

By following these customization guidelines and leveraging the advanced features, you can tailor CodeWhisper to better suit your specific needs and workflows.