Notch CLI

Runs on your device without a FreeSyntax account, website, or hosted backend. Local models and provider keys are configured locally. GitHub sign-in connects directly to GitHub using GitHub CLI, and Git operations use your local Git installation and configured remotes. GH_TOKEN / GITHUB_TOKEN also authenticate HTTPS GitHub operations without storing the token in Git configuration files.

A coding assistant for your terminal, powered by local Ollama models or your OpenRouter, OpenAI, or Anthropic API key. No hosted Notch account or provider sign-in is required. Merchandise supports development; buying a hat is not required to use the CLI.

Install

npm install -g @freesyntax/notch-cli
notch setup
notch doctor
notch

Setup offers provider and model choices. A first interactive launch without a saved model asks you to select with Up/Down and Enter, then remembers your choice for that project. Type to search the complete tool-capable OpenRouter catalog in the picker; Escape cancels. /model opens the same arrow-key picker; /model provider/model selects an exact model. Tab completes commands, themes, models and @files in a capable terminal. Arrow keys retain normal input history outside the picker. /help lists commands; /permissions shows access choices. Redirected output and TERM=dumb use plain output.

Use notch help or notch help <command> before starting a session. Setup and key menus use searchable arrow navigation: Up/Down moves, Page Up/Down skips a page, Home/End jumps, Enter selects, and Esc or Ctrl+C cancels. Ctrl+U clears a menu search. Menus adapt when the terminal is resized. Use @"my files/notes.txt" for filenames with spaces; Tab can complete into quoted folders. Multiword model searches work as /models browse --search "gemma 4". Help and invalid flags in model menus return to the session prompt.

GitHub and Git remotes

Run notch github login to install GitHub CLI when supported and sign in through the browser. notch github status shows the account used by GitHub actions; notch github repos lists accessible personal, organization and collaborator repositories across all pages. The IDE uses the same GitHub CLI sign-in. GH_TOKEN takes precedence over GITHUB_TOKEN, and both override saved credentials. Update or remove an environment token before switching to browser sign-in.

For an existing Git project, check its destination with git remote -v. Connect a missing remote with git remote add origin <repository-url>. Git uses your existing HTTPS credential helper or SSH keys; ordinary Git remotes do not require GitHub sign-in. A new repository also needs git init and a Git author name and email.

Cursor Origin

Run notch origin login and open the printed Cursor sign-in link in your browser. On Windows, the official Cursor SDK handles browser login natively; the CLI and IDE share a login protected with Windows DPAPI for the current user. No WSL or FreeSyntax service is required. Use notch origin repos to list accessible repositories, then notch origin clone owner/repo. Pasted HTTPS and SSH URLs keep their protocol; use --protocol ssh with owner/repo to select SSH.

Run notch origin pull --cwd ./repo and notch origin push --cwd ./repo for committed changes. Pull allows fast-forwards only; push never forces. Both check the configured origin URL before contacting the remote. Rejected pushes keep your local commits. To resolve a diverged history, use your normal Git workflow. These commands do not create commits, stage files, rewrite remotes or configure SSH trust. Register an SSH public key with Origin and verify its official host fingerprint before a first SSH connection.

On Windows, sign-in, repository listing, clone, pull and push use native Windows processes and paths. HTTPS Git obtains short-lived Origin access tokens through a host-scoped credential helper; credentials are never written into repository URLs or Git configuration files. SSH uses your registered native keys. --native remains accepted for compatibility. --distribution Ubuntu explicitly opts into the separate WSL workflow if you choose it.

macOS and Linux use native Git and the official Origin CLI. Origin requires an eligible Cursor account; GitHub sign-in does not authenticate Origin. Personal CURSOR_API_KEY values are exchanged at Cursor's documented token endpoint; CURSOR_AUTH_TOKEN is already a bearer token. Environment credentials take precedence over the saved login. API keys are never sent directly to Origin as bearer tokens. notch origin logout removes the saved local login; minted keys can also be revoked in Cursor's dashboard.

Inside a session, use /origin login, /origin repos, /origin clone owner/repo "folder with spaces", /origin pull and /origin push. Tab completes these commands; /origin --help lists options. Ctrl-C cancels the active child command and restores session input. Origin authentication follows Cursor's official CLI documentation, command reference and Git/SSH documentation.

