⚡ NeuralShell

The world's first AI-native shell layer.

MADE WITH ❤️ BY DXN1

What is NeuralShell

NeuralShell is an AI-native shell layer that sits beside your existing terminal workflow. It learns command patterns, predicts the next command, explains unfamiliar syntax, generates scripts from plain language, keeps a local recall index, and watches your system for anomalies.

It is designed to feel like a premium terminal companion rather than a wrapper that gets in the way.

Core Features

NeuralShell enhances your terminal experience with several AI-powered capabilities, seamlessly integrated into your workflow.

Workflow Prediction

NeuralShell learns your command patterns and predicts your next likely command, helping you work faster and more efficiently. It analyzes your command history, considering factors like frequency, success rate, and even your current working directory to offer highly relevant suggestions.

How it works:

Command Normalization: Commands are normalized to identify patterns, ignoring specific values like IPs, hashes, dates, and string literals. For example, git commit -m "Initial commit" and git commit -m "Fix bug" might both normalize to git commit -m <STR>.
Graph Building: NeuralShell builds a directed graph of your command sequences. Each command is a node, and transitions between commands are edges.
Contextual Awareness: Predictions are refined based on the current working directory, giving higher weight to commands frequently used in similar contexts.
Confidence Scoring: Each prediction comes with a confidence score, indicating how likely the suggestion is to be accurate.

In practice:

$ git push origin main
▸ Predicted: gh pr create --fill → gh pr view --web  [████████░░] 82%  [Tab]

In this example, after git push origin main, NeuralShell predicts that you might want to create a GitHub pull request (gh pr create --fill) and then view it (gh pr view --web), with an 82% confidence. You can often accept these predictions with a simple Tab press.

Configuration: You can adjust the prediction confidence threshold in your config.toml to control how often predictions are shown:

[core]
prediction_confidence = 0.75 # Only show predictions with confidence >= 75%

Explain Mode

NeuralShell's explain mode demystifies complex or unfamiliar shell commands by breaking them down into plain English. It leverages your configured AI backend to provide a clear summary, step-by-step breakdown, potential warnings, and related examples.

How it works:

AI-Powered Explanation: Uses a Large Language Model (LLM) to interpret the command and generate a human-readable explanation.
Structured Output: Explanations are presented in a structured format, making them easy to digest.
Caching: To ensure speed and avoid redundant LLM calls, explanations are cached locally. If you ask for an explanation of the same command again, it will be retrieved instantly from the cache.

In practice:

$ neuralshell explain "awk 'NR%2==0' file.txt"
╭─ ⚡ awk 'NR%2==0' file.txt ─────────────────────────────────────╮
│ Print every even-numbered line from file.txt.                  │
│                                                                │
│ Steps:                                                         │
│ • awk 'NR%2==0': This is the awk command, which is a powerful  │
│   text processing tool. 'NR%2==0' is the condition that checks│
│   if the current line number (NR) is even.                     │
│ • file.txt: This is the input file that awk will process.      │
│                                                                │
│ Warnings:                                                      │
│ • Ensure 'file.txt' exists and you have read permissions.      │
│                                                                │
│ Examples:                                                      │
│ • awk 'NR==1' file.txt (Print the first line)                  │
│ • awk '{print $1}' file.txt (Print the first column)          │
╰────────────────────────────────────────────────────────────────╯

This detailed output helps you quickly understand what a command does, its potential impact, and how to use it effectively.

Secret Scanning

NeuralShell includes a proactive secret scanning feature that inspects your commands before they are executed. This helps prevent accidental leakage of sensitive information (like API keys, tokens, or passwords) into your shell history or logs.

How it works:

Pre-execution Scan: Every command you type is scanned against a set of predefined and custom regular expressions.
Built-in Patterns: It comes with a comprehensive list of patterns for common secrets like AWS keys, OpenAI API keys, GitHub tokens, Stripe keys, and more.
Custom Patterns: You can extend its detection capabilities by adding your own regular expression patterns to the configuration.
Interactive Warning: If a potential secret is detected, NeuralShell will pause execution and prompt you for a decision: run the command anyway, run it but hide it from history, or cancel.

In practice:

If you accidentally type a command containing a sensitive token:

$ curl -H "Authorization: Bearer sk-live-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" https://api.example.com/data
╭─ ⚡ SECRET DETECTED ────────────────────────────────────────────╮
│ Potential secret 'sk-live-...' (OpenAI API Key) found in command.│
│                                                                │
│ Command: curl -H "Authorization: Bearer sk-live-..." https://api.example.com/data│
╰────────────────────────────────────────────────────────────────╯
  Action [Y] Run anyway   [H] Run & hide from history   [N] Cancel  → N

