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.

.notchy.json is an optional JSON file you place in your project root. When Notchly opens a directory containing this file, it reads the config to customize the shell, launch command, and environment variables for that project’s terminal sessions. All three fields are optional — you only need to specify what differs from your defaults.

​
File format

Create a .notchy.json file at the root of your project. Every field is optional; omit any you don’t need.
.notchy.json
{
  "shell": "/bin/bash",
  "command": "npm run dev",
  "env": {
    "NODE_ENV": "development",
    "PORT": "3000"
  }
}
​
shell
string
Path to the shell executable to use for this project’s terminal sessions. Must be located under /bin/, /usr/bin/, /usr/local/bin/, or /opt/homebrew/bin/, and must point to an executable file. Paths outside these directories are silently rejected and Notchly falls back to your default login shell.
​
command
string
A command to run automatically when the tab opens. The command is sent to the shell after the working directory is set. If the project also contains a CLAUDE.md, Claude Code will launch before this command runs.
​
env
object
Key-value pairs of environment variables to merge into the shell environment when the tab opens. These are merged on top of the inherited environment. See Filtered environment variables for keys that cannot be set here.

​
Trust prompt

Because .notchy.json can run arbitrary shell commands as soon as a project opens, Notchly requires explicit approval the first time it encounters a config file it hasn’t seen before. When Notchly opens a directory with a previously unseen .notchy.json, it displays a trust dialog that lists:
  • The full project path
  • The shell value, if present
  • The command value, if present (truncated at 200 characters to keep the dialog readable)
  • Each env key and its full value, sorted alphabetically
The dialog offers three choices:
OptionBehavior
Trust & ApplyApply the config for this session and remember this project as trusted. Future opens skip the prompt.
Open Without ConfigOpen the tab normally but ignore the .notchy.json for this session only. You’ll be asked again next time.
Don’t Ask AgainPermanently dismiss the prompt for this project. The config is never applied, even if it changes.
Trust is persisted by the canonical path of the project directory, with symlinks resolved. If you move or rename the project directory, Notchly treats it as a new, untrusted project and prompts again.
.notchy.json can execute arbitrary shell commands the moment a project opens. Only trust projects you wrote or audited. Cloning a repository from an untrusted source and opening it in Notchly without reviewing its .notchy.json could result in code execution on your machine.
To revoke trust for a project (for example, after pulling upstream changes), you can call ProjectTrustStore.revokeTrust(for:) or simply delete the saved entry from UserDefaults under the key trustedProjectPaths.

​
Filtered environment variables

The following keys are stripped from env before merging, regardless of what the .notchy.json file contains. They cannot be overridden via project config:
  • PATH
  • SHELL
  • HOME
  • USER
  • LOGNAME
  • TMPDIR
  • IFS
  • ZDOTDIR
  • BASH_ENV
  • ENV
  • Any key starting with DYLD_
  • Any key starting with LD_
This filtering is a security measure. Variables like DYLD_INSERT_LIBRARIES and LD_PRELOAD can redirect the dynamic loader, allowing a malicious config to inject code into every process the shell spawns. PATH and SHELL are protected to prevent a config from silently replacing your tools with hostile binaries. ZDOTDIR, BASH_ENV, and ENV are blocked because login shells read them before any command runs — setting them in env would execute arbitrary code ahead of your command field, bypassing the trust model entirely. If you need to adjust PATH for a project, do it inside the command string (e.g. export PATH="/opt/mytools:$PATH" && npm run dev).

​
Examples

Open a tab rooted at a Node.js project, set the runtime environment to development, expose a custom port, and start the Vite dev server immediately.
.notchy.json
{
  "command": "npm run dev",
  "env": {
    "NODE_ENV": "development",
    "PORT": "5173",
    "VITE_API_URL": "http://localhost:8080"
  }
}
When you open this project in Notchly, the shell starts, changes to the project root, then runs npm run dev with the three env vars already set. Claude Code will also be available in the same tab if you have a CLAUDE.md.
Use the virtualenv’s Python binary directly (no activate script needed) and point PYTHONPATH at your source tree so imports resolve correctly.
.notchy.json
{
  "shell": "/usr/bin/bash",
  "command": "source .venv/bin/activate && echo '✓ venv active'",
  "env": {
    "PYTHONPATH": "src",
    "PYTHONDONTWRITEBYTECODE": "1"
  }
}
The command runs source .venv/bin/activate in the shell, leaving you with the virtualenv active in the tab. PYTHONPATH=src means import mypackage resolves from ./src/mypackage without installing the package.
You might want to use a specific shell binary for a project, for example to pin zsh across machines where the default shell differs.
.notchy.json
{
  "shell": "/bin/zsh",
  "command": "echo '✓ project shell ready'",
  "env": {
    "MY_PROJECT_ENV": "staging"
  }
}
Note: ZDOTDIR is blocked and cannot be set via env. If you need zsh to load a project-specific dotfile, use a wrapper script instead:
scripts/shell-init.zsh
#!/bin/zsh
# Source your project config, then hand off to an interactive zsh
source "$(dirname "$0")/../.project.zshrc"
exec zsh
Then set "command": "exec scripts/shell-init.zsh" in your .notchy.json. The wrapper runs, sources your project config, and replaces itself with a clean interactive shell.

Build docs developers (and LLMs) love

Get started for freeTalk to us