Metadata-Version: 2.5
Name: cargai
Version: 0.7.0
Summary: Toolkit CLI pour installer et gérer des outils tiers liés à l'IA (headroom-ai, ...)
Project-URL: Repository, https://github.com/LionelHARRY/cargai
Project-URL: Issues, https://github.com/LionelHARRY/cargai/issues
Author: Lionel Harry
License-Expression: MIT
License-File: LICENSE
Keywords: ai,cli,installer,llm,toolkit
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: rich>=13
Requires-Dist: textual>=8
Requires-Dist: tomli>=2; python_version < '3.11'
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# cargai

```
▗▄▄▄▄▄▄▄▄▄▄▖  ┏━╸ ┏━┓ ┏━┓ ┏━╸ ┏━┓ ╻
▐┃┃┃┃◆┃┃┃┃┃▌  ┃   ┣━┫ ┣┳┛ ┃╺┓ ┣━┫ ┃
▝▀▀▀▀▀▀▀▀▀▀▘  ┗━╸ ╹ ╹ ╹┗╸ ┗━┛ ╹ ╹ ╹
```

*outils IA, livrés à bon port* — **carg**o + **ai**.

Toolkit CLI pour installer et gérer des outils tiers liés à l'IA, à partir d'un catalogue déclaratif.

## Installation

```bash
# recommandé
uv tool install cargai          # ou depuis le repo : uv tool install .
# alternative
pipx install cargai
```

## Utilisation

```bash
cargai list                         # catalogue + statut d'installation
cargai info headroom                # détails d'un outil
cargai install headroom             # installe headroom-ai[proxy]
cargai install headroom -e all      # avec d'autres extras
cargai install headroom --dry-run   # affiche la commande sans l'exécuter
cargai install headroom -U          # met à jour
cargai install headroom --setup     # applique la configuration sans la demander
cargai install rtk --variant oss    # choisit une variante (sinon : question, ou la 1re par défaut)
cargai install rtk --agent claude,codex   # configure rtk pour ces agents
cargai setup rtk --agent gemini     # ajoute un agent plus tard
cargai setup rtk --undo --agent codex     # retire un agent
cargai setup headroom               # (ré)applique la configuration
cargai setup headroom --undo        # retire la configuration
cargai dashboard headroom           # ouvre http://127.0.0.1:8787/dashboard
cargai uninstall headroom           # retire la configuration puis désinstalle
cargai doctor                       # vérifie uv / pipx / npm / brew
cargai ui                           # interface interactive
```

### Interface interactive

`cargai ui` ouvre une interface dans le terminal : liste des outils avec leur statut,
détails de l'outil sélectionné et journal des commandes en direct.

| Touche | Action |
|---|---|
| `↑` `↓` | naviguer |
| `1` / `2` / `3` | filtre : tous / installés / disponibles |
| `i` | installer l'outil sélectionné |
| `u` | désinstaller (avec confirmation) |
| `s` | configurer l'outil sélectionné |
| `o` | ouvrir son tableau de bord |
| `l` | personnaliser la statusline Claude Code |
| `r` | rafraîchir |
| `q` | quitter |

### Statusline Claude Code

```bash
cargai statusline preview      # aperçu dans le terminal
cargai statusline install      # branche la statusline dans ~/.claude/settings.json
cargai statusline uninstall    # la retire (et remet la précédente s'il y en avait une)
```

Deux lignes, aux couleurs de cargai :

```
◆ Opus · mon-projet ⎇ main · ctx ▰▰▰▱▱▱▱▱▱▱ 34 % · 1,23 $ · 12 min
cargai aujourd'hui  headroom ● ↓4,4 k tok (0,02 $) · rtk ↓1,2 k tok (58 %)
```

- ligne 1 : modèle, dossier, branche git, contexte utilisé (vert → ambre à 60 % → rouge à 85 %),
  coût et durée de la session ;
