Communitygithub.com

ming-14/PTY-Agent

Agent de communication bidirectionnelle avec des programmes CLI interactifs via subprocess ou pseudo-terminal (PTY). Fournit une interface CLI pour gérer les sessions.

Qu'est-ce que PTY-Agent ?

PTY-Agent est un agent spécialisé dans l'interaction avec des programmes en ligne de commande interactifs via un pseudo-terminal (PTY) ou un sous-processus. Il permet de lancer, surveiller, envoyer des commandes et lire les sorties de programmes tels que des REPL, débogueurs ou serveurs qui nécessitent un dialogue continu. L'outil gère automatiquement la détection d'états (blocage, crash, fenêtres GUI) et offre des options de timeout et de filtrage par expressions régulières pour optimiser les interactions. Il est conçu pour les cas où un script simple ne suffit pas et où une communication interactive et réactive est indispensable. Les développeurs peuvent l'utiliser dans des environnements comme Claude Code, Cursor ou Codex pour automatiser des tâches complexes impliquant des programmes en ligne de commande.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add ming-14/PTY-Agent

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Que fait PTY-Agent ?

PTY-Agent est un agent d'interaction pour programmes en ligne de commande interactifs qui communique en bidirectionnel avec des programmes CLI via subprocess ou pseudo-terminal (PTY).

Principe : un processus démon s'exécute en arrière-plan, reçoit les commandes de l'utilisateur et les transmet au programme CLI correspondant.

Le programme se trouve dans app.py, exécution : python app.py ...

Quand l'utiliser

  • En dernier recours lorsqu'il est nécessaire de dialoguer en continu avec un programme interactif (REPL, débogueur, serveur, compilation) — envoyer une entrée et attendre une sortie spécifique (invite) avant de continuer. Mais si un script suffit, ne pas utiliser PTY-Agent.
  • Le processus peut se bloquer ou s'exécuter longtemps — nécessité de vérifier régulièrement son état.
  • Le sous-processus peut planter — besoin de détecter le crash en temps réel.
  • Tests de simulation d'interactions utilisateur.

Quand ne pas l'utiliser

  • Tâches non interactives.
  • Cas où un script suffit.
  • Interfaces GUI, navigateurs, programmes TUI complexes.

Aide-mémoire des commandes

CommandeUtilisationOptions typiquesExemple
start/stopDémarrer/arrêter manuellement le démon ; le démarrage exec suffit généralement.
exec <nouvel-id-session> <options>Exécuter une commande pour lancer une session-c "<commande>" (obligatoire), -t "<regex>", --timeout <secondes>, --cwd <chemin>exec id_py -c "python -i" -t ">>>"
send <id-session> "<contenu>" [options]Envoyer une entrée à une session en cours-t "<regex>", --timeout <secondes>send id_py "print(1)" -t ">>>"
read <id-session> [options]Lire la sortie d'une session--lines, --grepread myid --lines 10
listLister toutes les sessions
kill <id-session>Terminer une session
events <id-session> [options]Voir les événements d'une session--last <N>, `--since <iso-datetimeHH:MM>`
closewin <id-session> <identifiant-fenêtre>Fermer une fenêtre GUI ; <identifiant-fenêtre> supporte décimal ou hexadécimal 0x

Conditions de retour de la commande send

ModeConditionInformation renvoyée
Avec triggerCorrespondance à la regexSortie incrémentale
Avec idle-timeoutTimeout d'inactivitéSortie incrémentale
Avec timeoutAtteinte du timeoutSortie incrémentale
AucunAtteinte du timeout par défautSortie incrémentale
Détection fenêtre GUI non ferméeFenêtre GUI détectée (subprocess peut ne pas être disponible)Infos fenêtre GUI + sortie incrémentale
Crash du processusÉvénement associé + sortie incrémentale
Fin du programmeSortie incrémentale

Remarque : Utiliser efficacement la fonction de conditions de retour du programme, en mettant à jour rapidement les conditions (notamment -t) en fonction du résultat du programme. Éviter les sleep dans le terminal, éviter d'enchaîner send puis read inutilement.

Utilisation de exec

python app.py exec <id-session> <options>

Options similaires à send. Options spécifiques :

  • -c "<commande>" (obligatoire) Commande à exécuter, requis.
  • --shell <shell> Supporte cmd/powershell/pwsh/bash (PowerShell par défaut, bascule automatique vers CMD si non supporté) ; configurable uniquement au lancement exec.
  • --pty Active le pseudo-terminal complet (ne supporte pas |, &&, etc.)
    • --force-pty-mode Ignore la détection des opérateurs shell en mode --pty
  • --cwd <chemin> Répertoire de travail du sous-processus ; par défaut, celui de l'appelant (client). À spécifier si différent.

