mirror of
https://github.com/Palm1r/QodeAssist.git
synced 2025-11-12 21:12:44 -05:00
doc: Move out docs from main README
This commit is contained in:
Petr Mironychev
417
README.md
417
README.md
@ -16,51 +16,29 @@
|
||||
|
||||
## Table of Contents
|
||||
1. [Overview](#overview)
|
||||
2. [Install plugin to QtCreator](#install-plugin-to-qtcreator)
|
||||
3. [Configure for Anthropic Claude](#configure-for-anthropic-claude)
|
||||
4. [Configure for OpenAI](#configure-for-openai)
|
||||
5. [Configure for Mistral AI](#configure-for-mistral-ai)
|
||||
6. [Configure for Google AI](#configure-for-google-ai)
|
||||
7. [Configure for Ollama](#configure-for-ollama)
|
||||
8. [Configure for llama.cpp](#configure-for-llamacpp)
|
||||
9. [System Prompt Configuration](#system-prompt-configuration)
|
||||
10. [File Context Feature](#file-context-feature)
|
||||
11. [Quick Refactoring Feature](#quick-refactoring-feature)
|
||||
12. [QtCreator Version Compatibility](#qtcreator-version-compatibility)
|
||||
13. [Development Progress](#development-progress)
|
||||
14. [Hotkeys](#hotkeys)
|
||||
15. [Ignoring Files](#ignoring-files)
|
||||
14. [Troubleshooting](#troubleshooting)
|
||||
15. [Support the Development](#support-the-development-of-qodeassist)
|
||||
16. [How to Build](#how-to-build)
|
||||
2. [Install Plugin](#install-plugin-to-qtcreator)
|
||||
3. [Configuration](#configuration)
|
||||
4. [Features](#features)
|
||||
5. [QtCreator Version Compatibility](#qtcreator-version-compatibility)
|
||||
6. [Hotkeys](#hotkeys)
|
||||
7. [Troubleshooting](#troubleshooting)
|
||||
8. [Development Progress](#development-progress)
|
||||
9. [Support the Development](#support-the-development-of-qodeassist)
|
||||
10. [How to Build](#how-to-build)
|
||||
|
||||
## Overview
|
||||
|
||||
- AI-powered code completion
|
||||
- Sharing IDE opened files with model context (disabled by default, need enable in settings)
|
||||
- Quick refactor code via fast chat command and opened files
|
||||
- Chat functionality:
|
||||
- Side and Bottom panels(enabling in chat settings due stability reason with QQuickWidget problem)
|
||||
- Chat in additional popup window with pinning(recommended)
|
||||
- Chat history autosave and restore
|
||||
- Token usage monitoring and management
|
||||
- Attach files for one-time code analysis
|
||||
- Link files for persistent context with auto update in conversations
|
||||
- Automatic syncing with open editor files (optional)
|
||||
- Support for multiple LLM providers:
|
||||
- Ollama
|
||||
- llama.cpp
|
||||
- OpenAI
|
||||
- Anthropic Claude
|
||||
- LM Studio
|
||||
- Mistral AI
|
||||
- Google AI
|
||||
- OpenAI-compatible providers (eg. llama.cpp, https://openrouter.ai)
|
||||
- Extensive library of model-specific templates
|
||||
- Easy configuration and model selection
|
||||
- Support tools/function calling (enabled by default)
|
||||
QodeAssist enhances Qt Creator with AI-powered coding assistance:
|
||||
|
||||
Join our Discord Community: Have questions or want to discuss QodeAssist? Join our [Discord server](https://discord.gg/BGMkUsXUgf) to connect with other users and get support!
|
||||
- **Code Completion**: Intelligent, context-aware code suggestions for C++ and QML
|
||||
- **Chat Assistant**: Multiple interface options (popup window, side panel, bottom panel)
|
||||
- **Quick Refactoring**: AI-assisted code improvements and alternative suggestions
|
||||
- **File Context**: Attach or link files for better AI understanding
|
||||
- **Tool Calling**: AI can read project files, search code, and access diagnostics
|
||||
- **Multiple Providers**: Support for Ollama, Claude, OpenAI, Google AI, Mistral AI, llama.cpp, and more
|
||||
- **Customizable**: Project-specific rules and extensive model templates
|
||||
|
||||
**Join our [Discord Community](https://discord.gg/BGMkUsXUgf)** to get support and connect with other users!
|
||||
|
||||
<details>
|
||||
<summary>Code completion: (click to expand)</summary>
|
||||
@ -118,7 +96,7 @@ QodeAssistUpdater is a command-line utility that automates plugin installation a
|
||||
|
||||
**Installation:**
|
||||
|
||||
Download pre-built binary from [QodeAssistUpdater releases](https://github.com/Palm1r/QodeAssistUpdater/releases) or build from source:
|
||||
Download pre-built binary from [QodeAssistUpdater releases](https://github.com/Palm1r/QodeAssistUpdater/releases) or build from source
|
||||
|
||||
**Usage:**
|
||||
|
||||
@ -146,273 +124,101 @@ For more information, visit the [QodeAssistUpdater repository](https://github.co
|
||||
- Click on "Install Plugin..."
|
||||
- Select the downloaded QodeAssist plugin archive file
|
||||
|
||||
## Configure for Anthropic Claude
|
||||
1. Open Qt Creator settings and navigate to the QodeAssist section
|
||||
2. Go to Provider Settings tab and configure Claude api key
|
||||
3. Return to General tab and configure:
|
||||
- Set "Claude" as the provider for code completion or/and chat assistant
|
||||
- Set the Claude URL (https://api.anthropic.com)
|
||||
- Select your preferred model (e.g., claude-3-5-sonnet-20241022)
|
||||
- Choose the Claude template for code completion or/and chat
|
||||
<details>
|
||||
<summary>Example of Claude settings: (click to expand)</summary>
|
||||
<img width="823" alt="Claude Settings" src="https://github.com/user-attachments/assets/828e09ea-e271-4a7a-8271-d3d5dd5c13fd" />
|
||||
</details>
|
||||
## Configuration
|
||||
|
||||
## Configure for OpenAI
|
||||
1. Open Qt Creator settings and navigate to the QodeAssist section
|
||||
2. Go to Provider Settings tab and configure OpenAI api key
|
||||
3. Return to General tab and configure:
|
||||
- Set "OpenAI" as the provider for code completion or/and chat assistant
|
||||
- Set the OpenAI URL (https://api.openai.com)
|
||||
- Select your preferred model (e.g., gpt-4o)
|
||||
- Choose the OpenAI template for code completion or/and chat
|
||||
<details>
|
||||
<summary>Example of OpenAI settings: (click to expand)</summary>
|
||||
<img width="829" alt="OpenAI Settings" src="https://github.com/user-attachments/assets/4716f790-6159-44d0-a8f4-565ccb6eb713" />
|
||||
</details>
|
||||
QodeAssist supports multiple LLM providers. Choose your preferred provider and follow the configuration guide:
|
||||
|
||||
## Configure for Mistral AI
|
||||
1. Open Qt Creator settings and navigate to the QodeAssist section
|
||||
2. Go to Provider Settings tab and configure Mistral AI api key
|
||||
3. Return to General tab and configure:
|
||||
- Set "Mistral AI" as the provider for code completion or/and chat assistant
|
||||
- Set the OpenAI URL (https://api.mistral.ai)
|
||||
- Select your preferred model (e.g., mistral-large-latest)
|
||||
- Choose the Mistral AI template for code completion or/and chat
|
||||
<details>
|
||||
<summary>Example of Mistral AI settings: (click to expand)</summary>
|
||||
<img width="829" alt="Mistral AI Settings" src="https://github.com/user-attachments/assets/1c5ed13b-a29b-43f7-b33f-2e05fdea540c" />
|
||||
</details>
|
||||
### Supported Providers
|
||||
|
||||
## Configure for Google AI
|
||||
1. Open Qt Creator settings and navigate to the QodeAssist section
|
||||
2. Go to Provider Settings tab and configure Google AI api key
|
||||
3. Return to General tab and configure:
|
||||
- Set "Google AI" as the provider for code completion or/and chat assistant
|
||||
- Set the OpenAI URL (https://generativelanguage.googleapis.com/v1beta)
|
||||
- Select your preferred model (e.g., gemini-2.0-flash)
|
||||
- Choose the Google AI template
|
||||
<details>
|
||||
<summary>Example of Google AI settings: (click to expand)</summary>
|
||||
<img width="829" alt="Google AI Settings" src="https://github.com/user-attachments/assets/046ede65-a94d-496c-bc6c-41f3750be12a" />
|
||||
</details>
|
||||
- **[Ollama](docs/ollama-configuration.md)** - Local LLM provider
|
||||
- **[llama.cpp](docs/llamacpp-configuration.md)** - Local LLM server
|
||||
- **[Anthropic Claude](docs/claude-configuration.md)** - Сloud provider
|
||||
- **[OpenAI](docs/openai-configuration.md)** - Сloud provider
|
||||
- **[Mistral AI](docs/mistral-configuration.md)** - Сloud provider
|
||||
- **[Google AI](docs/google-ai-configuration.md)** - Сloud provider
|
||||
- **LM Studio** - Local LLM provider
|
||||
- **OpenAI-compatible** - Custom providers (OpenRouter, etc.)
|
||||
|
||||
## Configure for Ollama
|
||||
### Additional Configuration
|
||||
|
||||
1. Install [Ollama](https://ollama.com). Make sure to review the system requirements before installation.
|
||||
2. Install a language models in Ollama via terminal. For example, you can run:
|
||||
- **[Project Rules](docs/project-rules.md)** - Customize AI behavior for your project
|
||||
- **[Ignoring Files](docs/ignoring-files.md)** - Exclude files from context using `.qodeassistignore`
|
||||
|
||||
For standard computers (minimum 8GB RAM):
|
||||
```
|
||||
ollama run qwen2.5-coder:7b
|
||||
```
|
||||
For better performance (16GB+ RAM):
|
||||
```
|
||||
ollama run qwen2.5-coder:14b
|
||||
```
|
||||
For high-end systems (32GB+ RAM):
|
||||
```
|
||||
ollama run qwen2.5-coder:32b
|
||||
```
|
||||
## Features
|
||||
|
||||
1. Open Qt Creator settings (Edit > Preferences on Linux/Windows, Qt Creator > Preferences on macOS)
|
||||
2. Navigate to the "QodeAssist" tab
|
||||
3. On the "General" page, verify:
|
||||
- Ollama is selected as your LLM provider
|
||||
- The URL is set to http://localhost:11434
|
||||
- Your installed model appears in the model selection
|
||||
- The prompt template is Ollama Auto FIM or Ollama Auto Chat for chat assistance. You can specify template if it is not work correct
|
||||
- Disable using tools if your model doesn't support tooling
|
||||
4. Click Apply if you made any changes
|
||||
### Code Completion
|
||||
- AI-powered intelligent code completion
|
||||
- Support for C++ and QML
|
||||
- Context-aware suggestions
|
||||
- Multiline completions
|
||||
|
||||
You're all set! QodeAssist is now ready to use in Qt Creator.
|
||||
<details>
|
||||
<summary>Example of Ollama settings: (click to expand)</summary>
|
||||
<img width="824" alt="Ollama Settings" src="https://github.com/user-attachments/assets/ed64e03a-a923-467a-aa44-4f790e315b53" />
|
||||
</details>
|
||||
### Chat Assistant
|
||||
- Multiple chat panels: side panel, bottom panel, and popup window
|
||||
- Chat history with auto-save and restore
|
||||
- Token usage monitoring
|
||||
- **[File Context](docs/file-context.md)** - Attach or link files for better context
|
||||
- Automatic syncing with open editor files (optional)
|
||||
|
||||
## Configure for llama.cpp
|
||||
1. Open Qt Creator settings and navigate to the QodeAssist section
|
||||
2. Go to General tab and configure:
|
||||
- Set "llama.cpp" as the provider for code completion or/and chat assistant
|
||||
- Set the llama.cpp URL (e.g. http://localhost:8080)
|
||||
- Fill in model name
|
||||
- Choose template for model(e.g. llama.cpp FIM for any model with FIM support)
|
||||
- Disable using tools if your model doesn't support tooling
|
||||
<details>
|
||||
<summary>Example of llama.cpp settings: (click to expand)</summary>
|
||||
<img width="829" alt="llama.cpp Settings" src="https://github.com/user-attachments/assets/8c75602c-60f3-49ed-a7a9-d3c972061ea2" />
|
||||
</details>
|
||||
### Quick Refactoring
|
||||
- Fast code refactoring with AI assistance
|
||||
- Selection-based improvements
|
||||
- Alternative code suggestions
|
||||
- **[Learn more](docs/quick-refactoring.md)**
|
||||
|
||||
## System Prompt Configuration
|
||||
|
||||
The plugin comes with default system prompts optimized for chat and instruct models, as these currently provide better results for code assistance. If you prefer using FIM (Fill-in-Middle) models, you can easily customize the system prompt in the settings.
|
||||
|
||||
## Project Rules Configuration
|
||||
|
||||
QodeAssist supports project-specific rules to customize AI behavior for your codebase. Create a `.qodeassist/rules/` directory in your project root.
|
||||
|
||||
### Quick Start
|
||||
```bash
|
||||
mkdir -p .qodeassist/rules/{common,completion,chat,quickrefactor}
|
||||
```
|
||||
```
|
||||
.qodeassist/
|
||||
└── rules/
|
||||
├── common/ # Applied to all contexts
|
||||
├── completion/ # Code completion only
|
||||
├── chat/ # Chat assistant only
|
||||
└── quickrefactor/ # Quick refactor only
|
||||
```
|
||||
All .md files in each directory are automatically loaded and added to the system prompt.
|
||||
|
||||
Example
|
||||
Create .qodeassist/rules/common/general.md:
|
||||
```markdown
|
||||
# Project Guidelines
|
||||
- Use snake_case for private members
|
||||
- Prefix interfaces with 'I'
|
||||
- Always document public APIs
|
||||
- Prefer Qt containers over STL
|
||||
```
|
||||
|
||||
## File Context Feature
|
||||
|
||||
QodeAssist provides two powerful ways to include source code files in your chat conversations: Attachments and Linked Files. Each serves a distinct purpose and helps provide better context for the AI assistant.
|
||||
|
||||
### Attached Files
|
||||
|
||||
Attachments are designed for one-time code analysis and specific queries:
|
||||
- Files are included only in the current message
|
||||
- Content is discarded after the message is processed
|
||||
- Ideal for:
|
||||
- Getting specific feedback on code changes
|
||||
- Code review requests
|
||||
- Analyzing isolated code segments
|
||||
- Quick implementation questions
|
||||
- Files can be attached using the paperclip icon in the chat interface
|
||||
- Multiple files can be attached to a single message
|
||||
|
||||
### Linked Files
|
||||
|
||||
Linked files provide persistent context throughout the conversation:
|
||||
|
||||
- Files remain accessible for the entire chat session
|
||||
- Content is included in every message exchange
|
||||
- Files are automatically refreshed - always using latest content from disk
|
||||
- Perfect for:
|
||||
- Long-term refactoring discussions
|
||||
- Complex architectural changes
|
||||
- Multi-file implementations
|
||||
- Maintaining context across related questions
|
||||
- Can be managed using the link icon in the chat interface
|
||||
- Supports automatic syncing with open editor files (can be enabled in settings)
|
||||
- Files can be added/removed at any time during the conversation
|
||||
|
||||
## Quick Refactoring Feature
|
||||
### Setup
|
||||
Since this is actually a small chat with redirected output, the main settings of the provider, model and template are taken from the chat settings
|
||||
### Using
|
||||
The request to model consist of instructions to model, selection code and cursor position
|
||||
The default instruction is: "Refactor the code to improve its quality and maintainability." and sending if text field is empty
|
||||
Also there buttons to quick call instractions:
|
||||
* Repeat latest instruction, will activate after sending first request in QtCreator session
|
||||
* Improve current selection code
|
||||
* Suggestion alternative variant of selection code
|
||||
* Other instructions[TBD]
|
||||
### Tools & Function Calling
|
||||
- Read project files
|
||||
- List and search in project
|
||||
- Access linter/compiler issues
|
||||
- Enabled by default (can be disabled)
|
||||
|
||||
## QtCreator Version Compatibility
|
||||
|
||||
- QtCreator 17.0.0 - 0.6.0 - 0.x.x
|
||||
- QtCreator 16.0.2 - 0.5.13 - 0.x.x
|
||||
- QtCreator 16.0.1 - 0.5.7 - 0.5.13
|
||||
- QtCreator 16.0.0 - 0.5.2 - 0.5.6
|
||||
- QtCreator 15.0.1 - 0.4.8 - 0.5.1
|
||||
- QtCreator 15.0.0 - 0.4.0 - 0.4.7
|
||||
- QtCreator 14.0.2 - 0.2.3 - 0.3.x
|
||||
- QtCreator 14.0.1 - 0.2.2 plugin version and below
|
||||
|
||||
## Development Progress
|
||||
|
||||
- [x] Basic plugin with code autocomplete functionality
|
||||
- [x] Improve and automate settings
|
||||
- [x] Add chat functionality
|
||||
- [x] Sharing diff with model
|
||||
- [ ] Sharing project source with model
|
||||
- [ ] Support for more providers and models
|
||||
- [ ] Support MCP
|
||||
| Qt Creator Version | QodeAssist Version |
|
||||
|-------------------|-------------------|
|
||||
| 17.0.0+ | 0.6.0 - 0.x.x |
|
||||
| 16.0.2 | 0.5.13 - 0.x.x |
|
||||
| 16.0.1 | 0.5.7 - 0.5.13 |
|
||||
| 16.0.0 | 0.5.2 - 0.5.6 |
|
||||
| 15.0.1 | 0.4.8 - 0.5.1 |
|
||||
| 15.0.0 | 0.4.0 - 0.4.7 |
|
||||
| 14.0.2 | 0.2.3 - 0.3.x |
|
||||
| 14.0.1 | ≤ 0.2.2 |
|
||||
|
||||
## Hotkeys
|
||||
All hotkeys available in QtCreator Settings
|
||||
Also you can find default hotkeys here:
|
||||
- To call chat with llm in separate window, you can use:
|
||||
- on Mac: Option + Command + W
|
||||
- on Windows: Ctrl + Alt + W
|
||||
- on Linux: Ctrl + Alt + W
|
||||
- To close chat with llm in separate window, you can use:
|
||||
- on Mac: Option + Command + S
|
||||
- on Windows: Ctrl + Alt + S
|
||||
- on Linux: Ctrl + Alt + S
|
||||
- To call manual request to suggestion, you can use or change it in settings
|
||||
- on Mac: Option + Command + Q
|
||||
- on Windows: Ctrl + Alt + Q
|
||||
- on Linux with KDE Plasma: Ctrl + Alt + Q
|
||||
- To insert the full suggestion, you can use the TAB key
|
||||
- To insert word of suggistion, you can use Alt + Right Arrow for Win/Lin, or Option + Right Arrow for Mac
|
||||
- To call Quick Refactor dialog, select some code or place cursor and press
|
||||
- on Mac: Option + Command + R
|
||||
- on Windows: Ctrl + Alt + R
|
||||
- on Linux with KDE Plasma: Ctrl + Alt + R
|
||||
|
||||
## Ignoring Files
|
||||
QodeAssist supports the ability to ignore files in context using a .qodeassistignore file. This allows you to exclude specific files from the context during code completion and in the chat assistant, which is especially useful for large projects.
|
||||
All hotkeys can be customized in Qt Creator Settings. Default hotkeys:
|
||||
|
||||
### How to Use .qodeassistignore
|
||||
- Create a .qodeassistignore file in the root directory of your project near CMakeLists.txt or pro.
|
||||
- Add patterns for files and directories that should be excluded from the context.
|
||||
- QodeAssist will automatically detect this file and apply the exclusion rules.
|
||||
|
||||
### .qodeassistignore File Format
|
||||
The file format is similar to .gitignore:
|
||||
- Each pattern is written on a separate line
|
||||
- Empty lines are ignored
|
||||
- Lines starting with # are considered comments
|
||||
- Standard wildcards work the same as in .gitignore
|
||||
- To negate a pattern, use ! at the beginning of the line
|
||||
```
|
||||
# Ignore all files in the build directory
|
||||
/build
|
||||
*.tmp
|
||||
# Ignore a specific file
|
||||
src/generated/autogen.cpp
|
||||
|
||||
```
|
||||
| Action | macOS | Windows/Linux |
|
||||
|--------|-------|--------------|
|
||||
| Open chat window | ⌥⌘W | Ctrl+Alt+W |
|
||||
| Close chat window | ⌥⌘S | Ctrl+Alt+S |
|
||||
| Manual code suggestion | ⌥⌘Q | Ctrl+Alt+Q |
|
||||
| Accept full suggestion | Tab | Tab |
|
||||
| Accept word | ⌥→ | Alt+→ |
|
||||
| Quick refactor | ⌥⌘R | Ctrl+Alt+R |
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If QodeAssist is having problems connecting to the LLM provider, please check the following:
|
||||
Having issues with QodeAssist? Check our [detailed troubleshooting guide](docs/troubleshooting.md) for:
|
||||
|
||||
1. Verify the IP address and port:
|
||||
- Connection issues and provider URLs
|
||||
- Model and template compatibility
|
||||
- Platform-specific issues (Linux, macOS, Windows)
|
||||
- Resetting settings to defaults
|
||||
- Common problems and solutions
|
||||
|
||||
- For Ollama, the default is usually http://localhost:11434
|
||||
- For LM Studio, the default is usually http://localhost:1234
|
||||
For additional support, join our [Discord Community](https://discord.gg/BGMkUsXUgf) or check [GitHub Issues](https://github.com/Palm1r/QodeAssist/issues).
|
||||
|
||||
2. Confirm that the selected model and template are compatible:
|
||||
## Development Progress
|
||||
|
||||
Ensure you've chosen the correct model in the "Select Models" option
|
||||
Verify that the selected prompt template matches the model you're using
|
||||
|
||||
3. On Linux the prebuilt binaries support only ubuntu 22.04+ or simililliar os.
|
||||
If you need compatiblity with another os, you have to build manualy. our experiments and resolution you can check here: https://github.com/Palm1r/QodeAssist/issues/48
|
||||
|
||||
If you're still experiencing issues with QodeAssist, you can try resetting the settings to their default values:
|
||||
1. Open Qt Creator settings
|
||||
2. Navigate to the "QodeAssist" tab
|
||||
3. Pick settings page for reset
|
||||
4. Click on the "Reset Page to Defaults" button
|
||||
- The API key will not reset
|
||||
- Select model after reset
|
||||
- [x] Code completion functionality
|
||||
- [x] Chat assistant with multiple panels
|
||||
- [x] Diff sharing with models
|
||||
- [x] Tools/function calling support
|
||||
- [x] Project-specific rules
|
||||
- [ ] Full project source sharing
|
||||
- [ ] Additional provider support
|
||||
- [ ] MCP (Model Context Protocol) support
|
||||
|
||||
## Support the development of QodeAssist
|
||||
If you find QodeAssist helpful, there are several ways you can support the project:
|
||||
@ -433,20 +239,43 @@ Every contribution, no matter how small, is greatly appreciated and helps keep t
|
||||
|
||||
## How to Build
|
||||
|
||||
Create a build directory and run
|
||||
### Prerequisites
|
||||
- CMake 3.16+
|
||||
- C++20 compatible compiler
|
||||
- Qt Creator development files
|
||||
|
||||
cmake -DCMAKE_PREFIX_PATH=<path_to_qtcreator> -DCMAKE_BUILD_TYPE=RelWithDebInfo <path_to_plugin_source>
|
||||
cmake --build .
|
||||
### Build Steps
|
||||
|
||||
where `<path_to_qtcreator>` is the relative or absolute path to a Qt Creator build directory, or to a
|
||||
combined binary and development package (Windows / Linux), or to the `Qt Creator.app/Contents/Resources/`
|
||||
directory of a combined binary and development package (macOS), and `<path_to_plugin_source>` is the
|
||||
relative or absolute path to this plugin directory.
|
||||
1. Create a build directory:
|
||||
|
||||
```bash
|
||||
mkdir build && cd build
|
||||
```
|
||||
|
||||
2. Configure and build:
|
||||
|
||||
```bash
|
||||
cmake -DCMAKE_PREFIX_PATH=<path_to_qtcreator> -DCMAKE_BUILD_TYPE=RelWithDebInfo <path_to_plugin_source>
|
||||
cmake --build .
|
||||
```
|
||||
|
||||
**Path specifications:**
|
||||
- `<path_to_qtcreator>`:
|
||||
- **Windows/Linux**: Qt Creator build directory or combined binary package
|
||||
- **macOS**: `Qt Creator.app/Contents/Resources/`
|
||||
- `<path_to_plugin_source>`: Path to this plugin directory
|
||||
|
||||
## For Contributors
|
||||
|
||||
QML code style: Preferably follow the following guidelines https://github.com/Furkanzmc/QML-Coding-Guide, thank you @Furkanzmc for collect them
|
||||
C++ code style: check use .clang-fortmat in project
|
||||
### Code Style
|
||||
|
||||
- **QML**: Follow [QML Coding Guide](https://github.com/Furkanzmc/QML-Coding-Guide) by @Furkanzmc
|
||||
- **C++**: Use `.clang-format` configuration in the project root
|
||||
- Run formatting before submitting PRs
|
||||
|
||||
### Development Guidelines
|
||||
|
||||
For detailed development guidelines, architecture patterns, and best practices, see the [project workspace rules](.cursor/rules.mdc).
|
||||
|
||||
|
||||
|
||||
|
||||
16
docs/claude-configuration.md
Normal file
16
docs/claude-configuration.md
Normal file
@ -0,0 +1,16 @@
|
||||
# Configure for Anthropic Claude
|
||||
|
||||
1. Open Qt Creator settings and navigate to the QodeAssist section
|
||||
2. Go to Provider Settings tab and configure Claude api key
|
||||
3. Return to General tab and configure:
|
||||
- Set "Claude" as the provider for code completion or/and chat assistant
|
||||
- Set the Claude URL (https://api.anthropic.com)
|
||||
- Select your preferred model (e.g., claude-3-5-sonnet-20241022)
|
||||
- Choose the Claude template for code completion or/and chat
|
||||
|
||||
<details>
|
||||
<summary>Example of Claude settings: (click to expand)</summary>
|
||||
|
||||
<img width="823" alt="Claude Settings" src="https://github.com/user-attachments/assets/828e09ea-e271-4a7a-8271-d3d5dd5c13fd" />
|
||||
</details>
|
||||
|
||||
33
docs/file-context.md
Normal file
33
docs/file-context.md
Normal file
@ -0,0 +1,33 @@
|
||||
# File Context Feature
|
||||
|
||||
QodeAssist provides two powerful ways to include source code files in your chat conversations: Attachments and Linked Files. Each serves a distinct purpose and helps provide better context for the AI assistant.
|
||||
|
||||
## Attached Files
|
||||
|
||||
Attachments are designed for one-time code analysis and specific queries:
|
||||
- Files are included only in the current message
|
||||
- Content is discarded after the message is processed
|
||||
- Ideal for:
|
||||
- Getting specific feedback on code changes
|
||||
- Code review requests
|
||||
- Analyzing isolated code segments
|
||||
- Quick implementation questions
|
||||
- Files can be attached using the paperclip icon in the chat interface
|
||||
- Multiple files can be attached to a single message
|
||||
|
||||
## Linked Files
|
||||
|
||||
Linked files provide persistent context throughout the conversation:
|
||||
|
||||
- Files remain accessible for the entire chat session
|
||||
- Content is included in every message exchange
|
||||
- Files are automatically refreshed - always using latest content from disk
|
||||
- Perfect for:
|
||||
- Long-term refactoring discussions
|
||||
- Complex architectural changes
|
||||
- Multi-file implementations
|
||||
- Maintaining context across related questions
|
||||
- Can be managed using the link icon in the chat interface
|
||||
- Supports automatic syncing with open editor files (can be enabled in settings)
|
||||
- Files can be added/removed at any time during the conversation
|
||||
|
||||
16
docs/google-ai-configuration.md
Normal file
16
docs/google-ai-configuration.md
Normal file
@ -0,0 +1,16 @@
|
||||
# Configure for Google AI
|
||||
|
||||
1. Open Qt Creator settings and navigate to the QodeAssist section
|
||||
2. Go to Provider Settings tab and configure Google AI api key
|
||||
3. Return to General tab and configure:
|
||||
- Set "Google AI" as the provider for code completion or/and chat assistant
|
||||
- Set the OpenAI URL (https://generativelanguage.googleapis.com/v1beta)
|
||||
- Select your preferred model (e.g., gemini-2.0-flash)
|
||||
- Choose the Google AI template
|
||||
|
||||
<details>
|
||||
<summary>Example of Google AI settings: (click to expand)</summary>
|
||||
|
||||
<img width="829" alt="Google AI Settings" src="https://github.com/user-attachments/assets/046ede65-a94d-496c-bc6c-41f3750be12a" />
|
||||
</details>
|
||||
|
||||
29
docs/ignoring-files.md
Normal file
29
docs/ignoring-files.md
Normal file
@ -0,0 +1,29 @@
|
||||
# Ignoring Files
|
||||
|
||||
QodeAssist supports the ability to ignore files in context using a `.qodeassistignore` file. This allows you to exclude specific files from the context during code completion and in the chat assistant, which is especially useful for large projects.
|
||||
|
||||
## How to Use .qodeassistignore
|
||||
|
||||
- Create a `.qodeassistignore` file in the root directory of your project near CMakeLists.txt or pro.
|
||||
- Add patterns for files and directories that should be excluded from the context.
|
||||
- QodeAssist will automatically detect this file and apply the exclusion rules.
|
||||
|
||||
## .qodeassistignore File Format
|
||||
|
||||
The file format is similar to `.gitignore`:
|
||||
- Each pattern is written on a separate line
|
||||
- Empty lines are ignored
|
||||
- Lines starting with `#` are considered comments
|
||||
- Standard wildcards work the same as in .gitignore
|
||||
- To negate a pattern, use `!` at the beginning of the line
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
# Ignore all files in the build directory
|
||||
/build
|
||||
*.tmp
|
||||
# Ignore a specific file
|
||||
src/generated/autogen.cpp
|
||||
```
|
||||
|
||||
16
docs/llamacpp-configuration.md
Normal file
16
docs/llamacpp-configuration.md
Normal file
@ -0,0 +1,16 @@
|
||||
# Configure for llama.cpp
|
||||
|
||||
1. Open Qt Creator settings and navigate to the QodeAssist section
|
||||
2. Go to General tab and configure:
|
||||
- Set "llama.cpp" as the provider for code completion or/and chat assistant
|
||||
- Set the llama.cpp URL (e.g. http://localhost:8080)
|
||||
- Fill in model name
|
||||
- Choose template for model(e.g. llama.cpp FIM for any model with FIM support)
|
||||
- Disable using tools if your model doesn't support tooling
|
||||
|
||||
<details>
|
||||
<summary>Example of llama.cpp settings: (click to expand)</summary>
|
||||
|
||||
<img width="829" alt="llama.cpp Settings" src="https://github.com/user-attachments/assets/8c75602c-60f3-49ed-a7a9-d3c972061ea2" />
|
||||
</details>
|
||||
|
||||
16
docs/mistral-configuration.md
Normal file
16
docs/mistral-configuration.md
Normal file
@ -0,0 +1,16 @@
|
||||
# Configure for Mistral AI
|
||||
|
||||
1. Open Qt Creator settings and navigate to the QodeAssist section
|
||||
2. Go to Provider Settings tab and configure Mistral AI api key
|
||||
3. Return to General tab and configure:
|
||||
- Set "Mistral AI" as the provider for code completion or/and chat assistant
|
||||
- Set the OpenAI URL (https://api.mistral.ai)
|
||||
- Select your preferred model (e.g., mistral-large-latest)
|
||||
- Choose the Mistral AI template for code completion or/and chat
|
||||
|
||||
<details>
|
||||
<summary>Example of Mistral AI settings: (click to expand)</summary>
|
||||
|
||||
<img width="829" alt="Mistral AI Settings" src="https://github.com/user-attachments/assets/1c5ed13b-a29b-43f7-b33f-2e05fdea540c" />
|
||||
</details>
|
||||
|
||||
36
docs/ollama-configuration.md
Normal file
36
docs/ollama-configuration.md
Normal file
@ -0,0 +1,36 @@
|
||||
# Configure for Ollama
|
||||
|
||||
1. Install [Ollama](https://ollama.com). Make sure to review the system requirements before installation.
|
||||
2. Install a language models in Ollama via terminal. For example, you can run:
|
||||
|
||||
For standard computers (minimum 8GB RAM):
|
||||
```bash
|
||||
ollama run qwen2.5-coder:7b
|
||||
```
|
||||
For better performance (16GB+ RAM):
|
||||
```bash
|
||||
ollama run qwen2.5-coder:14b
|
||||
```
|
||||
For high-end systems (32GB+ RAM):
|
||||
```bash
|
||||
ollama run qwen2.5-coder:32b
|
||||
```
|
||||
|
||||
3. Open Qt Creator settings (Edit > Preferences on Linux/Windows, Qt Creator > Preferences on macOS)
|
||||
4. Navigate to the "QodeAssist" tab
|
||||
5. On the "General" page, verify:
|
||||
- Ollama is selected as your LLM provider
|
||||
- The URL is set to http://localhost:11434
|
||||
- Your installed model appears in the model selection
|
||||
- The prompt template is Ollama Auto FIM or Ollama Auto Chat for chat assistance. You can specify template if it is not work correct
|
||||
- Disable using tools if your model doesn't support tooling
|
||||
6. Click Apply if you made any changes
|
||||
|
||||
You're all set! QodeAssist is now ready to use in Qt Creator.
|
||||
|
||||
<details>
|
||||
<summary>Example of Ollama settings: (click to expand)</summary>
|
||||
|
||||
<img width="824" alt="Ollama Settings" src="https://github.com/user-attachments/assets/ed64e03a-a923-467a-aa44-4f790e315b53" />
|
||||
</details>
|
||||
|
||||
16
docs/openai-configuration.md
Normal file
16
docs/openai-configuration.md
Normal file
@ -0,0 +1,16 @@
|
||||
# Configure for OpenAI
|
||||
|
||||
1. Open Qt Creator settings and navigate to the QodeAssist section
|
||||
2. Go to Provider Settings tab and configure OpenAI api key
|
||||
3. Return to General tab and configure:
|
||||
- Set "OpenAI" as the provider for code completion or/and chat assistant
|
||||
- Set the OpenAI URL (https://api.openai.com)
|
||||
- Select your preferred model (e.g., gpt-4o)
|
||||
- Choose the OpenAI template for code completion or/and chat
|
||||
|
||||
<details>
|
||||
<summary>Example of OpenAI settings: (click to expand)</summary>
|
||||
|
||||
<img width="829" alt="OpenAI Settings" src="https://github.com/user-attachments/assets/4716f790-6159-44d0-a8f4-565ccb6eb713" />
|
||||
</details>
|
||||
|
||||
35
docs/project-rules.md
Normal file
35
docs/project-rules.md
Normal file
@ -0,0 +1,35 @@
|
||||
# Project Rules Configuration
|
||||
|
||||
QodeAssist supports project-specific rules to customize AI behavior for your codebase. Create a `.qodeassist/rules/` directory in your project root.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
mkdir -p .qodeassist/rules/{common,completion,chat,quickrefactor}
|
||||
```
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
.qodeassist/
|
||||
└── rules/
|
||||
├── common/ # Applied to all contexts
|
||||
├── completion/ # Code completion only
|
||||
├── chat/ # Chat assistant only
|
||||
└── quickrefactor/ # Quick refactor only
|
||||
```
|
||||
|
||||
All `.md` files in each directory are automatically loaded and added to the system prompt.
|
||||
|
||||
## Example
|
||||
|
||||
Create `.qodeassist/rules/common/general.md`:
|
||||
|
||||
```markdown
|
||||
# Project Guidelines
|
||||
- Use snake_case for private members
|
||||
- Prefix interfaces with 'I'
|
||||
- Always document public APIs
|
||||
- Prefer Qt containers over STL
|
||||
```
|
||||
|
||||
18
docs/quick-refactoring.md
Normal file
18
docs/quick-refactoring.md
Normal file
@ -0,0 +1,18 @@
|
||||
# Quick Refactoring Feature
|
||||
|
||||
## Setup
|
||||
|
||||
Since this is actually a small chat with redirected output, the main settings of the provider, model and template are taken from the chat settings.
|
||||
|
||||
## Using
|
||||
|
||||
The request to model consist of instructions to model, selection code and cursor position.
|
||||
|
||||
The default instruction is: "Refactor the code to improve its quality and maintainability." and sending if text field is empty.
|
||||
|
||||
Also there buttons to quick call instractions:
|
||||
- Repeat latest instruction, will activate after sending first request in QtCreator session
|
||||
- Improve current selection code
|
||||
- Suggestion alternative variant of selection code
|
||||
- Other instructions[TBD]
|
||||
|
||||
70
docs/troubleshooting.md
Normal file
70
docs/troubleshooting.md
Normal file
@ -0,0 +1,70 @@
|
||||
# Troubleshooting
|
||||
|
||||
## Connection Issues
|
||||
|
||||
### 1. Verify provider URL and port
|
||||
|
||||
Make sure you're using the correct default URLs:
|
||||
- **Ollama**: `http://localhost:11434`
|
||||
- **LM Studio**: `http://localhost:1234`
|
||||
- **llama.cpp**: `http://localhost:8080`
|
||||
|
||||
### 2. Check model and template compatibility
|
||||
|
||||
- Ensure the correct model is selected in settings
|
||||
- Verify that the selected prompt template matches your model
|
||||
- Some models may not support certain features (e.g., tool calling)
|
||||
|
||||
### 3. Linux compatibility
|
||||
|
||||
- Prebuilt binaries support Ubuntu 22.04+
|
||||
- For other distributions, you may need to [build manually](../README.md#how-to-build)
|
||||
- See [issue #48](https://github.com/Palm1r/QodeAssist/issues/48) for known Linux compatibility issues and solutions
|
||||
|
||||
## Reset Settings
|
||||
|
||||
If issues persist, you can reset settings to their default values:
|
||||
|
||||
1. Open Qt Creator → Settings → QodeAssist
|
||||
2. Select the settings page you want to reset
|
||||
3. Click "Reset Page to Defaults" button
|
||||
|
||||
**Note:**
|
||||
- API keys are preserved during reset
|
||||
- You will need to re-select your model after reset
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Plugin doesn't appear after installation
|
||||
|
||||
1. Restart Qt Creator completely
|
||||
2. Check that the plugin is enabled in About Plugins
|
||||
3. Verify you downloaded the correct version for your Qt Creator
|
||||
|
||||
### No suggestions appearing
|
||||
|
||||
1. Check that code completion is enabled in QodeAssist settings
|
||||
2. Verify your provider/model is running and accessible
|
||||
3. Check Qt Creator's Application Output pane for error messages
|
||||
4. Try manual suggestion hotkey (⌥⌘Q on macOS, Ctrl+Alt+Q on Windows/Linux)
|
||||
|
||||
### Chat not responding
|
||||
|
||||
1. Verify your API key is configured correctly (for cloud providers)
|
||||
2. Check internet connection (for cloud providers)
|
||||
3. Ensure the provider service is running (for local providers)
|
||||
4. Look for error messages in the chat panel
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you continue to experience issues:
|
||||
|
||||
1. Check existing [GitHub Issues](https://github.com/Palm1r/QodeAssist/issues)
|
||||
2. Join our [Discord Community](https://discord.gg/BGMkUsXUgf) for support
|
||||
3. Open a new issue with:
|
||||
- Qt Creator version
|
||||
- QodeAssist version
|
||||
- Operating system
|
||||
- Provider and model being used
|
||||
- Steps to reproduce the problem
|
||||
|
||||
Reference in New Issue
Block a user