---
id: updating-troubleshooting
title: Updating, health, and troubleshooting
area: Going deeper
order: 95
summary: How updates work without touching your data, the doctor that keeps everything honest, and answers to the questions everyone asks.
---

Dex improves continuously, and it's built so that staying current is safe and boring: your data can't be touched by an update, every update can be undone, and a built-in doctor tells you the truth about what's working. This page covers the maintenance story end to end, then the frequently asked questions.

## Updating: `/dex-update`

When a new version exists, Dex shows you what's in it — version, changes in plain language — and waits. **Dex never updates itself; you always say go.** When you do:

1. **A restore point is taken first**, before anything changes. This is what makes rollback possible.
2. **New files download and merge.** The overwhelmingly common case is a clean update, done in under a minute.
3. **If a file was changed by both you and the update**, Dex resolves by a simple rule: *your data and settings always win; core Dex machinery takes the update; anything you customized stays yours.* Genuinely ambiguous cases get shown to you with the tradeoffs.
4. **Dex verifies itself** — tasks readable, profile intact, features working — and offers automatic rollback if anything looks wrong.

The structural guarantee behind all this: the folders holding your notes, tasks, projects, and people are **excluded from version control entirely**. The update mechanism literally cannot see them, which is a stronger promise than "we're careful." Your protected customizations — the extensions block, custom skills, custom connectors — survive by design.

If an update ever disappoints, `/dex-rollback` restores the exact pre-update state from the restore point, in about thirty seconds — and a rollback can itself be undone. If a restore point has aged out or files changed since, Dex refuses cleanly and explains, rather than guessing.

## Your customizations, protected before anything changes

If you've made Dex yours — edited a built-in skill, added your own, set up your own automations, changed settings — an update shouldn't quietly undo that work. So before anything changes, Dex runs a careful protection pass:

1. **It inventories what you changed.** Dex compares your setup against the version it shipped and lists exactly what you've edited, added, or removed — modified skills, your own skills, automations, settings.
2. **It seals the evidence in a protected capsule.** An exact, tamper-evident snapshot of your customizations is kept in your own vault, so nothing is lost as the update proceeds. Your notes are never touched.
3. **It tells you plainly what it can't be sure about.** If Dex can't verify which version you're on, or can't tell a custom skill from version drift, it says so and asks for your review — it never guesses, and never gives a false "all clear."

What you'll see is a plain-English summary: what's standard Dex, what you changed, what's now built in, and anything that needs your eyes. Nothing changes until you've seen it.

Two things worth knowing:

- **Custom skills belong in the custom folder.** Put your own skills in `.claude/skills-custom/`, not the shipped `.claude/skills/` folder. Skills in the shipped folder get flagged "needs review" — Dex can't prove they're yours rather than a leftover from another version.
- **A hand-built vault may show "can't verify."** If your vault wasn't installed through Dex's normal flow, Dex may not be able to confirm its version — so it honestly says it can't determine your customizations, rather than risk getting it wrong.

> The promise, honestly stated: Dex doesn't merely keep your old files. It inventories what you changed, preserves the evidence, and is upfront about anything it cannot safely carry forward on its own.

Between updates, Dex checks about weekly whether a new version exists and mentions it in one line during your daily plan. You may also occasionally see a carefully worded notice that a release "appears to exist" but hasn't been verified — that caution is deliberate security honesty, not a malfunction.

## Health: `/dex-doctor`

Run it any time something feels off — or just monthly. The doctor checks your configuration, tools, integrations, and background automation, and reports in four honest states:

- **Working** — verified, not assumed.
- **Off** — you chose not to enable it. Reported calmly, never nagged about.
- **Broken** — configured but failing, with the fix.
- **Couldn't check** — the check itself failed. Said plainly, never silently counted as a pass.

Fixes are tiered by risk: safe ones are applied automatically and reported; anything meaningful is proposed one at a time for your OK; and things only you can do (grant a Mac permission, add an API key) come as clear instructions. A deep-scan option goes further and tests live connections — actually calling Granola, actually reading the calendar — to prove real behavior rather than checking configuration exists.

