15개의 서브태스크로 에픽을 만든다. 여러 에이전트나 팀원에게 할당한다. 이틀 후 누군가 묻는다: "인증 리라이트 얼마나 진행됐어?"

bd show bb-r4f를 실행한다. 에픽 자체의 정보가 나온다. 제목, 설명, 우선순위. 하위 태스크가 몇 개 완료되었는지는 알려주지 않는다. bd list --parent bb-r4f를 실행한다. ID와 제목의 플랫 리스트가 나온다. 각각의 상태를 보려면 jq로 파이프하거나 하위 태스크마다 bd show를 개별 실행해야 한다. 그 하위 태스크 중 일부는 자체 서브태스크를 갖고 있다. 이제 3단계 깊이에서, 터미널 출력으로부터 머릿속에서 트리를 재구성하고 있다.

에픽의 하위 태스크가 3개일 때는 괜찮다. 10개에서 무너진다. AI 에이전트가 서브태스크를 생성하고, 블로커를 등록하고, 이슈를 빠르게 클로즈하는 상황이라면, CLI 출력은 명령을 실행한 시점과 읽기를 마치는 시점 사이에 이미 낡아버린다.

문제는 beads에 있지 않다. beads CLI는 구조화되고 스크립팅 가능한 이슈 관리에 탁월하다. 문제는 계층적 진행 상황이 비주얼한 개념이라는 것이고, 터미널은 텍스트를 행 단위로 렌더링한다는 것이다.

Beadbox에서 에픽 트리가 보이는 방식

Beadbox를 열고 에픽을 클릭하면, 접을 수 있는 트리에 하위 태스크가 표시된다. 각 하위 태스크에는 상태 배지(open, in_progress, ready_for_qa, closed), 우선순위 표시, 담당자가 보인다. 에픽 자체에는 프로그레스 바가 표시된다: "14개 중 9개 완료 (64%)." 하위 태스크가 클로즈될 때마다 이 숫자가 업데이트된다.

하위 태스크 자체가 에픽인 경우 펼칠 수 있고, 그 서브태스크가 아래에 중첩된다. 상위의 진행률은 직접 하위뿐 아니라 모든 자손에서 집계된다. 엔지니어링, QA, 문서에 걸쳐 총 40개 이슈가 있는 3단계 에픽은 트리의 모든 리프 노드를 고려한 실제 완료율을 최상위에 표시한다.

블로킹된 이슈에는 시각적 구분이 있다. bb-m3q가 bb-k7p에 의존하고 bb-k7p가 아직 오픈 상태라면, bb-m3q의 상태 옆에 블로킹 배지가 나타난다. 병목을 발견하기 위해 bd dep list를 실행할 필요가 없다. 트리 안에서, 중요한 레벨에서 바로 보인다.

CLI 워크플로와 비교해 보자. "인증 에픽의 진행을 막고 있는 것이 무엇인가"에 답하려면:

bd list --parent bb-r4f --status=open --json | \
  jq -r '.[].id' | \
  xargs -I{} bd show {} --json 2>/dev/null | \
  jq -r 'select(.blocked_by | length > 0) | "\(.id) blocked by \(.blocked_by | join(", "))"'

완벽하게 유효한 파이프라인이다. 정확한 답을 반환한다. 하지만 직접 작성해야 하고, 플래그를 기억해야 하고, 업데이트가 필요할 때마다 다시 실행해야 한다. Beadbox에서는 같은 정보가 항상 트리에 표시된다. 쿼리가 필요 없다.

실시간 업데이트: 보고 있는 동안 트리가 변한다

여기서 비주얼 모델이 진가를 발휘한다. 에이전트가 터미널에서 bd update bb-k7p --status=closed를 실행하면, Beadbox가 밀리초 이내에 파일 시스템 변경을 감지한다. WebSocket 서버가 .beads/ 디렉토리에 대한 쓰기를 감지하고, 변경을 브로드캐스트하며, React UI가 다시 렌더링된다.

에픽 트리에서는 이렇게 보인다: bb-k7p가 주황색 "in_progress" 배지에서 녹색 "closed" 배지로 바뀐다. 상위 에픽의 프로그레스 바가 64%에서 71%로 올라간다. 그리고 bb-k7p에 블로킹되어 있던 bb-m3q의 블로킹 표시가 사라지며 가용 작업으로 표시된다.

이 모든 것이 명령을 실행하거나 새로고침 버튼을 클릭하지 않아도 일어난다. 릴리스 에픽을 작업하는 에이전트 플릿을 감독하고 있다면, 태스크가 완료됨에 따라 트리가 채워지는 것을 지켜볼 수 있다. 병목은 블로킹 배지가 실시간으로 나타나기 때문에 형성되는 순간 드러난다. 정체된 서브트리(다른 곳의 꾸준한 진행과 대비되어 몇 분간 상태가 변하지 않는 이슈 클러스터)는 시각적으로 분명해진다.

