Korsur CLI

한국형 AI 코딩 에이전트 — 터미널에서 동작하는 대화형 코딩 어시스턴트입니다. Upstage Solar Open 2 (Solar Agent Partner 프로그램)를 기본 모델로 사용합니다.

Claude Code, Gemini CLI 같은 에이전틱 CLI 경험을 국산 LLM으로 제공하는 것이 목표입니다.

특징

• 🇰🇷 국산 LLM: Upstage solar-open2(reasoning 모델) 기본 탑재 · Solar/solar-code 전용 인트로그래픽
• 🛠 에이전트 도구 루프: 파일 읽기/쓰기/편집, 디렉토리 탐색·생성, 정규식 검색, 셸 실행을 스스로 연쇄 호출
• 🔍 실시간 웹 검색 RAG: web_search로 최신 정보를 검색 → web_fetch로 근거를 읽어 출처와 함께 종합 (키 불필요)
• ⚡ 라이브 스트리밍: 모델이 쓰는 답변을 실시간으로 줄단위 포맷 출력 (헤더·코드블록·불릿)
• 🚄 병렬 도구 실행: 한 턴의 여러 읽기 전용 도구(파일·검색)를 동시 실행 — 대기시간 단축
• 🔌 MCP 자동 연결: GitHub·Slack·DB 등 MCP 서버를 등록하면 시작 시 자동 연결, 도구가 모델에 노출
• 🧠 reasoning 제어: /think로 사고 과정 실시간 표시, /boost로 더 깊은 추론(16K 토큰)
• 🎯 장기 실행: /goal·/loop로 완료 선언까지 자동 라운드 연장 (되묻지 않고 끝까지 완수)
• 📂 프로젝트 지침 자동 로드: SOLAR.md(또는 CLAUDE.md·AGENTS.md 호환)를 시스템 프롬프트에 주입
• 💾 세션 이어하기: 매 턴 자동 저장, --resume//resume, /save 이름으로 보관
• 🔒 안전 확인: 위험 도구는 실행 전 y/N 확인 (--yolo/shift+tab로 auto mode)
• 📦 의존성 제로: Node.js 18+ 만 있으면 동작 (npm install 불필요)

설치 — 한 줄

npm install -g korsur-cli        # npm 배포 후

지금(저장소에서 직접):

npm install -g ./cli             # 저장소 루트에서

설치하면 터미널 어디서든 한 단어로 바로 실행됩니다:

solar        # ✦ Solar 에이전트 시작
solar-code   # 코드 전용 인트로그래픽 버전
upstage      # 동일
korsur       # 동일

API 키 설정

Upstage Console에서 API 키를 발급받은 뒤, 둘 중 하나로 설정합니다.

# 방법 1: 환경변수
set UPSTAGE_API_KEY=up_xxxx        # Windows cmd
$env:UPSTAGE_API_KEY="up_xxxx"     # PowerShell

# 방법 2: 대화형 세션에서
korsur
/key up_xxxx                       # ~/.korsur/config.json에 저장

사용법

korsur                          # 대화형 세션
korsur -p "이 폴더 구조 설명해줘"  # 원샷 모드
korsur --resume                 # 직전 세션 이어하기
korsur --yolo                   # 도구 실행 확인 생략
korsur --model solar-pro3       # 다른 Solar 모델 사용
korsur --no-mcp                 # MCP 연결 없이 시작

외부 플랫폼 연결 (MCP)

Claude Code처럼 MCP 서버를 등록하면 시작할 때 자동 연결됩니다.

korsur mcp add github -- npx -y @modelcontextprotocol/server-github
korsur mcp add fs -- npx -y @modelcontextprotocol/server-filesystem C:\projects
korsur mcp list
korsur mcp remove github

연결된 서버의 도구는 mcp__서버__도구 이름으로 모델에 노출되고, 세션 안에서 /mcp(연결 상태), /tools(전체 도구 목록)로 확인할 수 있습니다. 설정 파일: ~/.korsur/mcp.json

세션 명령어

| 명령 | 설명 | |------|------| | /help | 도움말 | | /key <키> | API 키 저장 | | /model [이름] | 모델 확인/변경 | | /mcp | 외부 플랫폼(MCP) 연결 상태 | | /tools | 사용 가능한 도구 목록 (내장 + MCP) | | /save [이름] | 현재 대화 보관 | | /resume | 직전 세션 이어하기 | | /clear | 대화 이력 초기화 | | /yolo | 위험 도구 자동 승인 토글 (Shift+Tab과 동일) | | /goal <작업> | 장기 실행 — 완료 선언(KORSUR-COMPLETE)까지 자동으로 라운드 연장 | | /loop <N> <작업> | 장기 실행 — 최대 라운드 수 지정 | | /skills · /skill <이름> | 스킬 목록 / 실행 (.claude/skills 호환) | | /init [global] | SOLAR.md 지침 생성 (프로젝트 / 전역) | | /chat-ui | 채팅 말풍선 UI (터미널 초심자용) | | /buddy | Solar 펫 가챠 | | /exit | 종료 |

한글 별칭도 됩니다: /사용량→/cost, /상태→/status, /모델→/model, /스킬→/skill 등.

SOLAR.md — 프로젝트 지침 (CLAUDE.md 계열)

SOLAR.md를 두면 매 작업의 시스템 프롬프트에 자동 주입됩니다.

• 프로젝트별: ./SOLAR.md (/init으로 생성) — KORSUR.md·CLAUDE.md·AGENTS.md도 호환
• 전역: ~/.korsur/SOLAR.md (/init global) — 모든 프로젝트에 공통 적용

원샷 장기 실행: solar --goal -p "작업". 확인 프롬프트가 떠 있을 때 Shift+Tab을 누르면 즉시 승인 + auto mode 전환 (Claude Code 방식).

에이전트 도구

모델이 필요에 따라 자동으로 호출합니다.

| 도구 | 기능 | 확인 필요 | |------|------|:---:| | read_file | 파일 읽기 (줄번호 포함) | — | | create_dir | 디렉토리 생성 (중간 경로 포함) | — | | list_dir | 디렉토리 나열 | — | | search_files | 정규식 파일 내용 검색 | — | | web_fetch | 웹 문서 조회 (API 문서 등) | — | | write_file | 파일 생성/덮어쓰기 | ✅ | | edit_file | 문자열 정밀 교체 | ✅ | | run_command | 셸 명령 실행 | ✅ | | mcp__*__* | 외부 MCP 서버 도구 | ✅ |

Rate Limit

Solar Agent Partner Stage 1 기준 400 RPM / 150,000 TPM. 429 응답 시 지수 백오프로 최대 3회 자동 재시도합니다.

주의

• Partner 프로그램 API 키는 승인된 용도로만 사용하고 제3자와 공유하지 마세요.
• API 입·출력에 개인정보·민감정보가 포함되지 않도록 주의하세요.