Project overview — Shell Sentinel
Mission
Deliver a terminal-native AI copilot that keeps persistent SSH/SFTP sessions, speaks natural language and brings human-friendly operations to critical infrastructure.
Technical stack
- Python 3.12, Textual 8.2.8 for the TUI, Strands Agents SDK 1.61.1 and Strands Agents Tools 0.8.9 for conversational reasoning, MCP transports on
mcp2.x. - Reproducible installs via
pyproject.tomland pip-tools lockfiles (make lock,make install). - Providers: Bedrock, OpenAI, LM Studio, Cerebras, Mistral AI, Google Gemini and Ollama. OpenAI supports Chat Completions and Responses; endpoint-specific token and reasoning parameters are normalized, Responses enables function tools with active reasoning, Mistral AI uses its official SDK and Google Gemini runs on Strands'
GeminiModelwith thegoogle-genaiSDK. - Per-provider prompt caching (
cacheblock) and a turn cap per instruction (agent.max_turns, default 25) keep costs and runaway loops under control. - Custom tools:
remote_ssh_command,remote_sftp_transfer,local_datetime. - Firecrawl MCP tools available for research, scraping and structured extraction.
Key responsibilities
- Keep configuration centralized in
conf/; no hardcoded values in code. - Update translations, manuals and the static website whenever behaviour changes.
- Document custom providers and plugin rules; each plugin must ship with concise operator documentation.
- Respect security policies (no plain-text secrets, environment variables only).
Workflow
- Create virtualenv with
python3.12 -m venv .venvand activate it. - Install dependencies via
make install. - Before PRs, run
make format,make lint,make test(unit tests plus the offline end-to-end layer intests/e2e, which drives the real TUI against an in-process SSH server). - When touching the TUI, the agent runtime or a provider, optionally run
make test-e2e-live(RUN_E2E=1plusOPENAI_API_KEY,MISTRAL_API_KEYorGEMINI_API_KEY; the MCP scenarios also needFIRECRAWL_API_KEYandnpx); it spends tokens and never runs in CI. - Validate the TUI with
make runand the website withmake website-serve.
For complete policies refer to the contributor handbook and internal governance documents. Treat the static site as part of the documentation contract.