Skip to content

Troubleshooting

Audience. New user and Daily user — anything that surprises someone using condash for real work.

If you hit something not on this page, file an issue with the OS, condash version (footer of the dashboard), and a minimal repro.

Install / first launch

"App can't be opened — developer cannot be verified" (macOS)

condash is unsigned on purpose. macOS asks you to confirm the download once. The bypass differs between Sonoma and Sequoia — see Install — macOS Gatekeeper bypass.

"Windows protected your PC" (Windows)

Click More info → Run anyway. SmartScreen flags every unsigned binary the first time it sees it. See Install — Windows SmartScreen bypass.

AppImage exits silently with no window (Linux)

Most likely a missing system library. Run the AppImage from a terminal so you can see stderr:

./condash-*.AppImage

If the error mentions libnss, libgtk, or libatk-bridge, install Electron's runtime deps:

sudo apt install libnss3 libatk-bridge2.0-0 libgtk-3-0 libgbm1   # Debian/Ubuntu
sudo dnf install nss atk at-spi2-atk gtk3 mesa-libgbm             # Fedora

Folder picker keeps coming back at every launch

condash should remember the conception path you picked. If the picker reappears every time, check the per-machine settings file:

cat ${XDG_CONFIG_HOME:-~/.config}/condash/settings.json

If lastConceptionPath is not set or points to a directory that no longer exists, condash falls back to the picker. Edit the file by hand to fix it, or pick the right path through the picker once more — condash writes the choice on success.

Empty dashboard

"Projects (0)" but my tree has READMEs

Check the conception path is correct (footer of the dashboard, or cat settings.json). If the path is right but the count is zero, your items don't match the strict layout. condash only renders items at:

projects/YYYY-MM/YYYY-MM-DD-<slug>/README.md

Items at the wrong nesting depth (e.g. projects/<slug>/ without a month directory) are skipped. The slug must match ^[a-z0-9-]+$ after the date prefix.

Fix: git mv the items into the right shape, or use the condash projects verbs to validate.

Code pane is empty / "Code (0)"

The Code pane scans workspace_path from .condash/settings.json (or the legacy condash.json) for direct subdirectories containing a .git/. Two common reasons it's empty:

  • workspace_path is unset. Set it to the directory containing your repos.
  • workspace_path points at a parent directory whose direct children are not git repos (e.g. an extra nesting level — ~/src/ when your repos are in ~/src/projects/). The scan is one level deep.

Fix: open the gear modal and edit workspace_path to point at the right directory. The Code pane refreshes within a couple of seconds.

Knowledge pane is empty

Same shape: condash looks for <conception_path>/knowledge/. If the directory is missing, the pane is hidden. Create it with mkdir knowledge && echo "# Knowledge" > knowledge/index.md — the pane appears immediately.

Embedded terminal

Terminal pane opens, but no shell prompt

The shell process exited immediately. Three common causes:

  • The configured terminal.shell doesn't exist (/bin/zsh on a system without zsh installed). Fall back to /bin/bash in settings.json.
  • The shell rc-file (.bashrc, .zshrc) errors out. Open the same shell in a separate terminal to see the error.
  • (Linux only) node-pty was built against the wrong Node ABI. This shouldn't happen for the packaged .AppImage / .deb. If it does, file an issue with the version.

A command on my PATH isn't found in the terminal

condash resolves your login-shell PATH at startup and uses it for the embedded terminal, repo Run commands, and launchers — so CLIs you added in ~/.profile / ~/.zprofile (opencode, ~/bin wrappers, ~/.local/bin tools) resolve even when condash was started from the GUI. If a command still isn't found:

  • Confirm it's actually on PATH in a login shell: bash -lic 'command -v <cmd>'. If that fails too, the entry is missing from your login dotfiles — not a condash problem.
  • Resolution runs once at startup. If you edited a dotfile after launching condash, restart condash to re-resolve.
  • A broken rc-file can make the probe time out (5 s), leaving the inherited PATH. Open the same shell in a separate terminal to check for errors.

Ctrl+C copies instead of sending SIGINT (or vice versa)

Ctrl+C does double duty: copy the current selection if there is one, otherwise send SIGINT. So if you've highlighted some output and hit Ctrl+C, you'll copy it. Click somewhere else to clear the selection, then Ctrl+C interrupts.

Terminal pane is missing on Windows

The terminal works on all three platforms. If the pane fails to open on Windows, check that PowerShell or cmd.exe resolves through process.env.ComSpec and that no system-level policy is blocking child-process creation.

"Open in IDE" buttons do nothing

The buttons spawn the command in open_with.<slot>.command from settings.json (per-machine) or .condash/settings.json (tree-wide; legacy condash.json still read). Two failure modes:

  • The command isn't on $PATH (typical for macOS GUI editors that don't install a shell launcher). Use the open -na form on macOS — see Config files — Per-OS recipes.
  • The path being passed isn't under workspace_path or worktrees_path. condash refuses to spawn launchers outside those sandboxes; check the toast message.

File-edit conflicts

"Reload before saving" toast on every save

A drift check failed: the file on disk no longer matches what condash had cached. Two reasons:

  • You edited the file in your editor while the dashboard had an older version. Click the refresh icon in the dashboard header, then redo the change.
  • A chokidar event was missed (rare; usually a network filesystem). Same fix.

My step toggles silently undo themselves

Same root cause as above. The renderer flips the marker optimistically, the IPC write fails the drift check, and the renderer rolls back. Refresh the dashboard to pick up the on-disk state.

Performance

Refresh button takes longer than a second

The conception tree is too big or sits on a slow filesystem (network mount). condash re-walks the tree on each refresh — there is no index on purpose (see Why no search index). At a few hundred items this should be well under 50 ms; if you hit a noticeably slower wall, file an issue with the tree size and FS type.

Embedded terminal is laggy under load

xterm.js renders a lot of cells on every paint. Two knobs help:

  • Lower terminal.xterm.scrollback from the default 10 000 to something smaller (1 000).
  • Toggle terminal.xterm.ligatures off — the ligatures addon is expensive on long lines.

Both keys live under terminal.xterm in .condash/settings.json (or the legacy condash.json). The Settings → Terminal tab in the gear modal edits them live.

CLI

condash projects list says "no conception"

The CLI honours the same path-resolution chain as the GUI but does not open the folder picker. Point it explicitly:

condash --conception ~/src/conception projects list

Or set the path through condash config conception-path ~/src/conception (writes to settings.json, picked up by both the GUI and the CLI).

condash reports an unknown noun

The single condash binary dispatches GUI vs. CLI based on argv (see CLI — How dispatch works). If you typed a typo for a CLI noun (e.g. condash projct list), condash reports unknown noun and exits with code 2. Re-run with the correct noun — condash --help lists every accepted one.

Reading the toasts

Toasts at the bottom of the dashboard come in three colours. The colour signals what just happened — read it before reading the message.

Colour Kind When you see it
Green / accent success A write completed: Created <slug>, Path copied, Force-stopped <repo>, Initialised conception template. The action took effect — nothing to do.
Red / warn error An action failed and was not retried: Run failed, Open failed, Status change failed, Could not persist layout. The trailing message is the underlying cause; the dashboard state was not mutated.
Neutral info Diagnostic context: [[slug]] matched 3 items — opening the first, branch warnings on close. The dashboard state did change; the toast is FYI.

Toasts auto-dismiss after 4 seconds. Identical messages don't stack — a second flash of the same text resets the timer instead of queuing a duplicate.

Still stuck?