BearDrive — AI 에이전트를 위한 Google Drive
Star on GitHub
Go Reference
Website
Docs
beardrive.ai · Docs · Managed cloud: 회원가입 시 무료 개인 작업 공간 제공
BearDrive는 모든 폴더를 동기화된 볼륨으로 마운트합니다. 그 내용은 BearDrive **허브(hub)**를 통해 사용자의 모든 기기와 팀원들 사이에서 동기화되며, 모든 변경 사항은 추적됩니다 (누가, 언제, 어떤 장치에서). 그리고 모든 것이 오프라인에서도 계속 작동합니다. CLI는 bdrive이며, 허브(hub)는 사용자가 (또는 우리가) 객체 스토어에 배포하는 bdrive serve 서버입니다. 클라이언트는 이를 통해 HTTPS로 동기화하며 저장소에 직접 접근하지 않습니다.
가장 중요한 용도는 AI 에이전트 간의 컨텍스트 공유입니다. 팀의 모든 에이전트에게 동일한 폴더를 메모리처럼 제공하여, 사용자의 에이전트가 다른 에이전트가 아는 것을 알게 합니다. (사람도 커버됩니다: 동기화된 모든 파일은 페이지로 렌더링되는 공개 URL이 됩니다.) 노트, 계획, 발견 사항, 그리고 아티팩트는 팀을 따라 어디든 이동하며 — 메모리 API와 달리, 이들은 출처(provenance)가 있는 실제 파일로 유지됩니다. 모든 변경 사항은 이를 만든 사람, 에이전트, 장치에 귀속되며, 허브의 대시보드(Dashboard)는 사용자의 에이전트가 실제로 무엇을 읽었는지 (그리고 아무도 관리하지 않는 '핫하지만 오래된' 문서가 무엇인지) 보여줍니다.
<p align="center">
<img src="https://raw.githubusercontent.com/runbear-io/beardrive/HEAD/docs/assets/insights.png" alt="지식 통찰력 — 에이전트/사용자 읽기 대비 오래된 정도에 따라 모든 파일 플롯; 핫하지만 오래된 문서는 위험 구역입니다." width="820">
</p>
| 읽기 열(read heat)로 탐색 | 공개 공유 페이지 |
|---|
| Folder listing with per-file agent read counts and change feed | A shared markdown file rendered as a public page |
$ bdrive login https://your-hub
$ cd ~/workspace && bdrive init
initialized /Users/snow/workspace
...
BearDrive Cloud — 제로 설정(zero-setup), 단순한 bdrive login만으로 가입 시 개인 작업 공간을 무료로 제공받을 수 있습니다. (beardrive.ai). 또는 자체 허브를 호스팅할 수도 있습니다.
다른 기기에서:
$ bdrive login https://your-hub && cd ~/workspace && bdrive init
# … 동일한 프로젝트에 연결하면 파일이 나타나고 동기화 상태를 유지합니다
작동 방식 (What this looks like)
팀원 Dana가 어제 오후 동안 자신의 에이전트와 함께 EU 카드 결제 실패 원인을 파악했고, 에이전트는 그 내용을 문서로 작성했습니다. 오늘 당신은 관련 버그를 발견합니다. 공유 폴더가 만들어내는 차이를 여기서 확인해 보세요.
공유 폴더가 없을 경우, 당신의 에이전트는 아무것도 없는 상태에서 시작합니다:
당신: EU 결제는 왜 실패하나요?
에이전트: 조사해 보겠습니다 — 결제 흐름을 검색 중입니다...
몇 분과 수천 개의 토큰(tokens) 시간이 지난 후에야 Dana의 에이전트가 이미 알고 있던 사실을 재발견합니다. 혹은 다른 결론에 도달하여 그녀의 내용과 조용히 모순되는 두 번째 문서를 작성하기도 합니다.
BearDrive를 사용할 경우, 에이전트가 파일을 읽기 전에 폴더는 이미 최신 상태입니다 — 엔터를 누르는 순간 풀 훅(pull hook)이 실행됩니다:
당신: EU 결제는 왜 실패하나요?
에이전트: shared/findings/eu-checkout.md 🔗에서 이 내용을 다루고 있습니다. Dana의 에이전트는 Safari에서 3-D Secure 리디렉션이 세션 쿠키(session cookie)를 떨어뜨리는 것으로 원인을 추적했으며, 제안된 수정 사항은 아직 적용되지 않았습니다. 제가 적용해 드릴까요?
당신의 에이전트가 자체 발견 내용을 문서로 작성하면, 푸시 훅(push hook)이 몇 초 후에 해당 내용을 허브에 올리고, Dana의 다음 세션은 당신의 작업 내용부터 시작됩니다. 양방향으로 모두 가능하며, 아무도 데이터를 내보내거나 복사/붙여넣기 할 필요가 없습니다.
이것들이 실제 파일이기 때문에, 같은 폴더는 웹사이트 역할도 수행합니다: 어떤 파일이든 페이지로 렌더링되는 공개 링크가 될 수 있으며, 히스토리 보기(History view)에서는 누가 어떤 장치에서 무엇을 변경했는지 보여주고, 대시보드(Dashboard)에서는 에이전트들이 실제로 읽은 문서와 아무도 관리하지 않는 '핫'한 문서를 알려줍니다.
기능 (Features)
- 모든 폴더가 프로젝트입니다(Any folder is a project) —
bdrive init은 모든 폴더를 동기화된 프로젝트로 만듭니다. 파일은 디스크의 실제 파일: 모든 도구, 에디터 및 에이전트가 통합 작업 없이 사용할 수 있습니다. 폴더는 자유롭게 이름 변경하거나 이동할 수 있으며, 상태는 경로가 아닌 안정적인 ID로 키 지정됩니다.
- 다중 장치 동기화(Multi-device sync) — 장치들은 공유 허브를 통해 수렴합니다. 각 장치는 자신만의 추가 전용 저널(append-only journal)만 작성하므로 잠금 서비스가 필요하지 않으며, 이 허브는 모든 오브젝트 스토리지(object store)로 백업될 수 있습니다.
- 변경 추적(Change tracking) —
bdrive log와 웹 UI의 기록(History) 보기에서는 어떤 계정이 언제, 어느 장치(이름, OS)에서 어떤 파일을 변경했는지 보여줍니다. 콘텐츠는 내용 주소 지정 방식(content-addressed)으로 저장되므로 모든 버전이 보존됩니다 — 파일 기록의 아무 시점이나 보고 다운로드할 수 있습니다. 피드는 경로, 작성자 및 날짜 범위로 좁힐 수 있으며, 이 좁혀진 보기에는 자체 URL이 있습니다.
- 클라우드 공급자 독립적(Cloud-provider agnostic) — 허브는 Amazon S3 (
s3://), Google Cloud Storage (gs://), 모든 S3 호환 스토리지(MinIO, Cloudflare R2를 AWS_ENDPOINT_URL을 통해 사용), 또는 일반 공유 디렉토리 (file://, 예: NAS)에 저장할 수 있습니다. 클라이언트는 이를 볼 수 없습니다.
- 오프라인 우선(Offline-first) — 작업 폴더는 네트워크가 없어도 항상 완전히 사용할 수 있습니다. 변경 사항은 로컬에 저널링(journaled)되고 원격 연결이 다시 가능해지면 푸시됩니다.
- 실시간(Live) — 허브를 통해 동료의 변경 사항이 다음 폴링(poll) 주기가 아닌 약 1초 만에 도착하며, 웹 UI에서 열린 파일은 제자리에서 업데이트됩니다. 상단 바에는 프로젝트에 누가 참여하고 있는지 표시되며, 같은 파일을 작업 중인 사람에게는 원형으로 표시됩니다. 둘 다 하나의 변경 스트림(change stream)을 사용합니다. 이를 제공할 수 없는 허브(오래된 버전, 버퍼링 프록시 등)는 폴링으로 되돌아가고 다른 것은 아무것도 변경되지 않습니다.
- 충돌 안전성(Conflict-safe) — 동시 편집은 결정론적으로 해결됩니다(마지막 작성자가 승리, last-writer-wins). 그리고 패배한 버전은
name.bdrive-conflict-<device>-<time> 파일로 보존됩니다. 아무것도 조용히 삭제되지 않습니다.
폴더 연결은 동시 편집(concurrent edit)이 아닙니다. 첫 번째 동기화 시, 프로젝트가 이미 가지고 있는 파일들(예: .bdriveignore, AGENTS.md, 체크아웃으로 가져온 모든 파일)은 프로젝트의 버전을 유지하며 충돌 복사본을 생성하지 않습니다. 사용자의 사본은 대체된 버전(superseded version)으로 기록되므로, 여전히 bdrive restore --list <path>를 통해 접근할 수 있습니다.
- 에이전트의 스킬도 동기화됩니다 —
.claude/skills, .claude/commands, .claude/agents, AGENTS.md, 그리고 CLAUDE.md는 프로젝트 내 일반 파일입니다. 따라서 한 사람이 작성한 스킬은 팀원 모두의 디스크에 존재하며, 에이전트가 다음 차례를 수행하기 전에 동기화됩니다. 개별 클라이언트마다 익스포트(export)나 레지스트리(registry), MCP 서버가 필요하지 않습니다. 에이전트 훅(hook) 설정은 절대 동기화되지 않습니다. 제품은 에이전트가 읽는 것을 공유하는 것이며, 에이전트가 실행하는 것은 그렇지 않습니다. 프로젝트의 구조를 잡으려면 skills 템플릿을 사용하여 프로젝트를 시작하세요 (bdrive init --template skills).
- 선택적 동기화(Selective sync) — gitignore 스타일의
.bdriveignore는 파일을 제외하며, bdrive init . --only wiki,docs (또는 대화형 프롬프트)는 동일한 규칙을 작성하여 마운트 지점을 일부 하위 폴더로 좁혀줍니다.
- macOS 및 Linux.
설치(Install)
BearDrive는 이를 사용할 에이전트에 의해 설정되어야 합니다. 가장 빠른 경로는 에이전트가 이 작업을 수행하도록 하는 것이며, 아래의 CLI 경로는 수동으로 진행하더라도 같은 목적지에 도달합니다.
에이전트가 설정하도록 하기 (권장)
터미널이 필요하지 않습니다. 동기화하려는 폴더에서 아무 에이전트(Claude Code, Codex, Gemini CLI, Hermes)를 시작하고 다음 붙여넣기를 제공하세요:
Follow beardrive.ai/setup to set up BearDrive. Ask me which folder to sync.
두 번째 문장은 그대로 유지해야 합니다. 이 문장이 없으면 에이전트는 첫 번째 문장을 자신에게 결정할 권한으로 해석하며, 일반적인 추측은 이 전체 폴더가 됩니다. 이는 매뉴얼(runbook)에서 절대 추천하지 않는 답변입니다. 두 번째 문장이 있으면, 처음부터 shared/와 같은 명명된 추천을 받아들이거나 재정의할 수 있거나, 이미 발견한 노트 폴더를 받을 수 있습니다.
자가 호스팅을 하시나요? 어디에 설정할지 지정하세요: … to set up BearDrive on https://hub.example.com.
팀원의 프로젝트에 참여하는 경우? 대신 웹 UI에서 해당 프로젝트의 홈 페이지에 붙여넣기를 사용하세요. 이 방법은 허브 URL과 프로젝트 ID를 포함하고 있어 에이전트가 옆에 두 번째 프로젝트를 생성하는 대신 기존 프로젝트에 참여하게 합니다.
beardrive.ai/setup은 INSTALL_FOR_AGENTS.md로 리디렉션하며, 에이전트는 이를 가져와 따릅니다: CLI(Command Line Interface)를 설치한 다음 bdrive init을 실행합니다. 이 명령어는 (로컬 브라우저가 없을 경우 승인 링크를 통해) 로그인하고, 동기화 훅(sync hooks)을 등록하며, 프로젝트 링크를 출력합니다. 지침은 프롬프트 안에 있는 것이 아니라 해당 URL에 존재하므로 누군가의 복사본에서 오래되지 않습니다. 또한 에이전트는 모든 예외 상황(이미 설치됨, Homebrew 없음, 로그인 필요, 잘못된 폴더 등)을 처리합니다.
이 훅들이 전체 통합 기능을 담당하며, bdrive init은 각 플랫폼의 사용자 설정 파일(~/.claude/settings.json 등)에 기기당 한 번만 등록합니다. 따라서 모든 폴더의 모든 세션이 커버됩니다:
- 메시지를 보낼 때 **블로킹 풀(blocking pull)**을 수행하여 에이전트가 항상 최신 팀 파일을 읽도록 합니다. 또한 프로젝트의 링크 규칙을 주입하므로, 에이전트가 언급하는 모든 동기화된 경로에 허브 링크를 추가합니다;
- 파일 편집 후마다 **비동기 푸시(async push)**를 수행하여 에이전트가 파일을 작성한 직후 아티팩트(artifacts)가 허브에 올라오게 합니다;
- **읽기 추적(read tracking)**을 통해 허브의 대시보드(Dashboard)에서 에이전트가 실제로 무엇을 읽었는지 보여줄 수 있습니다.
각 훅은 BearDrive 프로젝트 외부에서는 즉시 아무 작업도 수행하지 않으므로(no-ops), 기기 전체에 걸친 등록이 안전합니다. bdrive hooks를 실행하면 이 기기에 설정된 내용을 출력하며, CLI 업그레이드 후에는 다시 실행해야 합니다.
CLI 직접 설치하기
brew install runbear-io/tap/beardrive
또는 소스에서:
go install github.com/runbear-io/beardrive/cmd/bdrive@latest
빠른 시작
프로젝트 폴더를 이름 변경하거나 이동해도 안전합니다: 상태는 경로가 아닌 안정적인 ID(stable IDs)로 키됩니다. 볼륨 워커(volume worker)는 누락된 폴더를 감지하고 생존하는 형제 작업 트리(sibling worktree)의 작업을 계속 진행하거나, 삭제 전파 없이 중단됩니다. 새 위치에서 bdrive init을 실행하면 프로젝트가 재개됩니다.
백그라운드 동기화 (Background sync)
기기/사용자 세션당 하나의 백그라운드 감독 프로세스(supervisor process)가 실행됩니다: bdrive daemon run. 이 프로세스는 ~/.bdrive/daemon.lock을 보유하며, 그 옆에 daemon.pid와 daemon.log를 작성합니다. 활성 프로젝트 볼륨 각각은 자체적인 daemon.lock, daemon.pid, 그리고 daemon.log가 ~/.bdrive/volumes/<volume-id>/ 아래에 있는 워커 고루틴(worker goroutine) 하나를 가집니다. 이 듀얼 락(Dual-Lock) 방식은 볼륨당 감독관 하나와 워커 하나를 유지합니다. $BDRIVE_HOME 변수는 두 세트의 파일을 모두 재배치합니다.
bdrive stop은 선택된 마운트를 일시 중지합니다. 해당 볼륨에 활성 작업 트리(worktree)가 남아있지 않으면, 워커는 다른 프로젝트를 방해하지 않고 해당 볼륨의 잠금(lock)을 해제합니다. 더 이상 활성 볼륨이 없으면 감독관은 깔끔하게 종료됩니다. bdrive stop --all은 이 장치에 등록된 모든 프로젝트를 일시 중지합니다. bdrive init, bdrive resume, bdrive sync, bdrive status <folder>, 그리고 에이전트 동기화 후크(agent sync hooks)는 일시 중지되지 않은 프로젝트의 경우 이를 시작하거나 깨웁니다. 바이너리 업그레이드 후, 이러한 진입점(entry points)들은 이전 감독관을 현재 바이너리로 자동으로 대체합니다.
자격 증명 (Credentials)
beardrive는 각 제공업체의 표준 자격 증명 체인(credential chain)을 사용하며, beardrive 고유의 방식은 없습니다. 참고: 클라이언트 장치는 항상 https:// 허브 원격지(hub remote)를 사용합니다. 아래의 s3/gs/file 행들은 동기화 클라이언트가 직접 가리키는 것이 아니라 허브 운영자가 허브 자체의 스토리지(storage)를 구성하는 방식입니다:
| 원격지 (Remote) | 자격 증명 (Credentials) |
|---|
s3://bucket/prefix | AWS_PROFILE, ~/.aws/credentials, 환경 변수(env vars), IAM 역할. S3 호환 스토리지(S3-compatible stores)는 AWS_ENDPOINT_URL을 통해 사용합니다. |
| ... | |
명령어 (Commands)
| 명령어 | 설명 |
|---|
bdrive login [server-url] | 이 장치를 로그인합니다 (브라우저 흐름 — 페이지가 터미널이 작동할 계정을 지정하고 승인 전에 전환할 수 있게 해줍니다; --device는 승인 링크 흐름을 강제하며, TTY가 없는 셸은 자동으로 여기에 폴백(fallback)됩니다; 기본 서버는 beardrive.ai입니다 — 가입 시 제공되는 관리형 클라우드, 무료 개인 작업 공간입니다; 자체 호스팅을 위해 허브 URL을 전달하세요). 다른 허브로 전환하려면 bdrive login <new-url>를 사용합니다. |
| ... | |
프로젝트 파일(Project files)
각 마운트된 폴더는 자체 설정을 가지고 있으므로, 구성(configuration)은 프로젝트와 함께 이동합니다:
