Hmbown/CodeWhale

CodeWhale

모든 모델을 위한 터미널 코딩 에이전트 — 오픈 모델 우선.

CodeWhale은 터미널 코딩 에이전트입니다 — TUI와 CLI를 제공합니다. 모델과 프로젝트를 지정하면 코드 읽기, 편집, 명령 실행, 결과 확인, 다단계 작업 계획, 실패 시 자체 수정 등의 작업을 수행합니다.

오픈 소스(MIT, Rust)이며, 사용자 머신에서 실행되며, 사람들이 실제로 사용하는 모델과 함께 작동합니다. DeepSeek과 오픈 가중치 모델이 일급으로 지원되며, LAN의 로컬 vLLM/SGLang/Ollama 박스는 키가 전혀 필요하지 않습니다. 하지만 Claude, GPT, Kimi, GLM도 동일한 런타임과 동일한 도구를 통해 완전히 동등하게 사용할 수 있습니다. 제공자와 모델을 선택하면 CodeWhale이 실제 경로를 확인하고 실행합니다.

이 프로젝트는 DeepSeek 워크플로를 위해 구축된 코딩 도구 모음인 deepseek-tui로 시작되었습니다. 개발자 커뮤니티(대부분 중국)가 이를 채택하고, 보고서를 제출하고, 수정 사항을 기여하면서 이 도구 모음이 하나의 모델보다 더 크다는 것이 분명해졌습니다. 이후 다중 제공자 지원이 추가되었고, 프로젝트는 이에 맞춰 CodeWhale로 이름이 변경되었습니다. 원하는 모델, 엔드포인트 또는 기능이 보이지 않으면 이슈를 열어주세요. 그것이 프로젝트가 성장하는 방식입니다.

简体中文 README · 日本語 README · Tiếng Việt README · 한국어 README · codewhale.net · 설치 가이드 · 제공자 레지스트리 · 변경 로그

설치

npm install -g codewhale
codewhale --version   # 0.8.65

npm 래퍼(Node 18+)는 GitHub Releases에서 SHA-256 검증된 바이너리를 다운로드하여 codewhale, codew, codewhale-tui를 설치합니다. 소스에서 빌드하는 것을 선호하시나요? cargo(Rust 1.88+)를 사용하세요:

cargo install codewhale-cli --locked
cargo install codewhale-tui --locked

Linux 사용자: 먼저 시스템 빌드 종속성을 설치하세요:

sudo apt-get install -y build-essential pkg-config libdbus-1-dev.

INSTALL.md를 참조하세요.

다른 모든 방법:

# Docker
docker pull ghcr.io/hmbown/codewhale:latest

# Nix
nix run github:Hmbown/CodeWhale

# Windows
scoop install codewhale        # 또는 GitHub Releases의 NSIS 설치 프로그램

# GitHub에 안정적으로 접근할 수 없는 사용자를 위한 CNB 미러
cargo install --git https://cnb.cool/codewhale.net/codewhale --tag v0.8.65 codewhale-cli --locked --force
cargo install --git https://cnb.cool/codewhale.net/codewhale --tag v0.8.65 codewhale-tui --locked --force

# 레거시 Homebrew 호환성 (포뮬러 이름이 변경되는 동안)
brew tap Hmbown/deepseek-tui
brew install deepseek-tui

Linux riscv64를 포함한 모든 플랫폼용 사전 빌드 아카이브는 GitHub Releases에 첨부되어 있습니다. 체크섬, 중국 미러, Windows 세부 사항 및 문제 해결은 docs/INSTALL.md에 있습니다.

레거시 deepseek-tui 패키지에서 업그레이드하시나요? 설정, 세션, 스킬 및 MCP 설정이 보존됩니다. docs/REBRAND.md를 참조한 후 codewhale doctor를 실행하여 확인하세요.

첫 실행

codewhale auth set --provider deepseek
codewhale auth status
codewhale doctor
codewhale

