Palm1r/QodeAssist

QodeAssist는 C++ 및 QML을 위한 Qt Creator에 완전한 AI 코딩 워크플로우(workflow)를 제공합니다. 스마트한 코드 완성(code completion), 멀티 패널 채팅, 인라인 빠른 리팩토링(refactoring), 그리고 프로젝트 인지형 도구 호출(tool calling) 기능을 포함합니다. 이 도구는 로컬 런타임(Ollama, llama.cpp, LM Studio) 및 클라우드 제공업체(Claude, OpenAI, Google AI, Mistral)와 함께 작동하며, **MCP 서버 (MCP server)**로 실행되어 다른 클라이언트가 프로젝트 컨텍스트(context)를 재사용할 수 있게 할 수 있습니다. 또한 외부 MCP 서버로부터 도구를 가져오기 위한 **MCP 클라이언트 (MCP client)**로도 작동할 수 있습니다 (인증된 MCP 서버는 아직 지원되지 않습니다).

유료 제공업체에 관한 중요 공지

Claude, OpenRouter 또는 OpenAI 호환 서비스를 사용하는 경우:

• 이러한 서비스는 API 토큰을 소비하며, 이로 인해 귀하의 계정에 비용이 발생할 수 있습니다.

• QodeAssist 개발자는 발생한 모든 비용에 대해 책임을 지지 않습니다.

• 사용 전 제공업체의 가격 정책과 귀하의 계정 설정을 주의 깊게 검토하십시오.

• 개요 (Overview)

• 플러그인 설치 (Install Plugin)

• 설정 (Configuration)

• 기능 (Features)

• 컨텍스트 레이어 (Context Layers)

• QtCreator 버전 호환성 (QtCreator Version Compatibility)

• 단축키 (Hotkeys)

• 문제 해결 (Troubleshooting)

• 개발 진행 상황 (Development Progress)

• 개발 지원 (Support the Development)

• 빌드 방법 (How to Build)

QodeAssist는 AI 기반 코딩 지원을 통해 Qt Creator를 강화합니다:

코드 완성 (Code Completion)— C++ 및 QML을 위한 지능적이고 컨텍스트를 인식하는 제안(FIM 및 채팅 모델), 멀티라인(multiline) 지원
채팅 어시스턴트 (Chat Assistant)— 사이드 패널, 하단 패널 또는 분리된 창 형태; 자동 저장 기능이 있는 히스토리, 토큰 모니터링, 확장된 사고(extended thinking) 기능
빠른 리팩토링 (Quick Refactoring)— 검색 가능한 커스텀 지침(custom-instructions) 라이브러리를 통해 에디터 내에서 직접 수행하는 인라인 AI 지원 편집
에이전트 도구 (Agent Tools)— 파일 읽기, 검색, 생성 및 편집; 프로젝트 빌드; 터미널 명령 실행; 린터(linter)/컴파일러 이슈 접근; TODO 관리
에이전트 기술 (Agent Skills)— 필요 시 로드되는 전문화된 지침의 재사용 가능한 폴더; .qodeassist/skills/ 및 .claude/skills/에서 발견되며, /skill 명령으로 자동 호출됩니다.

, 또는 상시 가동되는 MCP Server— QodeAssist의 프로젝트 인식 도구들을 외부 MCP 클라이언트(Claude Code, VS Code, 브릿지를 통한 Claude Desktop)에 노출합니다. MCP Client Hub— QodeAssist를 외부 MCP 서버에 연결하고, 채팅(Chat) 및 빠른 리팩터링(Quick Refactor)에서 해당 도구들을 사용합니다 (인증된 MCP 서버는 아직 지원되지 않습니다). File Context— 더 풍부한 프롬프트를 위해 열려 있는 에디터 파일들을 첨부, 연결 또는 자동 동기화합니다. Many Providers— Ollama, llama.cpp, LM Studio (Chat + Responses), Claude, OpenAI (Chat + Responses), Google AI, Mistral, Codestral, OpenRouter, 모든 OpenAI 호환 엔드포인트. Customizable— 프로젝트별 규칙 (.qodeassist/rules/), 에이전트 역할(agent roles), 재사용 가능한 리팩터링 템플릿, 전체 프롬프트 템플릿 제어 가능.

Join our Discord Community를 통해 지원을 받고 다른 사용자들과 소통하세요!

QodeAssistUpdater는 Qt Creator 버전을 자동으로 감지하고 체크섬(checksum) 검증을 수행하여 플러그인 설치 및 업데이트를 자동화하는 명령줄 유틸리티(command-line utility)입니다.

Features (기능):

