A universal AI-powered terminal assistant for Linux
Features • Installation • Usage • Development • Contributing
- 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
- Python 3.8 or higher
- pip (Python package installer)
- Chrome/Chromium (optional, for screenshots)
pip install shellsenseThat's it! ShellSense is now installed and ready to use.
Run the setup command to create your configuration:
shellsense --setupThis 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# 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"| Tool | Description |
|---|---|
| WebSearch | Search the web using Bing/DuckDuckGo |
| Wikipedia | Search and retrieve Wikipedia articles |
| Translator | Translate text between languages |
| Screenshot | Capture webpage screenshots |
| GitHub | Fetch GitHub user/repo information |
| Stock | Get real-time stock market data |
| ProductHunt | Discover trending tech products |
| Coder | Generate code snippets and explanations |
-
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]"
-
Run tests:
pytest
-
Build documentation:
cd docs make html -
Build and publish:
python -m build twine upload dist/*
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
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 .We welcome contributions! Please see our Contributing Guide for details.
- Fork the repository
- Create your feature branch
- Make your changes
- Run the tests
- Submit a pull request
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
This project is licensed under the MIT License - see the LICENSE file for details.
Made with ❤️ by the Gemechis Chala