CrashSense AI

CrashSense AI is an open-source web app that turns crash logs into plain-English diagnosis. It is built for Minecraft modpacks, Docker and Unraid containers, GitHub Actions, and general application logs.

The app is privacy-first for the MVP: local rules always run first, AI is used only as a fallback when configured, sensitive values are redacted before analysis output, and no database is used.

Features

• Mobile-first dark UI for pasting logs and choosing Minecraft, Docker/Unraid, GitHub Actions, or Unknown.
• In-app setup panel for rules-only mode, local Ollama/Gemma, or a remote OpenAI-compatible provider.
• Log file upload, paste-from-clipboard, privacy preview, and redaction counts before analysis.
• Real streamed analysis progress from the server, including the AI fallback/provider step.
• Retry with AI and force AI triage controls.
• Ranked findings with summary, likely cause, confidence, evidence context, and fix steps.
• Rule coverage for common failures:
  • Java version mismatch
  • Fabric, Forge, or NeoForge mod mismatch
  • missing dependency
  • duplicate mod
  • mixin transformation errors
  • missing Java classes
  • mod version conflicts
  • corrupt chunks/world saves
  • datapack and resource loading errors
  • bad config files
  • client/server-only mod mismatch
  • Java null pointer crashes
  • permission denied and PUID/PGID mismatches
  • out of memory
  • disk full
  • port already in use
  • connection refused
  • database connection failures
  • file path not found
  • GPU/NVIDIA runtime not detected
  • Docker volume mapping issues
  • DNS failures
  • TLS certificate failures
  • image pull failures
  • container healthcheck failures
  • missing GitHub Actions secrets
  • checkout failures
  • GitHub token permission scope failures
  • package install failures
  • automated test failures
  • runtime version mismatches
  • dependency cache corruption
  • native segmentation faults
• Privacy redaction for tokens, secret-like values, emails, IP addresses, webhook URLs, and user filesystem paths.
• Copy-ready Discord replies and GitHub issue templates.
• Export markdown and JSON reports.
• Open a prefilled GitHub issue URL.
• Portable Windows .exe build target.
• Optional OpenAI-compatible enrichment controlled by environment variables.
• Local AI support through OpenAI-compatible servers such as Ollama or LM Studio.

Quick Start

Use Node.js 20.19.0 or newer. Node 22 LTS or Node 24 LTS is recommended for the desktop build tooling.

Option A: Guided Setup

Run the guided setup menu:

npm install
npm run setup

The setup command will:

1. Ask whether you want local AI, remote API AI, or rules-only mode.
2. Create .env.local for the selected setup.
3. For local AI, check whether Ollama is installed.
4. Pull the recommended Gemma 4 model when Ollama is available.
5. Print the exact next command to run.

Then start the app:

npm run dev

Open http://localhost:3000.

You can also use the setup panel at the top of the app to switch modes, save .env.local, and check whether the configured AI provider/model is reachable.

Option B: One-Line Local AI Setup

Use this after cloning the repo if you want the recommended local Ollama + Gemma 4 setup:

npm install && npm run setup:local && npm run dev

If Ollama is not installed yet, the setup command will tell you to install it from ollama.com/download, reopen your terminal, then run:

npm run setup:local

Option C: Remote API Setup

Use this if you want to provide an OpenAI-compatible API key instead of running a local model:

npm install
npm run setup:api

Then edit .env.local and replace:

CRASHSENSE_AI_API_KEY=replace-me

Start the app:

npm run dev

Option D: Rules Only

Use this if you do not want any AI calls:

npm install
npm run setup:rules
npm run dev

Local AI Checklist

For local Gemma 4 fallback:

1. Install Ollama from ollama.com/download.
2. Close and reopen your terminal.
3. Confirm Ollama is available:

ollama --version

4. Pull the model:

npm run ai:ollama:pull

5. Confirm .env.local contains:

CRASHSENSE_AI_MODE=fallback
CRASHSENSE_AI_BASE_URL=http://localhost:11434/v1
CRASHSENSE_AI_MODEL=gemma4:e4b
CRASHSENSE_AI_API_KEY=
CRASHSENSE_AI_TIMEOUT_MS=120000

6. Start CrashSense AI:

npm run dev

AI Fallback

CrashSense AI is rules-first. In the default recommended setup, AI only runs when no specific rule matches, or when the only match is the generic crash fallback.

If the result says Generic crash, CrashSense AI should hand the log to AI triage when AI is configured. If AI is not configured or the provider is unreachable, the UI will show AI fallback: not-configured or AI fallback: failed and include setup/provider fix steps instead of silently pretending the generic rule is enough.

Use Force AI triage when a rule matched but you still want the configured AI provider to review the redacted log and improve the wording/fix plan.

Supported modes:

• fallback: use AI only when the rules database does not identify a specific cause.
• always: use AI to enrich every result.
• off: never call an AI provider.

Local AI With Ollama

Recommended local model: Gemma 4 E4B for most developer laptops. Larger Gemma 4 variants can improve reasoning if your hardware can run them comfortably.

Google describes Gemma 4 as an open model family with E2B, E4B, 26B MoE, and 31B Dense sizes, and lists Ollama and LM Studio among supported tools. See Google's Gemma 4 announcement and the Ollama Gemma 4 library page:

• Google Gemma 4 announcement
• Ollama Gemma 4 library

Install Ollama from ollama.com/download, then pull the local model:

npm run ai:ollama:pull

If Ollama is missing, the npm command will print the install link and setup steps instead of failing with a raw command-not-found error.

Start or test the model:

npm run ai:ollama:run

Create .env.local:

CRASHSENSE_AI_MODE=fallback
CRASHSENSE_AI_BASE_URL=http://localhost:11434/v1
CRASHSENSE_AI_MODEL=gemma4:e4b
CRASHSENSE_AI_API_KEY=
CRASHSENSE_AI_TIMEOUT_MS=120000

Ollama's OpenAI-compatible server normally listens on http://localhost:11434/v1. No API key is required for local Ollama.

Remote API Provider

Any OpenAI-compatible chat completions provider can be used by changing the base URL, model, and API key.

Create .env.local:

CRASHSENSE_AI_MODE=fallback
CRASHSENSE_AI_BASE_URL=https://api.openai.com/v1
CRASHSENSE_AI_MODEL=gpt-4o-mini
CRASHSENSE_AI_API_KEY=your-api-key

The older OPENAI_BASE_URL, OPENAI_MODEL, and OPENAI_API_KEY names are still accepted for compatibility.

The AI prompt is constrained to use only the redacted log and rule result. Evidence returned by AI is accepted only when the excerpt appears in the redacted log.

Example Logs

Sample logs live in examples:

• minecraft-java-mismatch.log
• minecraft-missing-dependency.log
• minecraft-mixin-error.log
• minecraft-null-pointer.log
• docker-port-in-use.log
• docker-database-refused.log
• docker-volume-mapping.log
• unraid-nvidia-missing.log
• github-actions-missing-path.log
• github-actions-missing-secret.log
• github-actions-package-install.log
• minecraft-corrupt-chunk.log
• privacy-redaction.log

The web UI also includes built-in examples.

Architecture

src/app/page.tsx                    Web UI
src/app/api/analyze/route.ts        Server-side analysis API
src/app/api/analyze/stream/route.ts Streamed analysis API
src/app/api/setup/route.ts          Local setup and provider health API
src/lib/analysis                    Parser, rule definitions, redaction, formatters, AI enrichment
src/lib/crashsense.ts               Bot/App-friendly analyzer export
src/lib/examples.ts                 Built-in example logs
desktop/main.cjs                    Electron desktop wrapper
examples                            Standalone test logs
.github/workflows/ci.yml            Lint, test, build, and production audit

The analyzer core is independent from the UI. A Discord bot, GitHub App, CLI, or worker can import:

import { analyzeCrashLog } from "@/lib/crashsense";

const result = analyzeCrashLog({
  logType: "minecraft",
  log: crashLog,
});

API

POST /api/analyze

{
  "logType": "minecraft",
  "log": "paste crash log here",
  "forceAi": false
}

Response:

{
  "summary": "The log points to a Java runtime or bytecode version mismatch.",
  "likelyCause": "The app or modpack was built for a different Java version than the one currently running it.",
  "confidence": "high",
  "evidence": ["> L2: java.lang.UnsupportedClassVersionError..."],
  "fixSteps": ["Check the required Java version..."],
  "discordReply": "...",
  "githubIssue": "...",
  "markdownReport": "...",
  "jsonReport": "...",
  "githubIssueUrl": "https://github.com/new?...",
  "detectedRules": ["java-version-mismatch"],
  "findings": [],
  "redactions": []
}

POST /api/analyze/stream accepts the same body and returns text/event-stream events:

event: stage
data: {"id":"rules","label":"Running rule parser","status":"done","message":"Matched 1 rule(s)."}

event: result
data: {"summary":"..."}

GET /api/setup?check=1 returns the current public AI config and provider health. POST /api/setup writes .env.local for local use and updates the current server process.

Desktop App

Build the portable Windows executable:

npm run desktop:build

The generated file is written to:

dist-desktop/CrashSense AI-0.1.0-win-x64.exe

The desktop app bundles CrashSense AI itself. It does not bundle Ollama or Gemma model files; use the in-app setup panel to point it at local Ollama or a remote OpenAI-compatible provider.

Rule Authoring

Rules live in src/lib/analysis/rule-definitions.ts. Add a structured rule definition rather than changing matcher logic.

Each rule should include:

1. Stable id.
2. Human-readable title, summary, and cause.
3. Regex patterns as strings.
4. confidence and specificity.
5. fixSteps.
6. Optional appliesTo.
7. Tests in src/lib/analysis/analysis.test.ts.

Evidence context, scoring, ranking, and report formatting are handled by the shared analyzer.

Development

npm test
npm run test:ui:install
npm run test:ui
npm run lint
npm run build
npm audit --omit=dev
npm run desktop:build

CI runs lint, unit tests, Playwright UI tests, build, and production audit on push and pull requests to main.

Contributing

Contributions are welcome. Good first issues include:

• Add more real-world crash signatures and example logs.
• Improve fix steps for specific launchers, mod loaders, containers, or CI runners.
• Add hosted deployment configuration.
• Build a Discord bot or GitHub App around analyzeCrashLog.
• Add private paste redaction previews and user-controlled redaction toggles.

Roadmap

• Hosted demo.
• More Minecraft launcher-specific diagnostics.
• Unraid template rule packs.
• GitHub issue comment helper.
• Discord bot command.
• Signed desktop releases.

License

MIT