- ligne 2 : gains du jour des outils installés — headroom (● vert : session mesurée, ● ambre :
  session non branchée, ○ rouge : proxy arrêté) et rtk.

**Personnalisable** : chaque ligne est une liste d'éléments, dans l'ordre.

```bash
cargai statusline elements                 # éléments disponibles et position actuelle
cargai statusline add limit_5h             # ajoute à la ligne 1
cargai statusline add lines --after cost   # place juste après « cost »
cargai statusline add effort --line 3      # crée une 3e ligne
cargai statusline remove duration
cargai statusline reset                    # revient à la configuration par défaut
```

| Élément | Affiche |
|---|---|
| `model`, `dir`, `branch` | modèle, dossier, branche git |
| `context` | jauge du contexte utilisé |
| `cost`, `duration`, `lines` | coût, durée, lignes ajoutées / retirées |
| `effort` | niveau d'effort du raisonnement |
| `limit_5h`, `limit_7d` | limites d'usage (abonnés Pro / Max) |
| `cache` | taux de succès du cache de prompt |
| `session` | nom de la session |
| `label` | logo cargai + « aujourd'hui » |
| `headroom`, `rtk` | gains du jour des outils |

Dans `cargai ui`, la touche `l` ouvre le même réglage en interactif : aperçu en direct,
`espace` afficher / masquer, `←` `→` déplacer dans la ligne, `1` `2` `3` changer de ligne,
`b` brancher / débrancher dans Claude Code, `r` revenir au défaut.

La configuration est enregistrée dans `~/.config/cargai/statusline.toml` (modifiable à la main).
Un élément sans donnée (ex. limites hors abonnement) ne s'affiche pas.

Rapide (~50 ms, données des outils en cache 5 s), compacte dans un terminal étroit, et silencieuse
si cargai est désinstallé. Une statusline existante n'est remplacée qu'avec confirmation (ou `--force`).

### Headroom : trafic mesuré dès l'installation

`cargai install headroom` installe headroom puis propose de le **configurer** :
le proxy est lancé en service d'arrière-plan (démarré avec la session) et les outils IA détectés
(Claude Code, Codex…) sont branchés dessus (`headroom install apply`). Le trafic est donc mesuré
immédiatement : tableau de bord sur **http://127.0.0.1:8787/dashboard** (`cargai dashboard headroom`),
ou en ligne de commande `headroom savings` / `headroom perf`.
À la désinstallation, cargai retire d'abord cette configuration (`headroom install remove`)
pour ne pas laisser tes outils pointer vers un proxy disparu.

### Catalogue

| Outil | Rôle | Variantes |
|---|---|---|
| **headroom** | proxy qui compresse le contexte envoyé à l'API (dashboard sur `http://127.0.0.1:8787/dashboard`) | — |
| **rtk** | hook qui compacte la sortie des commandes shell lues par l'agent (`rtk gain`) | `full` (Apache-2.0 + BUSL-1.1, par défaut), `oss` (Apache-2.0) |
| **herdr** | multiplexeur de terminal pour agents IA : sessions persistantes, état de chaque agent (au travail, bloqué, inactif) | — |

**rtk est multi-agents** : cargai détecte les agents présents (Claude Code, Codex, Gemini CLI, Cursor,
GitHub Copilot, Mistral Vibe, Factory Droid), propose de configurer ceux détectés (cases à cocher dans
`cargai ui`, question ou `--agent` en ligne de commande) et retient lesquels l'ont été
(`~/.local/state/cargai/state.json`) pour les retirer à la désinstallation. Les agents configurés par
projet (Cline, Kilo Code, Windsurf, Kimi…) restent à faire dans le dossier du projet : `rtk init --agent cline`.

**herdr est multi-agents** aussi : `cargai setup herdr` branche les agents dont le dossier de configuration
existe (Claude Code, Codex, Copilot CLI, Cursor, OpenCode, Droid, Pi, Kimi, Qwen, Grok… 17 au total) via
`herdr integration install <agent>`, et les débranche à la désinstallation. Ensuite : `herdr` dans le dossier de travail.

