Skip to main content

NatShell

PyPI version CI

Natural language shell interface for Linux, macOS, and WSL — a local-first agentic TUI powered by a bundled LLM.

Type requests in plain English and NatShell plans and executes shell commands to fulfill them, using a ReAct-style agent loop with a bundled local model via llama.cpp. Supports optional remote inference via Ollama or any OpenAI-compatible API.

Install

From PyPI

pip install natshell              # Remote/Ollama mode (no C++ compiler needed)
pip install natshell[local]       # Includes llama-cpp-python for local inference
git clone https://github.com/Barent/natshell.git && cd natshell
bash install.sh

The installer handles everything — Python venv, GPU detection (Vulkan/Metal/CPU), llama.cpp build, model download, and Ollama configuration. No sudo required. Missing system dependencies (C++ compiler, clipboard tools, Vulkan headers, etc.) are detected and offered for install automatically.

Model options during install:

Preset Model Size Best for
Light Qwen3-4B (Q4_K_M) ~2.5 GB Low RAM systems, fast responses
Standard Qwen3-8B (Q4_K_M) ~5 GB General purpose, better reasoning
Enhanced Mistral Nemo 12B (Q4_K_M) ~7.5 GB Best quality, 128K context
Gemma Light Gemma 4 E2B (Q4_K_M) ~1.5 GB Ultra-light MoE, 128K context
Gemma Standard Gemma 4 E4B (Q4_K_M) ~5 GB Efficient MoE, 128K context
Gemma Enhanced Gemma 4 12B (Q4_K_M) ~7.1 GB Dense 12B, 128K context
Remote only Ollama server 0 GB Offload to a remote machine

Mistral Nemo 12B is recommended for most systems with 16+ GB RAM (or a GPU with 8+ GB VRAM). For users who prefer Google's model family, the three Gemma 4 tiers (gemma-light, gemma-standard, gemma-enhanced) mirror the same light/standard/enhanced progression.

Development setup

git clone https://github.com/Barent/natshell.git && cd natshell
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pip install llama-cpp-python                # CPU-only
# CMAKE_ARGS="-DGGML_VULKAN=on" pip install llama-cpp-python --no-cache-dir  # Vulkan (Linux)
# CMAKE_ARGS="-DGGML_METAL=on" pip install llama-cpp-python --no-cache-dir   # Metal (macOS)
natshell

Usage

natshell                          # Launch with defaults (local model)
natshell --model ./my-model.gguf  # Use a specific GGUF model
natshell --remote http://host:11434/v1 --remote-model qwen3:4b  # Use Ollama/remote API
natshell --download               # Download the default model and exit
natshell --update                 # Self-update from git and reinstall
natshell --config path/to/config.toml  # Custom config file
natshell --verbose                # Enable debug logging
natshell --headless "list files"  # Single-shot non-interactive mode (stdout pipeable)
natshell --headless --danger-fast "deploy" # Headless with auto-approve confirmations
natshell --mcp                    # Start as MCP server (stdin/stdout JSON-RPC)

Features

Agent Loop

NatShell uses a ReAct-style agent loop — the model reasons about your request, calls tools (shell commands, file operations, etc.), observes results, and iterates until the task is complete. Up to 15 tool calls per request by default.

Inference Backends

  • Local: Bundled llama.cpp via llama-cpp-python. Six model tiers: Qwen3-4B (light), Qwen3-8B (standard), Mistral Nemo 12B (enhanced), Gemma 4 E2B (gemma-light), Gemma 4 E4B (gemma-standard), Gemma 4 12B (gemma-enhanced). Selected during install, auto-downloaded on first run.
  • Remote: Any OpenAI-compatible API — Ollama, vLLM, LM Studio, etc.
  • Fallback: If the remote server is unreachable, NatShell automatically falls back to the local model.
  • Runtime switching: Switch models on the fly with /model commands without restarting.

GPU Acceleration

  • Auto-detects GPUs via vulkaninfo, nvidia-smi, and lspci
  • Prefers discrete GPUs over integrated on multi-GPU systems
  • Supports Vulkan (Linux/AMD/NVIDIA), Metal (macOS), and CPU fallback
  • Prints helpful reinstall instructions if GPU support is missing

Tools

The agent has access to 12 tools:

  • execute_shell — Run any shell command via bash
  • read_file — Read file contents
  • write_file — Write or append to files (always requires confirmation)
  • edit_file — Targeted search-and-replace edits (always requires confirmation)
  • run_code — Execute code snippets in 10 languages (Python, JS, Bash, Ruby, Perl, PHP, C, C++, Rust, Go)
  • list_directory — List directory contents with sizes and types
  • search_files — Search file contents (grep) or find files by name
  • git_tool — Structured git operations (status, diff, log, branch, commit, stash)
  • natshell_help — Look up NatShell documentation by topic
  • fetch_url — Fetch URL contents (blocks private/internal IPs for SSRF protection)
  • kiwix_search — Search offline Wikipedia/Kiwix ZIM archives
  • update_config — Modify NatShell configuration at runtime

