Reset & Diagnostics

Reset preferences, clear cache, and run diagnostics to fix persistent issues.

Overview

When something in Yukkai isn't working as expected — a provider won't connect, sessions keep failing, or the app feels sluggish — the Reset & Diagnostics tools help you figure out what's wrong and, when needed, restore things to a clean state.

There are two complementary capabilities:

Capability What it does When to reach for it
Diagnostics Runs a series of automated health checks across your configuration, providers, permissions, storage, and local models. Multiple features are misbehaving or you want a full health report before making changes.
Reset Clears selected data — cache, preferences, sessions, local indexes — so Yukkai can rebuild them from scratch. You've confirmed the issue is app-wide and simpler fixes haven't worked.

⚠️ Reset is not a first step. It can remove preferences, provider configuration, session state, and cached data. Always try diagnostics and a new session first.

How it works

Diagnostics

When you trigger a diagnostic run, Yukkai performs a checklist of system checks behind the scenes. Each check inspects a different subsystem and reports a status — pass, warn, or fail — along with a short explanation.

Checks typically include:

  • App configuration — verifies core settings are present and valid.
  • Required folders — confirms that the directories Yukkai needs exist and are writable.
  • Provider connectivity — tests each configured AI provider's connection.
  • Permission state — checks whether macOS permissions (Notifications, Full Disk Access, etc.) are granted and detected.
  • Storage — inspects available disk space and local database integrity.
  • Local model state — verifies that any downloaded local models are intact and loadable.
  • Connected services — validates integrations such as Calendar, Telegram, or MCP servers.

A diagnostic report can be exported so you can share it with support or keep it for reference.

Reset

Yukkai's reset is granular — you choose what to clear rather than wiping everything at once. The categories you can reset individually include:

Reset target What gets cleared
Cache Temporary files, image caches, downloaded media, and session-derived data.
Preferences App-level settings such as default model, theme, window layout, and notification preferences.
Sessions Active and saved conversation sessions.
Local indexes RAG vector indexes and on-device knowledge bases (will be rebuilt automatically).
Provider configuration API keys, provider settings, and connection details. This will disconnect all providers.

After resetting a category, Yukkai rebuilds what it can on the next launch. For example, clearing local indexes triggers a re-index of your knowledge base on restart.

How to use it

1. Run diagnostics first

Recommended path: Help menu → Diagnostics
  1. Open the Help menu in Yukkai's menu bar.
  2. Select Diagnostics.
  3. Wait for the checks to complete — usually a few seconds.
  4. Review the results. Each line shows a status icon and a one-line description.
  5. If any check reports warn or fail, read the explanation and follow the suggested fix.
  6. Optionally click Export Report to save a text or PDF copy.

2. Try a new session

Before resetting anything, start a new conversation session and reproduce the issue. If the problem doesn't appear in a fresh session, the issue was tied to a stale session — no reset needed.

3. Reset only what's broken

If diagnostics confirm a systemic problem:

  1. Go to Settings → Advanced → Reset.
  2. Pick only the category that relates to your issue.
  3. Confirm the reset prompt.
  4. Restart Yukkai.

Tip: If you're unsure which category to reset, start with Cache. It's the safest option and resolves many performance and display glitches without affecting your configuration.

4. Back up before a full reset

If you decide to reset Preferences or Provider configuration, export or back up your important data first:

  • Copy any API keys you've stored.
  • Note your preferred models and settings.
  • Export conversation sessions you want to keep.

A full reset removes or disconnects these resources, and you'll need to reconfigure them afterward.

Examples

Example: Provider connection is flaky

Symptom: Requests to your AI provider intermittently time out, but diagnostics show the provider test passes sometimes.
  1. Run Diagnostics. If the provider check shows warn, the issue may be intermittent connectivity.
  2. Open a new session and send a test message. If it works, the old session was stale.
  3. If the problem persists across sessions, reset Cache only.
  4. Restart Yukkai and test again.
  5. If still failing, reset Provider configuration and re-enter your API key.

Example: Yukkai feels slow after a large import

Symptom: The app takes a long time to respond after indexing a large folder into RAG.
  1. Run Diagnostics. The Local model state and Storage checks should pass.
  2. Reset Local indexes — this clears the RAG database. Yukkai will re-index on the next launch.
  3. Restart and let the re-index complete. If the folder is very large, consider indexing fewer files at once.

Example: Notifications stopped working

Symptom: Proactive alerts and morning briefings no longer appear.
  1. Run Diagnostics and look at the Permission state check.
  2. If notifications show warn or fail, open System Settings → Notifications on your Mac and verify Yukkai is allowed.
  3. If permissions look correct, reset Preferences (this resets notification settings within the app).
  4. Restart Yukkai and re-enable proactive alerts in Settings → Proactive.

Tips

  • Diagnostics before reset. Always run diagnostics first. A diagnostic report tells you exactly what's wrong, which often means you can fix the issue without resetting anything.
  • Start with cache. Cache resets are non-destructive — your settings, keys, and conversations are preserved. When in doubt, try this first.
  • One category at a time. Don't reset everything at once. Narrow down the problem by resetting one category, restarting, and testing. This makes it easier to identify what was causing the issue.
  • Export the diagnostic report. If you need to contact support, attach the exported report. It gives the team a detailed snapshot of your system state and speeds up troubleshooting.
  • Re-indexing takes time. After resetting local indexes, Yukkai rebuilds its knowledge base on the next launch. For large collections, this can take several minutes. Let it finish before starting a conversation.
  • Provider reset means re-entering keys. Resetting provider configuration disconnects all providers. Have your API keys ready so you can reconfigure quickly.
  • Check for macOS updates. Some permission and connectivity issues are caused by macOS itself. Running diagnostics can reveal whether a system-level problem is the root cause.
  • A clean test session is the best smoke test. If a fresh session works fine, the issue is session-specific — not a systemic problem. No reset required.

Last updated: July 19, 2026