Skip to content
Docs

Troubleshooting

This page lists the errors and unexpected states most likely to surface during normal use. Each entry names the symptom and gives the fix. If nothing here matches your situation, the activity log at design/.denote/activity.jsonl and the embedded terminal's own output are the next places to look.

Install and first launch

macOS warns about the download

Symptom: the first launch shows a dialog saying Denote is an app downloaded from the internet.

Not an error. Denote is signed and notarized with Apple; this is the standard one-time confirmation for any downloaded app. Click Open.

If macOS instead claims the app is damaged or can't be verified, the download was likely corrupted or is very old. Delete it and download the latest .dmg from the releases page.

The app opens but the terminal says Claude Code isn't installed

Symptom: Denote opens, the workspace loads, but the terminal pane shows a "Claude Code not found" notice with an install command.

Likely cause: Claude Code is not installed, or not reachable from your login shell.

Fix: run the install command shown (or follow the Anthropic install guide), then use the retry button or reopen the project.

If claude --version works in your regular terminal but Denote still can't find it, your PATH modification lives in a file login shells don't read. Move it to .zprofile (or .bash_profile) rather than an interactive-only block of .zshrc.

Claude Code says "not logged in"

Symptom: the terminal prints a login prompt when Denote opens.

Fix: click into the terminal and run claude login. Follow the standard auth flow. Authentication applies across all Claude Code sessions on this machine, so you only do this once.

Note that Denote deliberately launches Claude Code without any ANTHROPIC_API_KEY from your shell, so the terminal always uses your Claude subscription login rather than API billing.

Running skills

A skill seems stuck

Symptom: you typed /ontology (or another skill), the terminal printed something, and nothing has happened for a while.

Likely cause: the skill is waiting for your input. The skills are conversational. They ask questions and wait.

Fix: click into the terminal and read the last prompt. Respond. The skill will continue.

If the terminal genuinely shows no prompt and has not printed anything for more than a minute, the model may have timed out. Press Ctrl+C in the terminal to cancel, then re-run the skill.

A skill writes an empty or broken file

Symptom: after running a skill, the corresponding layer canvas shows an error, an empty state, or garbled content.

Likely cause: the skill produced output that fails schema validation.

Fix: open the file in question (e.g., design/ontology.json) and inspect it. Common failures:

  • Missing required fields.
  • Invalid values in closed sets — check type, role, cardinality, level, pattern IDs, and surface names.
  • Arrays where objects are expected, or vice versa.

You can hand-fix the file, or revert with git checkout design/<file> and re-run the skill with a cleaner prompt. Telling the skill what looked wrong usually gets it repaired in place.

Skill output does not appear in the layer canvas

Symptom: a skill ran, the file on disk updated, but the canvas still shows old content.

Denote watches design/ and normally re-renders within a moment of the write landing. If a canvas is genuinely stuck, switch layers and back, and failing that reopen the project. If this happens repeatedly, check that the file passes validation (see above) — invalid writes are rejected rather than rendered.

Activity hub warnings

A layer is flagged as possibly stale

Symptom: after editing an upstream layer, the activity hub notes that a downstream layer may be stale.

Not an error. This is expected behavior. There is no dialog, no blocker, no cascade. Run the downstream skill (e.g. /architecture) when you want to bring it in sync.

Dangling reference warning

Symptom: after deleting an entity, the activity hub logs that a task, screen, or composition zone now references a non-existent entity.

Fix: decide whether the downstream reference is still meaningful.

  • If it is, edit the reference by hand to point at a still-existing entity, or re-run the downstream skill.
  • If it is not, delete the reference from the downstream file.

The dangling reference will not block skill runs, but it can produce confusing output until resolved.

File conflicts

Denote and a hand edit disagree

Symptom: you edited a design file in your code editor. Later, your edit is gone.

Likely cause: a skill ran after your edit and rewrote the file.

Fix: two options.

  • Edit when no skill is running, and confirm the canvas reflects your change (it renders live).
  • Use git. Commit before each edit session. If a hand edit is lost, git diff shows what was overwritten.

.claude/commands/ is regenerated

Symptom: you edited one of the five layer commands (for example, ontology.md) and the next time you opened the project, your edit was gone.

Expected. The five owned command files are overwritten on every project open. They encode Denote app behavior, not designer intent. To customize the reasoning, edit intelligence/ (which is preserved) rather than .claude/commands/. Commands you add under your own names are left alone.

See Writing your own intelligence for the right place to customize.

CLAUDE.md

Custom rules disappeared

Symptom: you edited CLAUDE.md and the next time you opened the project, your edits were gone.

Likely cause: your edits were above the ## Custom Rules marker, which is overwritten on regeneration.

Fix: place all custom content below the ## Custom Rules marker line. Anything below that marker is preserved across regenerations. (In build mode the whole file is yours and is never regenerated.)

Home screen and projects

A recent project shows "not found"

Symptom: a recent project entry on the Home screen shows an error when clicked.

Likely cause: the project folder was moved, renamed, or deleted on disk.

Fix: remove the recent entry (the X on the row) and use Open existing folder to point at the project's current location.

Creating a new project fails with "folder already exists"

Symptom: the project creation dialog refuses to create a project because a folder with that name already exists.

Expected. Denote refuses to overwrite an existing folder during scaffolding to avoid destroying existing work.

Fix: choose a different name, choose a different parent location, or use Open existing folder instead to open the folder as a project in place.

Git

"not a git repository" in the terminal

Symptom: Claude Code prints an error about git repository not being found.

Likely cause: the project's .git/ directory was deleted or the project was opened from an unusual path that Denote's scaffolder could not write to.

Fix: open a regular terminal, cd into the project folder, and run git init. Quit and reopen the project in Denote.

Updates

Update notification never appears

Symptom: a new version of Denote has been released but the app does not offer it.

Denote checks on launch and once every 24 hours while open, and closing the update dialog snoozes it until the next launch. Quit and reopen Denote to trigger a fresh check. If the dialog still doesn't appear, download the new .dmg directly from the releases page — installing over the old copy is the same thing the update flow does.

When to re-open the project

Several behaviors only run at project open:

  • Regenerating CLAUDE.md (design mode only).
  • Re-copying the five layer commands and refreshing intelligence/catalog/.
  • Syncing new knowledge files from Denote's intelligence/ (existing files are preserved).
  • Initializing .git/ if missing.

After updating Denote itself, reopen your project so it picks up the current commands and catalogs.

When to restart Denote

  • After installing or updating Claude Code.
  • After changing your shell's PATH configuration.
  • When the terminal behaves oddly (no prompt, garbled output, unresponsive input).

Quitting and relaunching is fast and almost always resets a confused terminal.

Where to next