🐳 CodeWhale

このターミナルネイティブのコーディングエージェントは、DeepSeek V4 の 100 万トークンのコンテキストウィンドウとプレフィックスキャッシュ機能を中心に構築されています。単一のバイナリとして配布され、Node.js や Python のランタイムは不要です。MCP クライアント、サンドボックス、永続的なタスクキューも標準で同梱されています。

English README 简体中文 README

インストール

codewhale は自己完結型の Rust バイナリとして提供されており、実行に Node.js や Python のランタイムは必要ありません。 すでにマシンにインストールされているものを選んでください。いずれの方法でも同じバイナリが PATH に配置されます。

# 1. npm — すでに Node を使っているなら最も簡単。npm パッケージは
#    GitHub Releases から対応するビルド済みバイナリをダウンロードする
#    薄いインストーラーであり、codewhale 本体に Node ランタイム依存を加えるものではありません。
npm install -g codewhale

# 2. Cargo — Node 不要。
cargo install codewhale-cli --locked   # `codewhale` (エントリーポイント)
cargo install codewhale-tui     --locked   # `codewhale-tui` (TUI バイナリ)

# 3. Homebrew — macOS パッケージマネージャ。
brew tap Hmbown/deepseek-tui
brew install deepseek-tui

# 4. 直接ダウンロード — Node もツールチェーンも不要。
#    https://github.com/Hmbown/CodeWhale/releases
#    Linux x64/ARM64、macOS x64/ARM64、Windows x64 向けのビルド済みバイナリがあります。

# 5. Docker — ビルド済みリリースイメージ。
docker volume create codewhale-home
docker run --rm -it \
  -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \
  -v codewhale-home:/home/codewhale/.deepseek \
  -v "$PWD:/workspace" \
  -w /workspace \
  ghcr.io/hmbown/codewhale:latest

中国本土では、--registry=https://registry.npmmirror.com を指定して npm 経由のダウンロードを高速化するか、下記のCargo ミラーを利用してください。

既にインストール済みの場合は、インストール方法に合わせて更新してください:

codewhale update
npm install -g codewhale@latest
brew update && brew upgrade deepseek-tui
cargo install codewhale-cli --locked --force
cargo install codewhale-tui     --locked --force

codewhale とは？

codewhale は、ターミナル内で完結するコーディングエージェントです。DeepSeek のフロンティアモデルがあなたのワークスペースに直接アクセスできるようにし、ファイルの読み取り・編集、シェルコマンドの実行、Web 検索、Git 管理、サブエージェントの統制などを、すべて高速でキーボード駆動の TUI を通じて行えます。

DeepSeek V4 向けに構築 (deepseek-v4-pro / deepseek-v4-flash)。100 万トークンのコンテキストウィンドウとネイティブの thinking-mode（思考連鎖）ストリーミングをサポートします。

主な機能

• Auto モード — --model auto / /model auto がターンごとにモデルと推論強度を選択
• ネイティブ RLM (rlm_open/rlm_eval) — 永続 REPL セッションでバッチ解析を行い、peek、search、chunk、sub_query_batch などの補助関数で低コストな deepseek-v4-flash 子タスクを実行
• Thinking-mode ストリーミング — モデルがタスクに取り組む様子をリアルタイムで観察し、思考連鎖の展開を追える
• 完全なツールスイート — ファイル操作、シェル実行、Git、Web 検索／ブラウズ、apply-patch、サブエージェント、MCP サーバー
• 100 万トークンコンテキスト — コンテキスト追跡、手動または設定ベースのコンパクション、プレフィックスキャッシュのテレメトリ
• 3 つのモード — Plan（読み取り専用の探索）、Agent（承認ありのインタラクティブ）、YOLO（自動承認）
• 推論努力ティア — Shift + Tab で off → high → max を切り替え
• セッション保存／再開 — 長時間実行のセッションをチェックポイント化して再開可能
• ワークスペースのロールバック — リポジトリの .git には触れずに、サイド Git によるターン前後のスナップショットを /restore と revert_turn で扱える
• 永続的タスクキュー — 再起動を超えて生き残るバックグラウンドタスク。スケジュール自動化や長時間レビューなどに
• HTTP/SSE ランタイム API — codewhale serve --http でヘッドレスエージェントワークフローを実現
• MCP プロトコル — Model Context Protocol サーバーに接続して拡張ツールを利用可能。詳細は docs/MCP.md を参照
• LSP 診断 — rust-analyzer、pyright、typescript-language-server、gopls、clangd により、編集ごとにエラー／警告をインライン表示
• ユーザーメモリ — クロスセッションの嗜好をシステムプロンプトに注入できる、オプションの永続メモファイル
• ローカライズ済み UI — en、ja、zh-Hans、pt-BR を自動検出
• ライブコスト追跡 — ターンごと／セッションごとのトークン使用量とコスト見積もり、キャッシュヒット／ミスの内訳
• スキルシステム — GitHub から取得できる命令パック。初回起動時に skill-creator、mcp-builder、documents、presentations、spreadsheets、pdf、feishu などのスターターセットを同梱

