Here's a scenario every AI coding agent user has faced:
Your agent is mid-way through a refactor. It has the system prompt in context, your project's .clinerules loaded, a stale memory from last session about "prefer enums over constants," and just got back a compiler error from the tool it ran. In the same turn, it needs to decide: do I follow the stale convention, obey the user's latest instruction, trust the compiler output, or respect the system-level security rule?
Claude Code guesses. Codex CLI guesses. CodeWhale doesn't guess — it has a 9-tier authority hierarchy that tells the model exactly which source wins.
I spent the weekend digging into CodeWhale's source code, and what I found isn't just another API wrapper. It's a fundamental rethink of how AI agents should resolve conflicts. Here are the seven architecture decisions that set it apart — and why Claude Code and Codex CLI still haven't solved the problem.
1. The Constitution — A Legal System, Not a Prompt
Both Claude Code and Codex CLI use system prompts. Really good ones, in fact. But a prompt is a one-shot instruction. The model reads it once (assuming it even reads the whole thing) and has to remember the priority rules from memory.
CodeWhale replaces prompts with a Constitution — seven articles (prompts/base.md) that define identity, truth obligations, scope of agency, verification mandates, and — critically — a formal authority hierarchy.
The difference is open-book vs closed-book exam:
# Claude Code / Codex CLI (closed-book):
System prompt → model reads once → hopes it remembers → drifts
# CodeWhale (open-book):
Constitution always in context → RLM Session peeks at specific articles → exact ruling
DeepSeek V4's 1M context window makes this feasible. The Constitution is long, but it's always there when the model needs to look something up.
Why it matters: When a user says "ship it now" but your project rules say "run tests first," Claude Code has to guess the priority. CodeWhale's Article VII says: user intent (L2) trumps project rules (L3) — but the verification mandate (Article V, L1) cannot be overridden by anything. The model doesn't guess. It reads the law.
2. The 9-Tier Authority Hierarchy — Explicit Conflict Resolution
This is the core innovation. When multiple instruction sources collide, CodeWhale doesn't ask the model to "figure it out." Article VII defines a strict hierarchy:
L1 Constitution itself (absolute, never overridden)
L2 User's current message (overrides stale rules)
L3 Project rules / instructions
L4 System defaults
L5 Live tool output (verification > assumption)
L6 Stale memories / assumptions
L7 Prior session handoffs (lowest priority, easily discarded)
Two critical intercept points:
- Article II (Truth First): Even a user's explicit request cannot override the obligation to tell the truth. If the user asks the agent to lie about a test result, the Constitution says no.
- Article V (Verification Mandate): Every action must leave verifiable evidence. "It looks right" is not an acceptable completion criterion.
Claude Code and Codex CLI have no equivalent. Their models resolve conflicts through implicit alignment tuning — you can't configure the priority rules, and you definitely can't enforce that tool output beats stale memory.
3. Prefix Cache Awareness — Why the Long Constitution Is Economically Viable
Here's the objection everyone raises: "A 7-article constitution is expensive token-wise." True — if you pay full price every turn.
DeepSeek V4's prefix caching changes the economics. The Constitution is a fixed prefix — identical every turn. After the first injection, every subsequent turn hits the cache:
| Scenario | Cost per 1M tokens |
|---|---|
| V4 Pro · Cache Hit | $0.0036 |
| V4 Pro · Cache Miss | $0.435 |
| V4 Flash · Cache Hit | $0.0028 |
| V4 Flash · Cache Miss | $0.14 |
Each turn costs roughly 1% of cold-start price. CodeWhale was designed for this from day one — the Constitution is structured so the invariant prefix is maximized and only the variable turn-specific content changes.
Claude Code and Codex CLI don't optimize for prefix caching. Their prompts aren't structured as fixed prefixes, so they miss this cost advantage entirely.
4. Structured Self-Correction — Failures Become Correction Vectors
When a tool call fails in Claude Code or Codex CLI, the error message goes back into the conversation as plain text. The model has to infer what went wrong and whether to retry, adjust, or abort.
CodeWhale wraps every failure into a structured correction vector:
# Simplified concept — not exact API
correction_vector = {
"lsp_diagnostics": ["E0308: type mismatch at src/main.rs:42"],
"exit_codes": {"cargo build": 101},
"sandbox_denials": ["write denied: /etc/hosts"],
}
# Injected before next model inference turn
The model can see exactly what failed, why it failed, and adjust its next action accordingly. Supported LSP servers include rust-analyzer, pyright, typescript-ls, gopls, clangd, jdtls, and vue-language-server.
If the model can't fix the issue, per-turn git snapshots (side-git) let you rollback instantly:
# Rollback to previous turn
/restore
# Or from within the session
revert_turn --to-last-passing
Claude Code can self-correct, but it's implicit — the model has to recognize its own mistakes from conversational context. Codex CLI terminates on sandbox violations but doesn't analyze failure patterns. CodeWhale treats every failure as structured input for the next round.
5. Sub-Agent Concurrency — Real Parallelism, Not Promise.all
This is where CodeWhale pulls ahead for complex tasks. agent_open is non-blocking — the parent agent continues working while sub-agents execute in parallel:
// Parent agent spawns three sub-agents and keeps working
agent_open("Research API changes in auth module")
agent_open("Run lint on new controllers")
agent_open("Check for breaking changes in dependencies")
// ...parent keeps coding...
// Sub-agent results auto-inject when done
// <codewhale:subagent.done> → summary + transcript handle
Concurrent pool: default 10, configurable up to 20. Sub-agent results are injected into the parent session via sentinel markers, with on-demand deep reading via handle_read (supports slicing, line ranges, JSONPath projection).
Claude Code can dispatch sub-tasks, but they're mostly sequential. Codex CLI has no built-in sub-agent system at all. For large refactors or multi-file changes, CodeWhale's parallelism cuts wall-clock time significantly.
6. Auto Mode — Route to the Right Model, Not the Biggest One
Not every turn needs deepseek-v4-pro with max thinking. A greeting, a status check, or a simple read operation doesn't warrant the expensive model. CodeWhale's Auto Mode runs a cheap routing call first:
Every turn start:
→ deepseek-v4-flash (thinking: off) — ~$0.0001 routing call
→ Analyze complexity
├── Simple/chatty → Flash, thinking off
├── Coding/debugging → Pro, thinking high
├── Architecture → Pro, thinking max
└── Route fails → Local heuristic fallback
The TUI shows the routing decision in real-time. Sub-agents inherit auto mode by default.
Claude Code uses Claude for everything. Codex CLI uses Codex/GPT for everything. Neither dynamically adjusts model selection or thinking intensity per turn. CodeWhale's approach means you're not burning Pro tokens on trivial turns.
7. Open Source + Multi-Provider — No Vendor Lock-In
Both Claude Code and Codex CLI are platform-locked — Anthropic and OpenAI respectively. CodeWhale ships under MIT license and supports 16+ providers:
# Install options — pick your poison
npm install -g codewhale
cargo install codewhale
brew install codewhale
docker pull ghcr.io/hmbown/codewhale
# Provider configuration
codewhale --provider deepseek # DeepSeek V4 (optimized)
codewhale --provider openrouter # 200+ models
codewhale --provider ollama # Local models
codewhale --provider nvidia # NVIDIA NIM
# ...13+ more providers
You can self-host entirely — run CodeWhale against your own GPU with vLLM or Ollama. No data leaves your infrastructure.
The tradeoff: setup is more involved than npm install -g @anthropic/claude-code. You need to pick a provider and configure an API key. But you get vendor independence, data sovereignty, and a skill ecosystem that installs from GitHub repos without any backend service.
The Architecture Lesson
Here's what I keep coming back to: Every AI coding agent faces the same fundamental problem — conflicting signals in every turn. The user says one thing, the project rules say another, the tool output contradicts both, and stale memory adds noise.
Claude Code and Codex CLI punt this problem to the model's implicit alignment. It works most of the time, but when it fails, the failure is silent — the model just does the wrong thing confidently.
CodeWhale formalizes the answer: a written constitution with explicit priority tiers. The model doesn't guess. It consults the hierarchy, applies the rule, and moves forward.
That's not a minor optimization. It's a different philosophy about what an agent should be: not a chat model with file access, but a rule-governed system that happens to run on an LLM.
# What I'd tell anyone building an AI coding agent today:
# 1. Give it a constitution, not just a system prompt
# 2. Design for prefix caching from day one
# 3. Structure failures as input, not noise
# 4. Parallel sub-agents are a feature, not an optimization
# 5. Route to the right model, not the biggest one
# 6. Open source isn't free — it's a strategic choice
# 7. Conflict resolution is the hard problem — solve it explicitly
The code is on GitHub (MIT license). Go read the Constitution yourself — it's the most interesting architecture document I've seen in the AI agent space all year.
Top comments (0)