CrypticMechanic 🔧

CrypticMechanic is a premium developer tool that translates raw, confusing error logs, terminal outputs, and stack traces into human-readable diagnoses and clear, actionable steps. Powered by Google's Gemini models, it brings clarity to chaotic errors so you can fix bugs faster and keep coding.

Available as both a responsive Web Application (with full PWA support) and a lightweight, self-contained Portable Desktop App for Windows.

---

✨ Features

• Modular Provider Architecture & Extension Engine:
  • Pluggable AI engine layer (src/lib/providers/AIProvider.js) cleanly decoupling the UI from inference backends.
  • Universal provider registry (src/lib/providers/providerRegistry.js) for seamless runtime selection across cloud and local providers.
  • Zero-merge-conflict dynamic extension auto-discovery (src/lib/extensionRegistry.js) allowing downstream capabilities without modifying core files.
• Intuitive UI/UX & Real-Time Streaming: Paste your raw logs and watch diagnoses stream in live with generateContentStream. Side-by-side or clean stacked layout highlights a focused Diagnosis and a checkable list of Actionable Fixes.
• Interactive Checklists: Markdown task checkboxes (- [ ] / - [x]) are fully interactive toggles so developers can tick off steps as bugs are resolved directly within the diagnostic output.
• Enhanced Code Blocks:
  • Language badge headers (BASH, JAVASCRIPT, DOCKERFILE, etc.).
  • Dedicated per-code-block copy buttons with immediate visual feedback (Copied!).
  • Dark terminal container (#14161f) with high WCAG contrast across all themes, including Clean Room (light mode).
• Workflow & Ergonomics:
  • Drag-and-Drop: Drop .log or .txt files directly onto the log input area.
  • Keyboard Shortcuts: Ctrl+Enter (or Cmd+Enter) in the log input triggers translation; Escape closes open drawers.
  • Export Options: One-click "Copy Markdown", "Export as GitHub Issue" (generates ready-to-paste markdown issue template with collapsible raw logs <details> and actionable checkboxes), and "Download .md" (CrypticMechanic-Analysis.md).
  • Token Estimator: Real-time character and token counter (e.g. 1,200 chars (~300 tokens)).
  • 9 Polyglot Error Presets: Instant one-click test logs covering Node.js (MODULE_NOT_FOUND), Docker port conflicts, Python KeyError, Git merge conflicts, Rust borrow checker, Kubernetes Pod CrashLoopBackOff & OOMKilled (Exit 137), Go runtime nil pointer dereference panic, Spring Boot UnsatisfiedDependencyException, and C++/GDB SIGSEGV segmentation faults.
• Highly Customisable Outputs: Customise how your responses are generated via the settings panel:
  • Detail Level: Choose between Concise (fast checklist), Standard, or Thorough (deep explanation).
  • Response Format: Toggle between Diagnosis + Fixes, Step-by-Step, Root Cause, or Quick Fix.
  • Response Tone: Match your style with Professional, Friendly, or ELI5.
• 5 Premium CompSci & SWE Themes:
  • 🌌 Midnight Terminal (Default) – Sleek, high-contrast dark theme.
  • 🚨 Kernel Panic – Vibrant, error-state dark theme with deep crimson accents.
  • 📟 Circuit Board – Classic matrix-green console vibe.
  • 🟦 Blue Screen – Nostalgic retro BSOD crash theme.
  • 🥼 Clean Room – Sleek, premium light theme for crisp day reading with dark terminal code blocks.
• Next-Gen Gemini 3 & 2.5 Model Lineup:
  • gemini-3-flash (Default / Recommended – Next-gen speed and surgical reasoning)
  • gemini-3-pro (Deepest reasoning & complex multi-file stack traces)
  • gemini-2.5-flash (Balanced & fast)
  • gemini-2.5-flash-lite (Cheapest & ultra-fast)
  • gemini-2.5-pro (High capability)
  • Custom Model ID: Type any model identifier (e.g. gemini-3.1-pro) to keep the app future-proof.
• Deterministic Troubleshooting: Configured with temperature: 0.2 and native systemInstruction parameters for consistent, accurate fixes.
• Local History with Model Badges: Browse recent translations with model badge pills (e.g. 3 Flash, 3 Pro) and delete individual items or clear history.
• Offline & Desktop Native:
  • Electron Portable App: Downloadable, zero-install portable .exe executable for Windows.
  • PWA Ready: Installable directly onto your system from Chromium-based browsers.

---

🛠️ Tech Stack

• Frontend Core: React 19, Vite 8, JavaScript (ESM)
• Architecture: Pluggable AIProvider base class, dynamic providerRegistry, and zero-conflict extensionRegistry auto-discovery
• Styling: Vanilla CSS with custom properties (CSS variables) for real-time theme swapping.
• Icons: Lucide React
• Markdown Rendering: react-markdown with syntax highlighting via react-syntax-highlighter (Prism oneDark).
• AI Integration: Google Generative AI SDK (@google/generative-ai) with real-time streaming
• Desktop Wrapper: Electron 36 & electron-builder

---

🚀 Getting Started

Prerequisites

Ensure you have Node.js installed (v18.0.0 or later is recommended).

Installation & Local Dev

1. Clone the Repository:

   git clone https://github.com/MaskirovkaOtdel/CrypticMechanic.git
   cd CrypticMechanic

2. Install Dependencies:

   npm install

3. Run Web Dev Server:

   npm run dev

   Open your browser and navigate to the address shown in the terminal (usually http://localhost:5173).

---

🖥️ Desktop App (Electron)

CrypticMechanic can run as a standalone desktop application.

Run Desktop in Development

To run the Vite dev server bundled inside an Electron window:

npm run electron:dev

Build Portable Windows Executable

To package the app into a single, self-contained executable (CrypticMechanic-Portable.exe):

npm run electron:build

The resulting executable will be saved in the release/ directory. Double-click it to run without installing or starting any terminal scripts.

---

⚙️ Configuration & Settings

To access customization options, click the Settings (Gear) icon in the top header.

• AI Provider:
  • Choose between active providers registered in the engine (Google Gemini Cloud default, with dynamic extension support).
• API Key:
  • Obtain a free API key from Google AI Studio and paste it into the field.
  • Use the eye toggle button to view or obscure your key.
  • Your key is stored locally in your browser/app's localStorage and is never shared or transmitted anywhere else except directly to Google's API endpoint.
• Model Choice:
  • gemini-3-flash (Default / Recommended - Fastest & Next-Gen)
  • gemini-3-pro (Deepest Reasoning / Complex Stack Traces)
  • gemini-2.5-flash (Balanced & Fast)
  • gemini-2.5-flash-lite (Cheapest)
  • gemini-2.5-pro (High Capability)
  • Custom Model ID... (Enter any custom model name)
• Prompt Customizer: Adjust the Detail Level, Response Format, and Tone to modify the system prompt.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Developed with 💻 by Thodoris Efstathiadis (MaskirovkaOtdel).