====== Beads ======

[[https://github.com/gastownhall/beads|Beads]] je CLI nástroj pro task tracking a perzistentní paměť AI coding agentů. Podle [[https://github.com/gastownhall/beads/blob/main/README.md|README]] nahrazuje volné markdown plány dependency-aware grafem nad [[https://github.com/dolthub/dolt|Dolt]] databází, takže stav práce zůstává uložený i mimo krátkodobý kontext jedné session.

  * **Hlavní binárka:** ''bd''
  * **Jazyk:** Go
  * **Licence:** MIT
  * **Datové úložiště:** Dolt
  * **Dokumentace:** [[https://gastownhall.github.io/beads/|gastownhall.github.io/beads]]

===== Co projekt řeší =====

Beads míří na workflow, kde běžný TODO seznam nebo markdown plán přestává stačit. README vyzdvihuje hlavně tyto problémy:

  * agent ztrácí kontext při delší nebo restartované session
  * tasky potřebují explicitní závislosti, prioritu a audit trail
  * při práci ve více větvích nebo s více agenty vznikají kolize v ručně vedených plánech
  * je potřeba strojově čitelný stav, ne jen volný text pro člověka

Výsledkem je databázově uložený graf tasků, který jde dobře číst jak člověkem, tak agentem.

===== Jak funguje =====

==== Tasky, závislosti a identita ====

Beads funguje jako issue tracker orientovaný na agenty. Každý task má vlastní ID typu ''bd-a1b2'', lze ho claimnout, uzavřít, navazovat na další tasky a číst přes JSON výstup.

Projekt podporuje i hierarchické ID pro větší celky práce:

  * ''bd-a3f8'' jako epic
  * ''bd-a3f8.1'' jako task
  * ''bd-a3f8.1.1'' jako sub-task

Kromě blokujících závislostí umí i další typy vztahů jako ''relates_to'', ''duplicates'', ''supersedes'' nebo ''replies_to''. README také zmiňuje message issue typ s vláknem zpráv a compaction, tedy průběžné zkracování staré uzavřené historie kvůli úspoře kontextového okna.

==== Storage mode ====

[[https://gastownhall.github.io/beads/|Dokumentace]] popisuje dva základní režimy:

  * **Embedded mode** je výchozí. Dolt běží in-process, data jsou v ''.beads/embeddeddolt/'' a režim je vhodný hlavně pro single-writer workflow.
  * **Server mode** používá externí ''dolt sql-server'', data ukládá do ''.beads/dolt/'' a hodí se tam, kde je potřeba více současných writerů.

===== Instalace a bootstrap =====

README výslovně upozorňuje, že Beads se instaluje jako globální CLI a neklonuje se do každého projektu zvlášť. Základní instalace vypadá takto:

<code bash>
brew install beads
# nebo
npm install -g @beads/bd
</code>

Po instalaci se nástroj inicializuje v konkrétním projektu:

<code bash>
cd your-project
bd init
</code>

Součástí doporučeného bootstrapu je i doplnění instrukce do ''AGENTS.md'', aby agent věděl, že má používat právě ''bd'' pro task tracking.

===== Typické příkazy =====

Základní sada příkazů z README vypadá takto:

<code bash>
bd ready
bd create "Title" -p 0
bd update bd-a1b2 --claim
bd dep add bd-a1b3 bd-a1b2
bd show bd-a1b2
</code>

Zjednodušeně to znamená:

  - ''bd ready'' vypíše tasky bez otevřených blockerů
  - ''bd create'' založí nový task s prioritou
  - ''bd update --claim'' task atomicky přiřadí a přepne do stavu in progress
  - ''bd dep add'' vytvoří závislost mezi dvěma tasky
  - ''bd show'' zobrazí detail tasku a audit trail

===== Zajímavé režimy použití =====

README popisuje několik režimů, které jsou pro agentické workflow praktické:

  * **Stealth mode** přes ''bd init --stealth'' umožní používat Beads lokálně bez commitování metadat do hlavního repozitáře.
  * **Git-free usage** funguje i bez gitu, pokud se nastaví ''BEADS_DIR'' a použije se ''--stealth''.
  * **Contributor mode** přes ''bd init --contributor'' oddělí planning issues do samostatného úložiště, což je užitečné hlavně při práci z forku na open-source projektu.

To dává smysl hlavně tam, kde agent nebo člověk potřebuje evidovat práci mimo hlavní historii repozitáře.

===== Vztah ke Gas Town =====

Ve wiki už je samostatný článek [[ai:platformy:agenti-a-orchestrace:gastown|Gas Town]]. Ten používá Beads jako perzistentní vrstvu pro evidenci tasků, convoye a dlouhodobý stav práce nad agenty a worktree.

Samotný Beads je ale použitelný i mimo Gas Town. Je to samostatný nástroj pro task tracking a paměť agentů, zatímco Gas Town nad ním staví širší orchestration vrstvu.

===== Praktické poznámky =====

Beads není jen textový wrapper nad TODO souborem. Je to databázově orientovaný task tracker s důrazem na JSON výstupy, závislosti a merge-safe identifikátory. Z README je také vidět, že projekt řeší i bezpečnost instalace — například doporučuje ověření checksumů release balíčků a popisuje rozdíly mezi embedded a server režimem.

Pro jednodušší solo workflow typicky stačí embedded mode. Jakmile ale nad jedním stavem práce zapisuje více agentů současně, dává smysl přemýšlet o server mode a explicitnější koordinaci.

===== Zdroje =====

  * [[https://github.com/gastownhall/beads|Beads – GitHub repo]]
  * [[https://github.com/gastownhall/beads/blob/main/README.md|Beads – README]]
  * [[https://gastownhall.github.io/beads/|Beads – dokumentace]]
  * [[https://wiki.petrnosek.cz/ai/platformy/agenti-a-orchestrace/gastown|Gas Town – související článek ve wiki]]