bd - Beads
Dolt를 기반으로 하는 AI 에이전트를 위한 분산 그래프 이슈 트래커입니다.
플랫폼: macOS, Linux, Windows, FreeBSD
License
Go Report Card
Release
npm version
PyPI
문서: https://beads.gascity.com/
Beads는 코딩 에이전트를 위한 영구적이고 구조화된 메모리를 제공합니다. 이는 지저분한 마크다운(markdown) 계획을 의존성 인식 그래프(dependency-aware graph)로 대체하여, 에이전트가 컨텍스트를 잃지 않고 장기 범위 작업(long-horizon tasks)을 처리할 수 있게 합니다.
flowchart LR
create["bd create<br/>새로운 bead"] --> depgraph["의존성<br/>그래프"]
depgraph --> ready["bd ready<br/>할당 가능한 작업"]
...
⚡ 빠른 시작
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
...
참고: Beads는 한 번 설치하여 모든 곳에서 사용할 수 있는 CLI 도구입니다. 이 저장소를 프로젝트에 클론할 필요가 없습니다.
bd init은 기본적으로 AGENTS.md 파일을 생성하거나 업데이트하여 에이전트가 beads 워크플로우를 발견할 수 있게 하며, --skip-agents 또는 --stealth 플래그를 전달하지 않는 한 프로젝트에 Claude Code, Codex, Cursor 통합을 설치합니다. 지원되는 모든 통합(예: bd setup codex, bd setup factory, bd setup claude, bd setup mux, bd setup cursor 등)은 bd setup --list를 사용하여 확인할 수 있습니다. Agent 및 IDE 설정을 참조하세요.
수동 복사 붙여넣기는 지원되지 않는 에이전트, bd init/bd setup을 다시 실행할 수 없는 기존 프로젝트 또는 사용자 지정 명령어 파일에만 해당합니다. 이 경우, bd onboard를 실행하고 출력된 스니펫을 에이전트가 읽는 파일에 붙여넣으세요.
만약 사용 중인 에이전트가 bd setup으로 커버되지 않는다면, 다음 최소한의 AGENTS.md 섹션을 추가하세요:
This project uses bd (beads) for issue tracking.
- Run `bd prime` for workflow context and command guidance.
...
🛠 기능(Features)
- Dolt 기반: 셀 수준 병합, 네이티브 브랜칭, Dolt 원격 저장소(remotes)를 통한 내장 동기화 기능을 갖춘 버전 관리형 SQL 데이터베이스.
- 에이전트 최적화: JSON 출력, 의존성 추적(dependency tracking), 자동 준비 작업 감지 기능.
- 충돌 제로(Zero Conflict): 해시 기반 ID(
bd-a1b2)가 다중 에이전트/다중 브랜치 워크플로우에서 병합 충돌을 방지합니다.
- 압축(Compaction): 의미론적 '메모리 감쇠(memory decay)' 기능으로 오래된 완료된 작업을 요약하여 컨텍스트 창(context window)을 절약합니다.
- 메시징: 스레딩(
--thread)이 가능한 메시지 이슈 유형, 일시적 생명 주기(ephemeral lifecycle), 메일 위임 기능을 제공합니다.
- 그래프 링크: 지식 그래프를 위한
relates-to, duplicates, supersedes, replies-to 연결을 지원합니다.
📖 필수 명령어(Essential Commands)
| 명령어 | 동작 |
|---|
bd ready | 열려 있는 블로커가 없는 작업을 목록으로 표시합니다. |
| ... | |
🔗 계층 구조 및 워크플로우(Hierarchy & Workflow)
Beads는 에픽(epics)을 위한 계층적 ID를 지원합니다:
bd-a3f8 (에픽, Epic)bd-a3f8.1 (작업, Task)bd-a3f8.1.1 (하위 작업, Sub-task)
스텔스 모드(Stealth Mode): bd init --stealth를 실행하여 파일을 메인 저장소에 커밋하지 않고 Beads를 로컬에서 사용할 수 있습니다. 공유 프로젝트에서 개인적으로 사용하기에 완벽합니다. 아래 Git 미사용 사용법을 참조하세요.
기여자 vs 유지 관리자(Contributor vs Maintainer): 오픈 소스 프로젝트 작업 시:
- 기여자(Contributors) (포크된 저장소):
bd init --contributor를 실행하여 계획 관련 이슈가 별도의 저장소(예: ~/.beads-planning)로 라우팅되도록 합니다. 실험적인 작업을 PR에서 분리할 수 있습니다.
- 유지 관리자(Maintainers) (쓰기 접근 권한): Beads는 SSH URL 또는 자격 증명이 포함된 HTTPS를 통해 유지 관리자 역할을 자동으로 감지합니다. 쓰기 접근 권한이 있지만 자격 증명 없이 GitHub HTTPS를 사용하는 경우에만
git config beads.role maintainer가 필요합니다.
📦 설치(Installation)
brew install beads
npm install -g @beads/bd
다른 방법: 설치 스크립트 | go install | 소스에서 빌드 | Windows | Arch AUR
요구 사항: macOS, Linux, Windows 또는 FreeBSD. 전체 설치 가이드는 docs/getting-started/installation.md를 참조하십시오.
업그레이드하기? 바이너리 교체가 항상 전부는 아닙니다. 요약하자면: 현재의 bd와 원격 백업(remote-backed) 데이터베이스를 동기화하고, bd export --all로 백업한 다음, 바이너리를 업그레이드하고, 이어서 bd info --whats-new, bd hooks install, 그리고 bd version을 실행합니다. 만약 업그레이드가 원격 백업 데이터베이스의 스키마 마이그레이션(schema migration)을 거치는 경우, 지정된 단 하나의 클론(clone)만이 bd migrate schema와 bd dolt push를 실행하며, 나머지 클론들은 새 바이너리를 설치하고 bd bootstrap을 실행합니다. 전체 업그레이드 가이드 또는 docs/getting-started/installation.md를 참조하십시오.
보안 및 검증 (Security And Verification)
명령어 및 자격 증명 대상 설정은 .beads/.env가 아닌 셸 환경 또는 사용자 구성에서 가져와야 합니다. .beads/.env는 명령어 형태의 BEADS_* 및 BD_* 변수, 그리고 두 개의 Dolt 원격 자격 증명 변수(DOLT_REMOTE_USER, DOLT_REMOTE_PASSWORD)만 허용합니다. Beads는 이 파일에서 자격 증명 명령어, 메일 위임(mail delegates), 에디터, 페이지 매거진기(pager), Dolt 실행 파일/호스트/자격 증명 파일/루트 경로 재정의, 그리고 나머지 dolt 소유의 DOLT_* 네임스페이스(예: DOLT_SSH_COMMAND, DOLT_PAGER) 및 비-Beads 프로세스 변수(예: GIT_*, SSH_*, LD_*, DYLD_*)를 무시하며, 각각에 대해 경고 메시지를 출력합니다.
bd config set mail.delegate "gt mail"은 복제된 데이터베이스가 아닌 사용자 전역 YAML 파일에 쓰기 작업을 수행합니다. 워크스페이스 설정 API는 mail.delegate를 거부합니다. 메일 위임 기능 역시 프로젝트의 .beads/config.yaml을 무시하며, 셸 환경 변수와 사용자 전역 YAML만 위임을 선택할 수 있습니다.
다운로드한 바이너리를 신뢰하기 전에, 반드시 해당 체크섬(checksum)을 릴리스 checksums.txt 파일과 비교하여 검증하십시오.
설치 스크립트는 설치 전에 릴리스 체크섬을 검증합니다. 수동으로 설치하는 경우, 첫 실행 전에 직접 이 검증 과정을 수행해야 합니다.
macOS의 경우, scripts/install.sh는 기본적으로 다운로드된 서명을 보존합니다. 로컬 임시 재서명(ad-hoc re-signing)은 BEADS_INSTALL_RESIGN_MACOS=1을 통해 명시적으로 옵트인해야 합니다.
Windows 환경의 AV 오탐지 관련 안내 및 검증 워크플로우는 docs/reference/antivirus.md를 참조하십시오.
💾 저장 모드 (Storage Modes)
Beads는 데이터베이스로 Dolt를 사용합니다. 두 가지 모드가 있습니다:
- 임베디드(Embedded, 기본값) —
bd init. Dolt가 인프로세스(in-process)로 실행되며, 데이터는 .beads/embeddeddolt/에 저장되고 단일 작성자(single writer)를 사용합니다. 대부분의 사용자에게 권장됩니다.
- 서버(Server) —
bd init --server. 여러 동시 작성자를 위해 외부 dolt sql-server에 연결하며, 데이터는 .beads/dolt/에 저장됩니다.
크로스 머신 동기화(Cross-machine sync)는 git 원격 저장소의 refs/dolt/data에 대해 bd dolt push / bd dolt pull을 사용합니다. .beads/issues.jsonl은 뷰어 및 교환용 내보내기 파일일 뿐, 진실의 근원지(source of truth)나 백업본이 아닙니다. 모드 간 백업 및 마이그레이션은 bd backup으로 수행하고, 공간을 확보하려면 bd prune / bd purge를 사용하세요.
연결 플래그, 소켓, 유지보수, 백업, 마이그레이션에 대한 전체 세부 정보는 Dolt 백엔드 가이드에서 확인할 수 있습니다.
스키마 버전 가드 (Schema Version Guard)
bd는 열기 시점에 데이터베이스의 스키마 버전을 확인합니다. 만약 데이터베이스가 더 최신 바이너리에 의해 마이그레이션되었는데, 구형 바이너리가 이를 열려고 하면, bd는 암호 같은 SQL 오류를 내는 쿼리를 실행하는 대신 처리 가능한(actionable) 오류와 함께 종료됩니다:
schema version mismatch: database is at v45, binary knows up to v42 (3 migrations ahead)
Your bd binary is stale. Queries for dropped or renamed columns will fail...
발생 시점: 데이터베이스 스키마가 바이너리보다 앞설 때만 발생합니다 (더 최신 바이너리가 데이터베이스를 마이그레이션했고, 이 바이너리는 그 마이그레이션을 알지 못하는 경우). 바이너리가 데이터베이스를 앞으로 마이그레이션하는 일반적인 업그레이드는 영향을 받지 않습니다.
우회 장치: BD_IGNORE_SCHEMA_SKEW=1 (또는 --ignore-schema-skew)을 사용하면 경고 메시지와 함께 가드를 우회합니다. 이 기능은 순방향 마이그레이션이 누적적(additive)이고 특정 워크로드에 안전하다는 것을 알 때만 사용해야 합니다.
🔌 HTTP 백엔드 (실험적)
워크스페이스는 로컬 Dolt 데이터베이스를 여는 대신 HTTP를 통해 원격 bd serve와 통신할 수도 있습니다. 이는 공유 서버에 연결되는 씬 클라이언트(thin client)나, 다른 프로그램에 라이브러리 형태로 beads를 임베딩하는 경우 유용합니다.
bd connect https://bd.example.com --expect-project-id my-project
...
HTTP 모드는 로컬 모드의 바이트 대 바이트(byte-for-byte) 미러는 아니지만, 일부 작업은 의도적으로 거부되거나(통신 채널이 이를 표현할 방법이 없기 때문) 다르게 작동하지만 오해의 여지가 없는 방식으로 저하됩니다(예를 들어, 몇 가지 제한되지 않은 목록 형태는 단일 쿼리 스냅샷 격리(single-query snapshot isolation)를 잃고 대신 서버 페이지를 페이지별로 탐색합니다). 이 모든 것은 고요한 간격이 아니라 의도적이고 테스트된 항목입니다. 어떤 작업에 의존하기 전에 무엇이 다르고 왜 다른지 전체 생성 목록은 engdocs/design/http-divergence-ledger.md에서 확인하십시오. 특히 한 가지 알아야 할 거부 사항이 있습니다: bd close --claim-next는 HTTP를 통해 아무것도 닫지 않습니다. 통신 채널의 배치 종료(batch close)가 클레임(claim)을 전달할 수 없기 때문입니다. 클레임 없이 닫은 다음, bd ready --claim을 실행하십시오.
Cross-repo dependencies는 HTTP에서도 정책을 유지합니다. 클라이언트는 각 external: 참조를 자체 external_projects 구성과 대조하여 해결합니다. bd dep tree는 해당 참조를 리프(leaf)로 보여주며, 이 참조가 충족되지 않은 상태라도 이슈는 bd ready와 bd ready --claim에 포함되지 않으며, --force 없이 bd close는 이를 거부합니다. 이러한 정책을 자체적으로 강제한다고 광고하는 서버는 대신 신뢰할 수 있습니다.
사전에 알아둘 가치가 있는 세 가지 CLI 수준의 차이점이 있습니다:
- ID가 정확하게 해결됩니다: 약어화된 ID는 확장되지 않습니다(통신 채널에는 부분 문자열 검색 기능이 없기 때문), 그리고 누락된 ID는 한 번 조회 후 찾을 수 없는 것으로 보고됩니다.
bd update -s closed는 closed_by_session (즉, --session 또는 CLAUDE_SESSION_ID로부터 온 값)를 기록하지 않습니다. 통신 채널의 업데이트가 이를 전달할 수 없기 때문입니다. 닫기 자체는 평소와 같이 발생합니다. bd close는 세션을 기록합니다. bd reopen의 히스토리 항목은 서버 자체의 레이블을 가집니다.- 기여자 자동 라우팅(
routing.* 설정)은 로컬 config.yaml 또는 환경에서만 읽히며, 절대 서버 설정에서는 읽히지 않습니다: 그 대상(targets)은 로컬 경로입니다.
bd connect는 성공적으로 실행되면 두 가지를 기록합니다: .beads/metadata.json에는 "backend": "http"가 저장되고, 사용자별로 존재하며 절대 git에 의해 추적되지 않는 사이드카 파일(.beads/http_target.json)에는 서버 URL과 고정된 프로젝트 ID가 기록됩니다. 이 명령어는 절대로 자격 증명(credential)을 디스크에 기록하지 않습니다. 만약 서버가 필요로 하는 경우, 베어러 자격 증명(bearer credential)은 BEADS_HTTP_TOKEN=host[:port]=<token> 변수에서 오거나, 다음으로 BEADS_HTTP_TOKEN_COMMAND=host[:port]=<command> (토큰을 출력하는 헬퍼)를 거치거나, 자격 증명 파일 또는 아예 자격 증명이 없을 수도 있습니다. 두 변수 모두 자신이 위한 서버 이름을 지정해야 합니다 (포트가 없는 패턴은 해당 호스트의 모든 포트에 일치합니다). 단순히 값을 제공하는 것은 거부되는데, 이는 그 값이 작업 공간의 http_target.json이 지정하는 어떤 서버로 전송될 것이기 때문입니다. 일반 http://를 통해 루프백(non-loopback) 서버에 연결하는 것은 기본적으로 거부됩니다 (베어러 자격 증명은 네트워크를 통해 암호화되지 않은 상태로 전송될 것이기 때문입니다). 이를 무시하려면 --allow-plaintext 플래그를 전달하거나 https://를 사용해야 합니다. 이미 다른 백엔드(backend)를 선택한 작업 공간을 전환하려면 --force가 필요합니다.
