nsh - The Natural Shell

Your shell already saw you fail - now it can actually help

AI-powered shell assistant for zsh, bash, fish, and PowerShell.

nsh lives in your terminal. It records command history, understands your project context, reads your scrollback, and turns natural-language requests into shell commands or direct answers - all without leaving your prompt.

? why did my last command fail
? set up a python virtualenv for this repo
? fix

nsh prefills commands at your prompt for review before execution. It never runs anything blindly (unless you enable autorun mode).

How it works

nsh wraps your shell in a PTY, capturing scrollback and command history into a local SQLite database. When you ask a question with ?, nsh builds context from your OS, shell, working directory, recent terminal output, project structure, git state, and conversation history, then streams a response from your configured LLM provider.

It responds by calling tools: command to prefill a shell command, chat for text answers, or any of its other built-in tools for investigation, file editing, web search, memory, and more. It can chain multiple tool calls in a single turn, investigating before acting.

you: ? install ripgrep
nsh: [searches history] -> [checks brew availability] -> [prefills command]
     $ brew install ripgrep
     Enter to run . Edit first . Ctrl-C to cancel

Features

Natural language interface

Three aliases, each a single character:

? ... - standard query
?? ... - reasoning/thinking mode (extended thinking for complex problems)
?! ... - private mode (query and response are not saved to history)

Append !! to any query to auto-execute the suggested command without confirmation.

Command prefill

nsh writes suggested commands to your shell's editing buffer. You see the command at your prompt, can edit it, then press Enter to run it - or Ctrl-C to cancel.

Two alternative modes are available via configuration: confirm (approve/reject without editing) and autorun (execute immediately for safe commands).

Context awareness

Every query includes context assembled automatically:

Terminal scrollback - recent output from your PTY session, including SSH sessions
Command history - past commands with exit codes, durations, and AI-generated summaries
Project detection - recognizes Rust, Node.js, Python, Go, Ruby, Java, C/C++, Nix, Docker, and Make projects
Git state - current branch, status, and recent commits
Cross-TTY context - optionally includes activity from other open terminal sessions
Environment - OS, architecture, installed package managers, development tools

Multi-step agent loop

nsh can chain multiple tool calls per query (50 by default, configurable). It investigates before acting - searching history, reading files, running safe commands, querying the web, and asking clarifying questions when needed - then executes and verifies results.

The pending flag on command suggestions enables autonomous multi-step sequences. Safe pending=true commands auto-execute by default and feed their output back into the same tool loop, so nsh can continue investigating, fixing, and verifying without stopping. If you prefer explicit approval for each intermediate step, set execution.confirm_intermediate_steps = true.

Coding agent

The code tool delegates programming tasks to a working-directory-constrained sub-agent that uses a more capable model. The sub-agent can read and write files, search the codebase with grep and glob, and run shell commands (build, test, lint) to verify its work. It shares the same iteration limit as the main agent (50 by default).

Use it for writing new code, refactoring, fixing bugs, running tests and fixing failures, debugging, or code reviews. The sub-agent gets the same project context and memory as the main agent.

? add pagination to the /users API endpoint
nsh: [launches coding agent] -> [reads existing code] -> [writes changes]
     -> [runs tests] -> [fixes failing test] -> [done]

Built-in tools

| Tool | What it does | |---|---| | command | Prefill a shell command for review | | chat | Text response (status updates, explanations) | | done | End the tool loop with a structured summary | | search_history | FTS5 + regex search across all command history | | grep_file | Regex search within files with context lines | | read_file | Read file contents with line numbers | | list_directory | List directory contents with metadata | | glob | Find files by glob pattern | | web_search | Search the web via Perplexity/Sonar | | github | Fetch READMEs, file trees, or specific files from GitHub repos | | run_command | Execute safe, allowlisted commands silently | | ask_user | Ask a clarifying question while keeping the loop active | | code | Launch a working-directory-constrained coding sub-agent for multi-step file editing | | write_file | Create or overwrite files (with diff preview and trash backup) | | patch_file | Surgical find-and-replace in files (with diff preview) | | man_page | Retrieve man pages for commands | | manage_config | Modify nsh settings (with confirmation) | | install_skill | Create reusable custom tool templates or clone skill repos | | uninstall_skill | Remove installed skills | | install_mcp_server | Add MCP tool servers to configuration | | skill_exists | Check if a skill is already installed | | search_memory | Search across all memory tiers | | core_memory_append | Append to core memory blocks | | core_memory_rewrite | Rewrite core memory blocks | | store_memory | Store entries in semantic, procedural, resource, or knowledge memory | | retrieve_secret | Retrieve encrypted secrets from the knowledge vault |

