OpenCodeRAG

OpenCodeRAG는 시맨틱 코드 및 이미지 검색을 위한 로컬 우선 (local-first) RAG 플러그인이며, 빠른 분류를 위해 내장된 **로컬 결정 모델 (local decision model)**을 갖추고 있습니다. 이 플러그인은 코드베이스 전체를 벡터 인덱스(vector indices)로 변환하고 자연어 질의에 대해 관련 코드 청크(code chunks)를 검색합니다. 주된 목표는 전체 파일 읽기 대신 타겟팅된 청크 검색을 사용하여 토큰 사용량을 절감하고, 대규모 코드베이스에서 도구 호출(tool calls) 속도를 높이는 것입니다. OpenCode와 원활하게 통합되며, 독립적인 MCP 서버 또는 다른 AI 하네스용 CLI 도구로 작동합니다.

작은 임베딩 LLM(embedding LLMs)의 경우 전용 GPU가 필요하지 않으며, 이러한 모델들은 최신 CPU에서도 여전히 성능을 발휘할 수 있습니다.

⚠️ 참고: 이 플러그인을 다른 작성자가 만든 npm 패키지 opencode-rag와 혼동하지 마십시오 (단종된 프로젝트입니다).

빠른 시작 (Quick Start)

# 1. 전역 설치 (자동으로 OpenCode 런타임 설정)
npm install -g opencode-rag-plugin

...

opencode-rag setup은 머신 레벨 런타임을 설치/확인하며, 프로젝트 내부에서 실행될 경우 워크스페이스(.opencode/, 플러그인 엔트리, 스킬 파일, opencode-rag.json)를 한 번에 초기화합니다. 설치된 버전이 오래되었을 경우, npm에서 최신 게시 버전을 가져와 설치합니다. opencode-rag init은 이미 초기화된 워크스페이스를 재동기화하는 데 계속 사용할 수 있으며, opencode-rag update는 새 릴리스로 업그레이드합니다.

사전 요구 사항 (Prerequisites): Node.js v22 이상, Ollama (기본값) 또는 기타 LLM 호스팅 서비스 (OpenAI-, Google- 또는 Anthropic-호환).

pnpm add -g opencode-rag-plugin, yarn global add opencode-rag-plugin, 및 bun add -g opencode-rag-plugin은 전역 설치의 대체재로 작동하며, 설정 및 업데이트 시 소유한 패키지 관리자를 감지하므로 PATH에 npm이 필요하지 않습니다.

기여자 / 개발자: 리포지토리를 클론하고 npm install --legacy-peer-deps; npm run build를 사용하십시오 — 개발 문서 (Development docs) 참조.

주요 기능 (Key Features)

웹 UI (Web UI)

색인된 벡터 데이터베이스를 탐색하기 위한 브라우저 기반 대시보드입니다. 청크(chunks)를 찾아보고, 시각화하고, 검사하며, 검색된 청크 수, 소모 토큰 등 OpenCode 세션을 평가할 수 있습니다.

opencode-rag ui로 실행합니다. 자세한 내용은 Web UI 문서를 참조하세요.

문서 (Documentation)

의사 결정 모델 (make_decision)

OpenCodeRAG는 로컬 의사 결정 모델을 사용하여 빠른 분류(classification), 라우팅(routing), 정책(policy), 및 점수화(scoring) 질문에 답변합니다. 이는 Together AI의 tev1이며, Ollama의 /v1/systemone 엔드포인트를 통해 사용됩니다. 채팅 모델과 달리, tev1은 짧은 state를 1~64개의 명명된 질문에 대해 점수화하고 확률과 함께 선택된 옵션을 반환합니다 — 일반적으로 에이전트 토큰을 소모하지 않고 따뜻한(warm) 상태에서 40–150ms가 걸립니다.

효율적인 사용 방법: 항상 none 또는 "판단 불가(cannot be determined)" 옵션을 포함해야 합니다. state는 관련 발췌 내용으로 유지하는 것이 좋습니다 (유효 컨텍스트는 약 2k 토큰입니다). confidence < ~0.3인 경우 미결정 상태로 간주하고, 사실적 회상이나 높은 위험을 수반하는 결정의 유일한 확인 수단으로 사용하지 마십시오.