Tests cover real local Git clone/pull/push and rejected pushes, URL/argument validation, both execution modes and credential redaction. Live Cursor-hosted account authentication and writes require an Origin-enabled account and are not verified without one.

Ask notch to commit and push to review the files and destination before publishing. Sensitive file paths, including either side of a rename, are excluded from this combined action. Existing committed branches can be published even without an upstream. /pr pushes current commits before creating a GitHub pull request and uses the repository's actual default branch. Force pushes to protected or ambiguous destinations are blocked by the Git tool.

Download and run a local model

notch models
notch models browse --search gemma
notch models browse --search gemma --page 1 --json
notch models recommend --json
notch models install --runner ollama --model unsloth/Qwen3.5-4B-GGUF --yes --no-launch
notch
notch models unload

notch models offers numbered Hugging Face choices using available RAM and detected dedicated GPU memory, including Windows AMD GPUs. Apple unified memory is counted once. Choices are ordered by repository creation date; that date does not establish model quality. Public model sizes and metadata are cached for six hours, and cached downloads are reused. Memory estimates reserve loading/context headroom; the installer loads the model and checks both a harmless native tool call and its result round trip before replacing your project selection. A failed check keeps the previous selection.

Each runtime uses the selected model's tokenizer and chat format. Imported GGUF architecture/template metadata selects verified native Ollama tool profiles for Gemma4, Qwen3.5, Qwen3-Coder and GLM4.7; other models keep their embedded runtime template. Native context limits come from the imported Ollama model or revision-specific MLX configuration, rather than the repository name. Preflight token estimates remain approximate; actual usage counts come from the provider. Arbitrary repositories may lack compatible tool support and fail validation.

Browsing and installation search Hugging Face's public compatible catalog, rather than stopping at three recommendations. Ollama choices require verifiable Q4_K_M GGUF weights; Apple MLX choices require safetensors. Search includes chat and coding conversions; tool support is checked during installation. --page follows the Hub's next-page link after the preceding page has been browsed, and --refresh refreshes cached results. The install prompt accepts a model number, n/p to change page, s to search, and q to cancel. Selection refreshes metadata and available-memory estimates before downloading. Offline unfiltered browsing can show the saved Qwen recommendations with a warning; a new search does not silently substitute unrelated models. You can still specify a public repository with --model.

The Qwen3.5 4B Hugging Face model completed all three local coding checks on the tested Windows machine at 16K context / batch 64. This small suite is not a general quality benchmark.

Ollama starts locally if installed. If it is absent or too old for the selected model, Notch downloads a compatible official runtime, verifies its SHA-256 digest, and runs it separately at 127.0.0.1:11436. The existing installation remains available. This first download can exceed 1 GiB; model weights are an additional download. The guided installer saves the measured context/batch choice for the project. /models install, /models recommend, /models status and /models unload are also available inside the CLI.

Apple Silicon Macs (M1 or newer, macOS 14+) can choose MLX (beta) or Ollama. MLX needs native ARM64 Python 3.11+; the CLI installs mlx-lm in its own user environment and downloads weights into the Hugging Face cache. Python, MLX and model weights are downloaded separately, rather than bundled in the npm package. MLX listens on loopback and is owned by the running Notch session. Quit that session or use /models unload to release its memory. MLX has platform/protocol tests, but has not been tested on Apple hardware for this release.

--no-launch validates an install and unloads it. Noninteractive installation also unloads afterward. Unloading releases model memory and keeps downloaded files. Ollama daemons can remain idle for reuse. Initial downloads require network access and free disk space; model licenses are shown before installation.

Colibri (experimental)

Colibri selects its tokenizer and supported chat template from the selected checkpoint and model family. Managed launches isolate tokenizer, template and stop-token settings from other models.

New Colibri setups use 16K context to leave room for coding tools and conversation. Loading still requires enough current free memory; existing explicit context choices are preserved.

Choose Colibri when you want to try disk-streamed mixture-of-experts models. Ollama remains the default. Setup needs 64-bit Python 3.10+ and downloads an isolated, checksum-verified engine; no Python packages are installed globally.

notch models install --runner colibri
notch models recommend --runner colibri --json
notch models status --runner colibri
notch models unload --runner colibri

