codewhale-hq/Codewhale

Open-source agent for the terminal written in Rust. Use any provider or model. Issues & PRs always welcome

GitHub에서 열기 ↗ agent-orchestrationai-agentclicodewhalecoding-agentdeveloper-toolslocal-firstmcpmulti-agentmulti-modelopen-sourcerustterminaltui

41,156

GitHub 스타

3,569

포크

Rust

언어

MIT

라이선스

2026.11.05

최근 푸시

2026.06.30

별표한 날

AI 분석

설치 난이도: 쉬움

큐레이터 노트

터미널 중심 워크플로에서 모델을 바꿔가며 코딩 에이전트를 운용하려는 경우 참고 가치가 크다. 특히 다중 프로바이더 지원, 승인/감사 체계, MCP·플러그인 확장 구조는 자체 에이전트 도구를 설계할 때 좋은 레퍼런스가 된다.

강점

Rust로 작성된 터미널 기반 코딩 에이전트로, 40개 이상의 프로바이더와 로컬 모델(Ollama, vLLM, SGLang)을 지원해 모델 종속성이 낮다.
Plan/Work/Operate 모드와 Ask/Auto-Review/Full Access 승인 자세, `/undo`, `/restore`, `/receipts` 등 제어와 감사 기능이 체계적으로 갖춰져 있다.
MCP 서버, 스킬, 플러그인, 훅, Claude Code 플러그인 로드 등 확장 생태계를 폭넓게 지원한다.
macOS Seatbelt, Linux bubblewrap 샌드박스와 `/preview-request` 마스킹 등 안전 장치를 문서화하고 있다.

약점

README에는 실제 코드 예시나 아키텍처 세부 내용이 거의 없고 대부분 문서 사이트 링크로 연결되어 있어 저장소만으로 내부 구조를 파악하기 어렵다.
데스크톱 앱(GPUI)과 VS Code 확장은 아직 개발 중이거나 커뮤니티 유지 관리 수준으로, 완성도가 검증되지 않았다.
Computer Use 플러그인은 별도 접근 권한 검토와 활성화가 필요해 기본 사용 흐름에서 추가 부담이 있다.

주의사항

설치 경로가 여러 개이므로 한 머신에 중복 설치하면 `PATH` 충돌이 발생할 수 있어 한 가지만 선택해야 한다.
텔레메트리(사용량 집계)가 기본 활성화되어 있어 필요 시 `codewhale config set telemetry false`로 꺼야 한다.
에이전트가 사용자 권한으로 파일 편집과 명령 실행을 수행하므로 승인 자세와 저장소 규칙을 신중히 설정해야 한다.

시작 가이드

macOS/Linux라면 `curl -fsSL https://codewhale.net/install.sh | sh`로 설치 후 `codewhale update` 동작을 확인한다.
`/provider`와 `/model`로 사용할 모델을 연결하고, `codewhale exec`로 헤드리스 실행이 CI에서 어떻게 동작하는지 테스트한다.
MCP 서버 연결과 플러그인/훅 확장 방식을 문서에서 확인해 기존 워크플로에 통합 가능한지 검토한다.
샌드박스와 승인 자세, 텔레메트리 설정을 점검해 보안 정책에 맞게 구성한다.

README 한국어 번역

이 번역은 AI가 원문 README를 옮긴 것입니다. 원문이 항상 우선합니다.

어떤 모델과도 함께 동작하는 오픈소스 코딩 에이전트.

Codewhale은 프로젝트를 읽고, 파일을 편집하고, 명령을 실행하며, 스스로 작업을 검증합니다. 사용자가 선택한 호스팅 모델 또는 로컬 모델과 함께 터미널에서 동작합니다.

설치

macOS 및 Linux:

curl -fsSL https://codewhale.net/install.sh | sh

설치 프로그램은 체크섬이 검증된 바이너리를 ~/.local/bin에 내려받습니다. 이후 codewhale 실행 시 "command not found"가 뜬다면 설치 프로그램이 출력한 PATH 한 줄을 실행하거나 Put it on your PATH 문서를 참고하세요. 언제든 codewhale update로 업그레이드할 수 있습니다.

Windows, npm, Cargo 및 기타 경로

winget install HunterBown.CodeWhale  # Windows x64 (또는 Scoop, 또는 GitHub Releases의 설치 프로그램)
npm install -g codewhale            # 동일한 릴리스 바이너리를 감싼 패키지
cargo install codewhale-cli --locked  # crates.io에서 빌드

Docker, Nix, Linux용 Homebrew, Android/Termux, 체크섬 검증을 포함한 수동 다운로드, 그리고 선택적 CNB 미러는 설치 가이드에서 다룹니다. 한 가지 경로만 선택하세요. 한 머신에 여러 설치가 있으면 PATH를 두고 서로 충돌하게 됩니다.

빠른 시작

프로젝트를 엽니다. 작업하려는 폴더에서 codewhale을 실행합니다.
모델을 연결합니다. /provider를 실행하거나 F3을 눌러 호스팅 키를 추가하거나 로컬 런타임을 선택합니다. Ollama가 이미 채팅 모델과 함께 실행 중이라면 Codewhale이 자동으로 해당 모델로 전환합니다. /model로 모델을 변경할 수 있습니다.
구체적인 작업을 지시합니다.

Fix the failing tests and explain what changed.

동일한 작업을 스크립트나 CI 작업에서 헤드리스로 실행할 수 있습니다:

codewhale exec "fix the failing tests and explain what changed"

