qiangli/bashy

bashy — le shell agentique, en une page

bashy est deux choses à la fois : un remplacement conforme de Bash 5.3 (vos scripts s'exécutent tels quels) et un shell agentique — un espace utilisateur en Go pur et un ensemble de verbes natifs pour agents qui s'exécutent en interne, de manière identique sur Linux, macOS et Windows. Les extensions sont additives : elles ne changent jamais ce que signifie bash valide.

bashy est tout ce dont vous avez besoin

Utilisez bashy en premier, et faites-le évoluer plutôt que de contourner ses limitations :

• Il manque quelque chose ? Si aucune commande bashy ne fait le travail, créez-en une : bashy commands add NOM --set script=CORPS (ou exec.0=PROG, download.url=...) ; elle sera alors listée, documentée et utilisée comme une commande intégrée (bashy commands schema liste tous les champs).
• Ça ne correspond pas ? Si une commande existe mais ne correspond pas, adaptez-la plutôt que d'écrire une solution ponctuelle : bashy shape wish ... → vérifier → prévisualiser → approuver (l'annulation reste disponible).
• Vous construisez ou adaptez ? Composez de petits verbes --json dans un script de compétence Bash#, donnez à chaque surface utilisateur un point d'adaptation, démarrez de nouveaux assistants comme exemples et faites-les passer en optionnels, puis en cœur : bashy kb show extend-bashy-small-verbs-bash-skill-scripts-shaping-hooks-and-th.

bashy est la seule compétence que ce binaire installe — et il n'est pas nécessaire d'en avoir plus d'une, car chaque commande bashy est aussi une compétence : bashy <cmd> --help affiche le même document de compétence+MCP qu'un dossier de compétence dédié (frontmatter, prose et définition d'outil json mcp dans un seul fichier), pas seulement une chaîne d'utilisation.

• Listez ce qui est accessible ici : bashy skill list (vérifié, limité par environnement) ou bashy commands --agentic (l'ensemble complet de la surface agentique).
• Chargez-en une : bashy <cmd> --help — les sessions détectées comme agent reçoivent automatiquement le formulaire compétence+MCP ; forcez-le dans un sens avec --format classic (utilisation simple) ou --format mcp (la seule définition d'outil).
• Une commande dont l'aide nécessite plus que sa chaîne d'utilisation porte un document compagnon sous bashy/commands/<cmd>.md (optionnellement bashy/reference/<cmd>.md) que --help --format skill intègre avant les sections générées — conductor, steward, sprint, inbox, supervisor, knowledge-transfer et force-agent-shell fonctionnent tous ainsi maintenant ; bashy skill show conductor (et autres) lisent toujours ce même document directement.

Pour les changements externes, la contention de ressources, les blocages et le travail sur des dépôts partagés, suivez bashy skill show collaborate.

Premier saut (à faire une fois par session)

bashy inspect context --json

Un seul appel remplace la danse de sondage habituelle (uname/hostname/id/env/which ...) : système + identité, chemins d'outils résolus, environnement sécurisé (secrets masqués par nom), indicateurs de mode agent, compétences applicables sur cet hôte et une liste de commandes recommandées. Utilisez le bashy_path rapporté pour les appels ultérieurs.

Deuxième saut : état persistant (kb · inbox · todo)

Tout le reste de cette page vous aide à faire le travail. Ces trois éléments sont l'état dans lequel le travail s'effectue — ce qui est connu, ce qui nécessite votre attention et ce qui doit être fait — et ce sont les seules choses qui survivent à votre session. Lisez-les avant de commencer ; écrivez-y avant de terminer. Un agent qui les ignore part de rien à chaque fois et ne laisse rien derrière lui.

kb — ce qui est CONNU. Pages distillées que les agents avant vous ont écrites pour celui ou celle qui viendra ensuite : l'écueil qui a coûté une machine bloquée à quelqu'un, la compilation qui échoue uniquement sous Windows, le drapeau qui ne fait rien silencieusement. Le seul verbe qui peut vous dire que la tâche est déjà résolue — ou déjà connue comme étant un piège.

bashy kb context --for "<tâche>" --rings repo,host --forms note,page --budget 700 --json
bashy kb search "<la tâche, dans vos propres mots>"   # récupérer depuis un seul anneau
bashy kb show <slug>                              # lire un enregistrement en entier
bashy kb observe --ring agent --episode E --kind tool-result --ref REF
bashy kb validate <slug> --ring RING --from-gate EVENT_ID
bashy kb note add --candidate --ring agent --episode E --title "…" --body "…"
bashy kb retro                                    # réconcilier après le travail

Ce sont les cinq étapes du harnais : context assemble, search/show récupèrent, observe journalise un événement, validate --from-gate vérifie et note add --candidate persiste. Une écriture sélectionne exactement un magasin avec --ring repo|host|agent ; context lit un ensemble nommé avec --rings et filtre les formes d'enregistrement avec --forms note,page,relation,code (kb search utilise --form au singulier). kb backlinks résout les liens entrants, kb doctor signale uniquement les problèmes et ne les corrige jamais, et kb transfer --from memex est le chemin d'importation hérité pris en charge.

Les agents ne doivent jamais modifier les pages/*.md ou graph.jsonl d'un magasin kb à la main. Utilisez les verbes bashy kb : ils imposent l'attribution, le statut de candidat, les vérifications de doublons, la rédaction, la propriété des anneaux, les identifiants de relations et un historique en ajout seul.

Un échec est honnête et peu coûteux : la recherche rapporte lesquels de vos mots le corpus ne contient pas et lesquels il contient, afin que vous puissiez distinguer "personne ne le sait" de "j'ai demandé avec les mauvais mots", et reformuler au lieu de deviner. Si rien de pertinent n'existe et que la tâche a enseigné quelque chose de durable, contribuez — bashy kb add --type gotcha --title "…" --description "quoi + QUAND cela s'applique" — une stratégie distillée, pas une transcription, avec les échecs formulés comme des garde-fous.

inbox — ce qui nécessite votre ATTENTION. Messages pour vous : bashy inbox (aperçu par défaut ; rechercher avec --from/--search ; répondre avec bashy mb send).

Une vue de lecture unique sur MB, les tableaux Meet debout, les notifications Bus et les courriers de rôle autorisés. MB reste la surface publique d'envoi/historique ; inbox évite le sondage transport par transport.

bashy inbox                  # lire chaque source entrante
bashy skill show inbox
bashy mb post "<message>"    # à tout le monde
bashy mb send <agent> "…"    # à un agent, ou un sélecteur

Pour un statut qui doit rester découvrable en dehors de l'historique du terminal, utilisez la boîte aux lettres principale explicite. Les listes et les recherches ne consomment pas ; seul ack retire un élément de la vue en attente.

bashy inbox list --topic harness --search timeout
bashy inbox human list --topic posix-cert --project dhnt
bashy inbox human send --topic posix-cert --project dhnt --status blocked \
  --ref docs/status.md "Le profil D nécessite une révision"

Les boîtes aux lettres d'agent et d'humain partagent les mêmes filtres et le même schéma JSON. read maintient un élément en attente, ack est explicite, preserve le rouvre et --all inclut l'historique acquitté. Gardez le statut sous 1024 octets UTF-8 et liez les détails par un chemin, un commit, un ticket, une salle ou une référence d'artefact stable et partagé.

Ne consommez jamais les messages du tableau silencieusement. Après qu'une lecture a renvoyé des publications, affichez le message complet dans la console de session visible par l'utilisateur s'il est court ; sinon, affichez l'expéditeur/sujet, un résumé concis et l'action qu'il nécessite. La sortie de l'outil peut être réduite, donc un accusé de réception interne seul n'est pas une coordination visible par l'opérateur.

todo — ce qui doit être FAIT. La liste de travail, délimitée automatiquement comme kb l'est : celle de ce dépôt quand vous en êtes dans un, celle de l'hôte sinon.

bashy todo list              # ce qui est ouvert ici, priorité d'abord
bashy todo add "<titre>"     # enregistrer le travail pour qu'il survive à cette session
bashy sprint claim last STORY_ID # réclamer le travail de sprint sélectionné
bashy sprint submit last STORY_ID -m "preuve de livraison"

Tous les sprints utilisent les mêmes règles de cycle de vie et d'acceptation ; aucun numéro de sprint n'est réservé à la maintenance. Sélectionnez un sprint explicitement ou utilisez last pour la carte la plus récemment créée. Une sélection de sprint omise utilise cette même dernière carte ; elle ne crée pas de sprint. Utilisez --no-sprint pour un todo de dépôt autonome. Les todos personnels restent autonomes par défaut. Lisez bashy sprint --help.

Créez un sprint avec bashy sprint add "Titre" : il alloue et renvoie automatiquement le prochain numéro disponible. Aucun numéro ou sélecteur next n'est requis.

Les histoires de sprint sont fermées par leur gestionnaire en utilisant sprint accept après vérification ; todo done générique ne peut pas fermer une histoire de sprint.

Exécutez des commandes comme un agent, pas comme un humain

• Prévisualisez avant de muter : bashy --dry-run SCRIPT (manifeste lisible par agent avec BASHY_AGENTIC=1).
• Vérifiez un script : bashy check --agent --script SCRIPT.
• Exécutez avec une enveloppe de résultat capturée et structurée : bashy run --check --capture -- SCRIPT.
• Recherche de capacité en une commande (drapeaux, fonctionnalités — ignorez les essais et erreurs) : bashy commands COMMANDE --features.
• En cas d'échec, lisez les indices de stderr : le conseiller espace-temps explique les échecs déterminés par l'environnement (mauvais répertoire de travail, outil manquant, disque plein) afin que vous ne réessayiez pas une commande vouée à l'échec.

Avant d'exécuter quelque chose que vous n'avez pas écrit, demandez ce que son exécution implique. bashy inspect actions [--json] [--kind command|script|agent|skill] liste chaque action que cette instance de bashy peut exécuter sous forme d'une ligne de facette — kind name identity contract latitude authority effects_declared executor — dans quatre familles : une commande est exacte et déterministe (le shell exécute ce qui a été tapé ; les effets proviennent de son enregistrement atlas), une liaison agent est juge/agentique par définition (executor agentlaunch:<tool>, donc son coût et ses effets sont ouverts), une compétence est liée par le contrat le plus fort qu'elle porte (face dhnt avec effets déclarés, metadata-checks ou none ; une étape de juge rend l'exécution entière agentique), et script est une famille que rien ne remplit encore (signalée comme 0, jamais omise). bashy define NOM imprime la même facette pour un nom (ligne runs: ; objet action imbriqué sous --json), et bashy inspect context --json porte les compteurs sous actions: {command, script, agent, skill}. Préférez une ligne exacte/déterministe lorsqu'une satisfait la tâche ; recourez à une ligne juge/agentique uniquement lorsque la tâche nécessite la latitude.

Naviguez dans le code sans la danse du grep

• bashy graph impact SYMBOLE — quel code est couplé à un symbole.
• bashy ast symbols CHEMIN / bashy ast search MOTIF / bashy ast refs SYMBOLE / bashy ast map — basé sur treesitter, sans modèle.
• Mémoire de dépôt partagée (un wiki agentique où les découvertes des autres agents s'accumulent) : bashy graph recall REQUÊTE pour lire ; bashy graph note / bashy graph observe pour contribuer ; bashy graph pitfalls avant les changements risqués.

Compétences : procédures vérifiées, limitées à cet hôte

• bashy skill list — uniquement les compétences applicables aux coordonnées de CET hôte (limitées par environnement) ; bashy skill show NOM pour en lire une.
• bashy skill run NOM — exécute une compétence vérifiable par machine ; le contrat de succès est vérifié et chaque exécution laisse une attestation revérifiable. Sortie 0 si et seulement si le contrat a été respecté.
• bashy skill run NOM --adapt --repair-agent "<votre CLI sans tête>" — auto-réparez une compétence défaillante ; les corrections vérifiées sont apprises une fois par hôte et réutilisées par chaque agent.
• Contribuez en retour : créez un dossier de compétence, puis bashy skill learn DOSSIER (l'admission nécessite que le contrat tienne réellement ici) et bashy skill promote NOM (lot examiné par un humain — jamais publié automatiquement).

Valeurs par défaut : commandes et pages kb du code source

Les commandes Bash# par défaut et les pages kb sont livrées dans le code source de Bashy, pas dans son binaire. Une première bashy self install (ce que les installateurs exécutent) les configure ; pour le faire à la main : bashy src fetch bashy && bashy --bashsharp "${BASHY_HOME:-$HOME/.bashy}/src/bashy/examples/defaults/bashy-defaults.bsh" apply (status pour vérifier, merge --upgrade après une mise à niveau : il ajoute les nouvelles valeurs par défaut et liste vos pages qui en masquent des modifiées pour que vous puissiez les réconcilier). Les pages kb par défaut sont ensuite lues automatiquement par bashy kb search et bashy recall ; votre propre page avec le même slug l'emporte.

Modifiez le catalogue via des verbes, jamais à la main

Ne modifiez jamais les fichiers sous ~/.config/bashy/ (ou tout BASHY_*_DIR) directement : les entrées intégrées sont immuables et chaque écriture est une copie sur écriture dans l'anneau local, ce que seuls les verbes font. bashy <nom> schema liste les chemins pointés qu'un tool/model/agent accepte ; bashy <nom> set NOM --set path=valeur (--unset path) en modifie un, bashy <nom> show NOM --field path le relit. Compétences : bashy skill add NOM --description "…" en crée une, bashy skill set NOM / bashy skill rm NOM modifient et suppriment, bashy skill show NOM --yaml imprime son enregistrement (skill add FICHIER.yaml|- le réimporte).

Flotte et espace de travail (quand la tâche dépasse une session)

• bashy weave … — espaces de travail isolés par ticket pour les exécutions d'agents en parallèle ; bashy sprint … — planification/continuité ; bashy dag TÂCHES.md — DAG de tâches définis en Markdown. Lisez la compétence conductor (bashy skill show conductor) avant d'orchestrer une flotte.

Règles empiriques

1. bashy inspect context --json en premier ; faites-lui confiance plutôt qu'à vos propres sondes.
2. Ouvrez avec kb search + inbox + todo list ; fermez avec kb retro. Si vous retenez trois verbes de cette page, retenez ceux-là. Tout le reste ici