The install menu supports arrow keys and search. It shows currently available RAM, a safety reserve, download sizes, minimum/recommended RAM and disk restrictions before confirmation. Models that fail the free-memory precheck cannot be downloaded through setup. Passing this preliminary estimate does not verify that the model will run at 16K context: the exact checkpoint and context are checked after download and before loading. Rerun setup to refresh memory after closing applications. Downloads resume after interruption. Setup validates a harmless tool call and its result before changing your project selection. /model includes the validated model; /context limit changes its context after unloading. /models unload releases the active Colibri model while retaining its weights.

Colibri is an optional download, not bundled in npm. It currently supports Windows x64, Linux x64 and Apple Silicon. Large models can have long waits before the first token; fitting in memory does not establish useful coding speed. Model weights have their own licenses. This experimental integration starts one conversation slot and shares notch's local inference queue.

Already have weights converted for Colibri? Import them with notch models install --runner colibri --model-dir /path/to/model. GGUF files are for Ollama and cannot be imported as Colibri containers.

Browse OpenRouter

notch models openrouter
notch models openrouter --search gemma --json
notch models openrouter --page 1
notch models coding --search coder

OpenRouter browsing uses the complete public text-model catalog without an API key. Plain output shows 20 models per page; --json includes every matching row, context size, prices and tool support. coding restricts results to models advertising tools. Chat-only models remain visible in general browsing with a reason; the coding picker excludes them. Running a cloud model still requires a validated API key. Results are cached for six hours; --refresh bypasses the cache and an offline fallback is explicitly labelled. /models openrouter --search gemma and /models browse --search gemma work in a running session too.

Commands, servers and checks

Notch executes tool calls in order and skips duplicate calls within a response. An unchanged failing action runs at most twice before notch stops the retry loop. A successful change allows another attempt.

For local development servers, ask notch to use shell with background: true. It returns a process ID and log paths. Starting a process does not verify that a website is ready; notch must check its endpoint separately. Tests run in the foreground so their exit status is available.

Failed checks remain recorded until the same command succeeds. A failed check cannot be turned into a successful completion by the model's final wording. Headless runs exit with status 2 and report verification-failed or stalled when appropriate. This checks command execution results; it cannot prove that a test suite covers every requirement.

Automatic updates

Global npm installations check the selected npm channel on each interactive agent launch. When a newer version is available, Notch installs it and relaunches with the same arguments before opening a session. Registry checks time out after five seconds; an offline or permission failure reports the problem and continues with the current version. No active conversation is restarted for an update.

--no-update or NOTCH_AUTO_UPDATE=0 disables this. --update-channel latest|next|beta overrides NOTCH_UPDATE_CHANNEL, the saved channel and the default latest channel. notch update forces a manual update; notch update --check checks without installing. Source checkouts, local project installs, npx caches, JSON/headless runs, help/version and discovery commands do not install global updates automatically.

Run this checkout

Use Node.js 22.19 or newer and Git (Node.js 24 LTS is tested). From notch-cli:

npm ci --workspaces=false
npm run build
node dist/index.js setup
node dist/index.js doctor
node dist/index.js "Explain this repository"

npm link --workspaces=false makes this checkout available as notch.

Local Ollama

Install/start Ollama, then pull a model with tool support. qwen3-coder:30b completed the three-task local coding evaluation on this machine; it requires considerably more memory than a small chat model:

ollama pull qwen3-coder:30b
notch setup --provider ollama --model qwen3-coder:30b
notch doctor
notch "Read the failing test, fix the implementation, and run the test"

Setup lists installed models, checks tool capability and writes .notch.json in the current project. Local Ollama needs no API key. Model quality determines coding quality. qwen3:4b was also tested, but failed most of the coding evaluation and is not a reliable default for autonomous changes. The three tasks are behavioral checks, not a general benchmark.

OLLAMA_HOST or notch setup --host http://localhost:11434 selects a different daemon. Bare hosts, /api and /v1 suffixes are normalized. Requests use native /api/chat so the context size is explicit instead of inheriting a potentially inadequate daemon default. NOTCH_OLLAMA_CONTEXT defaults to 8192 tokens (allowed 2048–262144) and is clamped to the verified native model limit; choose a size supported by your model and available RAM/VRAM. Larger contexts require more memory. NOTCH_OLLAMA_THINK=0 requests disabled thinking on models that support it.

notch ollama list, status, pull <model>, and launch --model <model> remain available. launch saves the selection; run notch afterward. Noninteractive setup never silently downloads a model.