headroom et rtk sont complémentaires (l'un agit sur les requêtes API, l'autre sur la sortie des commandes).
Le proxy optionnel de rtk n'est pas activé par cargai : il entrerait en conflit avec headroom.

**Sans Homebrew** (ex. sur Linux), rtk et herdr s'installent par leur script officiel
(`curl … | sh`, binaire dans `~/.local/bin`) : la colonne « Méthode » affiche alors `script`.
Relancer le script met à jour (`cargai install <outil> -U`), la désinstallation supprime le binaire,
et la variante de rtk (`--variant oss`) est retenue dans l'état de cargai. Un outil déjà installé
par script reste géré par script, même si Homebrew arrive ensuite. `cargai doctor` vérifie `curl`
et la présence de `~/.local/bin` dans le PATH.

Les outils Python sont installés isolément via `uv tool` (ou `pipx` à défaut), chacun dans son propre environnement.

## Ajouter un outil

Chaque outil est un fichier TOML :

- intégré au package : `src/cargai/catalog/<nom>.toml`
- perso (sans modifier le package) : `~/.config/cargai/tools/<nom>.toml` — prioritaire sur le catalogue intégré

```toml
name = "mon-outil"
description = "Ce que fait l'outil."
homepage = "https://..."
dashboard = "http://127.0.0.1:1234/"  # optionnel : cargai dashboard <nom>, touche o

[install]
method = "python"        # python | npm | brew
package = "mon-outil"    # nom du package PyPI / npm / formule brew
extras = []              # python uniquement
python = "3.12"          # optionnel, version de Python à utiliser
binaries = ["mon-outil"] # sert à détecter si l'outil est installé
# optionnel : script officiel utilisé si le gestionnaire de la méthode manque ;
# il doit déposer les binaires dans ~/.local/bin
script = "https://exemple.dev/install.sh"
script_env = { EDITION = "lite" }   # variables passées au script (redéfinissables par variante)

# optionnel : variantes (la première est celle par défaut) ; chacune peut
# redéfinir method, package, extras, python, script_env. Une seule variante installée à la fois.
[[variants]]
name = "standard"
description = "Édition standard"

[[variants]]
name = "lite"
description = "Édition allégée"
package = "mon-outil-lite"

# optionnel : configuration proposée juste après l'installation
[setup]
description = "Ce que fait la configuration."
run = [["mon-outil", "setup"]]       # commandes exécutées dans l'ordre
undo = [["mon-outil", "teardown"]]   # obligatoire : exécuté avant la désinstallation
message = "Affiché une fois la configuration appliquée."

# … ou, à la place de run / undo, une configuration par agent IA :
[[setup.agents]]
name = "claude"
label = "Claude Code"
detect = ["claude", "~/.claude"]     # binaires, ou chemins (~ ou /) signalant l'agent
run = [["mon-outil", "init", "--claude"]]
undo = [["mon-outil", "init", "--claude", "--uninstall"]]

[post_install]
message = "Lance : mon-outil --help"
```

## Développement

```bash
uv venv --python 3.12
uv pip install -e ".[dev]"
uv run pytest
```

## Publication

La publication sur PyPI est automatisée par GitHub Actions (`.github/workflows/publish.yml`),
via le Trusted Publishing de PyPI (aucun jeton à gérer). Pour sortir une version :

1. Mettre à jour `__version__` dans `src/cargai/__init__.py` (seule source de la version).
2. Committer, puis tagger et pousser :
   ```bash
   git tag -a v0.2.0 -m "cargai 0.2.0" && git push origin main v0.2.0
   ```

Le workflow lance les tests, vérifie que le tag correspond à la version, publie sur PyPI
et crée la release GitHub.

## Licence

MIT — voir [LICENSE](LICENSE).