仕組み

codewhale（ディスパッチャー CLI）→ codewhale-tui（コンパニオンバイナリ）→ ratatui インターフェース ↔ 非同期エンジン ↔ OpenAI 互換のストリーミングクライアント。ツール呼び出しは型付きレジストリ（シェル、ファイル操作、Git、Web、サブエージェント、MCP、RLM）を経由してルーティングされ、結果はトランスクリプトへとストリーム返送されます。エンジンはセッション状態、ターン管理、永続タスクキューを管理し、LSP サブシステムは編集後の診断を次の推論ステップ前にモデルのコンテキストへ供給します。

詳しくは docs/ARCHITECTURE.md を参照してください。

クイックスタート

npm install -g codewhale
codewhale --version
codewhale --model auto

ビルド済みバイナリは Linux x64、Linux ARM64（v0.8.8 以降）、macOS x64、macOS ARM64、Windows x64 向けに公開されています。その他のターゲット（musl、riscv64、FreeBSD など）は ソースからのインストール または docs/INSTALL.md を参照してください。

初回起動時に DeepSeek API キー の入力を求められます。キーは ~/.deepseek/config.toml に保存されるため、OS のクレデンシャルプロンプトなしに任意のディレクトリから利用できます。

事前に設定することもできます:

codewhale auth set --provider deepseek   # ~/.deepseek/config.toml に保存

export DEEPSEEK_API_KEY="YOUR_KEY"      # 環境変数による代替方法。非対話シェルでは ~/.zshenv を使用
codewhale

codewhale doctor                         # セットアップを検証

保存済みキーをローテーション／削除するには: codewhale auth clear --provider deepseek。

Linux ARM64（Raspberry Pi、Asahi、Graviton、HarmonyOS PC）

npm i -g codewhale は v0.8.8 以降、glibc ベースの ARM64 Linux で動作します。Releases ページ からビルド済みバイナリをダウンロードし、PATH 上に並べて配置することもできます。

中国 / ミラーフレンドリーなインストール

中国本土から GitHub または npm のダウンロードが遅い場合は、Cargo レジストリのミラーを利用してください:

# ~/.cargo/config.toml
[source.crates-io]
replace-with = "tuna"

[source.tuna]
registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"

その後、両方のバイナリをインストールしてください（ディスパッチャーは実行時に TUI へ委譲します）:

cargo install codewhale-cli --locked   # `codewhale` を提供
cargo install codewhale-tui     --locked   # `codewhale-tui` を提供
codewhale --version

ビルド済みバイナリは GitHub Releases からもダウンロードできます。ミラーされたリリースアセットには DEEPSEEK_TUI_RELEASE_BASE_URL を使ってください。

Windows（Scoop）

Scoop は Windows のパッケージマネージャです。インストール後、次を実行してください:

scoop install deepseek-tui