NOTCH_OLLAMA_BATCH sets Ollama's prompt batch size (default 64; integer 1–2048). Smaller batches can reduce temporary GPU memory use at the cost of prompt-processing speed. Measure a model/context/batch combination on your hardware rather than assuming a larger model fits.

The startup banner shows the effective context and batch size. /context shows the current limit; /context limit opens an arrow-key menu, and /context 16384 sets an exact local Ollama limit. Settings are saved for the project and take effect on the next request. NOTCH_OLLAMA_CONTEXT, if set, overrides these project settings; unset it before changing the limit through the CLI. Hosted providers enforce their own model limits.

On the tested machine, the 30B model required NOTCH_OLLAMA_CONTEXT=16384 and NOTCH_OLLAMA_BATCH=64; 32K context exhausted GPU memory. Set these environment variables before starting Notch if appropriate for your hardware. When finished, ollama stop qwen3-coder:30b releases model memory while keeping the download.

OpenRouter

OpenRouter uses its maintained AI SDK adapter for streaming and tool calls, including reasoning metadata needed by some models when continuing after a tool result. Compatibility is checked against OpenRouter's official integration guide, streaming format and reasoning documentation, with local protocol fixtures rather than paid inference.

notch setup --provider openrouter
notch doctor
notch "Fix the failing tests"

The setup wizard shows the current OpenRouter coding model catalog and offers masked API-key entry. Keys are stored in the user credential store, not the project config. Alternatively set OPENROUTER_API_KEY in your environment and use notch setup --provider openrouter --model <provider/model>.

OpenRouter usage is billed to your OpenRouter account. Setup validates authentication, model availability and tool support; it does not send a billable coding request. Current model IDs come from the provider catalog rather than a fixed recommendation in this README.

OpenAI and Anthropic

notch setup --provider openai
notch setup --provider anthropic

Set OPENAI_API_KEY or ANTHROPIC_API_KEY, or paste your key into the hidden setup prompt. OpenAI uses the native Responses API; Anthropic uses the native Messages API. Setup checks model access without generating a billable response. Multi-workspace Anthropic keys may require ANTHROPIC_WORKSPACE_ID. API usage is billed separately from ChatGPT or Claude subscriptions. Use developer API credentials; Notch does not accept Claude subscription tokens or collect provider sign-in sessions. OpenAI API authentication, Anthropic credential policy.

Automation and overrides

notch --cwd /path/to/repo --provider ollama --model qwen3:4b "Explain the tests"
notch --json --provider openrouter --model <provider/model> "Review the changes"
notch doctor --json

Explicit CLI provider/model options override environment and project selection. Changing providers clears stale provider credentials and endpoints. Use --base-url only when intentionally overriding the selected provider endpoint. --no-repo-map skips automatic repository mapping, and --no-markdown disables Markdown rendering.

--json emits JSONL events. Fatal model/transport failures return a nonzero exit code. Tool permissions still apply; --trust autoapproves tool operations and should be used only in a workspace where you intend to allow those operations. Existing resume, checkpoints, permission controls, project instructions and MCP support remain available through notch --help.

Access profiles

Local Ollama/MLX generation requests share one cancellable queue across notch CLI and IDE processes using the same operating-system user/home directory. OpenRouter requests can run in parallel. A waiting task displays its status; Ctrl+C cancels the current CLI turn. Slots are released before tools or approvals, so workers cannot deadlock their parent. A killed process's queue entry is reclaimed automatically. Other applications using the runtime do not join this queue.

Tasks work directly in your project folder by default. Writable turns take turns across notch CLI and IDE processes, including shell commands and workers. Read-only cloud tasks can still run in parallel. Use /settings or /workspace for an arrow-key menu, /workspace shared to use the project folder, or /workspace isolated for parallel OpenRouter worktrees. The choice is saved in .notch.json as workspaceMode; notch config set workspaceMode isolated and --workspace-mode isolated also work. Local tasks always take turns.

In isolated mode, writable OpenRouter tasks use private Git worktrees, including their terminal commands and writable workers. No setup or branch switching is needed. Your staged edits, working files and untracked inputs are copied without changing your branch or index. Git must be installed; non-Git folders use a private Git database without initializing your project. Ignored dependencies and build outputs are not shared; a task can install its own dependencies.

