leitum 0.1.0__tar.gz

leitum-0.1.0/.claude/history/260613-1700-Initial-Prompt-DE.md

@@ -0,0 +1,43 @@
+Ich möchte ein kleines CLI Tool in Python erstellen, dass einen Coding Agenten wie Claude Code so launcht, dass alternative LLM Router und Modelle verwendet werden können.
+
+Ein gutes Beispiel für das was ich möchte ist z.B. das der Ollama CLI Befehlt `ollama launch`, den ich in der Kommandozeile vor `claude` einfüge und damit auf lokale Ollama Modelle statt Anthropic Modelle und APIs zugreife - siehe auch https://docs.ollama.com/integrations/claude-code.
+ 
+Ein anderes Wertkzeug, dass das als eine Funktion hat ist das der CLI von OMLX (https://github.com/jundot/omlx). Das Tool besitzt ebenfalls einen `launch` Befehl hat. Das CLI ist selber in Python geschrieben, hier ist der relevante Code für den Launch von Claude Code mit so angepasstem Environment, dass aben die durch OMLX bereitgestellten Modelle ausgewählt und verwendet werden können.
+
+Mein CLI Tool soll `leitum` heißen und nach dem Vorbild der obigen Beispiele funktionieren, d.h. mit dem Aufruf `leitum claude` Claude Code mit einem vorgegeben, konfigurierten API-Provider aufrufen. Für den Start soll erst einmal nur Claude Code unterstützt werden, andere Tools wie copilot-cli, opencode etc. folgen vielleicht später.
+
+Hier meine funktionalen Ideen:
+
+* Konfiguration über YAML, mit Konfigurationsdateien in $HOME/.config/leitum
+* `api-providers.yaml` zum Hinterlegen von Providern mit Zugangsdaten. Jeder Provider hat einen Identifier/Namen, eine URL und ein API Token. Zusätzlich *kann* eine Liste der Modelle hinterlegt werden, pro Modell mit der Angabe des technischen Modellnamen sowie (optional) eines Anzeigenamens.
+* Der Referenzprovider für die erste Iteration des Projektes ist Requesty.ai. Die Standard Claude Code Integration von Requesty ist hier beschrieben: https://docs.requesty.ai/integrations/claude-code
+* Das Tool speichert die zuletzt gesetzten Kontext-Parameter in seinem Config-Verzeichnis, z.B. den zuletzt ausgewählten Provider. Hier denke ich an eine ähnliche Verwaltung wie einen Kubernetes kubectl context.yaml, wo mehrere Kontexte hinterlegt werden können und ein current-context Feld den zuletzt gesetzten Kontext sich merkt und beim nächsten Start widerverwendet.
+* Ein Provider kann mit dem Parameter `--provider <name>` bzw. `-p <name>` vorgegeben werden. Wenn das nicht geschieht und außerdem mehr als ein Provider hinterlegt ist, dann soll eine Auswahldialog per Curses oder ähnlichem angezeigt werden, um einen Provider zu wählen. Der zuletzt gewählte ist immer vorbelegt. Jede Auswahl im der Kontext-Config ("current-context") gespeichert für den nächsten Start. Wenn nur ein Provider da ist, wird dieser automatisch verwendet. `--use-last-provider` bzw. `-P` überspringt den Provider-Auswahldialog und benutzt den zuletzt ausgewählen.
+* Danach erfolgt die Modellauswahl, ähnlich im grundsätzlichen Vorgehen
+	* Verfügbare Modelle sind entweder die beim Provider als Liste der Verfügbaren per API Call erhaltenen, oder die in `api-providers.yaml` vorgegebenen. Wenn es vorgegebene git, haben die immer Vorrang und die Liste der verfügbaren wird nicht abgerufen bzw. ignoriert.
+	* die Modellauswahl erfolgt wieder über eine curses Liste, wenn nicht schon vorgegeben über die folgend beschriebenen Parameter und natürlich nur, wenn mehr als ein Modell verfügbar ist. Vorbelegt ist immer die letzte Auswahl, falls vorhanden. Auswählbar sind
+		* START-MODELL, entspricht dem Modell das beim Aufruf von `claude` mit dem `--model` Parameter übergeben wird
+		* OPUS-MODELL, zum Setzen der Environment Variable `ANTHROPIC_DEFAULT_OPUS_MODEL` für den Start von `claude`
+		* SONNET-MODELL, zum Setzen der Environment Variable `ANTHROPIC_DEFAULT_SONNET_MODEL` für den Start von `claude`
+		* HAIKU-MODELL, zum Setzen der Environment Variable `ANTHROPIC_DEFAULT_HAIKU_MODEL` für den Start von `claude`
+	* `--model <name>` bzw. `-m <name>` wählt alternativ das START-MODELL direkt aus. `--use-last-model` bzw. `-M` wählt, falls vorhanden, das letzte Modell aus und führt zum Überspringen der interaktiven Modellauswahl
+	* `--opus <name>` bzw. `-o <name>` wählt alternativ das OPUS-MODELL direkt aus. `--use-last-opus` bzw. `-O` wählt, falls vorhanden, das letzte Modell aus
+	* `--sonnet <name>` bzw. `-s <name>` wählt alternativ das SONNET-MODELL direkt aus. `--use-last-sonnet` bzw. `-S` wählt, falls vorhanden, das letzte Modell aus
+	* `--haiku <name>` bzw. `-h <name>` wählt alternativ das HAIKU-MODELL direkt aus. `--use-last-haiku` bzw. `-H` wählt, falls vorhanden, das letzte Modell aus
+* nach erfolgten Vorgaben launcht claude mit der gewählten Umgebungsvorgabe.
+
+Weitere nicht-fachliche Ideen und Vorgaben:
+* Sprache für Dokumentation, Commit-Messages, Pull Requests und ähnliches ist Englisch
+* Sprache für PRDs ist die des Prompts, also jetzt gerade Deutsch
+* das Tool soll auf Pypi veröffentlicht werden und per uvx oder Homebrew ausgeführt bzw. installiert werden können. Referenzsystem ist zunächst ein aktuelles macOS.
+* Die Dokumentation des Tools soll in Markdown gestaltet sein, so dass bei einer Veröffentlichung auf GitHub ein sofortiger Einstig in die Dokumentation erfolgen kann
+
+Bitte mache folgendes:
+1. durchleuchte die gemachten Vorgaben und hinterfrage diese auf Konsistenz und Sinnhaftigkeit. Mache Verbesserungsvorschläge, wenn passend. Diskutiere intensiv alle offenen Fragen, Unklarheiten und Entscheidungen mit mir. Benutze die erarbeiteten Erkenntnisse für die folgenden Aufgaben
+2. Erstelle eine CLAUDE.md, die alle grundsätzlichen Vorgaben für das Projekt enthält. Halte diese so ausführlich wie nötig und so knapp wie möglich. Halte darin auch fest, dass das der gesamte Kommunikationsstil im Projekt sein soll.
+3. Erstelle danach einen detaillierten Umsetzungsplan in Form von PRD-Dokumenten. Das beinhaltet den Produktiven Code, Tests und Dokumentation. Stelle Fragen, wenn nötig. Setze noch nichts aus den erstellten PRDs um.
+
+
+
+
+	

leitum-0.1.0/.claude/history/260613-1701-Initial-Prompt-EN.md

@@ -0,0 +1,38 @@
+I want to build a small Python CLI tool that launches a coding agent such as Claude Code in a way that allows alternative LLM routers and models to be used.
+
+A good example of what I want is the Ollama CLI command `ollama launch`, which I prepend to `claude` on the command line so that I access local Ollama models instead of Anthropic models and APIs — see also https://docs.ollama.com/integrations/claude-code.
+
+Another tool that has this as a feature is the CLI of OMLX (https://github.com/jundot/omlx). It also has a `launch` command. The CLI itself is written in Python; here is the relevant code for launching Claude Code with an adjusted environment so that the models provided by OMLX can be selected and used.
+
+My CLI tool shall be called `leitum` and work along the lines of the examples above, i.e. invoking `leitum claude` to call Claude Code with a pre-configured API provider. To begin with, only Claude Code shall be supported; other tools such as copilot-cli, opencode, etc. may follow later.
+
+Here are my functional ideas:
+
+* Configuration via YAML, with configuration files located in `$HOME/.config/leitum`
+* `api-providers.yaml` to register providers along with their credentials. Each provider has an identifier/name, a URL, and an API token. Additionally, a list of models *may* be provided, with each model specifying the technical model name and (optionally) a display name.
+* The reference provider for the first iteration of the project is Requesty.ai. The standard Claude Code integration for Requesty is described here: https://docs.requesty.ai/integrations/claude-code
+* The tool stores the most recently set context parameters in its config directory, e.g. the last selected provider. I'm thinking of a management approach similar to a Kubernetes kubectl `context.yaml`, where multiple contexts can be stored and a `current-context` field remembers the most recently set context and reuses it on the next start.
+* A provider can be specified via the parameter `--provider <name>` or `-p <name>`. If this is not done and more than one provider is registered, a selection dialog (via Curses or similar) shall be shown to pick a provider. The most recently chosen one is always pre-selected. Each selection is stored in the context config (`current-context`) for the next start. If only one provider is present, it is used automatically. `--use-last-provider` or `-P` skips the provider-selection dialog and uses the most recently chosen provider.
+* After that, the model selection happens, similar in its basic approach:
+    * Available models are either those retrieved from the provider as a list of available models via an API call, or those pre-configured in `api-providers.yaml`. If pre-configured ones exist, they always take precedence and the list of available models is not retrieved or is ignored.
+    * The model selection again uses a curses list, unless already specified via the parameters described below, and of course only if more than one model is available. The most recent selection is always pre-selected, if one exists. The selectable items are:
+        * START MODEL — corresponds to the model passed to `claude` via the `--model` parameter
+        * OPUS MODEL — sets the environment variable `ANTHROPIC_DEFAULT_OPUS_MODEL` for the `claude` start
+        * SONNET MODEL — sets the environment variable `ANTHROPIC_DEFAULT_SONNET_MODEL` for the `claude` start
+        * HAIKU MODEL — sets the environment variable `ANTHROPIC_DEFAULT_HAIKU_MODEL` for the `claude` start
+    * `--model <name>` or `-m <name>` alternatively selects the START MODEL directly. `--use-last-model` or `-M`, if available, selects the last model and skips the interactive model selection.
+    * `--opus <name>` or `-o <name>` alternatively selects the OPUS MODEL directly. `--use-last-opus` or `-O`, if available, selects the last model.
+    * `--sonnet <name>` or `-s <name>` alternatively selects the SONNET MODEL directly. `--use-last-sonnet` or `-S`, if available, selects the last model.
+    * `--haiku <name>` or `-h <name>` alternatively selects the HAIKU MODEL directly. `--use-last-haiku` or `-H`, if available, selects the last model.
+* Once the specifications are in place, `claude` is launched with the chosen environment configuration.
+
+Further non-functional ideas and requirements:
+* The language for documentation, commit messages, pull requests, and similar artifacts is English.
+* The language for PRDs is the language of the prompt — at this moment, German.
+* The tool shall be published on PyPI and be runnable/installable via `uvx` or Homebrew. The reference system is, for now, a current version of macOS.
+* The tool's documentation shall be authored in Markdown so that, when published on GitHub, the documentation is immediately accessible.
+
+Please do the following:
+1. Scrutinize the requirements above and challenge them for consistency and soundness. Make improvement suggestions where appropriate. Discuss intensively with me all open questions, ambiguities, and decisions. Use the insights gained for the subsequent tasks.
+2. Create a `CLAUDE.md` that contains all foundational requirements for the project. Keep it as detailed as necessary and as concise as possible. Also state therein that this is meant to be the overall communication style for the project.
+3. Afterwards, create a detailed implementation plan in the form of PRD documents. This includes production code, tests, and documentation. Ask questions if needed. Do not yet implement anything from the created PRDs.

leitum-0.1.0/.claude/history/260613-1729-Initial-Review.md

@@ -0,0 +1,260 @@
+# Initial Specification Review — 2026-06-13
+
+This document captures the review of the initial product specification for
+`leitum` (a Python CLI that launches Claude Code against alternative LLM
+routers), the open questions that emerged from the review, and the
+pre-decisions that were used to author `CLAUDE.md` and the PRDs in `prd/`.
+
+## Context
+
+- Original specification: `intial-prompt.md` (German, user-authored).
+- Outputs of this session: `CLAUDE.md` (English) and PRDs `00`–`07` in
+  `prd/` (German).
+- No code was written in this session — pre-implementation alignment only.
+
+## Review findings
+
+### 1. Flag collisions
+
+- `-h` for `--haiku` collides with the universal `--help` short flag, which
+  every standard CLI framework reserves.
+- `-p` for `--provider` collides with Claude Code's own `-p`/`--print`
+  short flag, which would create ambiguity when users want to use Claude
+  Code's print mode through `leitum`.
+
+### 2. Authentication mechanics
+
+- The original specification did not fix which environment variable carries
+  the auth token. Requesty uses `ANTHROPIC_AUTH_TOKEN`; other Anthropic-
+  compatible routers may use `ANTHROPIC_API_KEY` or other names.
+- A pre-existing `ANTHROPIC_API_KEY` on the user's shell could silently win
+  over the provider's auth value if not actively scrubbed before launch.
+
+### 3. Token storage
+
+- Storing API tokens in plain text in `~/.config/leitum/api-providers.yaml`
+  is a security risk and forecloses sharing the config across machines.
+- The specification did not mention permission modes for any of the on-disk
+  files.
+
+### 4. "Context" semantics
+
+- The spec referenced kubectl-style contexts but described behavior that
+  matches a simple "remember last selection" model, not the kubectl model
+  (which is a named bundle plus a `current-context` pointer).
+- Two distinct interpretations existed: (A) remember last selection only,
+  or (B) named, switchable profiles. Implementation effort differs by
+  roughly 3×.
+
+### 5. Model-slot UX
+
+- The spec implied four sequential interactive selections per launch
+  (start, opus, sonnet, haiku), which is tedious for daily use.
+- "Last selection" was implied as a single global value, but each provider
+  has a different model space, so "last model" only makes sense per
+  provider.
+- The spec did not say what happens if a slot remains unset — does `claude`
+  launch with no `--model`? Does the env var get set to an empty value?
+
+### 6. Model discovery via API
+
+- The spec said "fetch the model list from the provider," but did not
+  specify the endpoint, caching behavior, or fallback on failure. Different
+  providers expose different endpoints (OpenAI-compatible `/v1/models`,
+  Ollama `/api/tags`, etc.).
+
+### 7. Curses or higher-level UI?
+
+- "Curses" was named explicitly, but raw curses is verbose and brittle on
+  modern terminals. Several high-quality TTY-prompt libraries exist that
+  remove most of the friction.
+
+### 8. Lifecycle commands
+
+- The spec described `leitum claude` but not how the user creates,
+  inspects, or removes providers. A bare-YAML workflow is viable but
+  hostile to first-time users.
+
+### 9. Pass-through arguments
+
+- The spec did not explicitly define what should happen to extra arguments
+  after `claude`. Without a rule, an invocation like `leitum claude
+  --resume` would be ambiguous.
+
+### 10. Language ambiguity for CLAUDE.md
+
+- The spec set "documentation → English, PRDs → German" but did not
+  classify `CLAUDE.md` itself.
+
+### 11. Minor items
+
+- Naming "START-MODELL" as a slot is awkward outside German; "main/primary"
+  reads better in English documentation, but the slot identifier should
+  stay machine-stable.
+- No `--dry-run` or `--verbose` modes were specified, though both are
+  cheap and standard.
+- Python minimum version, license, build backend, packaging tools were not
+  pinned.
+
+## Decisions taken to author CLAUDE.md and the PRDs
+
+The decisions below were either confirmed interactively with the user or
+taken autonomously where the trade-off was small. Decisions confirmed by
+the user are marked **[user]**; decisions taken autonomously and reported
+back are marked **[auto]**.
+
+### Flag layout and pass-through **[user]**
+
+- `leitum`-own options must appear **before** the subcommand name; every
+  argument after `claude` is forwarded unchanged to the `claude` binary.
+- This eliminates the `-p` collision entirely: leitum's `-p` is consumed
+  before `claude` ever sees it, and `claude`'s `-p` lives in the
+  pass-through bucket.
+
+### Haiku short flags **[user, revised]**
+
+- `--haiku` short flag: `-k`.
+- `--use-last-haiku` short flag: `-K`.
+- `-h` remains `--help` per universal convention.
+- (Initial draft used "no short flag" for `--haiku`; user revised to
+  `-k`/`-K`.)
+
+### Context model **[user]**
+
+- v1 implements **last-selection-only**. No named profiles.
+- `state.yaml` stores `last_provider` plus, per provider, the last
+  selected model for each of the four slots.
+
+### Model selection UX **[user]**
+
+- A **single dialog** with four slot rows, not four sequential selects.
+- Each slot can be set to "do not set", which omits the corresponding
+  env var (and, for `start`, omits `--model` entirely).
+- Pre-population per slot: explicit flag → `--use-last-*` → provider
+  defaults → last state → `roles` match → "do not set".
+
+### Interactive prompt library **[user]**
+
+- `questionary` instead of raw curses. The selection-algorithm logic is
+  factored out of the UI layer so it remains unit-testable without a TTY.
+
+### Authentication scheme **[auto]**
+
+- Per provider, `auth.token` plus an optional `auth.env_var` (default
+  `ANTHROPIC_AUTH_TOKEN`). Tokens support `${VAR}` interpolation against
+  the live shell environment so users can keep secrets outside the file.
+- Before launch, `ANTHROPIC_API_KEY` is actively removed from the child
+  environment unless the active provider's `auth.env_var` is exactly
+  `ANTHROPIC_API_KEY`.
+
+### File security **[auto]**
+
+- `api-providers.yaml` and `state.yaml`: mode `0600`.
+- Config directories: mode `0700`.
+- On read, a permissions check warns if the file is more permissive than
+  `0600` but does not silently rewrite.
+- Tokens never appear in stdout, stderr, or any log line — including with
+  `--verbose`. `leitum provider show --reveal-token` is the single opt-in
+  path to display a token, with confirmation and a stderr warning.
+
+### Model discovery **[auto]**
+
+- API contract for v1: OpenAI-compatible `GET /v1/models` with bearer auth.
+- Cache: `~/.cache/leitum/models/<provider>.json`, 24 hour TTL, JSON.
+- `leitum refresh` clears the cache and re-fetches.
+- On HTTP failure: stale cache is acceptable; without any cache, the
+  command errors with a clear hint and exits with code 4.
+- If the YAML defines a `models` list for the provider, the API is never
+  contacted for that provider.
+
+### Slot default behavior **[auto]**
+
+- An unset `start` slot launches `claude` without `--model` — Claude Code
+  uses its own default.
+- Unset `opus` / `sonnet` / `haiku` slots simply omit the corresponding
+  `ANTHROPIC_DEFAULT_*_MODEL` env var.
+
+### "Last model" scoping **[auto]**
+
+- The "last selection" for each model slot is stored **per provider**, not
+  globally. Otherwise `--use-last-model` would suggest nonsense after a
+  provider switch.
+
+### Management subcommands **[auto]**
+
+- `leitum init`, `leitum provider {list,show,add,remove}`,
+  `leitum refresh`, `leitum doctor`, `leitum completions` are in scope for
+  v1.
+- `leitum doctor` is read-only diagnostics: it reports, never repairs.
+
+### Diagnostics flags **[auto]**
+
+- `--dry-run` prints the resolved child environment (token values
+  redacted) and the final exec line, then exits without launching.
+- `--verbose` / `-v` writes progress events to stderr, including resolved
+  provider, set env-var names (never values), and the exec line.
+
+### Tech-stack choices **[auto]**
+
+- Python 3.11+.
+- CLI: `typer`. Prompts: `questionary`. Validation: `pydantic` v2.
+- YAML I/O: `ruamel.yaml` (preserves comments and order on write).
+- HTTP: `httpx` (sync client by default).
+- Tests: `pytest` + `pytest-mock` + `respx` + `freezegun`.
+- Linting / formatting: `ruff`. Static typing: `mypy --strict`.
+- Build backend: `hatchling`. Dev workflow: `uv`.
+
+### Distribution **[auto]**
+
+- Primary: PyPI as `leitum`, runnable through `uvx leitum`.
+- Secondary: dedicated Homebrew tap. Homebrew-core submission is deferred.
+- macOS is the reference platform; Linux must stay functional; Windows is
+  not supported in v1.
+
+### License **[user, revised]**
+
+- **Apache 2.0**. SPDX identifier `Apache-2.0` in `pyproject.toml`,
+  `LICENSE` and `NOTICE` files at the repository root.
+- (Initial draft used MIT; user revised to Apache 2.0.)
+
+### Language convention for CLAUDE.md **[auto]**
+
+- `CLAUDE.md` is English, in line with the broader "documentation is
+  English" rule. PRDs remain German, per explicit user instruction.
+
+### Exit codes **[auto]**
+
+- A defined ladder: 0 success, 2 argument error, 3 configuration error,
+  4 unresolved provider/model, 5 `claude` binary missing, 130 user
+  cancellation, otherwise pass-through from the launched process.
+
+### Schema versioning **[auto]**
+
+- Both `api-providers.yaml` and `state.yaml` carry `schema_version: 1`.
+  Migrations land in `leitum/config/migrations/` with a `.bak` snapshot
+  before any in-place rewrite.
+
+## Items intentionally deferred
+
+The following were considered and explicitly placed in the roadmap rather
+than v1:
+
+- macOS Keychain integration for token storage.
+- Named, kubectl-style contexts/profiles.
+- Additional agents (`copilot-cli`, `opencode`, `gemini-cli`).
+- Provider presets beyond Requesty (OpenRouter, LiteLLM, Ollama).
+- Homebrew-core submission.
+- A `mkdocs`-based documentation site (v1 ships Markdown in `docs/`).
+
+## Artifacts produced this session
+
+- `CLAUDE.md`
+- `prd/00-overview.md`
+- `prd/01-configuration.md`
+- `prd/02-cli.md`
+- `prd/03-selection-flows.md`
+- `prd/04-launch.md`
+- `prd/05-management-commands.md`
+- `prd/06-testing.md`
+- `prd/07-packaging-and-docs.md`
+- `.claude/history/260613-1729-Initial-Review.md` (this file)

leitum-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+        os: [macos-latest, ubuntu-latest]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Ruff lint
+        run: uv run ruff check src/ tests/
+
+      - name: Ruff format check
+        run: uv run ruff format --check src/ tests/
+
+      - name: Mypy
+        run: uv run mypy src/
+
+      - name: Pytest
+        run: uv run pytest

leitum-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,31 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  id-token: write
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: dist/*

leitum-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+.mypy_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+.pytest_cache/

leitum-0.1.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-14
+
+### Added
+- `leitum claude` — launch Claude Code via a configured provider
+- Provider configuration in `~/.config/leitum/api-providers.yaml`
+- Interactive provider and model selection with `questionary`
+- State persistence to `~/.local/state/leitum/state.yaml`
+- Project-local config via `leitum.yaml`
+- Model discovery via API with 24-hour cache
+- `leitum init` — initialize config
+- `leitum provider list/show/add/remove` — manage providers
+- `leitum refresh` — refresh model cache
+- `leitum doctor` — sanity check suite
+- `leitum completions` — shell completion scripts
+- `--dry-run` and `--verbose` flags
+- Full test suite (unit + integration)
+- CI via GitHub Actions (Python 3.11–3.13, macOS + Linux)

leitum-0.1.0/CLAUDE.md

@@ -0,0 +1,132 @@
+# leitum — Agent Working Instructions
+
+`leitum` is a small Python CLI that launches coding agents (initially Claude Code)
+against alternative LLM routers/providers (initially Requesty). It mirrors the
+ergonomics of `ollama launch` and `omlx launch`: the user runs `leitum claude` and
+leitum prepares the environment so that Claude Code talks to the chosen provider
+and models instead of the Anthropic API.
+
+This file is loaded automatically by Claude Code at session start. Read it first.
+
+## Languages
+
+- **Code, documentation, comments, README, commit messages, PR titles/bodies, issue
+  titles/bodies, code review comments**: English.
+- **Product Requirements Documents (PRDs in `prd/`)**: German. They reflect the
+  language of the original prompt.
+- **Conversation with the user**: whatever language the user writes in. The current
+  user writes German; respond in German unless asked otherwise.
+
+When in doubt: code-facing artifacts are English, product-thinking artifacts are
+German.
+
+## Product scope (v1)
+
+- One agent: Claude Code.
+- One reference provider: [Requesty](https://docs.requesty.ai/integrations/claude-code).
+  The configuration model must already generalize to other Anthropic-compatible
+  routers (OpenRouter, LiteLLM, local Ollama in Anthropic-shim mode).
+- Configuration in `~/.config/leitum/`, runtime state in `~/.local/state/leitum/`
+  (XDG), model cache in `~/.cache/leitum/`. An optional project-local
+  `leitum.yaml` in the current working directory pins provider/model choices
+  per repository (see PRD 01 and PRD 03). It is checked into version control
+  and must never contain tokens.
+- Interactive TTY selection where ambiguous; non-interactive when fully specified
+  by flags or by a single-option configuration.
+
+Out of scope for v1: copilot-cli, opencode, other agents; macOS Keychain;
+named/multi-context profiles (kubectl-style); GUI; Windows support.
+
+## Tech stack
+
+- Python 3.11+.
+- CLI framework: [`typer`](https://typer.tiangolo.com/).
+- Interactive prompts: [`questionary`](https://questionary.readthedocs.io/).
+- Config validation: [`pydantic` v2](https://docs.pydantic.dev/).
+- YAML: [`ruamel.yaml`](https://yaml.readthedocs.io/) (preserves comments/order).
+- HTTP for model discovery: [`httpx`](https://www.python-httpx.org/).
+- Tests: `pytest`, `pytest-mock`, fake `claude` binary via fixture.
+- Build backend: `hatchling` with `pyproject.toml`.
+- Package/dev workflow: `uv` (lockfile, sync, run).
+- License: Apache 2.0.
+
+## Distribution
+
+- Primary: PyPI as `leitum`, runnable via `uvx leitum`.
+- Secondary: Homebrew via a dedicated tap (`brew tap <owner>/leitum`).
+  Homebrew-core submission is a later goal, not v1.
+- Reference platform: current macOS. Linux must keep working; Windows is not
+  supported in v1.
+
+## CLI shape
+
+```
+leitum [LEITUM_OPTS] <subcommand> [SUBCOMMAND_ARGS_PASSED_THROUGH]
+```
+
+- `leitum claude [...]` launches Claude Code. Every argument that follows
+  `claude` is passed through to the `claude` binary unchanged. Leitum's own
+  flags must appear **before** the subcommand name.
+- Management subcommands (`leitum provider …`, `leitum doctor`, `leitum refresh`,
+  `leitum init`) are first-class and do not pass through.
+- Use `--dry-run` to print the resolved environment and final exec line without
+  launching. Use `-v`/`--verbose` for progress logging on stderr.
+
+## Behavioral rules
+
+- **Never** write a token, API key, or any secret to logs, stdout, or to files
+  outside `~/.config/leitum/api-providers.yaml`. Redact in verbose output.
+- Files in `~/.config/leitum/` must be created with mode `0600`. If an existing
+  file has weaker permissions, warn and offer to fix; do not silently rewrite.
+- Before launching, strip a host-inherited `ANTHROPIC_API_KEY` from the child
+  environment so it cannot override the provider's auth.
+- The user's last interactive selections (provider, and per-provider models) are
+  persisted to `~/.local/state/leitum/state.yaml`. Treat this file as cache:
+  recoverable on loss, schema-versioned (`schema_version: 1`).
+- Model discovery via API is **only** used if the provider has no model list in
+  YAML. Results are cached under `~/.cache/leitum/models/<provider>.json` with a
+  24h TTL; `leitum refresh` clears the cache.
+
+## Coding conventions
+
+- Type hints on all public functions. `mypy --strict` should pass.
+- Format with `ruff format`, lint with `ruff check`. Keep both clean before
+  commit.
+- Module layout under `src/leitum/`:
+  - `cli.py` (typer app, root command, pass-through plumbing)
+  - `config/` (pydantic models, YAML I/O, paths, env interpolation)
+  - `state.py` (last-used persistence)
+  - `providers/` (model discovery, HTTP, cache)
+  - `selection/` (provider + model interactive selection)
+  - `launch.py` (env composition, exec)
+  - `commands/` (subcommand handlers: claude, provider, doctor, refresh, init)
+- Tests in `tests/`, mirroring the source tree.
+- No emojis in code or docs.
+- Comments only when the *why* is non-obvious. Don't comment what the code says.
+
+## Git workflow
+
+- `main` is the default branch and always green.
+- Feature branches: `feat/<topic>`, `fix/<topic>`, `docs/<topic>`.
+- Commit messages: imperative, English, Conventional-Commits style
+  (`feat: …`, `fix: …`, `docs: …`, `test: …`, `refactor: …`, `chore: …`).
+- One logical change per commit. Squash trivia before opening a PR.
+- PR titles in the same Conventional-Commits style; PR bodies in English with a
+  short summary and a test plan checklist.
+
+## When you make changes
+
+1. If you change observable CLI behavior, update `README.md` and any affected
+   PRD.
+2. If you change a YAML schema, bump the schema version and document the
+   migration in the PRD for configuration.
+3. Run `ruff format`, `ruff check`, `mypy --strict`, and `pytest` before
+   declaring a task done. State explicitly when any check is skipped and why.
+4. Manual smoke test for Claude-launch changes: `leitum --dry-run claude` and
+   verify the printed environment matches expectations.
+
+## PRDs
+
+The authoritative product specification lives in `prd/`. Read the matching PRD
+before changing the corresponding area of the code, and update it when the
+product behavior changes.