Codewhale

터미널에서 어떤 모델과도 작동하는 오픈소스 코딩 에이전트입니다.

Codewhale에 작업을 주면 저장소를 읽고, 파일을 편집하고, 명령을 실행하며 작업이 완료되거나 여러분의 입력이 필요할 때까지 진행합니다. 40개 이상의 내장 프로바이더와 함께 작동하며, 기본값은 DeepSeek V4.1 Flash이고, 여러분의 머신에서 실행되는 모델과도 함께 작동합니다. /receipts는 변경한 파일, 실행한 명령, 그리고 수행한 웹 및 MCP 호출을 나열합니다.

Website · Documentation · Changelog · Contributing

简体中文 · 日本語 · Tiếng Việt · Bahasa Indonesia · 한국어 · Español · Português · Русский · Українська · Français · Deutsch · 繁體中文 · हिन्दी · Türkçe · Italiano · Polski · العربية · Català

스크립트로 작성된 테스트 모델을 사용한 0.10.2 개발 빌드로, 일회용 워크스페이스 안에서 Full Access로 실행한 모습입니다. 편집, 세 개의 테스트, 그리고 서브 에이전트 리뷰가 실제로 실행되었습니다.

Codewhale × OrcaRouter 혜택 보기 . Codewhale은 OrcaRouter로부터 추천 수수료를 받습니다.

설치
macOS 및 Linux:

curl -fsSL https://codewhale.net/install.sh | sh
설치 프로그램은 체크섬으로 검증된 codewhale과 그 짧은 별칭 codew를 ~/.local/bin 에 넣습니다. 그 후 셸에서 command not found 가 나오면, 설치 프로그램이 출력하는 PATH 줄을 실행하세요 ( 자세히 ). codewhale update 로 업그레이드합니다. 이 명령들은 최신 릴리스를 설치합니다. 이 페이지는 main 을 따르므로, 버전 표시가 있는 기능은 해당 릴리스에서 제공됩니다. 각 릴리스가 추가하는 내용은 변경 로그에 나열되어 있습니다.

Windows, npm, Cargo 및 기타 설치 방법
winget install HunterBown.CodeWhale # Windows x64 (또는 Scoop, 또는 GitHub Releases의 설치 프로그램)
npm install -g codewhale # 동일한 릴리스 바이너리를 감쌉니다
cargo install codewhale-cli --locked # crates.io; GitHub Releases보다 늦을 수 있음
사전 빌드된 바이너리는 x64 및 arm64의 Linux, macOS, Windows를 지원합니다. Nix, Linux의 Homebrew, Android/Termux(프리뷰), 수동 다운로드는 설치 가이드 에 있고, 컨테이너는 Docker 에 있습니다. 머신당 하나의 설치 방법만 사용하세요. 그렇지 않으면 PATH에 두 개의 복사본이 생기고 먼저 오는 쪽이 이깁니다.

빠른 시작

작업을 커밋하거나 스태시한 다음, git 저장소의 루트에서 codewhale을 실행하세요. 기본적으로 파일 편집을 묻지 않고 적용하며 diff를 보여줍니다.
/provider 를 실행하거나(또는 F3 누르기) 프로바이더를 선택하고, API 키를 붙여넣고, 모델을 선택하세요. DeepSeek이 기본 프로바이더입니다. 키가 없으면 대신 로컬 런타임을 선택하세요. 프로바이더가 구성되지 않았고 Ollama가 이미 채팅 모델을 서빙하고 있다면, Codewhale은 이를 자동으로 사용합니다. 0.10.2부터는 첫 메시지를 보낼 때 이를 제안합니다.
작업을 입력하세요:

Fix the failing tests and explain what changed.

읽기 전용 명령은 즉시 실행됩니다. 다른 셸 명령의 경우 Codewhale이 먼저 묻습니다: y는 한 번 실행, a는 대화가 끝날 때까지 비슷한 명령을 허용, n은 거부합니다. /undo 는 마지막 요청과 그 파일 변경을 되돌립니다. /help 는 명령과 키를 나열합니다.

