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 refuses to open the app

Symptom: double-clicking Denote shows "Denote can't be opened because Apple cannot check it for malicious software" or similar Gatekeeper warning.

Fix: right-click the app icon in Applications and choose Open from the menu. macOS will ask once to confirm. After that, double-click works normally.

This warning disappears once Denote ships with Apple notarization, which is part of the D1 distribution milestone. During the beta, manually bypassing Gatekeeper is expected.

The app opens but the terminal shows no prompt

Symptom: Denote opens, the workspace loads, the terminal pane is present, but there is no Claude Code prompt.

Likely cause: Claude Code is not on PATH.

Fix: open your regular terminal and run claude --version. If that command is not found, install Claude Code per the Anthropic install guide. Quit and reopen Denote after installation.

If claude --version works in your regular terminal but not in Denote's embedded terminal, the shell Denote spawns is not picking up your PATH modifications. Check that your PATH additions are in a file loaded by login shells (.zprofile, .bash_profile) rather than interactive-only shells (.zshrc interactive-only blocks).

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.

Running skills

A skill seems stuck

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

Likely cause: the skill is waiting for your input. Claude Code 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/entities.json) and inspect it. Common failures:

  • Missing required fields. The schema in src/shared/schemas/ documents what each file must contain.
  • Invalid enum values. Check that type, role, cardinality, pattern, and similar fields use one of the allowed values.
  • Arrays where objects are expected, or vice versa.

You can hand-fix the file and reload the layer, or revert with git checkout design/<file> and re-run the skill with a cleaner prompt.

Skill output does not appear in the layer canvas

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

Fix: switch to a different layer and back. Denote re-reads files on layer change. This is a known rough edge; a proper watcher is on the roadmap.

Activity feed warnings

"Extract changed. Map may be stale."

Symptom: after editing a file in Extract, the activity feed shows a "may be stale" hint pointing at Map.

Not an error. This is expected behavior. Denote logs hints when an upstream change might affect a downstream layer. There is no dialog, no blocker, no cascade. Run the downstream skill (/map) when you want to bring it in sync.

Dangling reference warning

Symptom: after deleting an entity, the activity feed logs that a pattern assignment, architecture node, or layout region 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. The next time you open the layer, your edit is gone or partially merged.

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

Fix: two options.

  • Edit the file when no skill is running. Denote reads files at layer open and after skill runs, not continuously. Your hand edits persist as long as the next skill run does not overwrite them.
  • 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 a file in .claude/commands/ (for example, vision.md) and the next time you opened the project, your edit was gone.

Expected. Skill 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/.

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.

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 from Home (right-click or X button) 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 to update.

Expected during beta. Automatic updates are wired up in the D1 distribution milestone. Until then, download the new .dmg manually when a release ships.

When to re-open the project

Several behaviors only run at project open:

  • Regenerating CLAUDE.md.
  • Re-copying .claude/commands/ from Denote's source.
  • Syncing new files from Denote's intelligence/ (existing files are preserved).
  • Initializing .git/ if missing.

If you have edited Denote itself (source code) or need Denote-side defaults refreshed, close and reopen the project. Denote does not hot-reload these files within a session.

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