TUI Commands

Command Description
/help Show available commands
/clear Clear chat and model context
/cmd <command> Execute a shell command directly (bypasses AI, respects safety)
/model Show current engine and model info
/model list List models available on the remote server
/model use <name> Switch to a remote model
/model switch Switch local GGUF model (opens command palette)
/model local Switch back to local model
/model default <name> Save default remote model to config
/compact Summarize conversation to free context window space
/plan <description> Generate a step-by-step plan (PLAN.md) from natural language
/exeplan run PLAN.md Execute a previously generated plan
/undo Undo the last file edit (restores from backup)
/save [name] Save current conversation to a session file
/load <id> Load a saved conversation session
/sessions List all saved sessions
/keys Show keyboard shortcuts
/history Show conversation message count

Keyboard Shortcuts

Key Action
Ctrl+C Quit
Ctrl+E Copy entire chat to clipboard
Ctrl+L Clear chat
Ctrl+P Command palette (model switching)
Ctrl+Y Copy selected text
Mouse drag / double-click / triple-click Select text; copied to the clipboard on release ([ui] copy_on_select)

Backup & Undo

Every file edit creates a timestamped backup in ~/.local/share/natshell/backups/. Use /undo to restore the most recent edit. Backups are pruned to 10 per file by default.

Session Persistence

Save and restore conversations with /save, /load, and /sessions. Sessions are stored as JSON in ~/.local/share/natshell/sessions/.

Headless Mode

Run NatShell non-interactively with --headless "prompt". Response text goes to stdout (pipeable), everything else to stderr. Use --danger-fast to auto-approve confirmations, or --no-danger-fast to force confirmations back on for one run. Set [safety] danger_fast = true in config.toml (or answer "yes" to the setup wizard/installer prompt) to always run in danger-fast mode on a given machine, without passing the flag every time.

MCP Server

Run NatShell as an MCP (Model Context Protocol) server with --mcp. Exposes all tools via JSON-RPC over stdin/stdout for integration with other AI tools.

Skill System

NatShell ships 10 built-in skills covering spreadsheets, PDFs, Word docs, coding, testing, git, system administration, data analysis, web research, and markdown documentation. The model automatically sees a short description of each skill and calls skill(name=...) to load full instructions on demand.

Add your own skills by creating a directory under ~/.config/natshell/skills/<name>/ containing a SKILL.md file with YAML frontmatter and an instructions body. An optional tools.py with a register() function can add custom tools. See SKILL_AUTHORING.md for full details.

/skills                   # list all discovered skills
/skills show <name>       # print skill body inline
/skills enable <name>     # re-enable a disabled skill
/skills disable <name>    # hide a skill from the model

Prompt Caching

System prompt tokens are cached across requests to reduce latency on local inference. Cache is invalidated when the system prompt changes.

Diff Preview

File edits show a unified diff preview in the confirmation dialog, making it easier to review changes before approving.

Safety

Commands are classified into three risk levels by a fast, deterministic regex-based classifier:

  • Safe — auto-executed (ls, cat, df, grep, etc.)
  • Confirm — requires user approval (rm, sudo, apt install, docker rm, iptables, etc.)
  • Blocked — never executed (fork bombs, rm -rf /, destructive dd/mkfs to disks, etc.)

Additional safety features:

  • Commands chained with &&, ||, ;, &, or | are split and each sub-command is classified independently
  • Subshell expressions ($(...)) and backtick expansions are flagged for confirmation
  • Sensitive file paths (SSH keys, /etc/shadow, .env) require confirmation for read_file
  • Sensitive environment variables (API keys, tokens, credentials) are filtered from subprocesses
  • Sudo passwords are cached for 5 minutes with automatic expiry
  • LLM output is escaped to prevent Rich markup injection in the TUI
  • API keys sent over plaintext HTTP trigger a warning

Safety modes are configurable: confirm (default), warn, or danger. All patterns are customizable in config.

Configuration

Default configuration is bundled with the package. Copy it to ~/.config/natshell/config.toml to customize:

python -c "from pathlib import Path; import natshell; p = Path(natshell.__file__).parent / 'config.default.toml'; print(p.read_text())" > ~/.config/natshell/config.toml

Or if installed from source, copy src/natshell/config.default.toml directly.

Sections

  • [model] — GGUF path, HuggingFace repo/file for auto-download, context size (0 = auto-detect from model), GPU layers, device selection
  • [remote] — URL, model name, API key for OpenAI-compatible endpoints
  • [ollama] — Ollama server URL and default model (used by /model list and /model use)
  • [agent] — max steps (15), temperature (0.3), max tokens (2048)
  • [prompt] — persona (custom role description) and extra_instructions (appended to system prompt). Core safety rules are always included
  • [safety] — mode, confirmation regex patterns, blocked regex patterns
  • [backup] — backup directory, max backups per file
  • [mcp] — MCP server safety mode
  • [ui] — theme (dark/light), copy_on_select (copy a mouse selection when the drag is released; default on)