There's also a nightly self-test that runs Dex's core machinery against an isolated throwaway copy — never your real vault — so a breakage surfaces at your next session start instead of mid-workday. If the same check keeps failing across runs, Dex offers to draft a bug report.

## Common issues, quick fixes

- **Meetings stopped syncing** → `/dex-doctor`, which tests the Granola connection; usually the API key or the background job.
- **Calendar events missing (Mac)** → System Settings → Privacy & Security → Calendars → give your editor Full access.
- **Search feels stale** → ask Dex to refresh the search index (`qmd update && qmd embed`).
- **Tools show as unavailable after an update** → fully quit and reopen your editor; then `/dex-doctor`.
- **Dex feels vague in a very long chat** → start a fresh session; memory lives in your files, so nothing is lost. ([Why this happens.](claude-code-primer.html))

## Frequently asked questions

**Where is my data, exactly?**
In one folder of plain text files on your computer. No database, no Dex cloud. Open any file and read it — that's the entire truth of what Dex knows.

**Does my data get sent anywhere?**
Your conversations go to the AI provider you chose (Anthropic via Claude Code, or Cursor's providers) to generate responses — the same as using Claude or Cursor for anything. Dex adds no server of its own. Optional integrations talk directly to your own accounts using your own keys. Semantic search runs entirely on your machine. Anonymous usage analytics are on by default and switch off with one sentence: "turn off Dex analytics."

**How do I use Dex on two computers?**
Sync the vault folder. The recommended route is Obsidian Sync (about $8/month) because it's end-to-end encrypted — only you hold the key — and includes mobile apps. iCloud, Dropbox, Google Drive, or a private GitHub repository all work too, with the caveat that those providers can technically read your files.

**What's Obsidian and do I need it?**
A free note-taking app that reads the same files as Dex — entirely optional. It adds a visual layer: a clickable graph of your people, projects, and meetings, and pleasant reading and editing. Enable it any time with `/dex-obsidian-setup`; it's safe on an existing vault, and reversible.

**What if I stop using Dex?**
You keep everything. The vault is ordinary Markdown — readable in any editor, importable anywhere, no export step required. Delete the Dex machinery and the notes remain yours. This is the point of the plain-files design.

**How much does Dex cost?**
Dex itself is free and open source. You pay only for the AI underneath (a Claude or Cursor subscription) and any optional services you already use, like Granola.

**Is it safe to let an AI touch my files?**
The high-stakes operations (task IDs, multi-file syncs) run through deterministic tools, not AI improvisation; the assistant asks permission before new kinds of actions; updates can't reach your data folders; and everything is inspectable — [`/xray`](xray.html) shows you exactly what happened in any conversation. Skepticism is designed for, not discouraged.

When something misbehaves, resist the urge to describe it vaguely. Hand Dex the diagnosis job properly:

```prompt The self-diagnosis
Something's off: [WHAT YOU EXPECTED] but instead [WHAT HAPPENED]. Diagnose
your own setup: check the relevant tools, configuration, and background
jobs, tell me what you find in plain language, and separate what you can
fix yourself from what needs my hands. Don't guess — if a check is
inconclusive, say so.
```

> Still stuck? Ask Dex itself first — describe what's wrong in plain English; diagnosing its own setup is one of its jobs. Beyond that, [github.com/davekilleen/dex](https://github.com/davekilleen/dex) is where to report issues and see what's coming.

```handoff
I just read the Dex Guide's page on updating and health. Run the full
checkup on yourself now — configuration, tools, integrations, background
jobs — and give me the honest four-state report in plain words: working,
off by choice, broken, couldn't check. Fix what's safe automatically,
queue what needs my OK one at a time, and tell me exactly what needs my
hands. Then check whether a newer Dex exists, and if so, what's in it
for someone who works like me.
```