• 자동 Qt Creator 버전 감지
• 단일 명령어로 플러그인 설치, 업데이트 또는 제거
• 사용 가능한 모든 플러그인 버전 목록 표시
• 특정 플러그인 버전 설치
• 체크섬(Checksum) 검증
• CI/CD를 위한 비대화형 모드(Non-interactive mode)

Installation (설치):

QodeAssistUpdater 릴리스(releases)에서 빌드된 바이너리를 다운로드하거나 소스에서 빌드하세요.

Usage (사용법):

# 현재 상태 및 사용 가능한 업데이트 확인
./qodeassist-updater --status
# 최신 버전 설치
...

자세한 내용은 QodeAssistUpdater 리포지토리(repository)를 방문하세요.

• 최신 Qt Creator 설치

• 사용 중인 Qt Creator용 QodeAssist 플러그인 다운로드

• 이미 설치되어 있는 경우 이전 버전 플러그인 제거

• macOS의 QtCreator 16 기준: ~/Library/Application Support/QtProject/Qt Creator/plugins/16.0.0/petrmironychev.qodeassist

• Windows의 QtCreator 16 기준: C:\Users<user>\AppData\Local\QtProject\qtcreator\plugins\16.0.0\petrmironychev.qodeassist\lib\qtcreator\plugins

• 이미 설치되어 있는 경우 이전 버전의 플러그인을 제거합니다.

• Qt Creator를 실행하고 플러그인을 설치합니다:

• 다음 경로로 이동합니다:

• MacOS: Qt Creator -> About Plugins...

• Windows\Linux: Help -> About Plugins...

• "Install Plugin..."을 클릭합니다.

• 다운로드한 QodeAssist 플러그인 아카이브 파일을 선택합니다.

• 다음 경로로 이동합니다:

Quick Setup (빠른 설정) 기능은 인기 있는 클라우드 AI 모델에 대한 원클릭 구성을 제공합니다. 다음 3단계를 통해 시작하세요:

QodeAssist 설정 열기
프리셋(Preset) 선택

• Quick Setup 드롭다운에서 선택합니다:
  Anthropic Claude(Sonnet 4.5, Haiku 4.5, Opus 4.5)
  OpenAI(gpt-5.2-codex)
  Mistral AI(Codestral 2501)
  Google AI(Gemini 2.5 Flash)

API 키 구성

• "Configure API Key" 버튼을 클릭하고 Provider Settings (제공자 설정)에 API 키를 입력합니다.

모든 설정(제공자, 모델, 템플릿, URL)은 자동으로 구성됩니다. API 키만 추가하면 바로 사용할 준비가 완료됩니다!

고급 사용자 또는 로컬 모델의 경우, 선호하는 제공자를 선택하고 상세 구성 가이드를 따르십시오:

로컬 제공자 (Local providers):

Ollama— 네이티브 Ollama API
Ollama (OpenAI-compatible)— 도구 호출 (tool-calling) 모델을 위한 Ollama의 /v1 엔드포인트
llama.cpp— 로컬 llama-server

LM Studio— OpenAI 호환 Chat API
LM Studio (Responses API)— Responses 엔드포인트가 필요한 최신 모델

클라우드 제공자 (Cloud providers):

Anthropic Claude— 수동 설정 가이드
OpenAI— Chat Completions 및 Responses API
Mistral AI/Codestral
Google AI— Gemini
OpenAI-compatible— OpenRouter 및 모든 커스텀 엔드포인트

최적의 코딩 지원을 위해 다음의 최상급 모델 사용을 권장합니다:

코드 완성(Code Completion) 및 리팩터링(Refactoring)에 최적:

Claude 4.5 Haiku 또는 Sonnet(Anthropic)
GPT-5.1-codex 또는 codex-mini(OpenAI Responses API)
Codestral(Mistral)

채팅 어시스턴트(Chat Assistant)에 최적:

Claude 4.5 Sonnet(Anthropic) - 뛰어난 추론 능력과 자연스러운 대화 흐름
GPT-5.1-codex(OpenAI Responses API) - 고급 기능을 갖춘 최신 모델
Gemini 2.5 또는 3.0(Google AI) - Google의 최신 모델들
Mistral large(Mistral) - 빠르고 유능함

로컬 모델 (Local models):

Qwen3-coder(Qwen) - 최고의 로컬 모델

에이전트 역할 (Agent Roles) - 특화된 시스템 프롬프트(System Prompts)를 사용하여 AI 페르소나 생성
채팅 요약 (Chat Summarization) - 컨텍스트 토큰(Context Tokens)을 절약하기 위해 대화 압축
프로젝트 규칙 (Project Rules) - 프로젝트에 맞춰 AI 동작 사용자 정의
파일 제외 (Ignoring Files) - .qodeassistignore를 사용하여 컨텍스트에서 파일 제외