Environment Variables

  • NATSHELL_API_KEY — API key for remote inference (alternative to storing in config file)

Cross-Platform Support

Feature Linux macOS WSL
Shell execution bash bash bash
GPU Vulkan Metal Vulkan
Clipboard wl-copy, xclip, xsel pbcopy clip.exe
Package manager apt, dnf, pacman, zypper, apk, emerge brew apt
System context lscpu, free, ip, systemctl sw_vers, sysctl, vm_stat, ifconfig lscpu, free, ip
Safety patterns Linux + generic macOS-specific (brew, launchctl, diskutil) Linux + generic

Clipboard auto-detects the best backend with fallback to OSC52 terminal escape sequences for remote/VM sessions.

Architecture

src/natshell/
├── __main__.py              # CLI entry point, model download, engine wiring
├── app.py                   # Textual TUI application
├── backup.py                # Pre-edit backup system with undo support
├── commands.py              # Slash command dispatch (refactored from app.py)
├── config.py                # TOML config loading with env var support
├── config.default.toml      # Bundled default configuration
├── gpu.py                   # GPU detection (vulkaninfo/nvidia-smi/lspci)
├── headless.py              # Non-interactive single-shot CLI mode
├── mcp_server.py            # MCP server (JSON-RPC over stdin/stdout)
├── model_manager.py         # Model discovery, download, and switching
├── platform.py              # Platform detection (Linux/macOS/WSL)
├── skills/                  # Built-in skills (10 shipped; user skills in ~/.config/natshell/skills/)
├── session.py               # Conversation session persistence
├── agent/
│   ├── loop.py              # ReAct agent loop with safety checks
│   ├── system_prompt.py     # Platform-aware system prompt builder
│   ├── context.py           # System info gathering (CPU, RAM, disk, network, etc.)
│   ├── context_manager.py   # Conversation context window management
│   ├── plan.py              # Plan generation and markdown parsing
│   └── plan_executor.py     # Step-by-step plan execution engine
├── inference/
│   ├── engine.py            # Inference engine protocol + CompletionResult types
│   ├── local.py             # llama-cpp-python backend with GPU support
│   ├── remote.py            # OpenAI-compatible API backend (httpx)
│   └── ollama.py            # Ollama server discovery and model listing
├── safety/
│   └── classifier.py        # Regex-based command risk classifier
├── tools/
│   ├── registry.py          # Tool registration and dispatch
│   ├── execute_shell.py     # Shell execution with sudo, env filtering, truncation
│   ├── read_file.py         # File reading
│   ├── write_file.py        # File writing
│   ├── edit_file.py         # Targeted search-and-replace edits
│   ├── run_code.py          # Code execution in 10 languages
│   ├── list_directory.py    # Directory listing
│   ├── search_files.py      # Text/file search
│   ├── git_tool.py          # Structured git operations
│   ├── fetch_url.py         # URL fetching with SSRF protection
│   ├── file_tracker.py      # File read state tracking for edit safety
│   ├── limits.py            # Context-aware output truncation limits
│   └── natshell_help.py     # Self-documentation by topic
└── ui/
    ├── widgets.py           # TUI widgets (messages, command blocks, modals)
    ├── commands.py          # Command palette providers
    ├── clipboard.py         # Cross-platform clipboard integration
    ├── escape.py            # Rich markup escaping utilities
    └── styles.tcss          # Textual CSS stylesheet

Development

source .venv/bin/activate
pytest                    # Run tests (1,175+ tests)
ruff check src/ tests/    # Lint

License

MIT

Metadata

Release files for natshell 1.0.51

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for natshell 1.0.51
File Size Uploaded Provenance Actions
natshell-1.0.51.tar.gz 404.1 kB With provenance Details for natshell-1.0.51.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for natshell 1.0.51
File Interpreter ABI Platform Actions
natshell-1.0.51-py3-none-any.whl Python 3 none any Details for natshell-1.0.51-py3-none-any.whl

Total release size: 696.7 kB

Release files / natshell-1.0.51.tar.gz

Download URL natshell-1.0.51.tar.gz
Size 404.1 kB
Tags Source
SHA-256 checksum
How to use checksums
e963149b57103532f2f1ba0ca4f3936d821c70fd6b949d0c15da631b26a56595
BLAKE2b-256 checksum
How to use checksums
2d34ebf630ca9d2a1d98b6dbf333da9019962e556c53f8851914388ef7ae9634
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

Release files / natshell-1.0.51-py3-none-any.whl

Download URL natshell-1.0.51-py3-none-any.whl
Size 292.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5c931a236e2e52c0b5954a08bf212be4c4c7ed05408cbc123d6f2efc10ba98dd
BLAKE2b-256 checksum
How to use checksums
431dedc125c258210e81427a153d248191b9bfaf8d4b15656b953ca2e440962b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

Security for natshell 1.0.51

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for natshell-1.0.51.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.51 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page