This prevents the sensitive string from ever reaching your shell's history file, protecting your credentials.

Configuration: You can enable/disable secret scanning or add custom patterns in your config.toml:

[secrets]
enabled = true
# Add custom regex patterns here (e.g., for internal tokens)
patterns = [
    "my_custom_token_[A-Za-z0-9]{16,}"
]

Sentinel

NeuralShell's sentinel is an intelligent background daemon that continuously monitors your system's resource usage (CPU, memory, disk I/O, network I/O). Unlike traditional threshold-based monitors, Sentinel learns the normal behavior of your system and alerts you to statistically significant anomalies.

How it works:

Baseline Learning: Sentinel passively collects system metrics over time to build a unique statistical baseline of your machine's typical activity.
Anomaly Detection: It uses z-score analysis to identify deviations from this learned baseline. An "anomaly" is something that falls outside the expected range of behavior, even if it doesn't cross a fixed, arbitrary threshold.
Actionable Suggestions: When an anomaly is detected, Sentinel provides a clear alert in your terminal along with a suggestion for which command to run to investigate the issue further (e.g., htop for high CPU).
Local Persistence: The learned baseline is stored locally (~/.local/share/neuralshell/sentinel_baseline.json).

In practice:

To start the Sentinel daemon:

neuralshell sentinel start

If Sentinel detects an unusual spike in CPU usage, you might see an alert like this:

[⚡ SENTINEL HIGH] [14:35:22] Anomaly in CPU PERCENT: 95.2 (mean=15.3, z=4.5σ)
  → Check top processes with `htop` or `ps aux --sort=-%cpu | head -10`.

Configuration: You can adjust the sensitivity of anomaly detection in your config.toml:

[sentinel]
interval = 5 # Sample interval in seconds
anomaly_sensitivity = "medium" # "low", "medium", or "high"

