QodeAssist/docs/quick-refactoring.md

Quick Refactoring Feature

Quick Refactoring provides AI-assisted code improvements directly in your editor. Select code, press the hotkey, and get instant refactoring suggestions.

Overview

Quick Refactoring provides AI-assisted code refactoring with its own dedicated provider and model configuration, allowing you to use different settings than your Chat Assistant. You can use built-in quick actions or create your own custom instructions library.

Setup

Quick Refactoring has independent configuration separate from Chat Assistant:

Provider & Model Configuration

Configure provider and model in: Qt Creator → Preferences → QodeAssist → General Settings

Under the Quick Refactor section, you can set:

• Provider: Choose from Ollama, Claude, OpenAI, Google AI, etc.
• Model: Select the specific model for refactoring tasks
• Template: Choose the chat template for this provider
• URL: Set the API endpoint
• API Key: Configure authentication (for cloud providers)

This allows you to:

• Use a faster/cheaper model for refactoring than for chat
• Use a local model for refactoring and cloud model for chat
• Optimize costs by using different providers for different tasks

Quick Refactor Settings

Additional refactoring-specific options in: Qt Creator → Preferences → QodeAssist → Quick Refactor

Configure:

• Context Settings: How much code context to send
  • Read full file or N lines before/after selection
• LLM Parameters: Temperature, max tokens, top_p, top_k
• Advanced Options: Penalties, context window size
• Features: Tool calling, extended thinking mode
• System Prompt: Customize the base prompt for refactoring

Using Quick Refactoring

Basic Usage

1. Select Code (or place cursor for line-level refactoring)
2. Trigger Quick Refactor: Press Ctrl+Alt+R (Windows/Linux) or ⌥⌘R (macOS)
3. Choose Action:
   • Use a built-in quick action button
   • Select a custom instruction from the dropdown
   • Type your own instruction
4. Get Results: AI generates refactored code directly replacing your selection

Quick Action Buttons

The dialog provides three built-in quick actions:

Button	Description
Repeat Last	Reuses the last instruction from your session (enabled after first use)
Improve Code	Enhances readability, efficiency, and maintainability with best practices
Alternative Solution	Suggests different implementation approaches and patterns

Custom Instructions

Overview

Custom Instructions allow you to create a reusable library of refactoring templates. Instead of typing the same instructions repeatedly, save them once and access them instantly through the searchable dropdown.

Key Features:

• Quick Access: Search and select instructions by typing
• Flexible: Use as-is or add extra details for each use
• Manageable: Easy create, edit, and delete interface
• Persistent: Instructions saved locally and loaded on startup
• Accessible: Direct access to instruction files folder

Creating Custom Instructions

1. Click the + button in the Quick Refactor dialog
2. Fill in the form:
   • Name: Short descriptive title (e.g., "Add Documentation")
   • Instruction Body: Detailed prompt for the LLM

Example instruction:

Name: Add Documentation
Body: Add comprehensive documentation to the selected code or code afer cursor following: 
      Doxygen style. Include parameter descriptions, return value 
      documentation, and usage examples where applicable.

Using Custom Instructions

Method 1: Select and Use

1. Open Quick Refactor dialog (Ctrl+Alt+R / ⌥⌘R)
2. Click the dropdown or start typing instruction name
3. Select instruction (autocomplete will help)
4. Optionally add extra details in the text field below
5. Press OK

Method 2: Search by Typing

1. Open Quick Refactor dialog
2. Start typing in the instruction dropdown (e.g., "doc...")
3. Autocomplete shows matching instructions
4. Select with arrow keys or click
5. Add optional details and execute

Search Features:

• Case-insensitive search
• Match anywhere in instruction name
• Keyboard navigation (arrow keys, Enter)
• Instant filtering as you type

Combining Instructions with Additional Details

Custom instructions serve as base templates that you can augment with specific requirements:

Example 1 - Use instruction as-is:

Selected: "Add Documentation"
Additional text: [empty]
→ Sends: "Add comprehensive documentation..."

