CodeWhale is a specialized terminal-native coding agent designed to provide a structured harness for DeepSeek V4 and other open models. Created to solve the problem of agentic drift during long, complex coding sessions, it wraps the model in a 'Constitution'—a written rulebook that ranks sources of authority explicitly, including user intent, repository instructions, system defaults, and live tool feedback. By leveraging DeepSeek V4's prefix caching, the agent can reference this Constitution recursively at a fraction of the cost of cold reads, ensuring the model remains oriented throughout its execution.

CodeWhale operates by creating a tight feedback loop where the results of its actions—such as compiler errors, non-zero exit codes, or sandbox denials—are fed back into the context as correction vectors. This allows the model to self-correct during multi-step tasks. The agent supports multiple operating modes: Plan (read-only investigation), Agent (default multi-step tool execution with approval gates), and YOLO (auto-approval). A unique feature, 'Fin', acts as a local model auto-routing layer, analyzing task requirements and dispatching sub-tasks to the most appropriate tier, such as flash models for simple operations and pro models for intensive reasoning.

Some of the key features are:

• Constitution-based Authority: Defines a strict hierarchy of sources, ensuring user intent and live verification always outrank assumptions.
• Recursive Prefix Caching: Minimizes costs and maintains consistency by keeping the rulebook in the model's active context.
• Self-Correcting Feedback Loop: Dynamically incorporates tool outputs and error reports to adjust execution in real-time.
• Model Auto-Routing: Uses a light, fast model for routing decisions, escalating to Pro models only when deep reasoning is required.
• Approval Gates: Provides granular control over tool usage and side-effect operations to maintain workspace security.
• Sandboxed Execution: Utilizes bwrap, landlock, seccomp, and other process-hardening techniques to isolate execution environments.
• Extensible Architecture: Supports Model Context Protocol (MCP) servers and custom user skills to broaden functionality.

Usage involves initiating the agent within a project directory, where it interacts with the workspace via a terminal user interface (TUI). Users can cycle between operational modes using the Tab key. Configuration is handled through a project-scoped or global 'config.toml' file, enabling users to define hooks, API keys, and model preferences. The system maintains an 'audit.log' to track sensitive actions, and it ensures that no code is processed in the cloud, keeping all development local to the machine.

Some common use cases include:

• Large-scale Code Refactoring: Automating complex multi-file refactors while keeping the model aligned with architectural constraints.
• Automated Bug Resolution: Using the agent to investigate type errors and apply fixes, with immediate verification from build tools or testing suites.
• Complex Feature Development: Coordinating multi-step architecture and implementation tasks that require multiple rounds of investigation and execution.
• Sandbox-safe Experimentation: Safely executing unfamiliar code or commands in an isolated environment before merging changes into the primary repository.