(Note: Sentinel requires the psutil Python library. If you encounter issues, ensure it's installed: pip install psutil)

Recall

NeuralShell's recall feature acts as an intelligent memory for your command history. It allows you to search through your past commands not just by keywords, but also by their meaning, helping you quickly find that obscure command you used weeks ago.

How it works:

Local Storage: All your command history is stored locally in an SQLite database (~/.local/share/neuralshell/history.db), ensuring your data remains private.
Semantic Search: When an embedding model is configured (e.g., via Ollama), NeuralShell can perform semantic searches. This means you can describe what you did, and it will find commands that are conceptually similar, even if they don't contain the exact keywords.
Full-Text Search (FTS): If no embedding model is available, it falls back to a robust full-text search, matching keywords within your commands.
Contextual Information: Search results include the command, the directory it was run in, and the timestamp, providing valuable context.

In practice:

To search for commands related to "compressing log files":

$ neuralshell recall "compress log files"
╭─ ⚡ Recall results for "compress log files" ────────────────────╮
│ Score | Command                               | CWD           | Run At      │
│───────|───────────────────────────────────────|───────────────|─────────────│
│ 0.89  | tar -czvf logs_backup.tar.gz logs/    | ~/projects/app| 2023-10-25  │
│ 0.85  | find . -name "*.log" -exec gzip {} +  | ~/server/logs | 2023-10-20  │
│ 0.72  | zip -r archive.zip . -i "*.log"       | ~/data        | 2023-09-15  │
│ 0.68  | gzip access.log                       | ~/web/logs    | 2023-10-26  │
╰────────────────────────────────────────────────────────────────╯

This feature is invaluable for developers, system administrators, and anyone who frequently uses the terminal and needs to quickly retrieve past actions.

Script Generation

NeuralShell can generate robust and defensive bash scripts from simple plain language descriptions. It aims to produce production-quality scripts that are well-commented, safe, and follow best practices.

How it works:

Natural Language to Script: Describe what you want the script to do, and NeuralShell will generate the bash code.
Defensive by Design: Generated scripts include #!/bin/bash and set -euo pipefail for safety, inline comments, and often checks for dependencies or input validation.
Interactive Prompt: After generation, NeuralShell provides an interactive prompt allowing you to save, run, edit, or discard the script.

In practice:

$ neuralshell gen "watch a folder and compress new files"
╭─ ⚡ Generated: watch_a_folder_and_compress.sh ──────────────────╮
│ #!/bin/bash                                                    │
│ # NeuralShell generated — 2023-10-27                             │
│ set -euo pipefail                                              │
│                                                                │
│ # --- Configuration ---                                        │
│ WATCH_DIR="${1:-./watch}" # Folder to watch, defaults to ./watch│
│ COMPRESS_TYPE="gzip"     # Compression type (e.g., gzip, bzip2)│
│                                                                │
│ # --- Functions ---                                            │
│ usage() {                                                      │
│   echo "Usage: $0 [WATCH_DIRECTORY]"                           │
│   echo "Watches a directory for new files and compresses them."│
│   exit 1                                                       │
│ }                                                              │
│                                                                │
│ # Check for dependencies                                       │
│ command -v inotifywait >/dev/null 2>&1 || { echo >&2 "Error:   │
│ inotifywait not found. Please install inotify-tools."; exit 1; }
│ command -v "$COMPRESS_TYPE" >/dev/null 2>&1 || { echo >&2 "Error:
│ $COMPRESS_TYPE not found."; exit 1; }                          │
│                                                                │
│ # Main logic                                                   │
│ mkdir -p "$WATCH_DIR"                                          │
│ echo "Watching directory: $WATCH_DIR for new files..."         │
│                                                                │
│ inotifywait -m -e create --format '%w%f' "$WATCH_DIR" | while  │
│ read NEW_FILE                                                  │
│ do                                                             │
│   if [ -f "$NEW_FILE" ]; then                                  │
│     echo "New file detected: $NEW_FILE. Compressing..."        │
│     "$COMPRESS_TYPE" "$NEW_FILE"                               │
│     echo "Compressed: $NEW_FILE.$COMPRESS_TYPE"                │
│   fi                                                           │
│ done                                                           │
╰────────────────────────────────────────────────────────────────╯
  Action [S=save / R=run / E=edit / X=discard]: S
  [green]✓[/green] Saved to [bold]./watch_a_folder_and_compress.sh[/bold]

This feature empowers you to quickly automate tasks without needing to remember complex bash syntax.

Explain Mode

NeuralShell's explain mode demystifies complex or unfamiliar shell commands by breaking them down into plain English. It leverages your configured AI backend to provide a clear summary, step-by-step breakdown, potential warnings, and related examples.

How it works:

AI-Powered Explanation: Uses a Large Language Model (LLM) to interpret the command and generate a human-readable explanation.
Structured Output: Explanations are presented in a structured format, making them easy to digest.
Caching: To ensure speed and avoid redundant LLM calls, explanations are cached locally. If you ask for an explanation of the same command again, it will be retrieved instantly from the cache.

In practice:

$ neuralshell explain "awk 'NR%2==0' file.txt"
╭─ ⚡ awk 'NR%2==0' file.txt ─────────────────────────────────────╮
│ Print every even-numbered line from file.txt.                  │
│                                                                │
│ Steps:                                                         │
│ • awk 'NR%2==0': This is the awk command, which is a powerful  │
│   text processing tool. 'NR%2==0' is the condition that checks│
│   if the current line number (NR) is even.                     │
│ • file.txt: This is the input file that awk will process.      │
│                                                                │
│ Warnings:                                                      │
│ • Ensure 'file.txt' exists and you have read permissions.      │
│                                                                │
│ Examples:                                                      │
│ • awk 'NR==1' file.txt (Print the first line)                  │
│ • awk '{print $1}' file.txt (Print the first column)          │
╰────────────────────────────────────────────────────────────────╯

This detailed output helps you quickly understand what a command does, its potential impact, and how to use it effectively.

Workflow Prediction

NeuralShell learns your command patterns and predicts your next likely command, helping you work faster and more efficiently. It analyzes your command history, considering factors like frequency, success rate, and even your current working directory to offer highly relevant suggestions.

How it works:

Command Normalization: Commands are normalized to identify patterns, ignoring specific values like IPs, hashes, dates, and string literals. For example, git commit -m "Initial commit" and git commit -m "Fix bug" might both normalize to git commit -m <STR>.
Graph Building: NeuralShell builds a directed graph of your command sequences. Each command is a node, and transitions between commands are edges.
Contextual Awareness: Predictions are refined based on the current working directory, giving higher weight to commands frequently used in similar contexts.
Confidence Scoring: Each prediction comes with a confidence score, indicating how likely the suggestion is to be accurate.

In practice:

$ git push origin main
▸ Predicted: gh pr create --fill → gh pr view --web  [████████░░] 82%  [Tab]

In this example, after git push origin main, NeuralShell predicts that you might want to create a GitHub pull request (gh pr create --fill) and then view it (gh pr view --web), with an 82% confidence. You can often accept these predictions with a simple Tab press.

Configuration: You can adjust the prediction confidence threshold in your config.toml to control how often predictions are shown:

[core]
prediction_confidence = 0.75 # Only show predictions with confidence >= 75%

Installation

NeuralShell requires Python 3.10+ and pip.

Linux / macOS (Recommended)

The easiest way to install NeuralShell on Linux or macOS is using the official install.sh script. This script handles Python/pip checks, installs NeuralShell, and automatically configures your shell integration.

Ensure Python 3.10+ and pip are installed. If you don't have them, you can usually install them via your system's package manager (e.g., sudo apt install python3 python3-pip on Debian/Ubuntu, brew install python on macOS).

Run the installer script:

curl -fsSL https://raw.githubusercontent.com/DXN1-termux/Neuralshell/main/scripts/install.sh | bash

This command downloads and executes the installation script.

Alternatively, clone the repository and install:

git clone https://github.com/DXN1-termux/Neuralshell.git
cd Neuralshell
bash scripts/install.sh

Reload your shell: After installation, you'll need to restart your terminal or run source ~/.bashrc (or your respective shell's RC file) for the changes to take effect.

Windows (via WSL)

NeuralShell is designed for Unix-like environments. On Windows, the recommended way to use NeuralShell is via the Windows Subsystem for Linux (WSL).

Install WSL: Follow Microsoft's official guide to install and set up WSL: Install WSL
Follow Linux Installation Steps: Once WSL is set up, open your WSL terminal and follow the Linux / macOS (Recommended) installation instructions above.

Manual Installation (Advanced)

If you prefer a manual setup or encounter issues with the automated script, you can install NeuralShell directly via pip and configure your shell manually.

Install Python 3.10+ and pip: Ensure you have Python 3.10 or newer and pip installed on your system. Refer to Python's official documentation or your OS package manager for installation instructions.

Install NeuralShell via pip:

python3 -m pip install --upgrade neuralshell

Integrate with your shell: NeuralShell needs to be initialized in your shell's configuration file. Choose your shell and add the corresponding line to its RC file:
- Bash (~/.bashrc):
```
eval "$(neuralshell init bash)"
```
- Zsh (~/.zshrc):
```
eval "$(neuralshell init zsh)"
```
- Fish (~/.config/fish/config.fish):
```
neuralshell init fish | source
```
- Nushell (e.g., ~/.config/nushell/config.nu):
```
# Add the output of 'neuralshell init nu' to your config.nu
# You might need to run 'neuralshell init nu' in your terminal
# and then copy-paste the output into your config.nu
```
  (Note: Nushell integration might require manual copy-pasting of the neuralshell init nu output as direct eval or source might behave differently.)
Reload your shell: After modifying your RC file, restart your terminal or run source ~/.bashrc (or your respective shell's RC file) for the changes to take effect.

How it feels in practice

$ git push origin main
▸ Predicted: gh pr create --fill → gh pr view --web  [████████░░] 82%  [Tab]

$ neuralshell explain "awk 'NR%2==0' file.txt"
╭─ ⚡ awk 'NR%2==0' file.txt ─────────────────────────────────────╮
│ Print every even-numbered line from file.txt.                  │
╰────────────────────────────────────────────────────────────────╯

$ neuralshell gen "watch a folder and compress new files"
╭─ ⚡ Generated: watch_a_folder_and_compress.sh ──────────────────╮
│ #!/bin/bash                                                    │
│ set -euo pipefail                                              │
│ ...                                                            │
╰────────────────────────────────────────────────────────────────╯

Features worth noticing

Learns from your own command history instead of a generic public dataset.
Keeps everything local unless you explicitly choose a cloud backend.
Works with bash, zsh, fish, and nushell through lightweight shell init scripts.
Preserves a small, readable codebase instead of splitting into a hundred tiny abstractions.
Fails gracefully when Ollama, embeddings, or external APIs are unavailable.

Shell integration

neuralshell init bash
neuralshell init zsh
neuralshell init fish
neuralshell init nushell

The shell hook path is intentionally small:

preexec captures the command.
The secret scanner checks the line before it lands in history.
The workflow graph records transitions.
The history index stores the raw command locally.
The UI prints the prediction or explanation.

AI Backends

Provider	Best for	Notes
Ollama	Local privacy-first use	Default backend. No API key required.
OpenAI	Hosted reasoning and drafting	Supports OpenAI-compatible endpoints.
Anthropic	Strong natural-language output	Good for explanations and script drafting.
Groq	Fast hosted completions	OpenAI-compatible chat format.

Configure it with:

neuralshell config set backend.provider ollama
neuralshell config set backend.model llama3.2
neuralshell config set backend.endpoint http://localhost:11434

Data and privacy

NeuralShell stores its state locally:

~/.config/neuralshell/config.toml
~/.local/share/neuralshell/history.db
~/.local/share/neuralshell/graph.json
~/.local/share/neuralshell/explain_cache.json
~/.local/share/neuralshell/sentinel_baseline.json

It does not need telemetry to function. Cloud calls only happen when you choose a cloud backend.

Commands

Command	Purpose
`neuralshell init <shell>`	Print shell integration code.
`neuralshell explain <cmd>`	Explain a shell command in plain English.
`neuralshell gen <desc>`	Generate a bash script.
`neuralshell recall <query>`	Search command history.
`neuralshell stats`	Show workflow graph statistics.
`neuralshell doctor`	Check install health and backend reachability.
`neuralshell config show`	Print current configuration.
`neuralshell config set <k> <v>`	Update a configuration value.
`neuralshell sentinel start`	Start the anomaly daemon.
`neuralshell update`	Upgrade via pip.

Project structure

neuralshell/
├── neuralshell/
│   ├── core.py          # orchestration layer
│   ├── predictor.py     # command graph and predictions
│   ├── recall.py        # local search index
│   ├── secrets.py       # pre-exec secret scanner
│   ├── sentinel.py      # system anomaly detector
│   ├── generator.py     # bash script generation
│   ├── explainer.py     # natural-language command explanation
│   ├── backends/        # Ollama / OpenAI / Anthropic / Groq
│   └── ui/              # Rich terminal presentation
├── scripts/             # shell init and install scripts
├── docs/                 # architecture and contribution notes
├── assets/               # SVG visuals used by the README
└── tests/                # automated test suite

Quality

The repository ships with tests that cover the core hook flow, prediction graph, secret scanning, and sentinel anomaly detection. The latest rewrite also improved configuration serialization, graph persistence, and shared backend request handling.

Roadmap

a richer TUI dashboard
more shell-native quality-of-life commands
better recall ranking for larger command histories
optional encrypted local state
more diagrammed docs and example workflows

FAQ

Does it replace my shell?

No. It wraps your existing shell with lightweight hooks and keeps the workflow familiar.

Can it run without internet?

Yes, as long as you use a local backend such as Ollama and do not rely on cloud APIs.

What makes it feel polished?

The combination of a small hook surface, Rich-based terminal output, local persistence, and generated docs/assets makes it feel more like a complete product than a single script.

Is the codebase intentionally compact?

Yes. It is designed to be readable, maintainable, and easy to extend.

Contributing

Open a pull request if you want to improve the CLI, add shell integrations, make the output prettier, or tighten the safety and reliability story. Please keep the code readable and test-backed.

See also: docs/contributing.md and docs/architecture.md.

Changelog

Read CHANGELOG.md for the full release notes.

License

MIT.

Built for terminal people who like their tools sharp, clean, and honest.

Name		Name	Last commit message	Last commit date
Latest commit History 28 Commits
.github/workflows		.github/workflows
assets		assets
docs		docs
neuralshell		neuralshell
scripts		scripts
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

⚡ NeuralShell

Table of Contents

What is NeuralShell

Core Features

Workflow Prediction

Explain Mode

Secret Scanning

Sentinel

Recall

Script Generation

Explain Mode

Workflow Prediction

Installation

How it feels in practice

Features worth noticing

Shell integration

AI Backends

Data and privacy

Commands

Project structure

Quality

Roadmap

FAQ

Contributing

Changelog

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

⚡ NeuralShell

Table of Contents

What is NeuralShell

Core Features

Workflow Prediction

Explain Mode

Secret Scanning

Sentinel

Recall

Script Generation

Explain Mode

Workflow Prediction

Installation

How it feels in practice

Features worth noticing

Shell integration

AI Backends

Data and privacy

Commands

Project structure

Quality

Roadmap

FAQ

Contributing

Changelog

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages