어떤 모델과도 함께 쓸 수 있는 터미널용 코딩 에이전트.
Codewhale에 작업을 맡기면 저장소를 읽고, 파일을 편집하고, 명령을 실행하면서
작업이 끝나거나 사용자의 입력이 필요할 때까지 진행합니다. 40개가 넘는 내장
제공업체(기본값은 DeepSeek)와 사용자의 컴퓨터에서 실행되는 모델을 쓸 수
있습니다. /receipts는 Codewhale이 변경한 파일, 실행한 명령, 수행한 웹 및
MCP 호출을 보여 줍니다.
English · 简体中文 · 日本語 · Tiếng Việt · Bahasa Indonesia · Español · Português · Русский · Українська · Français · Deutsch · 繁體中文 · हिन्दी · Türkçe · Italiano · Polski · العربية · Català
로컬 데모 세션에서 캡처한 화면입니다.
macOS와 Linux:
curl -fsSL https://codewhale.net/install.sh | sh설치 스크립트는 체크섬을 검증한 codewhale과 짧은 별칭 codew를
~/.local/bin에 설치합니다. 이후 셸에서 command not found가 나오면 설치
스크립트가 출력하는 PATH 설정 줄을 실행하세요
(자세히). 업그레이드는
codewhale update로 합니다.
Windows, npm, Cargo 등 다른 설치 방법
winget install HunterBown.CodeWhale # Windows x64 (or Scoop, or the installer from GitHub Releases)
npm install -g codewhale # wraps the same release binaries
cargo install codewhale-cli --locked # build from crates.io미리 빌드된 바이너리는 x64와 arm64의 Linux, macOS, Windows를 지원합니다. Nix,
Linux의 Homebrew, Android/Termux(프리뷰), 수동 다운로드는
설치 안내서에서, 컨테이너는 Docker에서
다룹니다. 한 컴퓨터에는 설치 방법을 하나만 쓰세요. 그렇지 않으면 PATH에
사본이 두 개 생기고, 먼저 오는 쪽이 실행됩니다.
- 작업 중인 변경을 커밋하거나 stash한 다음, git 저장소의 루트에서
codewhale을 실행합니다. 기본 설정에서는 그 저장소의 파일 편집을 묻지 않고 적용하고 diff를 보여 줍니다. /provider를 실행하거나F3을 눌러 제공업체를 고르고, API 키를 붙여 넣은 뒤 모델을 선택합니다. 기본 제공업체는 DeepSeek입니다. 키가 없으면 대신 로컬 런타임을 고르세요. 설정된 제공업체가 없고 Ollama가 이미 채팅 모델을 제공하고 있으면 Codewhale이 자동으로 그 모델을 사용합니다.- 작업을 입력합니다.
Fix the failing tests and explain what changed.
읽기 전용 명령은 바로 실행됩니다. 그 밖의 셸 명령은 Codewhale이 먼저 묻습니다.
y는 한 번만 실행하고, a는 남은 대화 동안 같은 종류의 명령을 허용하며,
n은 거부합니다. /undo는 마지막 요청과 그 요청의 파일 변경을 되돌립니다.
명령과 단축키 목록은 /help에서 볼 수 있습니다.
스크립트와 CI용으로는 인터페이스 없이 작업 하나를 실행하는 codewhale exec
명령이 있습니다. --auto를 주면 묻지 않고 파일을 편집하고 셸 명령을
실행하므로, 컨테이너나 버려도 되는 체크아웃에서 실행하세요.
codewhale exec --auto "fix the failing tests and explain what changed"새로 설치하면 실행 모드와 확인 권한으로 시작합니다.
| 전환 방법 | 옵션 | |
|---|---|---|
| 모드 | Tab(입력란이 비어 있을 때) 또는 /mode |
계획(Plan)은 읽고 검색하지만 아무것도 바꾸지 않습니다. 실행(Work)은 파일을 편집하고 명령을 실행합니다. 운영(Operate)은 실행과 같은 접근 권한을 가지며, 요청을 목표로 다루고 목표가 검증되거나 사용자의 입력이 필요할 때까지 계속 진행합니다. |
| 권한 | Shift+Tab |
확인(Ask)은 저장소 안의 파일 편집은 묻지 않고 적용하고, 읽기 전용이 아닌 셸 명령은 실행 전에 묻습니다. 자동 검토(Auto-Review)는 규칙과 리뷰어 모델이 일상적인 호출을 승인하게 하고 위험도가 높은 호출은 거부합니다. 그런 호출을 직접 승인하려면 확인으로 전환하세요. 전체 접근(Full Access)은 전혀 묻지 않으며 Codewhale의 샌드박스를 끕니다. 저장소 규칙과 관리 정책은 계속 적용됩니다. |
자세한 내용은 모드와 권한 안내서를 참고하세요.
Anthropic, OpenAI, DeepSeek, Google, Mistral, Moonshot, OpenRouter, xAI를
포함해 40개가 넘는 제공업체가 내장되어 있습니다. OpenAI 호환 엔드포인트라면
어느 것이든 쓸 수 있고, Ollama, vLLM, SGLang을 통한 로컬 모델도 쓸 수
있습니다. /model로 턴 사이에 모델을 바꿉니다. 제공업체를
참고하세요.
/receipts(종료한 뒤에는 codewhale receipts --last)는 변경된 파일, 실행된
명령, 웹 및 MCP 호출, 시작된 에이전트, 승인 내역과 승인한 주체, 실패를 보여
줍니다. /undo는 마지막 요청을 되돌립니다. /restore는 작업 공간 전체를 이전
스냅샷으로 되돌리는데, 이후의 편집을 덮어쓰기 때문에 /trust on 또는 전체
접근 권한이 필요합니다. 영수증을 참고하세요.
/goal은 여러 턴에 걸쳐 유지되는 목표를 정합니다. Codewhale은 작업을
하위 에이전트에 나눠 맡기거나, 여러 에이전트로 구성된
Fleet를 실행하거나, 저장소에 커밋된
워크플로를 따를 수 있습니다.
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 서버를 연결하고, 스킬과 플러그인을 추가하고, 세션 및 도구 이벤트에서 훅을 실행할 수 있습니다. 기본 포함된 Computer Use 플러그인(실험적, macOS 전용)은 다른 앱을 관찰하고 조작할 수 있습니다. 접근 범위를 검토하고 활성화하기 전까지는 꺼져 있습니다 (안내서).
| 명령 | 하는 일 |
|---|---|
codewhale |
대화형 터미널 앱 |
codewhale exec "…" |
인터페이스 없이 작업 하나를 실행합니다. 옵션 없이 쓰면 도구를 사용하지 않고 답변만 하고, --auto는 파일 편집과 명령 실행을 허용하며, --output-format stream-json은 이벤트를 JSON으로 스트리밍합니다 |
codewhale web |
127.0.0.1에서 동작하는 로컬 웹 UI(안내서) |
codewhale review --pr N |
GitHub 풀 리퀘스트에 대한 참고용 리뷰. --post를 추가하지 않으면 아무것도 게시하지 않으며, GitHub Action이 CI에서 같은 리뷰를 실행합니다 |
codewhale app-server --http |
스레드, 이벤트, 승인을 다루는 로컬 HTTP API인 Runtime API |
codewhale serve --acp |
Zed 같은 에디터를 위한 stdio 기반 Agent Client Protocol |
터미널 앱, exec, web, Runtime API는 하나의 엔진을 공유합니다
(아키텍처). 커뮤니티가 관리하는
VS Code 확장은
사이드바에서 이 엔진에 연결됩니다(소스).
데스크톱 앱은 개발 중입니다. 제품 페이지를
참고하세요.
Codewhale은 무료이며 MIT 라이선스로 배포됩니다. 자신의 API 키를 쓰면
제공업체에 직접 비용을 내고, 로컬 모델은 키가 필요 없습니다. 가격을 알 수
있으면 하단 표시줄과 /cost에 세션 비용이 표시되며, 가격을 알 수 없으면 무료가
아니라 알 수 없음으로 표시합니다.
계정은 없어도 됩니다. 계정이 있으면(codewhale login) 제공업체 키를
Codewhale 계정에 보관할 수 있고,
다른 기기에서는 로그인한 뒤 /provider에서 Codewhale을 선택해 그 키를 사용할
수 있습니다. 로그인해도 이미 컴퓨터에 있는 키는 업로드되지 않습니다.
확인과 자동 검토 권한에서는 시스템에 OS 샌드박스가 있으면 그 안에서 명령이
실행됩니다. macOS에서는 Seatbelt를, Linux에서는 bubblewrap이 설치되어 있으면
bubblewrap을 사용합니다. Windows에는 아직 OS 샌드박스가 없으며, 전체 접근은
샌드박스를 끕니다. /preview-request는 다음 요청을 보내지 않고, 민감 정보를
가린 미리 보기를 보여 줍니다.
텔레메트리는 기본으로 켜져 있습니다. 90일마다 바뀌는 무작위 설치 ID와 함께
집계된 수치(버전과 플랫폼, 세션 길이와 결과, 기능 및 오류 횟수)를 보내며,
대화, 코드, 프롬프트, 파일 또는 저장소 이름, 자격 증명은 절대 보내지 않습니다.
codewhale config set telemetry false로 끌 수 있습니다. Codewhale은 시작할 때
GitHub에서 새 릴리스도 확인합니다. 이 확인을 건너뛰려면
CODEWHALE_NO_UPDATE_CHECK=1을 설정하세요. 자세한 내용은
권한 확인 순서, 샌드박스,
텔레메트리를 참고하세요.
| 시작하기 | 참고 자료 |
|---|---|
| 설치 | 설정 |
| 제공업체와 로컬 모델 | 아키텍처 |
| 모드와 권한 | Runtime API |
| 단축키 | 플러그인 작성 |
| GitHub PR 리뷰 | 전체 문서 |
빠진 제공업체가 있거나 불편한 작업 흐름이 있으면 이슈를 열거나 풀 리퀘스트를 보내 주세요. 반영된 작업의 기여 이력은 기여자에게 남으며, 무엇이 어디에 있는지는 저장소 구조에서 볼 수 있습니다.
Discord에서 이야기하거나, WeChat에서 메인테이너
Hunter(hunterbown)를 추가하고 Whale Brothers 그룹 가입을 요청하세요.
Codewhale은 deepseek-tui에서 시작했으며 지금도 그 프로젝트의 설정과 세션을
읽습니다. 독립적으로 유지되며 DeepSeek를 비롯한 어떤 모델 제공업체와도 제휴
관계가 없습니다. 기여해 주신 모든 분께 감사드립니다.
