Beads (bd) – AI 에이전트를 위한 분산 이슈 트래커

이것은 무엇인가 – AI 코딩 에이전트에게 작업 추적을 위한 구조화되고 버전 관리되는 "메모리"를 제공하는 명령줄 도구입니다. 작업(beads라고 함)을 Dolt SQL 데이터베이스에 저장하며, 이는 브랜치, 병합, 원격 동기화를 갖춘 Git 스타일 데이터 저장소처럼 동작합니다.

에이전트에게 중요한 이유 – 에이전트는 TODO를 markdown에 흩뿌리는 대신 의존성 그래프를 쿼리하고, 작업을 원자적으로 클레임하며, bd remember를 통해 지속적인 사실을 검색할 수 있습니다. JSON 출력과 해시 기반 ID는 프로그래밍 방식 소비를 위해 설계되어 여러 에이전트가 병합 충돌 없이 협업할 수 있습니다.

핵심 개념

개념	설명
Bead	Dolt DB에 저장된 작업/이슈. ID는 `bd‑a1b2`(에픽) 또는 `bd‑a1b2.1`(하위 작업)처럼 보입니다.
의존성 그래프	작업은 링크될 수 있습니다(`relates‑to`, `duplicates`, `supersedes`, `replies‑to`). `bd dep add <child> <parent>`는 블로커/부모 관계를 생성하여 `bd ready` 명령이 열린 블로커가 없는 작업만 나열할 수 있게 합니다.
Dolt 백엔드	Dolt는 셀 수준 병합, 네이티브 브랜치, 원격 push/pull을 갖춘 SQL 데이터베이스를 제공합니다. Beads는 Dolt를 임베디드로 실행하거나(기본값) 외부 Dolt SQL 서버에 연결하여 동시 작성자를 지원할 수 있습니다.
에이전트 최적화 워크플로	명령은 JSON을 출력하고, `--claim`(원자적 클레임 + 진행 중 플래그)을 지원하며, 프로젝트의 "메모리"(사실, 열린 작업)를 에이전트의 프롬프트에 주입하는 `bd prime` 명령을 제공합니다.
압축 / 메모리 감쇠	닫힌 작업은 자동으로 요약되어 데이터베이스가 작게 유지되고 LLM 컨텍스트 윈도우 내에 머무릅니다.

일반적인 워크플로(CLI 명령)

# One‑time install (system‑wide)
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

# Initialise a project (creates .beads/ and AGENTS.md)
cd my‑project && bd init

# Add a high‑priority task
bd create "Implement search endpoint" -p 0

# Declare that it blocks another task
bd dep add bd‑a1b2.1 bd‑a1b2   # child blocks parent

# Agent asks for work it can start now
bd ready --json   # only tasks with no open blockers

# Agent claims a task atomically
bd update bd‑a1b2.1 --claim

# While working, store a reusable insight
bd remember "ElasticSearch pagination uses `search_after`" 

# When finished, close the task (releases blockers)
bd close bd‑a1b2.1 "Implemented and tested"

*bd prime*는 현재 컨텍스트(열린 작업, 저장된 통찰)를 출력하여 LLM 기반 코딩 어시스턴트가 이를 프롬프트 앞에 추가할 수 있게 합니다.

통합 지점

통합	추가되는 것
Codex / Claude / Factory.ai (`bd setup <name>`)	언어 모델별 지시 파일(`AGENTS.md`)과 IDE 훅을 설치하여 모델이 Beads 명령을 알 수 있게 합니다.
VS Code / Cursor / Copilot	Beads 명령을 UI 작업으로 변환하고 생성 전에 자동으로 `bd prime`을 실행하는 확장을 제공합니다.
HTTP 백엔드(실험적)	원격 `bd serve` 프로세스에 대해 얇은 클라이언트를 실행합니다. 공유 서버나 Beads를 라이브러리로 임베드하는 데 유용합니다.
Git 없는 모드 (`bd init --stealth`)	저장소를 건드리지 않고 모든 것을 `.beads/`에 저장합니다. CI, 모노레포, 비 Git VCS에 이상적입니다.

AI 에이전트 스택에 맞는 방법

프롬프트 준비 – bd prime(또는 생성된 AGENTS.md 스니펫)이 준비된 작업과 기억된 사실의 간결한 목록을 LLM 프롬프트에 주입합니다.
의사 결정 – 에이전트는 bd ready/bd show의 JSON 출력을 파싱하여 작업을 선택합니다.
실행 – 에이전트는 bd update … --claim을 실행하고, 코드 변경을 수행한 다음 bd close …를 실행합니다.
협업 – 여러 에이전트(또는 인간)가 동시에 작업을 클레임할 수 있습니다. Dolt의 해시 기반 ID가 충돌 없는 병합을 보장합니다.
지속성 – 모든 작업 기록, 의존성, 저장된 통찰은 Dolt DB에 저장되며 bd dolt push/pull로 머신 간 동기화할 수 있습니다.

시작하기

설치 – brew install beads, npm install -g @beads/bd, 또는 제공된 설치 스크립트를 사용하세요.
문서 – https://beads.gascity.com/ (설치, 동기화 개념, HTTP 백엔드, 문제 해결).
커뮤니티 – UI 확장, 웹 프론트엔드, 관련 프로젝트는 docs/community-tools.md에 나열되어 있습니다.

TL;DR

Beads는 프로젝트의 작업 목록을 기계 판독 가능하고 버전 관리되는 그래프로 바꾸는 전용 이슈 트래커입니다. LLM 기반 코딩 에이전트와 결합하면 신뢰할 수 있고 충돌 없는 조정과 여러 실행 및 여러 에이전트에 걸쳐 지속되는 내구성 있는 "메모리"를 얻을 수 있습니다.

gastownhall/beads