ShellSense

Features

• AI Assistant: Get expert help for any terminal task with multiple AI providers
• Smart Search: Integrated web search and Wikipedia lookup
• Data Tools: GitHub info, stock data, and product research
• Translation: Built-in support for multiple languages
• Screenshots: Capture webpage screenshots
• Code Help: Generate and explain code snippets
• Rich Output: Beautiful terminal formatting with loading animations
• Universal: Works with any Linux terminal (bash, zsh, fish, etc.)
• Extensible: Easy to add new tools and providers

Installation

Prerequisites

• Python 3.8 or higher
• pip (Python package installer)
• Chrome/Chromium (optional, for screenshots)

Quick Install

pip install shellsense

That's it! ShellSense is now installed and ready to use.

First-time Setup

Run the setup command to create your configuration:

shellsense --setup

This creates a configuration file at ~/.config/shellsense/config.env. Edit this file with your API keys:

# OpenAI API Keys (Optional)
OPENAI_API_KEY=your-openai-api-key

# Gemini API Keys (Optional)
GEMINI_API_KEY=your-gemini-api-key

# Cloudflare Environment Variables
CLOUDFLARE_ACCOUNT_ID=your-cloudflare-account-id
CLOUDFLARE_AUTH_TOKEN=your-cloudflare-auth-token
FUNCTION_CALL_MODEL=@hf/nousresearch/hermes-2-pro-mistral-7b
FRIENDLY_RESPONSE_MODEL=@hf/mistral/mistral-7b-instruct-v0.2

Usage

Basic Commands

# Show help and available commands
shellsense --help

# Use Specific AI Provider
shellsense -p gemini -q "What is the current weather in New York?"

# Default to Cloudflare AI
shellsense -q "Search Wikipedia for quantum computing"

Available Tools

Development

Setup Development Environment

1. Clone and setup:

   git clone https://github.com/venopyX/shellsense.git
   cd shellsense
   
   # Create and activate virtual environment
   python -m venv venv
   source venv/bin/activate
   
   # Install in development mode with dev dependencies
   pip install -e ".[dev]"
   

2. Run tests:

   pytest
   

3. Build documentation:

   cd docs
   make html
   

4. Build and publish:

   python -m build
   twine upload dist/*
   

Project Structure

shellsense/
├── shellsense/        # Main package
│   ├── ai/           # AI providers and models
│   │   └── providers/# AI provider implementations
│   ├── tools/        # Tool implementations
│   │   ├── coder/    # Code generation tools
│   │   ├── data/     # Data processing tools
│   │   ├── language/ # Language tools
│   │   ├── media/    # Media tools
│   │   ├── shell/    # Shell tools
│   │   └── web/      # Web tools
│   ├── config/       # Configuration management
│   ├── utils/        # Utility functions
│   └── __main__.py   # CLI entry point
├── tests/            # Test suite
├── docs/             # Documentation
│   ├── api/         # API reference
│   ├── guides/      # User guides
│   └── examples/    # Usage examples
└── pyproject.toml    # Project configuration

Code Style

We use industry-standard Python tools:

• Black for code formatting
• isort for import sorting
• flake8 for linting
• mypy for type checking

Run all checks:

black .
isort .
flake8 .
mypy .

Contributing

We welcome contributions! Please see our Contributing Guide for details.

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

Documentation

For comprehensive documentation, visit our Documentation. Key sections include:

• API Reference: Detailed API documentation
• User Guides: Step-by-step guides
• Examples: Usage examples
• Contributing Guide: How to contribute

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Documentation
• Issue Tracker
• Discussions