사용해 본 모든 이슈 트래커가 같은 패턴을 따른다. 클라우드 서비스가 있다. Web UI가 있다. 누군가 클라우드 API와 통신하는 CLI를 만든다. CLI는 이등 시민이다: 느리고, 기능이 적고, 항상 API 버전이 하나 뒤처진다.

그 아키텍처를 뒤집는다. CLI에서 시작한다. 로컬 데이터베이스에 쓰게 한다. 데이터베이스에 버전 관리를 넣고, 소스 코드에 쓰는 것과 같은 브랜치와 머지 시맨틱을 적용한다. 그 위에 같은 데이터베이스 파일을 직접 읽는 네이티브 데스크톱 앱을 놓는다. API는 사이에 없다.

그것이 beads와 Beadbox다. 그리고 이 아키텍처가 존재하는 이유는 AI 에이전트다.

문제: 에이전트는 버튼을 클릭할 수 없다

AI 에이전트 플릿(코드 생성기, 리뷰어, 테스터, 디플로이어)을 조율하고 있다면, 에이전트가 이슈를 생성하고, 상태를 업데이트하고, 작업 큐를 읽어야 한다. Jira에 인증할 수 없다. Linear의 UI를 탐색할 수 없다. 로컬 데이터베이스에 쓰는 CLI가 필요하고, 빠르고, 네트워크 의존 제로여야 한다.

beads가 그 CLI다. 바로 이 워크플로를 위해 설계된 오픈소스 Git 네이티브 이슈 트래커다. bd 명령으로 이슈를 생성, 업데이트, 목록 조회, 클로즈한다. 모든 쓰기가 리포지토리의 .beads/ 디렉토리 안 로컬 Dolt 데이터베이스에 기록된다.

숫자가 중요하다. bd create는 약 15ms 걸린다. 1만 건 이슈에 대한 bd list는 약 200ms에 반환된다. 이 벤치마크는 beads 테스트 스위트에서 온 것이다. 에이전트가 타이트한 루프에서 작업 항목을 소화할 때, 작업당 밀리초가 이슈 트래커가 따라가느냐 병목이 되느냐를 결정한다.

SQLite가 아닌 Dolt를 쓰는 이유

Dolt는 Git 시맨틱을 구현한 SQL 데이터베이스다. 모든 쓰기가 커밋이 된다. dolt diff로 두 시점 간 변경을 확인할 수 있다. dolt log로 완전한 감사 히스토리를 얻는다. dolt branch와 dolt merge가 코드에 이미 쓰는 것과 같은 멘탈 모델로 사용 가능하다.

이슈 트래킹에서 이것은 프로젝트 히스토리가 두 개의 병렬 감사 추적을 가진다는 뜻이다: 코드 변경의 git log와 이슈 변경의 dolt log. "v2.1.0을 태그했을 때 이슈 데이터베이스는 어떤 상태였나?"라는 질문에 Dolt 히스토리의 그 시점을 체크아웃해서 답할 수 있다. 이슈 데이터베이스를 브랜치해서 재구성을 시도하고, 다시 머지하거나 버릴 수 있다.

beads는 v0.9.0에서 SQLite 지원을 폐기하고 Dolt로 전면 전환했다. 버전 관리 시맨틱은 있으면 좋은 기능이 아니라 기반이다. 20개 에이전트가 같은 이슈 데이터베이스에 쓸 때, 소스 컨트롤에 대해 가진 것과 같은 확신으로 그 데이터를 diff, 브랜치, 머지할 수 있는 능력이 필요하다.

선택적 협업은 DoltHub를 통해 동작한다. 이슈 데이터베이스를 리모트에 푸시하고, 팀원의 변경을 풀한다. Git과 같은 푸시/풀 워크플로가 구조화된 데이터에 적용된다.

비주얼 레이어: Beadbox

에이전트는 CLI에서 힘을 발휘한다. 인간은, 적어도 전체 그림이 필요할 때는 그렇지 않다. 의존관계 그래프, 에픽 진행 트리, 블로킹된 이슈 체인: 이것들은 터미널이 잘 렌더링할 수 없는 공간적 문제다.