사전 질문 라우팅 (선택 사항): decision.routeBeforeAsking: true를 설정하면 주입된 에이전트 가이드가 사용자에게 질문하기 전에 make_decision을 통해 옵션 선택을 해결하도록 지시합니다. 이 경우, 모델이 확신하는 답변에 대해서는 바로 진행하고, 모델이 미결정 상태이거나 선택이 선호도 기반일 때만 질문하게 됩니다. 기본값은 비활성화(Off)입니다.

opencode-rag decide를 사용하면 CLI에서 동일한 엔진을 노출할 수 있으며, init은 전용 make-decision 에이전트 스킬을 생성합니다. 플러그인 문서와 구성(Configuration)를 참조하십시오.

이미지 인덱싱 (Image Indexing)

OpenCodeRAG는 이미지 파일(PNG, JPEG, WebP 등)을 비전 기능이 있는 LLM에 전송하고 생성된 텍스트 설명을 검색 가능한 벡터 청크로 저장함으로써 색인화할 수 있습니다. 이를 통해 시각적 자산을 자연어 질의("로그인 화면 스크린샷", "아키텍처 다이어그램" 등)를 통해 발견할 수 있게 됩니다.

지원되는 제공업체: Ollama, OpenAI, Anthropic, Google Gemini 및 OpenCode Zen (opencode/opencode-go)과 호환되는 제공업체입니다.

기본적으로 비활성화되어 있습니다. 사용하려면 opencode-rag.json에서 활성화하여 옵트인해야 합니다 (전용 GPU에 권장).

문서화 모드 (Documentation Mode)

documentationMode.enabled가 true일 때, OpenCode 플러그인은 /doc 슬래시 명령어를 노출하여 에이전트가 문서화되지 않은 소스 파일에 JSDoc/TSDoc 주석을 추가하도록 구동합니다. 이 모드에서는 어떠한 에이전트 도구도 등록되지 않으며, 모든 문서화는 오직 슬래시 명령어와 문서화 시스템 프롬프트를 통해서만 이루어집니다.

{
  "documentationMode": {
    "enabled": true,
...

워크플로우: /doc을 입력하여 하위 디렉터리별로 문서화되지 않은 모든 파일을 나열합니다. 에이전트는 하나의 하위 디렉터리를 선택하고, 공개된 모든 심볼(기존 주석 및 구현 코드는 유지)을 문서화한 다음, 해당 하위 디렉터리가 완료되었음을 표시하기 위해 /doc src/auth/를 입력합니다. 진행 상황은 .opencode/rag_db/doc-mode-progress.json에 저장되어 이후 세션에서 중단했던 지점부터 재개할 수 있습니다.

자세한 내용은 플러그인 문서를 참조하십시오.

Wiki 모드

wikiMode.enabled가 true일 때, OpenCode 플러그인은 에이전트에게 .opencode/wiki/에 영구적인 지식 위키를 구축하고 유지하도록 지시하는 위키 관리자 시스템 프롬프트를 주입합니다. 이 위키는 코드베이스, 문서, 대화에서 얻은 지식을 합성한 구조적이고 상호 연결된 마크다운 페이지 모음입니다.

{

OpenCodeRAG는 에이전트가 명확하지 않은 사실들—예: 함정(gotchas), 선호도, 결정 사항, 환경 제약 조건 등—을 시간 경과에 따라 기억하고 확장할 수 있도록 **지속적이고 세션 간의 메모리**를 제공합니다. 이러한 특이사항(quirks)은 코드와 동일한 벡터 저장소에 임베딩되어 저장된 후, 관련성 점수가 설정된 임계값을 초과할 때마다 사용자 메시지에 **자동으로 에이전트 컨텍스트에 주입됩니다**. 검색(Recall)은 원시 벡터 유사도(0-1, 코사인 유사도를 [0, 1]로 매핑): 수동 `recall_quirks` 호출의 경우 `recallMinScore`(기본값 0.72), 자동 주입의 경우 더 엄격한 `autoInjectMinScore`(기본값 0.75)에 의해 제어됩니다—관련 없는 작업에서 강하게 관련된 특이사항만 유지하려면 이 값을 높게 설정하세요(예: 0.85). 이를 통해 에이전트는 수동 검색 없이도 실수 반복을 피하고 세션 전반에 걸쳐 프로젝트 지식을 축적할 수 있습니다.

**기본적으로 활성화됩니다.** `opencode-rag.json`에서 켜거나 끌 수 있습니다:

```json
{
  "memory": {
    "enabled": true,
...

에이전트 도구:

opencode-rag quirk add "npm needs --legacy-peer-deps" --type gotcha --tag installation
pencode-rag quirk list
pencode-rag quirk update <id> --content "..." --type decision
...

When `memory.autoInject`가 `true`인 경우, 플러그인은 결합된 에이전트 응답 + 사용자 질의를 검색 쿼리로 사용하여 모든 사용자 메시지에서 관련한 특이점(quirks)을 확인합니다. 특이점은 해당 쿼리에 대한 원시 벡터 유사도가 `autoInjectMinScore`(기본값 0.75)를 초과할 때만 주입됩니다. 이 점수는 사용자 메시지와 시스템 프롬프트 주입에 사용되는 임계값과 동일하며, 수동 `recall_quirks` 호출의 기준은 `recallMinScore`(기본값 0.72)입니다. 지연 시간 예산(`autoInjectLatencyBudgetMs`, 기본값 2000ms)은 느린 임베더가 메시지 처리를 차단하는 것을 방지합니다. 컨텍스트 창 오염을 피하기 위해, 각 특이점은 **세션당 최대 한 번**만 주입됩니다. 한번 회수되면 이후의 모든 자동 주입에서 필터링됩니다. 모든 `add_quirk` 및 콘텐츠를 변경하는 `update_quirk`는 불변 신뢰 모니터(immutable trust monitor)에 의해 검증되며, 파괴적인 패턴(예: `rm -rf`, `force push`, `bypass security`)은 거부됩니다. 오래되었거나 수정된 특이점은 새로운 메모와 모순되도록 방치하기보다는 `update_quirk` / `delete_quirk`로 수정해야 합니다. [플러그인 문서](doc/plugin.md#9-quirk-memory-experiential-memory) 및 [CLI 참조: `quirk`](doc/cli.md#quirk)를 참조하십시오.

## MCP 서버 (선택 사항)

OpenCodeRAG는 모든 MCP 호환 클라이언트(Claude Desktop, Cursor 등)에 의미론적 코드 도구를 노출하는 CLI 기반 [MCP (Model Context Protocol)](https://spec.modelcontextprotocol.io/) 서버를 제공합니다.

```bash
opencode-rag mcp

참고: MCP 서버는 선택 사항입니다. OpenCode 플러그인으로 실행될 때는 도구가 **프로세스 내(in-process)**에 등록되며 MCP 서버 없이 작동합니다. 단축키 주입을 위한 chat.message 훅도 프로세스 내에서 실행됩니다. MCP 서버가 필요한 경우는 외부 MCP 클라이언트가 OpenCodeRAG에 연결할 때뿐입니다. 플러그인은 설정(mcp.enabled)이 true인 경우에만 서버를 자동 시작합니다(기본값: false).

MCP 도구

에이전트 디스커버리 (Agent Discovery)

OpenCodeRAG는 에이전트가 직접 호출할 수 있는 도구들을 등록합니다. 에이전트는 OpenCode **스킬 시스템(skill system)**을 통해 이러한 도구들을 발견합니다. opencode-rag init은 .opencode/skills/opencode-rag/SKILL.md(워크플로우 가이드)와 .opencode/skills/make-decision/SKILL.md(의사결정 모델 가이드)를 생성합니다:

1. 스켈레톤 먼저 (Skeleton first) - get_file_skeleton(filePath): 파일 내에서 방향을 잡을 때
2. 사용처 찾기 (Find usages) - find_usages(symbolName): 어떤 심볼이든 편집하기 전에
3. 검색 (Search) - search_semantic(query): 관련 코드를 찾을 때
4. 이미지 설명 (Describe images) - describe_image(filePath): 컨텍스트에 이미지가 포함될 때
5. 결정 (Decide) - make_decision(state, questions): 작업이 선택, 참/거짓 확인 또는 짧은 텍스트에 대한 루브릭 점수로 줄어들 때 (decision.enabled 상태일 때; decision.routeBeforeAsking을 사용하면 에이전트가 질문하기 전에 이러한 선택들을 해결합니다)
6. 읽기 (Read) - 특정 라인 범위에 대해 read를 사용
7. 편집 (Edit) - 전체 컨텍스트로 변경 사항 적용

사용 가능한 도구 (Available Tools)