Ce guide pas à pas vous mène d'une installation fraîche d'AWR à une passation de session vérifiée : installer le CLI, initialiser un projet, démarrer une session de travail, et prouver qu'une session successeur peut reprendre là où la première s'est arrêtée. Tout est copiable-collable ; AWR embarque son propre SQLite.
1. Installer AWR
AWR est distribué sous forme de paquets natifs sur npm et PyPI. Les deux canaux installent le même CLI Rust (awr) et le même serveur MCP (awr-mcp) ; il n'y a pas de SDK JavaScript ou Python séparé.
Avec npm (requiert Node 22.14 ou plus récent) :
npm install -g @originoneai/agent-work-runtime@0.5.1
Ou avec pip, dans un environnement virtuel (requiert Python 3.9 ou plus récent) :
python -m pip install agent-work-runtime==0.5.1
Vérifiez les deux exécutables :
awr --version
awr-mcp --version
Les plateformes prises en charge sont macOS 15+ (arm64 et Intel x64), Linux x64 et arm64 avec glibc 2.39 ou plus récente (la base Ubuntu 24.04), et Windows x64. Sous Linux, vérifiez d'abord votre glibc :
ldd --version | head -n 1
Pour les installations npm, gardez les dépendances optionnelles activées — le lanceur résout un paquet natif par plateforme. Il n'y a ni script d'installation ni téléchargeur réseau ; les wheels pip embarquent les binaires. Un troisième canal existe pour les auteurs d'applications : une charge native épinglée des deux binaires qu'une application hôte peut embarquer, de sorte que ses utilisateurs n'ont besoin ni de Node, ni de Python, ni de Rust à l'exécution.
2. Initialiser votre projet
L'initialisation est une opération en deux étapes : un aperçu, puis une acceptation explicite. Rien n'est écrit tant que vous ne passez pas --accept.
AWR_PROJECT=/absolute/path/to/your/project
awr --project "$AWR_PROJECT" init
Lisez l'aperçu : il montre l'inventaire trouvé par AWR — registres de tâches Markdown existants, sources YAML, objectifs — et le mapping de sources qu'il propose. Les fichiers existants ne sont jamais écrasés ; vos documents originaux restent faisant autorité. Si l'aperçu vous convient, acceptez-le :
awr --project "$AWR_PROJECT" init --accept
Pour un projet vierge, énoncez son objectif dès le départ :
awr --project "$AWR_PROJECT" init --goal "Deliver a document portal" --accept
Si votre registre Markdown utilise des mots de statut non standard, mappez-les au moment de l'init :
awr --project "$AWR_PROJECT" init \
--status-map pending=planned --status-map complete=completed --accept
Puis inspectez le rapport d'organisation :
awr --project "$AWR_PROJECT" intake inspect --json
Le organization.state du rapport vous indique où vous en êtes : ready signifie qu'au moins une tâche a un objectif déclaré dans la source, des critères d'acceptation, une action suivante et des prérequis résolus. needs_organization signifie qu'il manque quelque chose — les actions ordonnées du rapport vous indiquent quoi ajouter à vos fichiers sources.
3. Démarrer une session de travail
Une session est l'unité de propriété du travail dans AWR. Ces commandes utilisent un petit helper shell pour que chaque appel porte le chemin du projet et une sortie JSON :
AWR_BIN=$(command -v awr)
AWR_WORK=INTAKE-001 # a task key from your intake report
AWR_AGENT=agent-primary # a label for who is working
AWR_MODEL=your-current-model # a recorded label; AWR does not invoke the model
AWR_NOTES=$(mktemp -d "${TMPDIR:-/tmp}/awr-session.XXXXXX")
awrj() { "$AWR_BIN" --project "$AWR_PROJECT" --json "$@"; }
Vérifiez ce qui est exécutable, puis démarrez une session avec une réservation (la propriété runtime de l'élément de travail) et la révision courante du projet :
awrj ready
AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session start --work "$AWR_WORK" --agent "$AWR_AGENT" \
--provider generic --model "$AWR_MODEL" --claim --ttl-ms 3600000 \
--expected-revision "$AWR_REV" > "$AWR_NOTES/start.json"
AWR_SESSION=$(jq -er '.session.id' "$AWR_NOTES/start.json")
Compilez le contexte de travail — l'objectif, les critères d'acceptation, les faits enregistrés et l'historique assemblés en un paquet borné :
awrj context compile --work "$AWR_WORK" --session "$AWR_SESSION" \
--budget 5000 > "$AWR_NOTES/context.json"
jq -e '.completeness.complete and (.work_context != null)' "$AWR_NOTES/context.json"
Lisez le paquet, pas seulement le booléen. Sur BudgetExceeded, élargissez --budget ; sur SourceStale, exécutez awrj source reindex et compilez à nouveau.
4. Enregistrer la progression avec un point de contrôle
Avant de vous éloigner — ou avant qu'une longue conversation hôte ne soit compactée — enregistrez un point de contrôle avec le hash de contexte que vous avez réellement utilisé, un résumé honnête, l'action suivante exacte et chaque boucle ouverte :
AWR_CONTEXT_HASH=$(jq -er '.work_context.context_hash' "$AWR_NOTES/context.json")
AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session checkpoint --session "$AWR_SESSION" --agent "$AWR_AGENT" \
--context-hash "$AWR_CONTEXT_HASH" \
--digest "Record the work actually done; do not invent a passing review." \
--next-action "State the exact next operator or agent action." \
--open-loop "List every unresolved loop." \
--expected-project-revision "$AWR_REV" > "$AWR_NOTES/checkpoint.json"
Un point de contrôle peut enregistrer du travail inachevé ; il n'est pas une preuve de tests réussis ni de critères d'acceptation remplis.
5. Continuer le travail dans une nouvelle session
Pour prouver que la continuation fonctionne, terminez la première session et repartez d'elle — le même chemin de reprise qu'utiliseraient un nouvel agent, une nouvelle machine ou une nouvelle conversation hôte. La fin libère la réservation ; elle ne marque pas le travail source comme terminé :
AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session end --session "$AWR_SESSION" --outcome incomplete \
--expected-revision "$AWR_REV"
Maintenant, reprenez. N'importe quel agent — un autre, ou le même plus tard — crée une session successeur à partir de la précédente :
AWR_PREDECESSOR="$AWR_SESSION"
awrj session show "$AWR_PREDECESSOR"
AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session resume --from-session "$AWR_PREDECESSOR" \
--agent successor --provider generic --model "$AWR_MODEL" \
--budget 5000 --expected-revision "$AWR_REV" > "$AWR_NOTES/resume.json"
jq -e '.context_ready' "$AWR_NOTES/resume.json"
AWR_SESSION=$(jq -er '.resumed.session.id' "$AWR_NOTES/resume.json")
Deux vérifications confirment que la passation a fonctionné :
jq -e '.context_ready'sort avec le code 0 : le successeur a reçu le contexte enregistré du prédécesseur, y compris le dernier point de contrôle réussi.- La session reprise a un nouvel identifiant — la reprise crée une nouvelle session AWR plutôt que de modifier l'ancienne.
Vous pouvez aussi inspecter l'état de reprise en lecture seule à tout moment :
awrj recovery inspect --session "$AWR_SESSION"
Vous travaillez dans le chat d'un agent de codage ? Liez la conversation hôte à la session AWR pour que les points de contrôle survivent à la compaction de l'hôte :
awrj client bind --client generic --external-session "myhost:$HOST_CONVERSATION_ID" \
--work "$AWR_WORK" --session "$AWR_SESSION"
AWR ne transfère pas la mémoire de processus d'un hôte et ne prend pas en charge des processus existants arbitraires — la continuité vient de ce qui a été explicitement enregistré.
Pour aller plus loin
- Concepts — ce que signifient sessions, réservations et points de contrôle.
- Référence CLI — l'ensemble complet des commandes utilisées ci-dessus.
- Flux de travail quotidien — cette boucle dans le travail de tous les jours.
- Dépannage — quand quelque chose signale un résultat inattendu.