모든 제공자는 동일한 한 줄 형태입니다: --provider openrouter, --provider moonshot, --provider openmodel, 또는 vllm, sglang, ollama를 자신의 localhost 런타임에 키 없이 지정합니다. 대신 Claude 키가 있나요? codewhale auth set --provider anthropic을 실행하거나 ANTHROPICAPIKEY를 내보내면 네이티브 Messages 어댑터가 처리합니다.

키는 ~/.codewhale/config.toml에 저장됩니다. 레거시 ~/.deepseek/ 설정은 호환성을 위해 계속 읽힙니다.

세션 내 유용한 명령어:

• /provider는 준비 상태 대시보드를 엽니다 — 제공자별로 인증 상태, 확인된 기본 경로, 비용/사용량 측정기를 보여줍니다. /model은 모델과 추론 노력을 선택합니다. 둘 다 인수를 받아(/provider nvidia-nim, /model auto) 세션 중간에 전환할 수 있습니다.
• /restore는 사이드-git 스냅샷에서 이전 턴을 롤백합니다.
• /fleet는 Fleet 설정 뷰를 엽니다 — 역할, 프로필, 로드아웃 및 정책.
• /skills는 ~/.codewhale/skills/에서 재사용 가능한 워크플로를 로드합니다.
• /config는 런타임 설정을 편집합니다. /statusline은 어떤 푸터 칩이 경로, 비용 및 세션 상태를 표시할지 선택합니다.
• ! cargo test -p codewhale-tui는 일반 승인 및 샌드박스 경로를 통해 모든 셸 명령을 실행합니다.

스크립트 및 CI를 위한 헤드리스 모드:

codewhale exec --allowed-tools read_file,exec_shell --max-turns 10 "fix the failing test"

제공자 및 라우팅

제공자와 모델을 선택하면 CodeWhale이 실제 경로를 확인합니다 — 구체적인 엔드포인트, 와이어 프로토콜, 모델 ID, 컨텍스트 제한 및 가격 — 단순히 기본 URL을 바꾸는 것이 아닙니다. RouteResolver만이 확인된 경로를 생성할 수 있으므로, 동일한 선택 로직이 TUI 선택기, CLI 및 헤드리스 실행을 뒷받침합니다. 그 뒤에 있는 카탈로그는 Models.dev 형태의 커밋된 네트워크 프리 스냅샷이며, 제공자의 라이브 /models 엔드포인트에서 선택적으로 새로 고칠 수 있습니다.

경로가 확인되므로 나머지 도구 모음은 이에 대해 정직할 수 있습니다:

• 경로 인식 컨텍스트 예산. 압축 임계값과 사용 가능한 창은 하드코딩된 추측이 아닌 확인된 경로의 실제 컨텍스트 제한에서 비롯됩니다.
• 정직한 비용 표시. 경로는 정확히 하나의 비용 상태를 보고합니다: 토큰당 가격, 구독/할당량 측정기, 계정 크레딧, 로컬 / 해당 없음, 또는 알 수 없음 / 오래됨. CodeWhale은 가지고 있지 않은 가격을 절대 만들어내지 않습니다 — 일치하는 모델이 없으면 $0 대신 알 수 없음으로 표시됩니다.
• 명시적 와이어 프로토콜. 경로가 Chat Completions, OpenAI Responses API 또는 네이티브 Anthropic Messages를 사용하는지 여부는 프롬프트에서 추론되지 않고 확인된 경로에 전달됩니다. 추론 노력은 각 제공자의 고유한 방식으로 변환됩니다.

/provider와 /model로 세션 중간에 경로를 전환하세요. 전체 레지스트리(자격 증명, 기본 URL, 기능 경계)는 docs/PROVIDERS.md에 있습니다.

지원되는 제공자

모든 제공자는 동일한 런타임과 동일한 도구를 통해 라우팅됩니다. 원하는 제공자가 여기에 없으면 이슈를 열어주세요.

