English · 简体中文 · Русский · Español
A fast, provider-independent coding agent for the terminal, written in Rust.
WhyCodes reads, writes and edits files, runs commands, searches the workspace and drives an LLM through multi-turn tool use — in a full-screen TUI or as a machine-readable one-shot CLI. It focuses on a small native footprint, an idle-efficient TUI, and a workflow that is not tied to any single model provider.
- One native binary. No required runtime dependencies. Search is
in-process (
ripgrepnot needed); optional OS integrations such as Linux bubblewrap strengthen sandboxing when available. - Cross-platform. The same workflow on Linux, macOS and Windows. Linux runs on every CI change; Windows and macOS jobs are available through the multi-OS CI matrix.
- Any provider. Anthropic, OpenAI, Google, GitHub Copilot, Groq, xAI,
DeepSeek, Ollama, OpenRouter, Mistral, Together, or any OpenAI-compatible
endpoint — with an API key or a subscription login (
whycodes auth login). - Fits your project. Loads project instructions from
AGENTS.mdand connects to existing MCP tools and language servers over LSP. - Remembers your work. Persisted sessions, cross-session memory
(
MEMORY.md, semantic recall) and an optional code index.
curl -fsSL https://why.codes/install | bashirm https://why.codes/install.ps1 | iexAdds %LOCALAPPDATA%\Programs\whycodes to your user PATH. No WSL required.
brew tap whycorporation/whycodes https://github.com/whycorporation/whycodes
brew install whycorporation/whycodes/whycodesHomebrew 6+ refuses untrusted third-party taps. The fully-qualified install trusts only this formula. If you already tapped and saw that error:
brew trust --formula whycorporation/whycodes/whycodes
brew install whycodes# Needs libsqlite3 (pkg-config). For a fully static binary:
# cargo build --release -p whycodes-cli --features bundled-sqlite
cargo build --release -p whycodes-cliUpdate with whycodes upgrade (script / cargo installs) or brew upgrade whycodes (Homebrew). Interactive TUI sessions check GitHub for a newer
release and ask on the home screen before installing. Pass --no-auto-update
to skip the prompt. The install scripts verify
release artifacts against the published SHA256SUMS. Downloadable binaries
and uninstall instructions:
docs/packaging.md.
Config and sessions live in ~/.whycodes (%USERPROFILE%\.whycodes on
Windows), or $WHYCODES_HOME when set. 0.6.5 moved them out of the
platform directory used by 0.6.4 and earlier
(~/.config/whycodes or ~/.config/com.whycorporation.whycodes on Linux,
~/Library/Application Support/com.whycorporation.whycodes on macOS,
%APPDATA%\whycorporation\whycodes on Windows). The first launch copies
config.toml, auth.json, and whycodes.db across when the new directory
is empty, and leaves the old files in place.
Shell completions
eval "$(whycodes completions zsh)" # ~/.zshrc
eval "$(whycodes completions bash)" # ~/.bashrc
whycodes completions fish > ~/.config/fish/completions/whycodes.fishexport ANTHROPIC_API_KEY="sk-ant-..."
whycodes -d ./my-project # interactive TUI
whycodes generate "Explain main.rs" -d ./my-project # one-shot
whycodes generate "Summarize the last commit" --format json
whycodes --continue # resume last session
whycodes -P openai -m gpt-4o generate "Refactor this module"Subscription OAuth login (whycodes auth login <provider>) is available
only after installing a local kind: "auth" plugin — WhyCodes ships no
third-party OAuth clients. See docs/auth.md.
The full guide — CLI reference, TUI keys, slash commands, agents, tools and configuration — is in docs/guide.md.
| Agents | build (full access), plan and ask (read-only) as primary agents; general, explore and scout subagents via the task tool; parallel workers in git worktrees via swarm |
| Tools | File edit/patch, in-process search, shell, git and GitHub, web fetch/search, a CDP-driven browser, background jobs, scheduling and to-do tracking |
| Sessions | Persisted per project; resume with --continue / --resume, import transcripts from other agent CLIs, share over the local server |
| Memory | Human-editable MEMORY.md, semantic facts with embeddings, optional code RAG index — all per project, all optional |
| Headless / CI | generate with --format json or stream-json (NDJSON), multiple prompts run concurrently, non-zero exit on failure; whycodes slop reports ΔLOC / verbosity / erosion on the diff |
| Safety | Permission gates per tool, shell command risk analysis, an optional OS sandbox (bubblewrap), HTTP domain allowlists and tool hooks |
| Extensibility | MCP servers (stdio and HTTP), LSP language servers, skills, shell plugins, custom slash commands, themes |
| Embedding | Rust and TypeScript SDKs over daemon protocol v1 (whycodes serve) |
Latest re-measure, Windows AMD64, 2026-09-11 (Ryzen 7 3800X). Linux 2026-09-02 remains the last PTY / PSS snapshot — do not compare Windows first-frame to the Linux ~12 ms PTY row. Method and machines in docs/benchmarks.md:
| Metric | Windows 2026-09-11 | Linux 2026-09-02 |
|---|---|---|
| 1 session PSS | — (/proc only) |
10.5 MB |
| 10 sessions PSS | — | 32.0 MB (~2.4 MB each extra) |
--version |
13.8 ms | 1.4 ms |
| First frame (harness, in-proc) | 0.1 ms (console inherit) | 12 ms (80×24 PTY) |
| Idle redraws (harness, 3 s) | 0.0 /s | 0.3 /s |
The TUI paints only when something changed. This Windows run’s 3 s harness idle is 0.0 redraws/s (Linux 2026-09-02 was 0.3/s); the product target is still 0 redraws/s, not a frames-per-second race. The first-frame harness writes one CSI splash (no ratatui); spawn-to-exit matches --version (~14 ms). Interactive home still hydrates after that paint.
Workspace line coverage is 85.58% (Linux x86_64, 2026-08-21). CI fails below 82%, with twelve foundational crates held at 100% production-code line coverage — see docs/coverage.md.
| Doc | What it covers |
|---|---|
| docs/guide.md | Usage: CLI, TUI, agents, tools, config, SDK |
| docs/auth.md | API keys, OAuth, credential import |
| docs/architecture.md | Crate map and layering |
| docs/roadmap.md | Current focus and deferred work |
| docs/knowhow.md | Hard-won bugs (TUI, tty, silent exits) |
| docs/tui-term-matrix.md | Manual TUI pass on Alacritty / Kitty / VTE |
| docs/benchmarks.md | Measuring startup, RSS, idle draws |
| docs/coverage.md | Measuring line coverage |
| docs/budgets.md | CI quality budgets |
| docs/packaging.md | Homebrew, installers, release download counts |
Contributions are welcome. CONTRIBUTING.md is the short path from clone to a merged change; AGENTS.md holds the rules for coding agents working in this repo. By participating you agree to the Code of Conduct. Help and bug reports: SUPPORT.md. Please report vulnerabilities through SECURITY.md, not public issues.
Same links as why.codes:
WhyCodes is independently developed and needs funding to keep shipping. Sponsor the project on GitHub Sponsors.
MIT · why.codes · GitHub · Discord · Telegram · X @whycodesai · YouTube · Sponsor