명령과 키보드 단축키는 /help를 실행해 확인하세요.

실행 방법

모든 클라이언트는 동일한 로컬 Codewhale Engine을 구동하므로 세션, 도구, 권한이 어디서나 동일하게 동작합니다.

	명령	하는 일
	`codewhale`	대화형 터미널 인터페이스
	`codewhale exec "…"`	스크립트나 CI에서 실행하는 단일 헤드리스 턴, JSON 스트리밍
	`codewhale web`	`127.0.0.1`에서 제공되는 번들 로컬 브라우저 클라이언트
	`codewhale review --pr N`	권고성 풀 리퀘스트 리뷰, 게시는 옵트인
	Runtime API	스레드, 이벤트, 승인을 위한 로컬 HTTP API

네이티브 데스크톱 앱(GPUI)이 로그인 기반 제품 클라이언트로 개발 중입니다. 제공 여부는 제품 페이지를 참고하세요. 커뮤니티가 유지 관리하는 VS Code 확장은 사이드바에서 동일한 Engine에 연결됩니다(소스).

하는 일

어떤 모델이든, 종속 없음. Anthropic, DeepSeek, Google, Mistral, Moonshot, OpenAI, OpenRouter, xAI 등 40개 이상의 내장 프로바이더 경로와, 모든 OpenAI 호환 엔드포인트, 그리고 Ollama, vLLM, SGLang을 통한 로컬 모델을 지원합니다. Providers
제어권은 사용자에게. Plan 모드는 아무것도 변경하지 않고 탐색만 합니다. Work와 Operate는 변경을 수행합니다. 승인 자세(posture)는 어떤 도구 호출에 사용자의 승인이 필요한지 결정하고, /undo와 /restore는 워크스페이스 변경을 복구하며, /receipts는 세션 내 모든 파일, 명령, 승인 내역을 나열합니다. Modes · Receipts
장시간 작업을 위해 설계. 지속적인 /goal을 설정하고, 제한된 작업을 서브 에이전트에 위임하고, 사전 지출 검사를 포함한 감독형 에이전트 팀을 실행하거나, 체크인된 워크플로로 스크립트화할 수 있습니다.
이미 사용하는 것을 확장. MCP 서버를 연결하고, 스킬과 플러그인을 설치하고, 세션 및 도구 이벤트에 훅을 실행하고, 기존 Claude Code 플러그인을 로드합니다.
Computer Use. 포함된 플러그인이 다른 애플리케이션을 관찰하고 조작하는 도구를 추가합니다. 사용 전에 접근 권한을 검토하고 활성화하세요. Guide

모드와 권한

		선택 방법	옵션
	모드 — 에이전트가 무엇을 하는지	`Tab` 또는 `/mode`	Plan(탐색, 변경 없음) · Work(편집 및 실행) · Operate(계획되고 검증된 단계를 통해 목표를 수행)
	자세 — 언제 먼저 물어보는지	`Shift+Tab`	Ask · Auto-Review · Full Access

Full Access도 강제 정책 경계는 여전히 준수합니다. 각 옵션에 대한 설명은 모드와 권한 가이드에서 확인하세요.

안전

Codewhale은 사용자가 부여한 접근 권한으로 사용자의 머신에서 실행됩니다. 승인 자세와 저장소 규칙이 에이전트가 할 수 있는 일을 제한하며, 지원되는 환경에서는 명령이 OS 샌드박스 내에서 실행됩니다(macOS에서는 Seatbelt, Linux에서는 bubblewrap이 옵트인). /preview-request는 무언가 전송되기 전에 정확한 마스킹된 요청을 보여줍니다. 알 수 없는 모델 가격은 무료로 보고되지 않고 알 수 없는 상태로 유지됩니다.

권한 부여 순서, 샌드박싱, 텔레메트리를 참고하세요. 사용량 집계는 기본적으로 켜져 있으며 codewhale config set telemetry false로 끌 수 있습니다.

문서

	여기서 시작	더 깊이
	설치	구성
	프로바이더와 로컬 모델	아키텍처
	모드와 권한	Runtime API
	키 바인딩	플러그인 작성
	GitHub PR 리뷰	전체 문서

커뮤니티

버그 리포트, 기능 아이디어, 풀 리퀘스트를 환영합니다. Codewhale을 몇 달간 사용한 분이든 처음 시도하는 분이든 마찬가지입니다. 프로바이더가 빠져 있거나 워크플로가 불편하다면 이슈를 열거나 풀 리퀘스트를 보내주세요. 첫 기여를 환영하며, 기여자는 반영된 작업에 대한 공로를 계속 유지합니다. 저장소 레이아웃이 시작하기 좋은 곳입니다.

Discord에 참여하거나, WeChat에서 Hunter(hunterbown)를 추가해 Whale Brothers 그룹 가입을 요청하세요.

역사와 라이선스

Codewhale은 deepseek-tui로 시작했으며 여전히 해당 프로젝트의 구성과 세션을 읽습니다. 현재는 프로바이더 중립적이며 독립적으로 유지 관리되고, 어떤 모델 프로바이더와도 제휴 관계가 없습니다. 모든 기여자와 성장을 도운 오픈소스 커뮤니티에 감사드립니다.

MIT. 다른 오픈소스 프로젝트에서 각색한 부분은 서드파티 고지에 기록되어 있습니다.

원본 저장소: codewhale-hq/Codewhale

라이선스: MIT

게재 제외를 원하시면 삭제 요청을 보내주세요.