• 호스팅된 오픈 모델: deepseek(기본값), openrouter, huggingface(Inference Providers), moonshot(Kimi), zai(GLM), minimax, volcengine(Ark), nvidia-nim, together, fireworks, novita, siliconflow / siliconflow-CN, arcee, xiaomi-mimo, openmodel, deepinfra, stepfun, atlascloud, qianfan, wanjie-ark, 그리고 모든 게이트웨이를 위한 일반 openai 호환 경로.
• 자가 호스팅 오픈 모델: 자체 localhost 엔드포인트에 대한 vllm, sglang, ollama — 키 불필요.
• 네이티브 폐쇄 제공자: 적응형 사고, 프롬프트 캐시 중단점 및 서명된 사고 재생을 갖춘 전용 /v1/messages 어댑터를 통한 anthropic; DeepSeek의 옵트인 Messages-API 경로인 deepseek-anthropic; 그리고 openai-codex(실험적)는 API 키 대신 기존 ChatGPT/Codex CLI 로그인을 재사용합니다.

Fleet

Fleet은 다중 워커 실행을 위한 CodeWhale의 내구성 있는 제어 평면입니다. Fleet 워커는 헤드리스 codewhale exec 실행이지만, Fleet은 이를 내구성 있게 시작하고 추적합니다: 작업은 추가 전용 원장(.codewhale/fleet.jsonl)에 기록되므로, 실행은 관리자 종료, 노트북 절전 또는 런타임 재시작에도 유지됩니다.

codewhale fleet run tasks.json --max-workers 4
codewhale fleet status
codewhale fleet resume <run-id>

fleet resume은 원장을 재생하고, 하트비트가 중지된 워커의 진행 중인 작업을 조정하며(예산 내에서 재시도, 실패 시 에스컬레이션), 멱등적입니다 — 관리자를 중단시킨 어떤 일 이후에도 안전하게 실행할 수 있습니다. 각 워커는 유형화된 영수증(pass / fail / partial / skip / timeout)을 기록하므로 fleet status가 실제로 발생한 일을 보고할 수 있습니다.

워커는 역할, 프로필, 로드아웃 및 슬롯에 의해 형성되며, 설정의 [fleet] 아래에 구성되거나 앱 내 Fleet 설정 뷰에서 작성됩니다. 로드아웃은 모델 의도를 strong, balanced 또는 fast와 같은 클래스로 표현하며, 경로 확인자가 이를 구체적인 제공자/모델로 변환합니다. 이는 세션 내 하위 에이전트를 뒷받침하는 동일한 헤드리스 런타임입니다. Fleet은 그 위의 내구성 계층입니다. docs/FLEET.md를 참조하세요.

안전

CodeWhale은 파일을 편집하고 명령을 실행하므로, 안전 자세는 부차적인 것이 아니라 제품의 일부입니다.

• 세 가지 모드. Plan(읽기 전용 조사), Agent(실행, 각 작업마다 확인), YOLO(자동 승인). Tab 또는 /mode로 전환합니다.
• 승인 게이트 도구. .codewhale/hooks.toml 훅 시스템은 도구 호출 전에 허용, 거부 또는 확인을 요청할 수 있으며, 실행 정책은 명령이 실행되는지, 승인이 필요한지, 또는 완전히 금지되는지 결정합니다.
• OS 샌드박싱. macOS의 Seatbelt, Linux의 Landlock 및 seccomp 시스템 콜 필터, 그리고 사용 가능한 경우 bubblewrap(bwrap).
• 롤백. 사이드-git 스냅샷은 저장소의 .git 외부에 있으므로, /restore는 실제 기록을 건드리지 않고 턴을 취소할 수 있습니다.

기능

