LLM Shell Assistant

An intelligent shell that combines traditional shell capabilities with natural language processing. Features include command generation from natural language, automatic error explanations, and command completion.

Prerequisites

• Python 3.8 or higher
• A Google API key for Gemini AI (the specific model used can be configured, check llm.py)
• GCC compiler (for the C core extension)

Setup

Method 1: Install from PyPI (Recommended)

Install directly using pip:

pip install shell-llm

Set up your Google API key (see "Post-Installation Setup" below).

Method 2: Install from Source (for Development)

1. Clone the repository:

   git clone https://github.com/jrdfm/shell-llm.git # Update URL if needed
   cd shell-llm
   

2. Create and activate a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows use `venv\Scripts\activate`
   

3. Install dependencies (including build/test tools):

   pip install -r requirements.txt
   pip install build twine cibuildwheel pytest pytest-asyncio pytest-mock
   

4. Build the C extension:

   # Build the C extension module and place it in the source tree
   python -m build --wheel --outdir . --no-isolation
   # Or build and install into the venv (needed to run `shell-llm` command directly)
   # pip install . --force-reinstall
   

5. Set up your Google API key (see "Post-Installation Setup" below).

Running the Shell

1. Activate Virtual Environment (if installed from source):

   source venv/bin/activate
   

2. Run:

   shell-llm
   

Usage

• Standard Shell Commands: Most standard shell commands work as expected. Pipelines (|) are supported. Note: Redirection (>, <, >>, etc.) is not currently implemented by the shell wrapper; these characters will likely be treated as literal arguments by commands.
• Natural Language Queries: Start your query with #.

  # how do I find large files?
  

• Verbosity Flags (for NL Queries): Add -v or -vv after # for more detailed explanations of the generated command.

  # -v list files sorted by size
  # -vv copy files securely between servers
  

• Smart Command Completion: Press Tab to get context-aware completion suggestions for commands, paths, flags, and environment variables.
• Pipe Completion: Intelligent completion works after pipe characters (|) to suggest commands.
• Exit: Type exit or press Ctrl+D.

Known Limitations / TODO

• Shell Aliases: User-defined aliases (e.g., alias ll='ls -l') are not recognized or expanded. The shell executes commands directly. (Common commands like ls and grep have --color=auto added automatically for visual consistency).
• Redirection: Input/output redirection (>, <, >>, 2>) is not currently implemented.
• Complex Shell Syntax: Features like command substitution ($(...)), process substitution (<()), brace expansion ({a,b}), background tasks (&), shell functions, and advanced globbing are not supported as they rely on a full shell interpreter.
• Environment Variable Completion: Tab completion for environment variables currently uses the environment shell-llm started with (os.environ), not the potentially modified environment within the core.Shell context.

Features

• Natural Language to Command: Generate shell commands from plain English.
• Command Execution: Executes commands using a performant C core extension.
• Pipeline Support: Handles command pipelines (cmd1 | cmd2).
• AI-Powered Error Explanations: Captures stderr and exit codes, providing explanations and potential solutions using an LLM.
• Command History: Persistent history across sessions (~/.llm_shell_history).
• Auto-Suggestion: Suggests commands based on history.
• Intelligent Command Completion: Smart completion for commands, paths, flags, and environment variables with special handling for pipe commands.

Technical Implementation

Architecture Overview

The project uses a hybrid architecture:

1. Core Shell Logic (core/shell.c): Written in C for executing commands and pipelines efficiently using fork, execvp, pipe, and waitpid. Manages the shell's internal state (CWD, environment variables, last exit code). Exposed to Python via CPython API bindings.
2. CPython Wrapper (core/shell_python.c): Provides the Python interface (core.Shell class) to the C functions using the CPython API. Handles type conversions (e.g., Python lists to C argv arrays) and memory management for interacting with the C layer.
3. Python Shell Interface (shell.py): The main interactive loop using prompt_toolkit. Handles user input, calls the core.Shell extension for execution, manages history and completions, and orchestrates LLM interactions.
4. Command Parsing (shell.py): User input strings are parsed into argument lists using Python's standard shlex module before being passed to the C extension. This ensures correct handling of quotes and escapes according to POSIX shell rules.
5. Command Completion (completions.py): Provides smart completion for commands, paths, flags, and environment variables with special handling for pipe context.
6. LLM Integration (llm.py): Manages communication with the Google Generative AI API (Gemini) for natural language command generation and error explanation.
7. Supporting Modules: formatters.py, error_handler.py, ui.py, models.py, utils.py provide specific functionalities.

For more in-depth details on the C core and Python wrapper implementation, please see docs/TECHNICAL_DETAILS.md.

Build System

• The project uses setuptools as the build backend, configured primarily via pyproject.toml.
• setup.py exists mainly to define the C extension module (core).
• Dependencies and project metadata (like version) are defined in pyproject.toml.
• The standard python -m build command is used to create source distributions and wheels.
• cibuildwheel is recommended for building cross-platform compatible Linux wheels for PyPI distribution.

Testing

• Unit Tests (test_core.py): Use pytest to test the Python interface (core.Shell) provided by the C extension. Ensures the C functions behave as expected when called from Python with pre-parsed arguments.
• Integration Tests (test_shell_integration.py): Use pytest, pytest-asyncio, and pytest-mock to test the main LLMShell class in shell.py. These tests verify the interaction between the Python shell logic (including shlex parsing) and the C core, as well as error handling pathways.

Contributing

Please refer to INSTRUCTIONS.md for detailed development, building, testing, and contribution guidelines.

License

[Specify Your License Here - e.g., MIT License]