The Magic

You run a command. It fails. You type wtf. Gemini analyzes the exact error that just occurred — but instead of just handing you a command to blindly paste, it tells you how confident it actually is, and behaves differently depending on the answer.

No re-running heavy build scripts. No scrolling. No copy-pasting.

Guide, Not Oracle

Most AI CLI tools sound equally confident whether they're right or making it up. wtf-terminal doesn't:

| Confidence | What you get | |---|---| | ✨ High | The buffer clearly shows a known error. Diagnosis, the exact evidence line, the fix command, and a step to verify it worked. | | ⚠ Medium | A plausible cause, visibly flagged as "likely, not certain" — read the evidence before running it. | | 🧭 Low | The error message isn't actually in the buffer. No command is shown at all — instead you get concrete next steps (a file to check, a flag to try) so you build the last bit of understanding yourself. |

This isn't the model grading its own homework: every claim it makes is checked in code. It has to quote the exact line from your terminal that supports its diagnosis — if that quote isn't verbatim in your real buffer, the confidence tier is automatically downgraded before you ever see it. Any suggested command that looks destructive (rm -rf, git reset --hard, DROP TABLE, etc.) gets a visible warning. And nothing is ever auto-executed — wtf prints, you decide, you run it.

Under the Hood

wtf-terminal uses a lightweight, invisible PTY wrapper (node-pty) and native OSC-133 shell integration. It wraps your native shell (Bash, Zsh, or PowerShell) and quietly tracks the output of your last failed command via a local IPC socket — nothing is logged to disk, nothing leaves your machine until you run wtf.

• Local Redaction First: Secrets are scrubbed from the buffer before it's ever sent to the AI (see Privacy below).
• Shell-Aware Fixes: The AI knows whether you're in PowerShell or bash, so it won't suggest export to a PowerShell user.
• Live Model Discovery: Queries Gemini for whichever models actually exist right now (cached 24h) instead of a hardcoded list that silently breaks as models are renamed.
• Hedged Model Racing: The primary model gets a ~2.5s head start; backups launch only if it's slow or fails, and the first verified answer wins. Healthy day = exactly one API request per fix (your free-tier quota is respected); bad day = a backup is already running instead of you waiting through a full timeout.
• Nested Session Lock: Prevents recursive wrapping by locking the WTF_SESSION_ID.

For the full system design — file-by-file responsibilities, data flow, and every architectural decision explained — see ARCHITECTURE.md and DESIGN.md.

Platform Support

This release is Windows-first. Linux and macOS integration is actively being worked on and lands in an upcoming release.

| Platform | Status | |---|---| | ✅ Windows (PowerShell 5 / 7) | Supported today | | ✅ Windows (WSL, bash) | Works today | | 🚧 Linux (bash / zsh) | Hooks are built and in testing — official support in an upcoming release | | 🚧 macOS (zsh) | In testing — official support in an upcoming release | | ❌ cmd.exe | Not supported — wtf falls back to PowerShell |

Installation

npm install -g wtf-terminal

You'll need Node.js 18 or newer. Installation compiles a small native component (node-pty); on Windows this is usually seamless, but if it fails, install the Visual Studio Build Tools and retry.

Or build from source:

git clone https://github.com/Akshay-1024/wtf-terminal.git
cd wtf-terminal
npm install
npm run build
npm link   # makes the `wtf` command available globally

Setup & Free API Key (BYOK)

wtf-terminal is 100% free to use. It uses a Bring-Your-Own-Key (BYOK) model, meaning you provide your own free Gemini API key, and the CLI stores it securely in your OS Keychain (Windows Credential Manager / macOS Keychain / Linux Secret Service).

1. Get your free key: Go to Google AI Studio and generate a free Gemini API key. (The free tier gives you 1,500 requests per day at zero cost).
2. Authenticate the CLI:

   wtf auth

   Paste your key when prompted — input is masked with * and the key goes straight into your OS keychain, never to disk or screen.
3. Start a session:

   wtf start

   Your shell looks and behaves exactly as before — wtf is now quietly watching for failures.

Day-to-Day Use

4. Work normally. Run your builds, git commands, scripts — nothing changes.
5. When a command fails, type:

   wtf

   In ~3 seconds you get a diagnosis, the exact line of evidence from your terminal, and (at High/Medium confidence) the fix command.
6. Read the confidence tier before acting. High = evidence-backed fix. Medium = plausible, verify the evidence line first. Low = no command shown by design; you get concrete next steps instead. Destructive suggestions (rm -rf, git reset --hard, …) always carry a visible warning — and nothing ever runs unless you run it.
7. Trust the staleness heads-up. If wtf says "N commands have succeeded since this failure", you're asking about an old error — it may already be resolved.
8. Done? Type exit (or wtf stop) to unwrap your shell.

(Pro tip: add wtf start --quiet to your ~/.bashrc or $PROFILE to wrap every terminal automatically, without the splash screen).

Privacy & Security

Your terminal output often contains sensitive information. wtf-terminal includes a Local Secret Redaction Engine that scrubs your buffer before it ever leaves your machine.

The following patterns are automatically stripped and replaced with [REDACTED]:

• Google / Gemini API keys (yes — including the very key you use with wtf)
• AWS Access & Secret Keys
• GitHub Personal Access Tokens (Classic & Fine-Grained)
• Stripe live/test keys
• Slack Bot & User Tokens
• Passwords embedded in connection URLs (e.g., MongoDB, PostgreSQL)
• RSA, EC, and DSA Private Keys
• Standard .env secrets (API_KEY, JWT_SECRET, etc.)

Roadmap & Future Plans

The CLI is live on npm, Windows-first. Multi-model and auto-execution support are deliberately deferred to keep the trust model simple while the platform base grows.

Phase 1: Open Source Release

• [x] Publish v1.0.0 to NPM globally (Windows-first).
• [ ] Official Linux & macOS support — hooks built, in testing now.
• [ ] Implement support for OpenAI (ChatGPT) and Anthropic (Claude) APIs.
• [ ] Support for Local LLMs (Ollama) for true air-gapped security.
• [ ] Auto-Execution mode (Press Enter to run the suggested fix) — paused pending a dedicated risk-review pass; this is the highest-scrutiny feature in the roadmap given it would let AI-suggested commands run unattended.
• [ ] wtf --another — explicitly ask for a different angle on the same failure. Re-running wtf on identical evidence deliberately gives a consistent diagnosis (determinism = trust); this flag would opt in to an alternative hypothesis by raising temperature and telling the model what the user has already seen and rejected. Deliberate variety, never ambient randomness.

Phase 2: Web Landing Page — ✅ Done

The landing page shipped: interactive multi-scenario terminal demo, SEO-optimized static site, waitlist form. Lives in its own repo (wtf-cli-landing).

Contributing

This codebase follows SOLID principles throughout, specifically so it's approachable to contribute to — start with ARCHITECTURE.md for the data-flow overview and a "where do I add X?" table (new AI provider, new secret pattern, new shell, etc.), then DESIGN.md for the reasoning behind every pattern used. Run npm test before opening a PR — 123 tests cover the trust layer, redaction, buffer parsing, IPC protocol, and AI model racing/fallback.

Built by Akshay
Because terminal errors shouldn't break your flow state.