Korsur CLI

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

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

특징

• 🇰🇷 국산 LLM: Upstage solar-pro4(최신 플래그십) 기본 탑재 · Solar/solar-code 전용 인트로그래픽
• 🛠 18종 에이전트 도구: 파일 읽기/쓰기/편집, glob·grep 코드 탐색, multi_edit 원자적 일괄 편집, 셸 실행, 백그라운드 실행(개발 서버), 웹 검색을 스스로 연쇄 호출
• ☑ 할 일 목록(todo): 여러 단계 작업은 모델이 먼저 계획을 등록하고, 단계마다 갱신 — 진행 상황이 화면에 그려진다
• 🕵 서브에이전트(spawn_agent): 넓은 코드베이스 조사는 읽기 전용 하위 에이전트에 맡기고 결론만 받는다 (컨텍스트 절약)
• ✅ 쓰기 즉시 문법 검사: .js·.py·.json을 저장하면 바로 문법을 확인해 오류를 모델에 돌려준다 — 스스로 고친다
• 🧩 관대한 편집: 들여쓰기가 어긋난 old_string도 자동 보정, 여러 곳이 일치하면 안전하게 거부
• 🔍 실시간 웹 검색 RAG: web_search로 최신 정보를 검색 → web_fetch로 근거를 읽어 출처와 함께 종합 (키 불필요)
• ⚡ 라이브 스트리밍 + 구문 강조: 모델이 쓰는 답변을 실시간 포맷 출력, 코드블록은 언어별로 색을 입힌다
• 🚄 병렬 도구 실행: 한 턴의 여러 읽기 전용 도구(파일·검색)를 동시 실행 — 대기시간 단축
• 📊 컨텍스트 게이지: 프롬프트 줄에 사용량을 상시 표시, 85%를 넘으면 /compact를 권한다
• ⛔ esc 중단: 실행 중 아무 때나 esc — 진행한 작업은 그대로 남는다
• 🔌 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 불필요)

스킬 — 재사용 지침 패키지

SKILL.md 한 장에 "이 상황에서는 이렇게 한다"를 적어 두면, 모델이 작업에 맞춰 스스로 불러옵니다 (use_skill 도구). Claude Code의 .claude/skills와 호환됩니다.

내장 스킬: test(테스트 실행·수정) · debug(원인 추적) · refactor(안전한 구조 개선) · plan(작업 쪼개기) · review(코드 리뷰) · commit(스마트 커밋) · explain · computer-use

/skills                 # 목록
/skill test 로그인 테스트  # 직접 실행
/skill new my-skill     # 새 스킬 만들기 (~/.korsur/skills/my-skill/SKILL.md)

프론트매터로 발동 조건을 선언합니다:

---
name: test
description: 테스트를 찾아 실행하고, 실패를 원인까지 파고들어 고친다
when: 테스트·test·pytest·jest·CI 실패를 다룰 때
allowed-tools: glob, grep, read_file, run_command, edit_file
---

탐색 경로(앞이 우선): ./.korsur/skills → ./.claude/skills → ~/.korsur/skills → 내장 → ~/.claude/skills

컴퓨터 유즈 (Solar CUA) — solar --computer-use

실제 Chrome 창을 열어 웹 작업을 대신 수행하는 에이전트입니다. 화면에는 "말하며 움직이는 가상 커서 + 하단 실시간 제어 채팅바"가 뜨고, 진행 중 언제든 채팅바에 지시를 입력해 방향을 바꿀 수 있습니다.

solar --computer-use                     # 대화형 (작업> 프롬프트)
solar --cu -p "네이버에서 오늘 날씨 알려줘"   # 원샷

• 시작 URL 지정: https://ko.wikipedia.org | 손흥민 생년월일 · 로그인 세션 재사용: @login ...
• 선행 설치(한 번): pip install -r computer-use/requirements.txt && python -m playwright install chromium (다른 파이썬은 KORSUR_PYTHON 환경변수로 지정). DOM 우선 엔진이라 대부분 스크린샷 없이 빠르게 동작.

설치 — 한 줄

npm install -g solar-code        # 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 입·출력에 개인정보·민감정보가 포함되지 않도록 주의하세요.