Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/javierpr0/Notchly/llms.txt

Use this file to discover all available pages before exploring further.

Notchly runs terminal sessions on your Mac with your user’s full permissions. Several safeguards prevent malicious project configs, hostile terminal output, and crafted filenames from executing unintended code or hijacking terminal state. This page describes each layer of the security model so you can understand what is protected and what remains your responsibility.

​
Project config trust (.notchy.json)

A .notchy.json file in a project directory can specify a custom shell, launch command, and environment variables. Because cloning a repo with a malicious .notchy.json would otherwise allow code execution the moment Notchly opens the directory, every .notchy.json must be explicitly trusted before Notchly applies it.
1

Trust dialog

When Notchly finds an untrusted .notchy.json, it shows a modal dialog before opening the project. The dialog displays the full shell, command, and all key=value environment pairs — values are shown in full, not just key names, so a hidden value cannot slip by. Fields longer than 200 characters are truncated in the display to prevent a deliberately long value from pushing the security warning off-screen.
2

Choose a response

The dialog offers three options:
  • Trust & Apply — applies the config and remembers the trust decision for this path.
  • Open Without Config — opens the project this one time, ignoring the config. You’ll be asked again next time.
  • Don’t Ask Again — permanently dismisses the prompt for this path without trusting it. The config is never applied.
3

Trust persistence

Trust is persisted by the canonical path (symlinks are resolved via URL.resolvingSymlinksInPath()). Moving or renaming the project directory changes its canonical path and re-triggers the prompt the next time you open it.
To revoke trust for a path that has already been trusted, call ProjectTrustStore.revokeTrust(for:) programmatically. A UI for this is not yet available.

​
Shell and environment restrictions

Even for trusted projects, Notchly enforces hard limits on what a .notchy.json can do.

​
Allowed shell paths

The shell field must point to an executable file under one of these directories: 
/bin/
/usr/bin/
/usr/local/bin/
/opt/homebrew/bin/
Any other path is silently rejected and the default shell is used instead.

​
Blocked environment variable keys

The following keys are always stripped from .notchy.json’s env before merging with the process environment, regardless of trust status:
PATH, SHELL, HOME, USER, LOGNAME, TMPDIR, IFSOverriding these could redirect binary lookups, change the effective user identity, or corrupt word splitting in shell scripts.
Any key with the prefix DYLD_ or LD_These are read by the macOS dynamic linker before any code in the target binary runs. A malicious value could cause every spawned process to load an attacker-supplied library.
ZDOTDIR, BASH_ENV, ENVThese environment variables tell login shells (zsh, bash, sh) where to load their initialization scripts. Setting them could execute arbitrary code before any command runs, bypassing the trust check entirely.

​
Terminal input sanitization

Drag-and-drop filenames — file and folder names dragged onto the Notchly panel are stripped of control bytes — specifically newline (\n), carriage return (\r), and escape (\x1b) — before their paths are sent to the terminal. A crafted filename in a cloned repository or unzipped archive cannot inject keystrokes or terminal escape sequences via drag-and-drop. OSC 7 directory updates — terminal output can include OSC 7 sequences reporting the shell’s current working directory. Notchly validates each one: it must use a file:// URL scheme, must not contain NUL, CR, or LF bytes, must canonicalize cleanly through standardizedFileURL, and must resolve to an existing directory on disk before Notchly updates its working-directory tracking.

​
Project name sanitization

Folder names and session names are sanitized of bidirectional-override characters (e.g. U+202E RIGHT-TO-LEFT OVERRIDE) and zero-width characters before appearing in notifications, tabs, and menus. This closes a Trojan-Source-style UI spoofing vector where a maliciously named directory in a cloned repo could make a dangerous tab name look innocuous.

​
Notification text sanitization

Notification bodies strip both C0/DEL control characters and C1 control characters (U+0080–U+009F, including NEL and CSI) from terminal output before it is embedded in a notification. This prevents hostile terminal output from spoofing notification content.

​
Git checkpoint security

Checkpoints use a temporary git index file (GIT_INDEX_FILE) so they never disturb your actual staging area. Two security measures apply to this file:
  • The temporary index is written inside a freshly-created 0o700 directory whose path is unpredictable. This prevents a hostile symlink at a guessable path from redirecting the write to an attacker-controlled location.
  • The git binary is resolved by searching $PATH first (supporting asdf, mise, and Homebrew shims), then falling back to known locations (/opt/homebrew/bin/git, /usr/local/bin/git, /usr/bin/git).

​
Full Disk Access

Notchly requests Full Disk Access on first launch. This permission is required to read shell history files and access project directories outside your home folder.
1

Grant Full Disk Access

Open System Settings → Privacy & Security → Full Disk Access and enable the toggle next to Notchly.
2

Restart if needed

macOS only refreshes a process’s TCC permissions on relaunch. If you grant Full Disk Access while Notchly is running, restart the app when prompted.
3

Re-open the settings pane

You can re-open the Full Disk Access settings pane at any time from the Notchly gear icon in the panel header.
Without Full Disk Access, Notchly may not be able to read ~/.zsh_history for autocomplete seeding, and it may be unable to open project directories located outside your home folder. The app will still work, but autocomplete suggestions for new projects will start from built-in defaults only.

​
App updates

As of version 0.31.1, Notchly does not install updates silently. Sparkle notifies you when a new version is available and waits for your approval before downloading or installing anything. This is a defense-in-depth measure to ensure an update is never applied to a running session without your knowledge.

Build docs developers (and LLMs) love

Get started for freeTalk to us