• 지속적인 목표 루프. /goal로 목표를 설정하면 에이전트가 턴을 넘어 계속 작업합니다 — 읽기, 편집, 실행, 결과 확인 — 목표가 완료되거나, 차단되거나, 중지할 때까지. 턴 제한 없음. /task는 백그라운드 작업을 추적합니다. 작업 사이드바는 실시간 계획 및 체크리스트 상태를 보여줍니다.
• 내구성 있는 세션. 재시작 및 시스템 절전 후에도 유지됩니다. 40번의 도구 호출이 필요한 작업도 41번째까지 유지됩니다.
• 헤드리스 모드. codewhale exec with --allowed-tools, --disallowed-tools(거부 우선), --max-turns, --append-system-prompt for scripts and CI.
• MCP, 양방향. 외부 MCP 서버의 도구를 사용하거나, codewhale mcp를 통해 CodeWhale 자체를 MCP 서버로 노출합니다.
• 스킬. ~/.codewhale/skills/의 재사용 가능한 워크플로, /skills로 로드.
• 어디에나 내장. HTTP/SSE 및 ACP 런타임 API, VS Code 확장, Telegram/Feishu 브리지(Weixin 실험적).

명령어 순위 지정 방법

프로젝트가 발전함에 따라 명령어가 쌓이고 필연적으로 충돌합니다: 원래 사양, 이를 반박하는 이후 리팩터, 오래된 메모리, 이전 에이전트의 인계, 현재 요청, 그리고 인계가 주장한 것과 일치하지 않는 새로운 테스트 출력. 평면 시스템 프롬프트는 모델이 추측으로 이를 해결하게 만듭니다. CodeWhale은 중첩 헌법을 사용하여 분위기 대신 정의된 순위를 제공합니다.

시스템 프롬프트는 가장 정적인 것부터 계층화되며, 순서는 코드에서 강제됩니다(이 순서가 흐트러질 수 없음을 확인하는 테스트가 있습니다):

1. 글로벌 헌법 — 모든 바이너리에 컴파일된 기본 법칙. 우선순위 조항은 충돌 시 권한 순서를 고정합니다.
2. 프로젝트의 법칙 — 저장소에 .codewhale/constitution.json을 넣어 protectedinvariants, branchpolicy, verificationpolicy, escalatewhen을 선언합니다. 메모리 및 인계 위에 자체 권한 블록으로 로드됩니다.
3. 현재 요청 — 이 턴의 작동 명령어.
4. 실시간 증거 — 도구가 실제로 반환한 것. 근본 진실; 모델이 이를 무시하라는 명령을 받을 수 있지만, 거기에 없는 사실을 보고해서는 안 됩니다.

두 명령어가 충돌하면 각각 위의 명령어에 양보합니다. 법칙이 모델이 아닌 도구 모음에 있기 때문에 모델을 교체해도 구조가 유지됩니다.

세부 정보 위치

README는 짧은 버전입니다. 나머지는 docs와 codewhale.net에 있습니다:

• 사용자 가이드 · 설치 가이드 · 설정 · 제공자 레지스트리
• 모드 — Agent, Plan, YOLO.
• Fleet · 하위 에이전트 — 역할, 수명 주기, 출력 계약, 복구 동작.
• 아키텍처 — 크레이트 레이아웃, 런타임 흐름, 도구 시스템, 확장 지점, 보안 모델.
• WhaleFlow 작성 · MCP · 런타임 API · Model Lab
• 키 바인딩 · 샌드박스 및 승인 · 접근성 · Docker · 메모리
• 전체 문서 색인 — 그 외 모든 것.

프로젝트

CodeWhale은 한 사람의 DeepSeek 사이드 프로젝트로 시작되었습니다. 전 세계의 개발자들이 지금의 모습으로 만들었습니다 — 모든 릴리스의 기여자 목록이 증거입니다. 프로젝트는 공개적으로 구축되며, 이슈는 공개적으로 분류되고, 릴리스는 main에서 만들어집니다.

가르치는 일에서 일찍 배운 것: 모든 피드백은 선물입니다. 이슈, PR, 버그 보고서, 기능 아이디어, "첫 PR", 호기심 많은 질문 모두 실제 프로젝트 작업으로 간주됩니다.

[...truncated...]