Beadbox는 Tauri(Electron 아님)로 구축된 네이티브 데스크톱 애플리케이션으로, CLI가 쓰는 것과 같은 .beads/ 디렉토리를 읽는다. 임포트 단계도 동기화 프로세스도 API 레이어도 없다. GUI가 fs.watch()로 파일 시스템을 감시하고, Dolt 데이터베이스 변경을 감지하고, 로컬 WebSocket을 통해 업데이트를 브로드캐스트한다. 에이전트가 bd update BEAD-42 --status in_progress를 실행하면, Beadbox의 상태 배지가 밀리초 이내에 바뀐다.

실제 워크플로는 이렇다:

# 에이전트가 이슈를 생성
bd create --title "Migrate auth to OIDC" --type task --priority 1

# 다른 에이전트가 담당
bd update BEAD-42 --claim --actor agent-3

# 인간이 Beadbox를 열어 전체 보드를 본다:
# 의존관계 그래프, 에픽 트리, 상태/우선순위/담당자로 필터
# 명령 불필요. 보기만 하면 된다.

# 에이전트가 완료하고 리뷰 대기로 표시
bd update BEAD-42 --status ready_for_qa

# Beadbox가 실시간 업데이트. QA 에이전트가 픽업.

에이전트는 CLI로 쓴다. 인간은 GUI로 읽는다. 둘 다 같은 로컬 Dolt 데이터베이스에서 작업한다. 조정 없음, 오래된 캐시 없음, "새로고침할게" 없음.

Beadbox는 macOS, Linux, Windows에서 동작한다. 여러 워크스페이스를 지원하여 재시작 없이 프로젝트를 전환할 수 있다.

"로컬 퍼스트"의 진짜 의미

이 용어는 남용되고 있다. beads와 Beadbox에서 구체적으로 무엇을 의미하는가:

계정 불필요. 아무것에도 가입하지 않는다. CLI를 설치하고, 앱을 설치하고, 디렉토리를 지정한다. 끝.

클라우드 의존 없음. 모든 것이 파일 시스템에서 동작한다. 명시적으로 리모트에 dolt push하지 않는 한 데이터가 머신을 떠나지 않는다. 인터넷이 끊겨도 아무것도 변하지 않는다. 작업을 계속할 뿐이다.

서버 불필요. 관리할 데몬도 Docker 컨테이너도 없다. Dolt 데이터베이스는 파일의 디렉토리다. CLI가 그 파일을 읽고 쓴다. Beadbox가 그 파일을 감시한다.

선택적 협업. 공유하고 싶을 때 DoltHub에 푸시한다. 팀원이 풀한다. 이슈 데이터의 머지 충돌은 코드와 같은 방식으로 해결된다. 하지만 이것은 옵트인이며 필수가 아니다.

대안과 비교한다. Jira에는 서버(또는 Atlassian Cloud)가 필요하다. Linear에는 계정과 인터넷 연결이 필요하다. GitHub Issues에는 GitHub 서버의 리포지토리가 필요하다. Gitea 같은 셀프 호스트 옵션도 웹 서비스 실행이 필요하다.

beads에는 디렉토리가 필요하다. Beadbox에는 그 디렉토리와 더블 클릭이 필요하다.

대상 사용자

공유 작업 큐를 통해 조율하는 AI 에이전트를 실행하고, 인간이 그 작업을 시각적으로 모니터링하고 방향을 조정하고 싶다면, 이 스택은 그 워크플로를 위해 구축되었다.

솔로로 프로젝트를 관리하고 클라우드 계정 없이 코드 옆에 사는 버전 관리된 이슈 트래킹이 필요하다면, 이 스택은 그것도 가능하다.

Jira의 엔터프라이즈 권한 모델이나 분산 팀 전체에서의 Linear의 협업적 실시간 편집이 필요하다면, 이것은 적합한 도구가 아니다. beads는 설계상 로컬 퍼스트다. 그것은 트레이드오프이지 실수가 아니다.

시작하기

beads CLI를 github.com/steveyegge/beads에서 설치하고, Beadbox를 설치:

brew tap beadbox/cask && brew install --cask beadbox

아무 프로젝트에서 beads 데이터베이스를 초기화:

cd your-project
bd init

Beadbox를 열고 디렉토리를 지정하면 이슈 보드가 보인다. 가입 없음. 설정 마법사 없음. "GitHub 계정 연결" 모달 없음.

Beadbox는 베타 기간 동안 무료.