nlsh-ai 0.1.2

Natural Language Shell - AI-augmented command line interface

nlsh - Natural Language Shell

An AI-augmented command line shell that wraps your existing shell and adds natural language command generation via LLM.

Features

• Shell Compatibility: Works with any shell (bash, zsh, fish, sh)
• Natural Language Commands: Use llm: <prompt> to generate shell commands from natural language
• Rich Context: LLM has access to current directory, file listings, shell info, and environment
• Command History: Full SQLite-based history tracking of all commands and LLM interactions
• Safety First: Always prompts for confirmation before executing AI-generated commands
• Rich Terminal Output: Beautiful terminal interface powered by Rich
• Streaming Responses: Real-time streaming with animated progress spinners for tool calls
• Tool-Enabled AI: AI can execute shell commands, read files, and gather system information with confirmation

Installation

Prerequisites

• Python 3.9 or higher
• OpenAI API key
• uv package manager (recommended) or pip

Using uv (recommended)

# Clone the repository
git clone <repository-url>
cd nlsh

# Install with uv
uv pip install -e .

# Or install dependencies directly
uv pip install rich openai typer python-dotenv

Using pip

pip install -e .

Configuration

1. Copy the example environment file:

cp .env.example .env

2. Edit .env and add your OpenAI API key:

OPENAI_API_KEY=your_openai_api_key_here

3. Optional: Configure the LLM model (default is gpt-4o-mini for cost efficiency):

OPENAI_MODEL=gpt-4o  # or gpt-3.5-turbo, etc.

Usage

Starting nlsh

nlsh

This will start the natural language shell interface with streaming enabled by default.

Command Line Options

nlsh --help                    # Show all available options
nlsh --no-stream              # Disable streaming (faster but less interactive)
nlsh --use-simple             # Use simple OpenAI interface instead of LangGraph
nlsh --debug                  # Enable debug mode

Commands

Regular Shell Commands

Just type commands normally - they'll be passed through to your default shell:

bitchin-shell $ ls -la
bitchin-shell $ cd src
bitchin-shell $ git status

Natural Language Commands

Use the llm: prefix for AI-generated commands:

nlsh $ llm: find all python files larger than 1MB
nlsh $ llm: show me git commits from last week
nlsh $ llm: compress all jpg files in this directory
nlsh $ llm: install the requests package

The AI will:

1. Proactively use tools to understand your environment (directory contents, git status, system info, etc.)
2. Analyze your request and current context (working directory, files, shell type)
3. Gather additional information if needed (with animated progress indicators)
4. Generate appropriate shell commands based on discovered information
5. Show you the commands and ask for confirmation
6. Execute the commands if you approve

Exiting

bitchin-shell $ exit
# or
bitchin-shell $ quit

How It Works

Streaming Interface

nlsh features a modern streaming interface that shows:

• 🔄 Animated spinners for tool operations (file reading, directory listing, etc.)
• 📁 Real-time tool call descriptions ("Reading file: config.py", "Checking git status")
• 💬 Streaming AI responses as they're generated
• ✅ Tool completion confirmations with result previews

Tool-Enabled AI

The AI has access to powerful tools and uses them proactively:

• 📁 File Operations: List, read, and find files
• ⚡ Shell Commands: Execute commands with mandatory confirmation
• 📊 Git Integration: Check status, view logs, and diffs
• 💻 System Info: Access environment and system details
• 🌳 Directory Trees: Navigate and understand project structure

Key Feature: The AI automatically uses these tools when relevant - you don't need to explicitly ask it to "check files" or "use git status". It proactively gathers information to provide better responses and commands.

Context Awareness

The LLM receives rich context about your environment:

• Current working directory and file listings
• Shell information (type, version, features)
• System information (OS, architecture)
• Environment variables (PATH, HOME, etc.)
• Recent command history
• Session conversation history for long-running interactions

Shell Detection

nlsh automatically detects your shell from the $SHELL environment variable and adapts:

• bash/zsh: Standard POSIX syntax
• fish: Fish-specific syntax and features
• sh: Basic POSIX compatibility mode

History Tracking

All interactions are stored in SQLite database (~/.nlsh/history.db):

• Shell commands and their output
• LLM interactions (prompts, generated commands, execution results)
• Context snapshots
• Session information

Session History Awareness

nlsh maintains awareness of your current session's history to enable natural, long-running conversations:

• Previous commands and their results are included in the LLM context
• Past AI interactions help the AI understand conversation flow
• Failed commands are remembered to avoid repeating mistakes
• Successful patterns can be referenced in follow-up requests

This enables commands like:

nlsh $ llm: find all large log files
# AI finds files and shows commands

nlsh $ llm: now compress those files from the previous search
# AI remembers the previous search results and can reference them

Examples

File Operations

nlsh $ llm: find all Python files modified in the last 24 hours
# Generates: find . -name "*.py" -mtime -1

nlsh $ llm: backup all my config files to a tar archive
# Generates: tar -czf config_backup_$(date +%Y%m%d).tar.gz ~/.bashrc ~/.vimrc ~/.gitconfig

Development Tasks

nlsh $ llm: run the tests and show coverage
# Generates: python -m pytest --cov=. --cov-report=term-missing

nlsh $ llm: start a local web server on port 8080
# Generates: python -m http.server 8080

System Administration

nlsh $ llm: show me processes using more than 100MB of memory
# Generates: ps aux | awk '$6 > 102400 {print $0}' | sort -k6 -nr

nlsh $ llm: check disk usage and show largest directories
# Generates: du -h --max-depth=1 | sort -hr

Architecture

nlsh/
├── src/nlsh/
│   ├── cli.py          # Main CLI interface and REPL loop
│   ├── shell.py        # Shell detection and command execution
│   ├── llm.py          # OpenAI integration and command generation
│   ├── context.py      # Environment and filesystem context gathering
│   └── history.py      # SQLite-based history management
├── pyproject.toml      # Python package configuration
└── README.md

Development

Running from Source

# Install in development mode
uv pip install -e .

# Run directly
python -m nlsh.cli

# Or run the installed command
nlsh

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Troubleshooting

Common Issues

"OPENAI_API_KEY environment variable is required"

• Make sure you've created a .env file with your OpenAI API key
• Verify the key is correct and has sufficient credits

"Shell detection failed"

• nlsh falls back to sh if it can't detect your shell
• You can manually set SHELL environment variable if needed

"Permission denied" errors

• Make sure nlsh has permission to create the history database in ~/.nlsh/
• Check file permissions in your working directory

Debug Mode

Run with debug flag to see detailed error information:

nlsh --debug

Roadmap

Phase 2 Features (Planned)

• Follow-up Commands: "rerun that but with sudo", "do the same for .js files"
• Trusted Commands: Auto-execute safe commands without confirmation
• Plugin System: Extensible AI tools and integrations
• Better Shell Integration: Tab completion, command substitution

Phase 3 Features (Future)

• Full Shell Replacement: Built-in shell features, not just wrapper
• Advanced Context: Git repository awareness, project type detection
• Collaborative Sessions: Shared session history and context
• Custom LLM Models: Support for local/custom models

License

[License information]

Credits

Built with:

• Rich for beautiful terminal output
• Typer for CLI framework
• OpenAI for language model integration