Development

Architecture overview

┌──────────────────────────────────────────────────────────────────┐
│  Entry Points                                                    │
│                                                                  │
│  tutr-cli <query>           tutr  /  python -m tutr             │
│  (one-shot CLI)             (interactive shell wrapper)         │
└──────────┬──────────────────────────────┬───────────────────────┘
           │                              │
           ▼                              ▼
┌──────────────────────┐   ┌─────────────────────────────────┐
│  src/tutr/cli/       │   │  src/tutr/shell/                │
│  app.py  – routing   │   │  loop.py  – PTY loop            │
│  query.py – query    │   │  detection.py – shell detect    │
│  configure.py        │   │  hooks.py – rc startup hooks    │
│  wizard.py – setup   │   │  shell.py – tutor prompt logic  │
└──────────┬───────────┘   └──────────────┬──────────────────┘
           └──────────────┬───────────────┘
                          │
                          ▼
           ┌──────────────────────────────┐
           │  src/tutr/                   │
           │  tutr.py    – orchestration  │
           │  llm.py     – LiteLLM calls  │
           │  prompt.py  – LLM prompts    │
           │  config.py  – config file    │
           │  context.py – system info    │
           │  safety.py  – command safety │
           │  models/    – Pydantic types  │
           └──────────────┬───────────────┘
                          │
                          ▼
           ┌──────────────────────────────┐
           │  LiteLLM → AI Provider       │
           │  OpenAI · Anthropic · Gemini │
           │  xAI · Ollama (local)        │
           └──────────────────────────────┘

Local setup

uv sync --dev

Validate changes

uv run poe check

Runs lint, format check, mypy, and tests.

Preview docs locally

cd docs
python -m http.server 8000

Then open http://localhost:8000.

Create a release

scripts/release.sh patch

Use minor, major, or an explicit X.Y.Z version as needed.

Publish path

Authoritative production publish path: GitHub Actions trusted publishing from .github/workflows/python-publish.yml, triggered by a published GitHub Release.

Manual twine uploads are maintainer fallbacks only. Use uv run poe publish_testpypi for staging, and reserve uv run poe publish_pypi for exceptional/manual recovery scenarios.