스크립트와 CI의 경우, codewhale exec 는 인터페이스 없이 하나의 작업을 실행합니다. 기본적으로 --auto 는 Full Access를 사용합니다: 도구는 묻지 않고 실행되고, 셸 명령에는 Codewhale 샌드박스가 없으며, 신뢰 모드에서는 파일 도구가 워크스페이스 밖에 쓸 수 있습니다. 셸 샌드박스와 파일 도구 워크스페이스 제한을 유지하고 신뢰 모드를 끄려면 --sandbox workspace-write 를 추가하세요:

codewhale exec --auto --sandbox workspace-write " fix the failing tests and explain what changed "
모드와 권한
새로 설치하면 Work 모드와 Ask 권한으로 시작합니다.

전환
옵션

모드
Tab (입력이 비어 있을 때) 또는 /mode
Plan은 읽고 검색하지만 아무것도 변경하지 않습니다. Work는 파일을 편집하고 명령을 실행합니다. Operate는 Work와 동일한 접근 권한을 가지며, 요청을 목표로 취급하고 목표가 검증되거나 여러분의 입력이 필요할 때까지 계속 진행합니다.

권한
Shift+Tab
Ask는 저장소의 파일 편집을 묻지 않고 적용하며, 읽기 전용이 아닌 셸 명령 전에 묻습니다. Auto-Review는 규칙과 리뷰어 모델이 일상적인 호출을 승인하고 고위험 호출은 거부합니다. 직접 승인하려면 Ask로 전환하세요. Full Access는 절대 묻지 않고 Codewhale의 샌드박스를 끕니다. 저장소 규칙과 관리 정책은 여전히 적용됩니다.

자세한 내용은 모드와 권한 가이드를 참조하세요.

기능
0.10.2의 새로운 기능

/pet on 은 터미널을 에이전트가 무엇을 하는지 보여주는 애니메이션 고래로 바꾸며, 메시지 상자는 계속 활성 상태로 유지됩니다. 980개의 입자가 현재 단계를 영어, 중국어 또는 일본어로 표시합니다.
/workbar terminal 은 에이전트가 실행 중인 셸을 실행되는 대로 보여줍니다. 그중 하나에 입력하거나, Ctrl+N을 눌러 자신만의 셸을 여세요(macOS 및 Linux).
/undo 는 변경한 모든 파일을 포함하여 마지막 요청 전체를 한 단계로 되돌리며, /diff 는 Git이 없는 폴더에서도 작동합니다.
계획이 준비되면 Codewhale은 Work를 Ask 또는 Auto-Review로 시작할지, 아니면 계속 계획할지 묻습니다.
/color 는 각 채팅에 고유한 컴포저 색상을 부여하며, 세션과 함께 저장됩니다.
web_search 는 DeepSeek의 새로운 Search API를 사용할 수 있습니다: DeepSeek 키와 함께 [search] provider = "deepseek" 를 설정하세요.
Full Access 외부에서는 자격 증명을 업로드하려는 curl 또는 wget이 승인 없이 실행되지 않으며, 보이지 않는 유니코드를 숨기는 명령은 거부됩니다. write 는 더 이상 에이전트가 읽지 않은 파일이나, 읽은 후 변경된 파일을 대체하지 않습니다.

모델
Anthropic, OpenAI, DeepSeek, Google, Mistral, Moonshot, OpenRouter, xAI를 포함하여 40개 이상의 프로바이더가 내장되어 있습니다. 모든 OpenAI 호환 엔드포인트가 작동하며, Ollama, vLLM, SGLang을 통한 로컬 모델도 마찬가지입니다. 기본값은 DeepSeek의 deepseek-flash 이며, DeepSeek은 2026-10-17에 이를 DeepSeek-V4.1-Flash-1017로 옮겼습니다. 0.10.1은 업데이트 없이 이를 실행합니다 ( 자세히 ).

/model 은 턴 사이에 모델을 전환하고, /model auto 는 각 턴마다 모델을 선택합니다( /router 가 방법을 설정). /turn inspect 는 한 턴이 어떤 모델을 사용했는지, 비용은 얼마였는지, 얼마나 걸렸는지 보여줍니다. codewhale auth chatgpt 를 사용하면 API 키 대신 ChatGPT 플랜을 사용할 수 있습니다(실험적). Providers 를 참조하세요.

영수증과 되돌리기
/receipts , 또는 종료 후 codewhale receipts --last 는 변경된 파일, 실행된 명령, 웹 및 MCP 호출, 시작된 에이전트, 승인 및 승인한 사람, 실패를 나열합니다. /undo 는 마지막 요청과 그 변경된 파일을 한 단계로, 신뢰 모드 없이 되돌립니다. /restore 는 전체 워크스페이스를 이전 스냅샷으로 롤백합니다. 이는 이후 편집을 덮어쓰므로 /trust on 또는 Full Access가 필요합니다. Receipts 를 참조하세요.

도구를 제공하는 Exec 실행은 모든 출력 형식으로 저장되므로, codewhale receipts --last 는 --json 을 포함한 exec --auto 이후에도 작동합니다. 답변 전용 텍스트와 --json 실행은 재개할 때 또는 대화 압축이 시작될 때만 저장됩니다. 영수증이나 exec --continue 를 위해 항상 저장하려면 --output-format stream-json 을 사용하세요.

더 긴 작업
/goal 은 턴에 걸쳐 이어지는 목표를 설정합니다. Codewhale은 작업을 서브 에이전트 로 나누거나, 에이전트 플릿을 실행하거나, 저장소에 체크인된 워크플로를 따를 수 있습니다.

다른 에이전트에서 오는 경우
Codewhale은 AGENTS.md 를 스스로 읽습니다. CLAUDE.md , .cursorrules , 또는 .github/copilot-instructions.md 와 같이 다른 도구용으로 작성된 지시 파일은 구성에서 project_instruction_imports = ["claude"] (또는 "cursor" , "cline" , "windsurf" , "copilot" , "all" )로 옵트인할 때만 로드됩니다. config.example.toml 을 참조하세요. Codewhale은 로드하지 않은 파일을 발견하면 경고합니다.

/import-claude 는 검토할 수 있도록 Claude Code 설정과 MCP 서버의 가져오기를 준비합니다. /plugin install 은 스킬, 명령, 에이전트 프로필, MCP 서버를 포함하는 Claude Code 플러그인을 허용하며, 훅이나 LSP 서버가 필요한 플러그인은 거부합니다 ( 자세히 ).

확장
MCP 서버 를 연결하고, 스킬 과 플러그인 을 추가하고, 세션 및 도구 이벤트에 훅을 실행하세요. 코드 모드(실험적, 기본 활성화)는 모델이 여러 MCP 및 플러그인 도구를 호출하는 하나의 execute_tools 프로그램을 작성하게 합니다. 각 호출은 여전히 여러분의 승인 규칙을 충족하고 영수증을 유지합니다. 독립적으로 설치되는 Computer Use 플러그인(실험적, macOS 전용)은 다른 앱을 관찰하고 조작할 수 있습니다. 접근 권한을 검토하고 활성화할 때까지 꺼져 있습니다 ( 가이드 ).

실행 방법

명령
기능

codewhale
대화형 터미널 앱

codewhale exec "…"
인터페이스 없이 하나의 작업. 단독으로는 도구를 사용하지 않고 답변합니다. --auto 는 기본적으로 Full Access로 도구를 활성화하고, --sandbox workspace-write 는 이를 제한하며, --output-format stream-json 은 이벤트를 JSON으로 스트리밍합니다

codewhale web
127.0.0.1 의 로컬 웹 UI ( 가이드 )

codewhale review --pr N
GitHub 풀 리퀘스트에 대한 권고 리뷰. GitHub 봇 설정은 자체 모델 키와 선택적 App 아이덴티티를 사용하여 자동 리뷰와 @codewhale review 를 위한 고정된 워크플로를 생성합니다