# Linux のビルド依存関係 (Debian/Ubuntu/RHEL):
#   sudo apt-get install -y build-essential pkg-config libdbus-1-dev
#   sudo dnf install -y gcc make pkgconf-pkg-config dbus-devel

git clone https://github.com/Hmbown/CodeWhale.git
cd CodeWhale

cargo install --path crates/cli --locked   # Rust 1.88+ が必要。`codewhale` を提供
cargo install --path crates/tui --locked   # `codewhale-tui` を提供

その他の API プロバイダー

# NVIDIA NIM
codewhale auth set --provider nvidia-nim --api-key "YOUR_NVIDIA_API_KEY"
codewhale --provider nvidia-nim

# AtlasCloud
codewhale auth set --provider atlascloud --api-key "YOUR_ATLASCLOUD_API_KEY"
codewhale --provider atlascloud

# Wanjie Ark
codewhale auth set --provider wanjie-ark --api-key "YOUR_WANJIE_API_KEY"
codewhale --provider wanjie-ark --model deepseek-reasoner

# OpenRouter
codewhale auth set --provider openrouter --api-key "YOUR_OPENROUTER_API_KEY"
codewhale --provider openrouter --model deepseek/deepseek-v4-pro

# Novita
codewhale auth set --provider novita --api-key "YOUR_NOVITA_API_KEY"
codewhale --provider novita --model deepseek/deepseek-v4-pro

# Fireworks
codewhale auth set --provider fireworks --api-key "YOUR_FIREWORKS_API_KEY"
codewhale --provider fireworks --model deepseek-v4-pro

# 汎用 OpenAI 互換エンドポイント
codewhale auth set --provider openai --api-key "YOUR_OPENAI_COMPATIBLE_API_KEY"
OPENAI_BASE_URL="https://openai-compatible.example/v4" codewhale --provider openai --model glm-5

# セルフホスト SGLang
SGLANG_BASE_URL="http://localhost:30000/v1" codewhale --provider sglang --model deepseek-v4-flash

# セルフホスト vLLM
VLLM_BASE_URL="http://localhost:8000/v1" codewhale --provider vllm --model deepseek-v4-flash

# セルフホスト Ollama
ollama pull codewhale-coder:1.3b
codewhale --provider ollama --model codewhale-coder:1.3b

TUI 内では /provider でプロバイダーピッカー、/model でローカルのモデル/思考モードピッカーを開けます。/provider openrouter や /model <id> で直接切り替え、/models で対応プロバイダーのライブモデル一覧を明示的に取得できます。

リリースノート

バージョンごとの変更点は CHANGELOG.md にまとめています。この README は、現在のインストール方法、主要ワークフロー、プロバイダー設定、ランタイムインターフェース、拡張ポイントに絞っています。

使い方

codewhale                                         # インタラクティブ TUI
codewhale "explain this function"                 # ワンショットプロンプト
codewhale exec --auto --output-format stream-json "fix this bug"  # NDJSON バックエンドストリーム
codewhale exec --resume <SESSION_ID> "follow up"  # 非対話セッションを継続
codewhale --model deepseek-v4-flash "summarize"   # モデルの上書き
codewhale --model auto "fix this bug"             # モデルと推論強度を自動選択
codewhale --yolo                                  # ツールを自動承認
codewhale auth set --provider deepseek            # API キーの保存
codewhale doctor                                  # セットアップと接続性のチェック
codewhale doctor --json                           # 機械可読の診断
codewhale setup --status                          # 読み取り専用のセットアップ状態
codewhale setup --tools --plugins                 # ツール／プラグインディレクトリの雛形作成
codewhale models                                  # ライブ API モデル一覧
codewhale sessions                                # 保存済みセッション一覧
codewhale resume --last                           # 最新セッションを再開
codewhale resume <SESSION_ID>                     # UUID 指定で特定セッションを再開
codewhale fork <SESSION_ID>                       # 保存済みセッションを兄弟パスに fork
codewhale serve --http                            # HTTP/SSE API サーバー
codewhale serve --acp                             # Zed/カスタムエージェント向け ACP stdio アダプター
codewhale run pr <N>                              # PR を取得しレビュープロンプトに先行投入
codewhale mcp list                                # 設定された MCP サーバー一覧
codewhale mcp validate                            # MCP の設定／接続性を検証
codewhale mcp-server                              # ディスパッチャー MCP stdio サーバーを実行
codewhale update                                  # バイナリ更新の確認と適用

