Development¶

Notes for contributors working on Smart-Shell itself.

Setup¶

Requires Python 3.10 or newer and git.

git clone https://github.com/Lusan-sapkota/smart-shell.git
cd smart-shell
python3 -m venv venv
source venv/bin/activate
pip install -e . pytest

Configure a provider with smart-shell setup, or point it at one with environment variables:

export SMART_SHELL_BASE_URL=http://localhost:11434/v1   # e.g. a local Ollama
export SMART_SHELL_API_KEY=your-api-key                 # if the provider needs one

Check that it works without executing anything:

smart-shell run "list files in current directory" --dry-run

Tests¶

pytest -q

Tests live in tests/. CI (.github/workflows/test.yml) runs ruff and the tests (Python 3.10 and 3.14) for pushes to development and main and for pull requests. Add a test for any new safety rule in tests/test_safety.py.

Project structure¶

smart_shell/
  main.py           CLI (click) and the interactive REPL
  ai_wrapper.py     requests-based client for OpenAI-compatible APIs, provider presets
  setup_logic.py    `smart-shell setup` wizard
  shell_builder.py  system prompt, plan parsing, explanations
  safety.py         command risk classification
  history.py        command history
  updater.py        `/update` (PyPI version check, upgrade via uv/pipx/pip)
  ui.py             interactive prompt: / menu, completion, status bar, history
  utils.py          command execution, OS/shell detection, error log
  config.py         load/save ~/.config/smart-shell/config.json
tests/              pytest suite
docs/               this documentation (MkDocs)
install.sh          installer

Dependencies are rich, click, requests and prompt_toolkit. Keep requirements.txt and pyproject.toml in sync if that changes.

Adding a provider¶

Any service with an OpenAI-compatible /models and /chat/completions endpoint already works through the custom provider. To add a preset, add an entry to PROVIDERS in smart_shell/ai_wrapper.py: name: (base_url, default_model_or_None, needs_api_key).

Safety changes¶

Patterns live in smart_shell/safety.py, grouped by level (blocked, high, medium, info_leak). Don't loosen a rule without a test showing the false positive it fixes. Update Safety when levels or behavior change.

Release¶

Bump the version in pyproject.toml and smart_shell/__init__.py.
Add an entry to docs/CHANGELOG.md.
Run pytest -q.
Tag the release.

See Contributing for the PR workflow and API Reference for the module overview.