도구

CodeWhale, 4만 Star Rust 터미널 코딩 Agent — Claude Code와 뭐가 다른가

Model-agnostic 설계와 단계별 승인 로그를 핵심 차별점으로 내세운 Rust 기반 TUI 코딩 Agent. Claude Code와는 다른 결의 경쟁 구도를 만든다.

글자 크기

터미널 코딩 Agent가 요즘 한꺼번에 쏟아져 나오고 있다. 대부분 특정 클라우드 벤더에 종속되거나, 승인 로직을 블랙박스 안에 숨겨둔다. CodeWhale은 좀 다른 각도에서 들어왔다. Model-agnostic + 승인 관측 가능성. 타깃 유저도 명확하다 — 오픈소스 모델을 쓰되, Agent의 경계를 직접 보고 싶은 개발자.

GitHub 저장소: https://github.com/Hmbown/CodeWhale, 현재 40,828 Star, README는 18개 언어로 번역돼 있다.

어떤 문제를 푸는가

터미널 코딩 Agent가 한꺼번에 쏟아져 나오고 있다. 대다수는 특정 클라우드 벤더에 묶여 있거나, 승인 로직을 블랙박스 속에 숨긴다 — 엔터를 누르기 전에 다음에 어떤 파일을 건드릴지 알 수 없다.

CodeWhale의 진입점은 두 가지다:

  1. Model-agnostic. 로컬 Ollama, vLLM, SGLang, 그리고 OpenAI 호환 프로토콜·Anthropic 같은 호스팅 모델까지 모두 연동하고, 런타임에서 자유롭게 전환.
  2. 승인 관측 가능. 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와 저장소 구조만 본 정적 분석이고, 실제로 돌려보진 않았다. 다음 순서로 확인할 것을 권한다:

  1. codewhale 설치 후 로컬 Ollama에서 띄운 qwen2.5-coder를 연결.
  2. toy repo에서 codewhale exec "Add unit tests to src/foo.py" 실행, Plan 등급과 Full Access 등급의 출력 차이를 비교 (Plan에서는 파일이 거의 안 바뀌어야 정상).
  3. /restore로 롤백해보고, snapshot이 완전한지, 특정 turn 단위로 정확히 복원되는지 확인.
  4. 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 협업, 웹 클라이언트를 다룬다.

출처: https://github.com/Hmbown/CodeWhale