キーボードショートカット

ショートカット完全版: docs/KEYBINDINGS.md。

モード

設定

ユーザー設定: ~/.deepseek/config.toml。プロジェクトオーバーレイ: <workspace>/.deepseek/config.toml（拒否される項目: api_key、base_url、provider、mcp_config_path）。すべてのオプションは config.example.toml にあります。

主な環境変数:

UI のロケールはモデルの言語とは別です。settings.toml で locale を設定するか、/config locale zh-Hans を使うか、LC_ALL/LANG に依存させてください。詳しくは docs/CONFIGURATION.md と docs/MCP.md を参照してください。

モデルと料金

レガシーエイリアス deepseek-chat / deepseek-reasoner は deepseek-v4-flash にマップされます。NVIDIA NIM のバリアントはあなたの NVIDIA アカウント条件に従います。

自分のスキルを公開する

codewhale はワークスペースのディレクトリ（.agents/skills → skills → .opencode/skills → .claude/skills）とグローバルな ~/.deepseek/skills からスキルを発見します。各スキルは SKILL.md ファイルを持つディレクトリです:

~/.deepseek/skills/my-skill/
└── SKILL.md

必要なフロントマター:

---
name: my-skill
description: DeepSeek にカスタムワークフローを実行させたいときに利用する。
---

# My Skill
ここにエージェント向けの指示を記述します。

コマンド: /skills（一覧）、/skill <name>（有効化）、/skill new（雛形）、/skill install github:<owner>/<repo>（コミュニティ）、/skill update / uninstall / trust。GitHub からのコミュニティインストールにバックエンドサービスは不要です。インストール済みのスキルはモデルに見えるセッションコンテキストに表示され、タスクが説明文にマッチした場合はエージェントが load_skill ツールを通じて関連スキルを自動選択できます。

ドキュメント

完全な変更履歴: CHANGELOG.md。

謝辞

このプロジェクトは、増え続けるコントリビューターのコミュニティから助けを得て出荷されています:

• merchloubna70-dot — 機能、修正、VS Code 拡張のスキャフォールドにまたがる 28 件の PR (#645–#681)
• WyxBUPT-22 — 表、太字／斜体、水平線の Markdown レンダリング (#579)
• loongmiaow-pixel — Windows と中国向けインストールドキュメント (#578)
• 20bytes — ユーザーメモリのドキュメントとヘルプの磨き込み (#569)
• staryxchen — glibc 互換性のプリフライト (#556)
• Vishnu1837 — glibc 互換性の改善 (#565)
• shentoumengxin — シェル cwd の境界バリデーション (#524)
• toi500 — Windows 貼り付け修正の報告
• xsstomy — ターミナル起動時の再描画報告
• melody0709 — スラッシュ接頭辞の Enter アクティベーション報告
• lloydzhou と jeoor — コンパクションコストの報告
• Agent-Skill-007 — README の明瞭化対応 (#685)
• woyxiang — Windows Scoop インストールドキュメント (#696)
• wangfeng — 料金／割引情報の更新 (#692)
• zichen0116 — CODE_OF_CONDUCT.md (#686)
• Hafeez Pizofreude — fetch_url の SSRF 保護と Star History チャート
• Unic (YuniqueUnic) — スキーマ駆動の設定 UI（TUI + Web）
• Jason — SSRF セキュリティの強化

コントリビューション

CONTRIBUTING.md を参照してください。プルリクエストを歓迎します。良い初コントリビューションは Open Issues を確認してください。

ライセンス

MIT

Star History