# CodeWhale — Open-Weight AI Coding Agent for the Terminal

> A terminal-based coding agent built in Rust that works with open-source and open-weight language models. Designed for developers who want local-first AI coding assistance without relying on proprietary APIs.

## Install

Save in your project root:

# CodeWhale — Open-Weight AI Coding Agent for the Terminal

## Quick Use
```bash
# Install from source
git clone https://github.com/Hmbown/CodeWhale.git
cd CodeWhale
cargo install --path .

# Run with a local model
codewhale --model deepseek-coder
```

## Introduction
CodeWhale is a terminal coding agent written in Rust that targets open-source and open-weight language models. It provides an interactive CLI for code generation, editing, and explanation without requiring proprietary API keys, making it suitable for air-gapped or privacy-sensitive environments.

## What CodeWhale Does
- Provides an interactive terminal UI for AI-assisted coding tasks
- Supports multiple open-weight models including DeepSeek, Llama, and Qwen
- Reads and edits files in your project directory with contextual awareness
- Generates code, fixes bugs, and explains existing code from natural language prompts
- Runs entirely locally with no data sent to external servers

## Architecture Overview
CodeWhale is a single Rust binary that communicates with local model servers via the OpenAI-compatible API format. It includes a built-in TUI for interactive sessions, a file indexer for project context, and a tool-use layer that allows the model to read, write, and search files. The Rust implementation keeps memory usage low and startup instant.

## Self-Hosting & Configuration
- Requires a local model server such as Ollama, llama.cpp, or vLLM
- Install via cargo or download pre-built binaries from GitHub releases
- Configure the model endpoint and default model in ~/.codewhale/config.toml
- Set project-specific instructions via a .codewhale file in your repo root
- Supports environment variables for API endpoint and model selection

## Key Features
- Pure Rust implementation for fast startup and low resource usage
- Works with any OpenAI-compatible local model server
- Built-in TUI with syntax highlighting and diff previews
- No telemetry or external data collection
- Extensible tool system for custom file operations

## Comparison with Similar Tools
- **Claude Code** — proprietary, requires Anthropic API access; CodeWhale runs fully local
- **Aider** — Python-based, supports many providers; CodeWhale is Rust-native and local-first
- **OpenCode** — similar local-first approach; CodeWhale focuses specifically on open-weight models
- **Continue** — IDE extension model; CodeWhale is terminal-native

## FAQ
**Q: What models does CodeWhale support?**
A: Any model served via an OpenAI-compatible API endpoint, including DeepSeek, Llama, Qwen, and Mistral variants.

**Q: Does it require a GPU?**
A: CodeWhale itself does not, but the underlying model server benefits from GPU acceleration for faster inference.

**Q: Can I use it with remote APIs?**
A: Yes. Point it at any OpenAI-compatible endpoint, local or remote.

**Q: How does it handle large codebases?**
A: It indexes project files and selectively includes relevant context in prompts, keeping token usage efficient.

## Sources
- https://github.com/Hmbown/CodeWhale

---
Source: https://tokrepo.com/en/workflows/asset-72941756
Author: AI Open Source