Example 2 - Add specific requirements:

Selected: "Optimize Performance"  
Additional text: "Focus on reducing memory allocations"
→ Sends: "Optimize Performance instructions... 

Focus on reducing memory allocations"

This approach allows maximum flexibility while maintaining a clean instruction library.

Managing Custom Instructions

The Quick Refactor dialog provides full CRUD operations:

Button	Action	Description
+	Add	Create new custom instruction
✎	Edit	Modify selected instruction
−	Delete	Remove selected instruction (with confirmation)
📁	Open Folder	Open instructions directory in file manager

Edit/Delete:

• Select an instruction from dropdown (or type its name)
• Click Edit (✎) or Delete (−) button
• Confirm changes

Storage Location

Custom instructions are stored as JSON files in:

~/.config/QtProject/qtcreator/qodeassist/quick_refactor/instructions/

File Naming Format:

Instruction_Name_with_underscores_{unique-uuid}.json

Examples:

Add_Documentation_a7f3c92d-8e4b-4f1a-9c0e-1d2f3a4b5c6d.json
Optimize_Performance_3b8e4f9a-7c2d-4e1b-8f3a-9c1d2e3f4a5b.json
Fix_Code_Style_c5d6e7f8-9a0b-1c2d-3e4f-5a6b7c8d9e0f.json

File Format:

{
    "id": "unique-uuid",
    "name": "Add Documentation",
    "body": "Add comprehensive documentation...",
    "version": "0.1"
}

Backup and Sharing

Since instructions are simple JSON files, you can:

1. Backup: Copy the instructions directory
2. Share: Share JSON files with team members
3. Version Control: Add to your dotfiles repository
4. Edit Manually: Modify JSON files directly if needed

Click the 📁 button to quickly open the instructions folder in your file manager.

Context and Scope

What Gets Sent to the LLM

The LLM receives:

• Selected Code (or current line if no selection)
• Context: Surrounding code (configurable amount)
• File Information: Language, file path
• Cursor Position: Marked with <cursor> tag
• Selection Markers: <selection_start> and <selection_end> tags
• Your Instructions: Built-in, custom, or typed
• Project Rules: If configured (see Project Rules)

Context Configuration

Configure context amount in: Qt Creator → Preferences → QodeAssist → Quick Refactor

Options:

• Read Full File: Send entire file as context
• Read File Parts: Send N lines before/after selection (configurable in "Read Strings Before/After Cursor")

Advanced Settings

Access all refactoring settings in: Qt Creator → Preferences → QodeAssist → Quick Refactor

Available Options:

Context Settings:

• Read full file vs. file parts
• Number of lines before/after cursor

LLM Parameters:

• Temperature (creativity/randomness)
• Max tokens (response length)
• Top P (nucleus sampling)
• Top K (vocabulary filtering)
• Presence penalty
• Frequency penalty

Ollama-specific:

• Lifetime parameter
• Context window size

Features:

• Enable/disable tool calling
• Extended thinking mode (for supported models)
• Thinking budget and max tokens

Customization:

• System prompt editing
• Use open files in context (optional)

Troubleshooting

Instruction Not Found

• Ensure you've typed the exact name or selected from dropdown
• Check if instruction file exists in instructions directory
• Reload Qt Creator if instructions were added externally

Poor Results

• Try adding more specific details in the additional text field
• Adjust context settings to provide more/less code
• Use extended thinking mode for complex refactorings
• Check if your model supports the complexity of the task

Instructions Not Loading

• Verify folder exists: ~/.config/QtProject/qtcreator/qodeassist/quick_refactor/instructions/
• Check JSON file format validity
• Review Qt Creator logs for parsing errors
• Try restarting Qt Creator

Fully local setup for offline or secure environments.

Related Documentation

• Project Rules - Project-specific AI behavior customization
• File Context - Attaching files to chat context
• Ignoring Files - Exclude files from AI context
• Provider Configuration - Setting up LLM providers