Entity-aware history search

nsh extracts structured entities (hostnames, IPs) from commands and stores them in a searchable index:

you: ? what servers have I ssh'd into recently
nsh: Recent machine targets for `ssh` (most recent first):
     - [2026-02-11T17:49:15Z] 135.181.128.145 (via ssh)
     - [2026-02-11T17:47:15Z] ssh.phx.nearlyfreespeech.net (via ssh)

Security

Secret redaction - over 100 built-in patterns detect and redact API keys, tokens, private keys, JWTs, database URLs, and more before sending context to the LLM. Custom patterns can be added.
Command risk assessment - every suggested command is classified as safe, elevated, or dangerous. Dangerous commands (recursive deletion of system paths, disk formatting, fork bombs, piping remote scripts to shell) always require explicit yes confirmation.
Sensitive directory blocking - reads and writes to ~/.ssh, ~/.gnupg, ~/.aws, ~/.kube, ~/.docker, and similar directories are blocked by default.
Tool output sandboxing - tool results are delimited by random boundary tokens and treated as untrusted data. Prompt injection attempts in tool output are filtered.
Protected settings - security-critical configuration keys (API keys, allowlists, redaction settings) cannot be modified by the AI.
Audit logging - all tool calls are logged to ~/.nsh/audit.log with automatic rotation.

Persistent memory

nsh has a 6-tier memory system inspired by the MIRIX architecture. Before every query, it retrieves relevant long-term memories and injects them as structured XML into the system prompt.

The six tiers:

Core - three fixed blocks (user facts, agent persona, environment). Always loaded into context.
Episodic - timestamped events: command executions, errors, instructions, file edits. Decays over time.
Semantic - facts extracted from episodes via LLM reflection. Things like "user builds with cargo" or "production database is on port 5433."
Procedural - step-by-step workflows with trigger patterns. Matched when your query resembles the trigger.
Resource - digests of important files and documentation, with content hashing to avoid re-ingestion.
Knowledge Vault - encrypted storage for secrets (AES-256-GCM). The LLM only ever sees captions, never the actual values.

The system runs an automatic lifecycle: ingestion buffers shell events, a classifier filters low-signal commands, a router categorizes what remains, and a consolidator deduplicates with Jaro-Winkler similarity. Periodically, episodic memories are promoted to semantic facts via LLM reflection, and old entries decay.

nsh memory search "cargo build"             # search all tiers
nsh memory search --type semantic "build"   # search a specific tier
nsh memory stats                            # counts per tier
nsh memory core                             # view core memory blocks
nsh memory maintain                         # run decay + reflection now
nsh memory bootstrap                        # initial scan of existing history
nsh memory clear                            # wipe all memories
nsh memory clear --type episodic            # wipe a specific tier
nsh memory export                           # export all memories as JSON
nsh memory decay                            # run decay only
nsh memory reflect                          # run reflection only

Control memory behavior in config:

# Pause recording (incognito mode)
nsh config edit   # set memory.incognito = true

Remote access and mobile companion

nsh supports P2P remote access using iroh, allowing you to connect to your shell sessions from a mobile device or another machine.

Pairing (mobile). Run nsh remote pair on your desktop. This generates a keypair (stored in ~/.nsh/remote_key) and displays a QR code containing your endpoint ID and relay URL. Enter the endpoint ID in the mobile app (or use LAN discovery). The desktop shows a connection request; confirm it, and the device is added to your allowed keys list.

**Connecting from another comp

Nsh

Install / Use

README