Safe changes return to your project automatically when a task finishes, including terminal-created files, and are recorded in Undo. If another task or editor changed the same file, the entire delivery stays separate. Ask notch to reconcile it; the agent can read the latest source using task_changes before updating its private files. Interrupted tasks resume their saved checkout. Completed checkouts are removed automatically; conflicting or unfinished work is retained under ~/.notch/worktrees. JSONL includes workspace-result events and a session ID; delivery conflicts return exit code 2.

Shared MCP servers, plugins and command hooks are disabled for isolated tasks because they may retain another workspace's paths. Shared-folder tasks retain their existing integrations. Built-in file tools refuse writes outside the task checkout and stale edits within it. Worktrees separate ordinary commands but are not an operating-system sandbox: arbitrary code with explicit external paths can still access your account's files. Symbolic-link/submodule inputs fail safely; binary outputs remain in the private checkout when Undo cannot record them. File tools and Undo continue coordinating local edits, but external editors do not participate in notch's locks.

notch --access approve "Review the change"
notch --access read-only "Plan the refactor"
notch --access full-access "Implement and test the change"
notch --dry-run "Show the proposed edits"

approve uses your configured allow/ask/deny rules and asks before tools that require approval; an empty answer or closed input denies. Headless calls deny prompt-level tools unless you explicitly grant access or use the existing --yes option. read-only allows built-in file/search/web reads and denies other tools, even if a permission rule allowed them. full-access grants tools access without permission prompts; --trust is its legacy alias. Set accessMode in .notch.json or NOTCH_ACCESS_MODE to select a default; an explicit --access overrides it.

Dry-run previews tools that may change state, including MCP/plugin and worker execution. /dry-run toggles it interactively; /sandbox remains an alias. Access profiles and dry-run are harness controls, not OS isolation of the CLI, hooks, plugins or subprocesses. See the release-readiness audit for the remaining execution-backend work.

Switch the running profile with /permissions approve, /permissions read-only, or /permissions full-access; the choice is saved for this project. /strict restores approvals after full access. Ctrl-C cancels the current turn, including its local shell process tree. Commands entered while a turn is running are processed in order.

/undo restores the most recent changes captured by built-in write, edit and patch tools. Checkpoints survive restarts: use /resume or notch --session <id> to reopen the saved session, then /undo. Later manual edits, changed workspaces and linked files are protected. Failed or cancelled turns retain captured edits; an unverified write interrupted by a crash is blocked for inspection. Shell, plugin and external changes are not captured, so keep projects in Git. History is stored privately under ~/.notch/undo with a 64 MiB limit per session; start a new session if that limit is reached. In headless mode, reaching the iteration limit returns exit code 2 and a session-end status of max-iterations.

Validate

Windows source builds also require Rust (MSVC toolchain) and Visual Studio C++ build tools for the hardware probe. Installed npm packages include the executable; end users do not need Rust.

npm run typecheck
npm test
npm run build

See implementation research and verification for live-test evidence and current limitations.

Web research

Ask notch to search current documentation and cite sources. DuckDuckGo is the default and needs no API key or browser installation, including with local models. Open /settings web → Choose search provider, or run notch web, to choose DuckDuckGo or optional Tavily. For Tavily, add a key in the same menu or set TAVILY_API_KEY. A saved or environment key does not switch providers automatically. No notch account is required.

DuckDuckGo uses its public HTML search. It can rate-limit requests or ask for human verification; notch reports this instead of inventing results or silently switching to a paid service. Retry later or choose Tavily. Results come from the first search page, so the requested result count is a maximum, not a guarantee.

web_fetch reads known HTTP(S) URLs without a search key. browser_read uses a real browser for JavaScript pages. browser_interact opens a URL and performs up to eight click/fill/select/press steps before reading the result. Each browser call uses a fresh private session; cookies and login sessions do not persist between calls. Browser interactions use the normal task approval policy and are unavailable in read-only mode.

An installed Edge or Chrome is used automatically. Choose a browser or install Chromium in /settings web, or run notch web install-browser. Downloads are explicit; browser tools never install software silently. notch web status shows setup without revealing your key. Disable Web research in the same settings to stop these built-in network tools.

Sources include clickable Markdown links and retrieval times. Terminal output also prints visible source URLs and hyperlinks where supported. Search queries go to your selected search provider and page requests go to the visited websites, including when your language model is local. CLI search keys are saved in your per-user notch configuration with restrictive file permissions, outside the project; use an environment variable if you do not want a saved key.