• AI 기반 지능형 코드 완성 (Code Completion)
• C++ 및 QML 지원
• 컨텍스트 인식 제안 (Context-aware suggestions)
• 다중 행 완성 (Multiline completions)

QodeAssist는 코드 완성을 위해 두 가지 트리거 모드를 제공합니다:

힌트 기반 (Hint-based)

• 3자 이상의 문자를 입력하면 커서 근처에 힌트 표시기가 나타남
• Space(또는 사용자 정의 키)를 눌러 완성 요청
• 가장 적합한 경우: 유료 API (Claude, OpenAI), 의식적인 제어가 필요한 경우
• 장점: 예상치 못한 API 비용 발생 방지, 요청에 대한 완전한 제어, 워크플로우 중단 없음
• 시각적 요소: 완성이 준비되었을 때 명확한 표시기 제공

자동 (Automatic, 기본값)

• 입력 임계값 도달 후 자동으로 완성 요청
• 추가 키 입력 없이 즉시 작동
• 가장 적합한 경우: 로컬 모델 (Ollama, llama.cpp), 최대 자동화가 필요한 경우
• 장점: 핸즈프리(Hands-free) 경험, 즉각적인 제안

💡 팁: 예상치 못한 비용을 방지하려면 힌트 기반 모드로 시작하세요. 무료 로컬 모델을 사용하는 경우 자동 모드로 전환하세요.

설정 위치: Tools → Options → QodeAssist → Code Completion → General Settings

• 다중 채팅 패널: 사이드 패널 (side panel), 하단 패널 (bottom panel), 팝업 창 (popup window)

• 자동 저장 및 복구가 지원되는 채팅 기록 (Chat history)

• 토큰 사용량 모니터링 (Token usage monitoring)
  에이전트 역할 (Agent Roles)

• AI 페르소나 간 전환 (개발자 (Developer), 리뷰어 (Reviewer), 사용자 정의 역할 (custom roles))
  채팅 요약 (Chat Summarization)

• 긴 대화를 AI가 생성한 요약본으로 압축
  파일 컨텍스트 (File Context)

• 더 나은 컨텍스트를 위해 파일 첨부 또는 연결

• 열려 있는 에디터 파일과 자동 동기화 (선택 사항)

• 확장 사고 모드 (Extended thinking mode) (Claude 및 요금제에 포함된 기타 제공업체) - 복잡한 작업을 위해 더 깊은 추론 (reasoning) 활성화

• AI 지원을 통해 에디터 내에서 직접 인라인 코드 리팩터링 (Inline code refactoring) 수행
  사용자 정의 지침 라이브러리 (Custom instructions library)

• 검색 및 자동 완성 기능 포함

• 재사용 가능한 리팩터링 템플릿 생성, 편집 및 관리

• 기본 지침과 특정 세부 사항 결합
  자세히 알아보기 (Learn more)

채팅 (Chat) 및 퀵 리팩터 (Quick Refactor)는 도구 (tools)를 호출하여 프로젝트를 조사하고 수정할 수 있습니다. 각 도구는 설정에서 개별적으로 활성화/비활성화할 수 있습니다.

도구 (Tool)	기능
list_project_files	활성 프로젝트 내 파일 목록 나열
find_file	이름 또는 부분 경로로 파일 찾기
read_file	파일 내용 읽기 (프로젝트 또는 절대 경로)
search_project	프로젝트 소스 전반에 걸친 Grep / 심볼 검색
create_new_file	디스크에 새로운 빈 파일 생성
edit_file	파일 내용 교체 (이전 내용 → 새 내용)
build_project	활성 프로젝트를 빌드하고 컴파일러 출력 반환
get_issues_list	현재 린터 (linter) / 컴파일러 진단 내용 읽기
execute_terminal_command	셸 명령 실행 (확인 절차 포함)
todo_tool	대화 중 다단계 작업 진행 상황 추적

에이전트 스킬 (Agent Skills) 패키지는 특화된 지침과 워크플로 (workflows)를 AI가 필요할 때마다 로드할 수 있는 재사용 가능한 폴더로 묶은 것입니다. QodeAssist는 개방형 에이전트 스킬 (Agent Skills) 형식을 구현하므로, Claude Code, Cursor 또는 기타 에이전트를 위해 작성된 스킬이 그대로 작동합니다.

스킬은 SKILL.md 파일을 포함하는 폴더입니다. 이 파일은 YAML 프런트매터 (frontmatter) (name, description)와 마크다운 (Markdown) 지침으로 구성됩니다.

my-skill/
└── SKILL.md

---

name: my-skill
description: 스킬의 기능 및 사용 시점.
...

