| 1 | # Codewhale messaging brief |
| 2 | |
| 3 | Owner of English home copy: `lib/i18n/dictionaries/en/home.ts`. Style rules: `COPY_STYLE.md`. |
| 4 | Facts: `docs/features.toml`, `docs/*.md`. Research date: 2026-10-04. |
| 5 | |
| 6 | ## 1. How the field advertises (condensed) |
| 7 | |
| 8 | | Tool | Hero (short quote) | Leads with | CTA | Any-model / open source | |
| 9 | | --- | --- | --- | --- | --- | |
| 10 | | OpenCode | "The open source AI coding agent" | LSP, multi-session, share links; 208K stars, 950 contributors | install command; "Read docs" | "connect any model from any provider" | |
| 11 | | Pi | "this one is yours" | minimal harness, 15+ providers, tree history | npm command; "Documentation" | MIT; switch models mid-session | |
| 12 | | Codex CLI | "a coding agent from OpenAI that runs locally" | terminal, IDE, app, cloud surfaces | curl installer | Apache-2.0 repo; OpenAI models | |
| 13 | | Claude Code | "Hand Claude a bug fix, test, or multi-day migration" | issues to PRs, long refactors; customer logos | "Download for macOS"; curl | single vendor; plan pricing | |
| 14 | | Cline | "The Open Coding Agent" | multi-file diffs, bash, Plan then Act; 11M+ installs | "Get Started" | "Every model, your choice"; Apache-2.0 | |
| 15 | | Zed | "Your last next editor" | Rust speed, parallel agents; named quotes | "Download now" / "Clone source" | "doesn't lock you into one model" | |
| 16 | | Cursor | "your coding agent for building ambitious software" | parallel agents; Fortune 500, CEO quotes | "Download for macOS" | model picker incl. Auto | |
| 17 | | Amp | "built for the frontier" | multi-model routing, cloud machines | sign up | "uses them all" | |
| 18 | | Warp | "Open Platform for Automating Development" | any model or harness; 800k+ devs, logos | "Request Early Access" | bring your own model | |
| 19 | | Aider | "AI pair programming in your terminal" | codebase map, git; 44K stars, 15B tokens/week | pip command | "almost any LLM, including local" | |
| 20 | | Factory | "Build Your Software Factory" | plan, build, review, ship | docs links | "multiple model providers" | |
| 21 | | Kilo Code | "One open agent for every developer workflow" | 500+ models, zero markup, MIT; 5M+ users | "Code for Free" | BYO keys, local, "No silent model switching" | |
| 22 | | Roomote (ex-Roo) | "The cloud coding agent you actually own." | verify, cross-model review | "Try now free" | source-available | |
| 23 | | Crush | "Your new coding bestie" | multi-model, LSP, MCP; 28.5k stars | brew / npm / winget | OpenAI- or Anthropic-compatible APIs | |
| 24 | | Gemini CLI | "Build, debug & deploy with AI" | large codebases, workflows | npm command | Gemini only | |
| 25 | | Hermes, OpenHands, Deep Agents, MiniMax, Kimi | category sentence + table of 5-7 capabilities | install first | "Use any model you want" / "Model-agnostic" | | |
| 26 | |
| 27 | openai.com/codex and ampcode.com blocked fetches; Codex and Amp rows use their README and manual. |
| 28 | |
| 29 | ## 2. Patterns that persuade |
| 30 | |
| 31 | 1. **Category in the first five words.** "The open source AI coding agent" (OpenCode). The reader knows what it is before reading on. |
| 32 | 2. **One concrete differentiator in the subhead.** "connect any model from any provider" (OpenCode). "500+ models, zero markup" (Kilo). |
| 33 | 3. **Install command above the fold.** OpenCode, Pi, Aider, Crush show a copyable command, not only a button. |
| 34 | 4. **Social proof as plain numbers.** "208K GitHub Stars · 950 Contributors" (OpenCode); "44K stars, 6.8M installs" (Aider). |
| 35 | 5. **Capabilities as verbs on real objects.** "Edits across your project", "Runs bash commands" (Cline). |
| 36 | 6. **Control stated as a mechanism.** "Plan, then Act" with approval steps (Cline); "No silent model switching" (Kilo). |
| 37 | 7. Weaker patterns to avoid: manifesto subheads (Cursor), clever slogans (Zed, Crush), enterprise logos we cannot claim. |
| 38 | |
| 39 | ## 3. Positioning |
| 40 | |
| 41 | For developers who want a coding agent they can inspect and point at any model, Codewhale is an |
| 42 | open-source (MIT) coding agent for the terminal, scripts, and CI. Unlike single-vendor agents, it |
| 43 | works with over 40 built-in provider routes, any OpenAI-compatible endpoint, and local models. |
| 44 | Proof: Plan/Work/Operate modes, Ask/Auto-Review/Full Access approvals, an OS sandbox, `/receipts`, |
| 45 | `/preview-request`, and a community of 41k GitHub stars and 244 contributors. |
| 46 | |
| 47 | ## 4. Hero candidates |
| 48 | |
| 49 | **A. Recommended.** |
| 50 | Headline: "The open-source coding agent for any model" |
| 51 | Subhead: "{brand} reads your project, edits files, and runs your tests from your terminal. Connect a hosted or local model, and choose which actions need your approval." |
| 52 | Why: category and differentiator in seven words; matches the README tagline, so docs and site agree; |
| 53 | noun phrase translates without English word order tricks; subhead adds the action list and control. |
| 54 | |
| 55 | **B.** Headline: "A coding agent that works with your models" |
| 56 | Subhead: same as A. |
| 57 | Why: warmer and reader-centred, but "open source" moves out of the headline and the README tagline diverges. |
| 58 | |
| 59 | **C.** Headline: "Describe the change, then review the diff" |
| 60 | Subhead: "{brand} is an open-source coding agent for your terminal. It works with hosted and local models, and it asks before it acts in Ask mode." |
| 61 | Why: shows the workflow. Rejected as the lead because it hides the category and depends on English imperative rhythm. |
| 62 | |
| 63 | ## 5. Proof points, in priority order |
| 64 | |
| 65 | 1. Any model: built-in provider routes, any OpenAI-compatible endpoint, local models (Ollama, vLLM, SGLang). |
| 66 | 2. Control you can check: modes, approval postures, sandbox, `/undo`, `/receipts`, `/preview-request`. |
| 67 | 3. Open source under MIT; no Codewhale account needed for the terminal or local browser. |
| 68 | 4. Runs where you work: `codewhale`, `codewhale exec`, `codewhale web`, `codewhale review --pr N`, Runtime API. |
| 69 | 5. Long work: `/goal`, sub-agents, Fleet with a pre-spend check, checked-in workflows. |
| 70 | 6. Extend: MCP, skills, plugins, hooks, Claude Code plugin compatibility. |
| 71 | 7. Community: GitHub stars and contributors, rendered from live data, never typed into copy. |
| 72 | |
| 73 | ## 6. Translation-safety rules (18 locales) |
| 74 | |
| 75 | 1. Write literal declarative sentences. One claim per sentence. |
| 76 | 2. Keep each sentence at 20 words or fewer. Headlines at 8 words or fewer. |
| 77 | 3. No idioms, puns, wordplay, slang, or cultural references ("bestie", "your last next editor"). |
| 78 | 4. No paired imperative slogans ("Describe X. Review Y.") or verbless fragments that rely on English rhythm. |
| 79 | Prefer a full noun phrase or one complete sentence. |
| 80 | 5. Use a single verb where one exists: "stop", not "shut down"; "divide", not "split up"; "check", not "look over". |
| 81 | 6. Use the glossary terms below exactly. Do not translate them, pluralize them, or replace them with synonyms. |
| 82 | 7. Commands, flags, paths, slash commands, and numbers are untranslated tokens: `codewhale exec`, `/receipts`. |
| 83 | 8. Keep `{brand}`, `{version}`, `{tag}` placeholders verbatim; one `{brand}` per hero lede. |
| 84 | 9. Avoid counts that drift (provider totals, star counts) in dictionary strings; render them from data. |
| 85 | 10. Avoid "it", "this", and "that" when the referent is in another sentence. |
| 86 | 11. Same claim, same words: reuse the docs sentence rather than paraphrasing it. |
| 87 | 12. No em-dash asides; use a period, comma, or colon. |
| 88 | |
| 89 | ## 7. Glossary (fixed terms, from `lib/content/vocabulary.ts` and `docs/features.toml`) |
| 90 | |
| 91 | | Term | Kind | Rule | |
| 92 | | --- | --- | --- | |
| 93 | | Codewhale | brand | never translated; `{brand}` in hero lede | |
| 94 | | Plan, Work, Operate | modes | keep English, capitalized | |
| 95 | | Ask, Auto-Review, Full Access | approval postures | keep English, capitalized | |
| 96 | | Fleet, Workflow, Lane, Runtime | product terms | keep English; definitions in vocabulary.ts | |
| 97 | | Provider, Model, Advisor | route identity | translate the common noun, keep the definition | |
| 98 | | Receipts (`/receipts`) | command | command token stays English | |
| 99 | | Request preview (`/preview-request`) | command | command token stays English | |
| 100 | | Goal (`/goal`), sub-agents, skills, plugins, hooks, MCP | features | MCP stays English | |
| 101 | | `codewhale`, `codewhale exec`, `codewhale web`, `codewhale review --pr N` | commands | never translated | |
| 102 | | Computer Use | plugin | English name, marked preview | |
| 103 | | CodeWhale GUI | community VS Code extension | proper noun | |
| 104 |