Utilisation de send

python app.py send <id-session> "<contenu>" [options]

Options

  • -t/--trigger "<regex>" Correspondance regex
    • --newline — Vérifier la condition de trigger seulement après un saut de ligne, combiné avec -t
  • --timeout <secondes> Timeout d'attente (120s par défaut)
    • --idle-after-first-output Démarrer la détection d'inactivité seulement après la première sortie, combiné avec --idle-timeout
    • Remarque : Utiliser efficacement la fonction de conditions de retour du programme, en mettant à jour rapidement les conditions (notamment -t) en fonction du résultat du programme. Éviter les sleep dans le terminal, éviter d'enchaîner send puis read inutilement.
  • --idle-timeout <secondes> Timeout d'inactivité : déclenché si aucune sortie dans le délai imparti.
  • --full Renvoyer toutes les données du terminal (volumineux, privilégier --lines N).
  • --json-escaping Mode d'échappement JSON : échappe <contenu> en JSON (\\ \" \n \t \r \uXXX ...), recommandé pour l'envoi de contenu multiligne.

<contenu> est automatiquement suivi d'un saut de ligne. Pas de paramètre --input.

Règles de traitement des guillemets (niveau ligne de commande)

  • cmd : utiliser \" imbriqué : -c "python -c \"print(1)\""
  • PowerShell/Pwsh : guillemets simples à l'extérieur, guillemets doubles à l'intérieur : -c 'python -c "print(1)"'

Utilisation de read

python app.py read <id-session> [options]

Options :

  • --lines <N> Dernières N lignes
  • --lines debut:fin Plage de lignes
  • --grep "<regex>" Filtre regex
  • --offset <octets> Lecture incrémentale
  • --full Renvoyer toutes les données du terminal (volumineux, privilégier --lines N)

Utilisation complète de events

python app.py events <id-session> [options]

Options :

  • --last N
  • --since <iso-datetime|HH:MM>
  • --until <iso-datetime|HH:MM>

Options globales/générales

  • --keep-ansi Conserver les codes de contrôle
  • --color Activer la sortie couleur dans le terminal
  • --output-by-natural-language Sortie en langage naturel
  • --encoding <encodage> Encodage du terminal ; en cas de caractères illisibles, définir utf-8/gbk/gb2312/gb18030/big5
  • --no-debug Désactiver la sortie de débogage dans la réponse (arborescence des processus/fenêtres GUI/événements)
  • --show-config [CLÉ] Afficher la configuration actuelle de l'appel
  • --default <CLÉ> <VALEUR> Surcharger temporairement la configuration par défaut (clés possibles : output-by-natural-language/timeout/newline/keep-ansi/encoding/debug, <VALEUR> est la valeur ou on/off)

Format de sortie

  1. Mode JSON (par défaut) — stdout ne produit que du JSON, un objet JSON par ligne. Toutes les réponses non liées aux commandes (infos de démarrage/arrêt du démon, requêtes de configuration, texte d'aide, avertissements) sont également au format JSON :
    • Réponse de commande : {"type": "result", ...} / {"type": "ok", ...} / {"type": "error", ...}
    • Info démon : {"type": "info", "message": "[pty-agent] Démon démarré (port 12345)"}
    • Requête de configuration : {"type": "config", "content": "Configuration actuelle de l'appel:\n ..."}
    • Texte d'aide : {"type": "help", "content": "usage: pty-agent ..."}
    • Avertissement : {"type": "warning", "message": "..."}
  2. Mode langage naturel — activé avec --output-by-natural-language

Exemples de scénarios

Surveillance de processus long + lecture intermédiaire + terminaison

app.py exec srv -c "python server.py" --idle-timeout 3 # Lancement, idle-timeout pour retour rapide après première sortie
app.py read srv --lines 20 # Consultation des 20 dernières lignes en cours
app.py read srv --offset 1024 # Lecture incrémentale (depuis le dernier offset)
app.py read srv --grep "ERROR" # Voir uniquement les lignes d'erreur
app.py kill srv # Terminer quand on n'en a plus besoin

Détection de crash de processus

app.py exec job -c "python worker.py" --idle-timeout 5 # Lancement, idle-timeout en attente de sortie
# Si le processus plante, la réponse contient trigger.reason="ended", program.exit_code non nul, error_message avec info de crash
app.py events job --last 10 # Voir les détails de l'événement de crash (type process_crash)

Skills associés