스킬이 발견되는 위치:

프로젝트 스킬 (Project skills)— 프로젝트 상대 경로의 하위 디렉토리(기본값 .qodeassist/skills/ 및 .claude/skills/)이며, Projects → QodeAssist → Skills에서 설정합니다. 이름 충돌이 발생할 경우 프로젝트 스킬이 글로벌 스킬보다 우선합니다. 글로벌 스킬 (Global skills)— 모든 프로젝트에서 공유되는 절대 경로 디렉토리(기본값 ~/.claude/skills/ 포함)이며, Tools → Options → QodeAssist → Skills에서 설정합니다.

두 설정 페이지 모두 현재 발견된 스킬 목록을 보여줍니다.

채팅에서 스킬을 사용하는 방법:

자동 (Automatically)— 각 스킬의 이름과 설명이 시스템 프롬프트 (System Prompt)에 추가됩니다. 요청이 일치하면 모델이 load_skill 도구 (Tool)를 통해 전체 지침을 로드합니다 (도구 호출 (Tool-calling) 모델이 필요합니다). 명시적 (Explicitly)— 채팅 입력창에 /를 입력하고 팝업에서 스킬을 선택합니다. 해당 스킬의 지침이 그 메시지에 주입됩니다. 모든 모델에서 작동합니다. 항상 켜짐 (Always-on)— 프론트매터 (Frontmatter)에 metadata: always-on: "true"가 포함된 스킬은 모든 채팅 요청에 자동으로 주입됩니다.

Tools → Options → QodeAssist → Skills에서 기능 전체를 활성화하거나 비활성화할 수 있습니다.

QodeAssist는 localhost에서 MCP (Model Context Protocol) 서버를 실행하여 위의 도구들을 외부 클라이언트에 노출할 수 있습니다. 이를 통해 Claude Code CLI, VS Code, Cursor, Claude Desktop 또는 기타 MCP 지원 클라이언트에서 QodeAssist의 프로젝트 인지 능력을 사용할 수 있습니다.

Tools → Options → QodeAssist → MCP Server에서 활성화 (Enable) 하세요.
전송 (Transport): 기본적으로 HTTP + SSE를 사용합니다. stdio만 지원하는 클라이언트(예: Claude Desktop)를 위해 stdio 브릿지 (Bridge)가 제공됩니다.
복사 가능한 스니펫 (Ready-to-copy snippets): Claude Code, VS Code 및 브릿지용 스니펫은 설정의 "Show connection instructions" 버튼을 통해 사용할 수 있습니다.

QodeAssist는 또한 MCP 클라이언트 (MCP client) 역할을 수행하여 외부 MCP 서버에 연결하고, 내장된 도구와 함께 해당 서버의 도구들을 채팅 (Chat) 및 빠른 리팩터링 (Quick Refactor)에서 사용할 수 있게 합니다.

Tools → Options → QodeAssist → MCP Client에서 서버를 설정 (Configure) 하세요.

Transports (전송 방식): stdio 및 HTTP/SSE
Limitation (제한 사항): 인증된 MCP 서버 (OAuth / 토큰 보호)는 아직 지원되지 않습니다 — 현재는 인증되지 않은 로컬 연결을 허용하는 서버만 작동합니다.

QodeAssist는 다양한 컨텍스트에 적응하는 유연한 프롬프트 구성 시스템을 사용합니다. 각 기능별 프롬프트가 구성되는 방식은 다음과 같습니다:

Code Completion (FIM 모델) - Codestral, Qwen2.5-Coder, DeepSeek-Coder (클릭하여 확장)

┌─────────────────────────────────────────────────────────────────────────────┐
│ CODE COMPLETION (FIM Models) │
├─────────────────────────────────────────────────────────────────────────────┤
...

Code Completion (Non-FIM 모델) - DeepSeek-Coder-Instruct, Qwen2.5-Coder-Instruct (클릭하여 확장)

┌─────────────────────────────────────────────────────────────────────────────┐
│ CODE COMPLETION (Non-FIM/Chat Models) │
├─────────────────────────────────────────────────────────────────────────────┤
...

Chat Assistant - 대화형 코딩 어시스턴트 (클릭하여 확장)

┌─────────────────────────────────────────────────────────────────────────────┐
│ CHAT ASSISTANT │
├─────────────────────────────────────────────────────────────────────────────┤
...

Quick Refactoring - 인라인 코드 개선 (클릭하여 확장)

┌─────────────────────────────────────────────────────────────────────────────┐
│ QUICK REFACTORING │
├─────────────────────────────────────────────────────────────────────────────┤
...

**Project Rules (프로젝트 규칙)**은 .qodeassist/rules/에서 자동으로 로드됩니다.