codewhale app-server --http
Runtime API , 스레드, 이벤트, 승인, 각 턴의 파일 변경을 위한 로컬 HTTP API

codewhale serve --acp
Zed와 같은 편집기를 위한 stdio 기반 Agent Client Protocol

터미널 앱, exec , web , 그리고 Runtime API는 하나의 엔진을 공유합니다 ( 아키텍처 ). 커뮤니티가 유지 관리하는 VS Code 확장 은 사이드바에서 여기에 연결됩니다 ( 소스 ). Runtime API를 기반으로 한 네이티브 데스크톱 앱이 개발 중이며, 아직 공개 다운로드는 없습니다.

비용과 계정
Codewhale은 무료이며 MIT 라이선스입니다. 자체 API 키를 사용하면 프로바이더에 직접 비용을 지불하며, 로컬 모델은 키가 필요 없습니다. 푸터와 /cost 는 가격을 알 수 있을 때 세션 비용을 보여주며, 알 수 없는 가격은 무료가 아니라 알 수 없음으로 표시됩니다.

계정이 필요하지 않습니다. /provider 로 추가한 키는 여러분의 머신에 남습니다.

안전과 개인정보
Ask 및 Auto-Review에서 명령은 시스템에 샌드박스가 있는 경우 OS 샌드박스에서 실행됩니다: macOS에서는 Seatbelt, Linux에서는 bubblewrap이 설치되어 있을 때 사용됩니다. Windows에는 아직 OS 샌드박스가 없으며, Full Access는 샌드박스를 끕니다. 샌드박스 내부에서 셸 명령은 ~/.ssh , ~/.aws 및 .env 파일과 같은 자격 증명 저장소를 읽을 수 없습니다. 0.10.2부터 동일한 규칙이 터미널 세션과 더 많은 파일 도구에 적용됩니다. /preview-request 는 보내지 않고 다음 요청의 마스킹된 미리보기를 보여줍니다.

텔레메트리는 기본적으로 켜져 있습니다. 집계 카운트(버전 및 플랫폼, 세션 길이 및 결과, 사용한 내장 프로바이더, 기능 및 오류 카운트)를 90일마다 교체되는 무작위 설치 ID와 함께 전송하며, 대화, 코드, 프롬프트, 모델 이름, 파일 또는 저장소 이름, 자격 증명은 절대 전송하지 않습니다. codewhale config set telemetry false 로 끕니다. 시작 시 Codewhale은 또한 새 릴리스를 위해 GitHub를 확인합니다. 이를 건너뛰려면 CODEWHALE_NO_UPDATE_CHECK=1 을 설정하세요. 자세한 내용은 승인 순서 , 샌드박싱 , 텔레메트리 에 있습니다.

문서

여기서 시작
레퍼런스

설치
구성

프로바이더 및 로컬 모델
아키텍처

모드와 권한
Runtime API

키 바인딩
플러그인 작성

GitHub PR 리뷰
모든 문서

커뮤니티
프로바이더가 없거나 워크플로가 어색하다면, 이슈를 열거나 풀 리퀘스트를 보내주세요. 기여자는 반영된 작업에 대한 공로를 유지하며, 저장소 레이아웃 은 무엇이 어디에 있는지 보여줍니다.

Discord 에서 채팅하거나, 메인테이너 Hunter를 WeChat( hunterbown )에 추가하고 Whale Brothers 그룹 참여를 요청하세요.

역사와 라이선스
Codewhale은 deepseek-tui로 시작했으며 여전히 해당 프로젝트의 구성과 세션을 읽습니다. 독립적으로 유지 관리되며 DeepSeek이나 다른 모델 프로바이더와 제휴하지 않습니다. 기여해 주신 모든 분들께 감사드립니다.

MIT . 다른 오픈소스 프로젝트에서 각색한 코드는 서드파티 고지 에 나열되어 있습니다.