터미널 코딩 Agent가 요즘 한꺼번에 쏟아져 나오고 있다. 대부분 특정 클라우드 벤더에 종속되거나, 승인 로직을 블랙박스 안에 숨겨둔다. CodeWhale은 좀 다른 각도에서 들어왔다. Model-agnostic + 승인 관측 가능성. 타깃 유저도 명확하다 — 오픈소스 모델을 쓰되, Agent의 경계를 직접 보고 싶은 개발자.
GitHub 저장소: https://github.com/Hmbown/CodeWhale, 현재 40,828 Star, README는 18개 언어로 번역돼 있다.
어떤 문제를 푸는가
터미널 코딩 Agent가 한꺼번에 쏟아져 나오고 있다. 대다수는 특정 클라우드 벤더에 묶여 있거나, 승인 로직을 블랙박스 속에 숨긴다 — 엔터를 누르기 전에 다음에 어떤 파일을 건드릴지 알 수 없다.
CodeWhale의 진입점은 두 가지다:
- Model-agnostic. 로컬 Ollama, vLLM, SGLang, 그리고 OpenAI 호환 프로토콜·Anthropic 같은 호스팅 모델까지 모두 연동하고, 런타임에서 자유롭게 전환.
- 승인 관측 가능. Agent가 뭘 할 수 있고 어디까지 했는지를 전부 사용자가 볼 수 있는 등급(Plan / Ask / Auto-Review / Full Access)과 롤백 가능한 스냅샷 로그로 노출.
타깃은 오픈소스 로컬 모델로 코딩 Agent를 돌리되, Agent가 파일을 함부로 바꾸는 게 마음에 걸리는 개발자다.
사용법
명령어 세 줄이면 시작한다:
# 세 단계로 시작
npm install -g codewhale # cargo / docker / nix도 가능
codewhale # TUI 실행, 첫 실행 시 provider 연결 또는 오프라인 유지 안내
# TUI 없이 바로 작업 실행
codewhale exec "fix the failing tests and explain what changed"
# TUI 안에서 자주 쓰는 명령어
# /model provider와 model 전환
# /undo 직전 작업 취소
# /restore 특정 workspace snapshot으로 롤백
# /goal 지속 목표 설정
# /help 단축키 전체 보기
# 로컬 모델을 쓰고 싶다면? Ollama를 띄운 뒤 /model에서 Ollama 선택,
# vLLM, SGLang도 동일 (OpenAI 호환 프로토콜)
설치 경로가 꽤 다양하다. npm, Cargo, Docker, Nix, Scoop, Termux 외에 CNB 미러도 지원한다.
동작 방식 (아키텍처)
CodeWhale은 시스템을 네 층으로 나눴고, 각 층마다 README에서 별도 docs로 연결한다. 골라 읽기 편하도록.
- 진입점 레이어: TUI(기본) +
codewhale exec(헤드리스, 1회성 작업용) + 로컬 웹 클라이언트(docs/WEB.md). 세 진입점이 동일한 agent runtime을 공유한다. - Provider 추상화: OpenAI 호환 프로토콜, Anthropic, Ollama, vLLM, SGLang을 내부 Model trait으로 통일. 모르는 모델의 가격을 0원으로 채우지 않고 빈칸으로 남겨둬서, 비용 표는 사용자가 직접 관리한다.
- 승인 정책 스택: 네 단계 등급 — Plan(읽기 전용, 파일 변경 없음) / Ask(매 단계마다 확인) / Auto-Review(자동 실행, 롤백 가능) / Full Access. 여기에
/undo+/restore를 더해 관측 가능한 안전 경계를 구성. 전체 정책은docs/AUTHORIZATION_ORDER.md에 정의돼 있다. - 확장 레이어: MCP server, 스킬 파일, hooks, agent role 파일(프로젝트 또는 전역 settings에 배치). 다중 agent 협업(
docs/FLEET.md) 시 내부 prompt가 사용자 transcript에 섞이지 않는다.
핵심 흐름은 단순하다: 사용자 입력 → goal/turn으로 파싱 → MCP + skills + hooks 로드 → Model 호출 → 현재 승인 등급에 따라 도구 호출 실행 여부 결정 → session snapshot 기록 → 결과 렌더링.
장점
- Model-agnostic이 진짜다. 말만 하는 게 아니라 Ollama, vLLM, SGLang 모두 연동되고
/model로 한 번에 전환. provider를 바꿔도 코드 수정이나 재배포가 필요 없다. - 승인 등급이 마케팅용이 아니다. 문서에 완전한 AUTHORIZATION_ORDER 정책 스택이 있고, 모든 작업에 롤백 가능한 snapshot이 남는다. Plan부터 Full Access까지 연속적으로 조절 가능, 단순 on/off가 아니다.
- 다중 agent 협업에서도 transcript가 깨끗하다.
docs/FLEET.md의 협업 모드에서 sub-agent 내부 prompt가 사용자 대화에 섞이지 않는다. 디버깅할 때 중요한 부분. - Rust 단일 바이너리 + 다채널 배포. Cargo로 깔든, npm으로 깔든, docker로 돌든 결국 같은 바이너리라 동작이 동일하다.
- 커뮤니티가 활발하다. 40,828 Star, README 18개 언어 번역, issue 대응도 꽤 빠른 편.
단점
- 이름이 Claude Code와 헷갈린다. CodeWhale이라는 이름이 커뮤니티에서 맥락 없이는 검색이 어렵고 노이즈에 묻히기 쉽다.
- 문서 양이 코드 양보다 압도적으로 많다. "설치해서 바로 쓰고 싶은" 사용자에는 진입장벽이 높은 편.
docs/AUTHORIZATION_ORDER.md,docs/FLEET.md,docs/WEB.md를 합치면 짧지 않다. - 모르는 모델의 가격은 빈칸으로 남는다. 비용에 민감한 팀은 가격표를 직접 유지해야 한다. 자동 추정은 해주지 않는다.
deepseek-tui에서 프로젝트명을 바꿨다. 기존 설정과 세션 호환성 문제가 숨은 비용이고, 마이그레이션 시 수동 조정이 필요할 수 있다.
직접 돌려보진 않았지만, 이렇게 검증해보길 권한다
이 글은 README와 저장소 구조만 본 정적 분석이고, 실제로 돌려보진 않았다. 다음 순서로 확인할 것을 권한다:
codewhale설치 후 로컬 Ollama에서 띄운qwen2.5-coder를 연결.- toy repo에서
codewhale exec "Add unit tests to src/foo.py"실행, Plan 등급과 Full Access 등급의 출력 차이를 비교 (Plan에서는 파일이 거의 안 바뀌어야 정상). /restore로 롤백해보고, snapshot이 완전한지, 특정 turn 단위로 정확히 복원되는지 확인.docs/FLEET.md예제대로 agent 역할을 두 개 띄워서, transcript가 실제로 깨끗한지(내부 sub-agent의 사고 과정이 보이지 않아야 한다) 확인.
검증 후 수치(로컬 모델 기준 token/s, 승인 지연, snapshot 용량)를 댓글에 공유하면 같이 맞춰볼 수 있다.
이런 사람에게는 맞다
적합:
- 오픈소스 로컬 모델(Ollama/vLLM)로 코딩 Agent를 돌리되 파일 변경이 마음에 걸리는 개발자.
- 팀 안에서 Agent 작업 로그를 감사하고, 승인 절차를 블랙박스가 아닌 관측 가능 시스템으로 만들고 싶은 엔지니어링 팀.
- Rust 생태계 기여자. 4만 Star짜리 Rust Agent 프로젝트가 어떤 구조인지, 디렉터리와 모듈 분할을 살펴볼 가치는 있다.
부적합:
- IDE 플러그인 하나 깔아서 쓰고 싶고, docs 다섯 개 읽기 귀찮은 사용자.
- Claude Code나 Cursor 같은 "설치 즉시 최고 모델" 경험에 익숙하고 락인 문제 따위 신경 안 쓰는 사용자 — CodeWhale은 모델 선택을 대신 해주지 않고, 전환 판단 비용이 사용자 쪽에 있다.
- 터미널 UI에 거부감이 있어 완전한 GUI가 필요한 팀. CodeWhale에 로컬 웹 클라이언트(
docs/WEB.md)는 있지만 주력은 여전히 TUI다.
참고: CodeWhale 저장소 https://github.com/Hmbown/CodeWhale. docs/AUTHORIZATION_ORDER.md, docs/FLEET.md, docs/WEB.md는 각각 승인 정책, 다중 agent 협업, 웹 클라이언트를 다룬다.