기반 메커니즘은 단순하다. Beadbox는 .beads/ 디렉토리에 fs.watch()를 호출하는 WebSocket 서버를 실행한다. 모든 데이터베이스 쓰기가 브로드캐스트를 트리거한다. 클라이언트 사이드 훅이 신호를 받아 관련 서버 액션을 다시 페치한다. 폴링 간격 없음, 수동 새로고침 없음. CLI 명령에서 UI 업데이트까지의 레이턴시는 보통 1초 미만이다.

키보드 중심 내비게이션

Beadbox는 개발자를 위한 데스크톱 앱이며, 그에 맞게 동작한다. j와 k로 이슈 목록을 이동한다(vim 스타일). Enter로 선택한 이슈를 디테일 패널에 연다. /로 검색 바에 포커스한다. Escape로 열린 것을 닫는다. 화살표 키로 에픽 트리 노드를 펼치고 접는다.

마우스에 손대지 않고 전체 백로그를 트리아지할 수 있다. j로 목록을 내려가며, 이슈를 열어 설명을 읽고, Escape로 닫고, 다음으로 이동한다. 상태 변경이 필요한 것을 발견하면, 뮤테이션은 터미널에서 한다(bd update). Beadbox는 설계상 읽기 중심 인터페이스다. CLI가 쓰기를 담당하고, GUI가 이해를 담당한다.

이 분리는 의도적이다. CLI를 대체하여 쓰기까지 처리하려는 GUI는 가능한 모든 플래그 조합에 대해 폼을 만들게 된다. 읽기와 내비게이션에 특화된 GUI는 터미널이 가장 못하는 것, 즉 계층적이고 상호 참조되는 데이터를 한눈에 보여주는 것에 최적화할 수 있다.

여러 프로젝트, 하나의 창

여러 코드베이스에서 작업하며 각각이 고유한 .beads/ 데이터베이스를 갖고 있다면, Beadbox의 워크스페이스 스위처가 처리한다. 헤더의 드롭다운에 감지된 모든 워크스페이스가 나열된다. 하나를 클릭하면(또는 / 검색으로 워크스페이스를 찾으면) 해당 프로젝트의 데이터베이스에서 전체 뷰가 다시 로드된다. 필터와 스크롤 위치가 워크스페이스별로 유지되므로, 다시 전환해도 위치를 잃지 않는다.

감지는 자동이다. Beadbox는 bd 설정의 등록된 워크스페이스와 .beads/ 데이터베이스를 포함하는 디렉토리를 스캔한다. 새 프로젝트를 추가하고 beads를 초기화하면, 다음에 Beadbox를 열 때 드롭다운에 나타난다. 임포트 없음, 설정 화면 없음.

여러 서비스를 관리하는 개발자나 각 에이전트가 별도의 리포지토리에서 작업하는 팀에게, Beadbox는 모든 활성 프로젝트에 대한 단일 뷰가 된다. 대안은 각각 다른 --db 경로에 대해 bd list를 실행하는 여러 터미널 창이다.

무엇을 대체하는가

Beadbox는 CLI를 대체하지 않는다. 워크플로를 스크립팅하고, bd list를 jq로 파이프하고, 에이전트가 프로그래밍 방식으로 이슈를 생성하고 클로즈하는 것은 변함없이 동작한다. Beadbox는 스크립트가 기록하는 것과 같은 데이터베이스를 읽는다.

대체하는 것은 플랫 텍스트 출력에서 프로젝트 상태를 재구성하는 정신적 부담이다. Beadbox가 한눈에 답하고, CLI는 조합 쿼리로만 답할 수 있는 질문들:

이 에픽이 실제로 얼마나 진행되었는가?
지금 무엇이 블로킹되어 있고, 무엇에 의해서인가?
몇 시간째 손대지 않은 서브태스크는 어떤 것인가?
에이전트들이 진행하고 있는가, 아니면 멈춰 있는가?

이것들은 비주얼한 질문이다. 비주얼한 답이 필요하다.

시작하기

Beadbox는 베타 기간 동안 무료다. Homebrew로 설치:

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

이미 beads를 사용하고 있다면, Beadbox가 실행 시 .beads/ 워크스페이스를 감지한다. 임포트 없음, 계정 없음. 앱을 열고, 에픽을 펼치고, 프로젝트의 실제 현황을 확인하면 된다.

macOS, Linux, Windows에서 동작한다.