bri — agents-bridge CLI

내 PC의 codex / claude(내 구독)를 웹앱에 연결한다. Agent는 내 PC에서 실행되고 웹은 그것을 조종한다. Agent에게 PC의 셸·파일 권한은 주지 않는다 — Agent가 쓸 수 있는 것은 웹앱이 정의한 도구뿐이다.

켜 둘 것

자동 연결(bri service install)을 켰다면 평소에는 PC 전원만 켜 두면 된다. Agent가 답하는 동안에는 그 브라우저 탭을 열어 둔다.

| 쪽 | 무엇 | 상태 | |---|---|---| | PC | PC 자체 | 켜져 있어야 하고 절전이면 안 된다 (절전이면 웹에서 offline) | | PC | bri | 자동 연결을 켰으면 할 일 없음. 아니면 터미널의 bri connect를 켜 둔다 (창을 닫거나 Ctrl+C면 offline) | | PC | 네트워크 | 밖으로 연결만 되면 된다. 포트를 열 필요 없음 | | PC | codex / claude | 따로 켜 둘 필요 없음. 설치·로그인만 해 두면 대화가 올 때 bri가 띄운다 | | 웹 | 턴을 시작한 브라우저 탭 | Agent가 답하는 동안 열어 둔다. 노트 같은 도구가 이 탭에서 실행된다 | | 웹 | 승인 | 다른 기기·탭(폰 포함)에서 해도 된다 |

• 대화는 시작한 기기에 고정된다(Agent 세션이 그 기기에 있다).

처음 한 번

| 순서 | 할 일 | 확인 | |---|---|---| | 1 | Node.js 20 이상 설치 | node --version | | 2 | Agent CLI 설치·로그인 (하나 이상) | codex login status / claude auth status | | 3 | Windows는 PowerShell, macOS·Linux는 터미널에서 npx @csm-kr/agents-bridge connect --app <앱 주소>(웹 /connect의 명령을 복사) → 터미널의 코드를 웹 /connect에서 확인 → [연결]. 로그인이 안 됐으면 여기서 안내한다 | 터미널에 "연결됨: <기기 이름>" | | 4 | 이어서 나오는 "PC를 켤 때 자동 연결할까요?"에 Y (npx로 실행했으면 bri를 전역 설치한 뒤 등록) | 터미널을 닫아도, 재부팅 후에도 웹에서 online | | 5 | (선택) bri doctor | Agent 인사 + 도구 1회 + 로컬 파일 접근 불가 |

자동 연결을 켜지 않았다면 쓸 때마다 npx @csm-kr/agents-bridge connect(전역 설치했다면 bri connect)를 실행해 둔다. 마지막으로 연결한 앱에 코드 없이 바로 연결된다.

설치

• 설치 없이: npx @csm-kr/agents-bridge connect (항상 같은 명령). 자동 연결 등록은 npx 캐시를 가리킬 수 없어 전역 설치가 필요하다
• 전역 설치: npm i -g @csm-kr/agents-bridge → bri connect. 등록은 npm prefix -g의 전역 설치 경로 기준이라 PATH에 전역 bin이 없어도 된다

자동 연결 — bri service install

• PC를 켤 때마다 자동으로 연결한다 (Linux systemd 사용자 서비스, macOS launchd, Windows 작업 스케줄러 — 로그온 시 창 없이 실행, 관리자 권한 불필요). 전역 설치한 bri로 등록한다(npx로 실행한 bri는 거부).
• 서비스는 브라우저를 열거나 질문하지 않는다. 처음 페어링과 Agent 로그인은 bri connect로 먼저 끝낸다.
• 기기가 해제됐거나 페어링 정보가 없으면 서비스는 다시 시작하지 않고 멈춘다(로그에 이유). bri connect로 다시 페어링한 뒤 bri service install.
• 절전·네트워크가 끊겼다 돌아오면 자동으로 다시 연결된다.
• Windows: 작업 스케줄러의 agents-bridge 작업으로 보인다. 로그온할 때 시작하고 창은 뜨지 않는다(conhost --headless). 로그는 %USERPROFILE%\.agents-bridge\logs\bridge.log.

여러 웹앱

• 같은 bri 하나로 여러 웹앱에 연결한다: 새 앱은 bri connect --app https://다른앱.example.com으로 한 번 페어링한다.
• bri connect --all: 페어링해 둔 모든 앱에 한 프로세스로 동시에 연결한다. 출력 줄 앞에 [앱 이름]이 붙는다. 페어링은 시작하지 않는다. 시작할 때 한 앱에 닿지 못하면(네트워크 오류) 그 앱만 1초에서 두 배씩(최대 30초) 기다려 다시 시도하고, 해제된 기기인 앱은 안내만 하고 건너뛴다.
• 한 앱의 기기가 해제돼도 다른 앱은 계속 연결된다. 모든 앱이 해제되면 종료한다.
• bri service install(--app 없이)은 connect --service --all로 등록한다. 나중에 페어링한 앱도 서비스를 다시 시작하면(bri service install) 함께 연결된다.

명령어

| 명령 | 하는 일 | |---|---| | bri connect [--app <URL>] | 페어링(처음) 또는 연결(이후). 실행 중인 동안 연결 유지 | | bri connect --all | 페어링된 모든 앱에 동시에 연결 (--app·--token과 함께 쓸 수 없음) | | bri connect --app <URL> --token - | 웹의 "명령어 한 줄" 토큰을 가려진 입력으로 받는다. 명령행 토큰은 같은 PC 다른 사용자에게 ps로 보일 수 있으니 공유 PC에서 쓴다 | | bri service install [--app <URL>] / uninstall | 자동 연결 등록 / 해제. --app이 없으면 모든 앱(--all) | | bri apps | 연결된 웹앱 목록 | | bri status | 앱별 페어링 여부, 자동 연결(서비스) 상태, Agent 설치·로그인 상태. 네트워크 없이 바로 끝난다 | | bri doctor | 실제 Agent로 스모크 테스트: 인사(첫 응답 시간), 앱 도구 호출, 샌드박스 밖 파일 읽기·@경로 차단. 웹·Supabase에는 접속하지 않고 구독 사용량을 조금(4턴) 쓴다. 모두 통과하면 종료 코드 0 (Codex는 아직 지원하지 않아 건너뜀) | | bri logout [--app <URL>] | 이 PC의 device secret 삭제(앱 지정 시 그 앱만). 웹의 기기 목록에서도 해제 권장 | | bri --version | 버전 |

• 업데이트: npm install -g @csm-kr/agents-bridge@latest
• 모델·effort: bri(0.2.0 이상)가 이 PC의 Claude 구독에서 쓸 수 있는 모델 목록을 웹에 알린다. 웹 왼쪽 아래 Claude 칩을 눌러 모델·effort를 고르면 다음 메시지부터 적용된다(기본값은 마지막 선택, 처음엔 CLI 기본값)
• 사용량: bri(0.3.0 이상)가 턴 중 받은 Claude 구독 한도(5시간·7일 사용률, 초기화 시각)를 웹에 알린다. 웹의 Claude 칩을 누르면 아래 "사용량"에 보이고, 한도에 가까우면 칩에 "한도 임박"
• 설정·샌드박스·로그: ~/.agents-bridge/ (config.json 권한 0600, 로그는 logs/)

문제 해결

| 증상 | 해결 | |---|---| | 웹에서 기기가 계속 offline | bri status로 자동 연결(서비스) 상태 확인, bri connect 실행 | | 칩이 회색 ("로그인 필요") | 해당 CLI로 로그인. 60초 안에 칩이 바뀐다 | | 칩이 회색 ("미설치") | CLI 설치 후 bri connect 재실행 | | "이 PC는 연결이 해제됐어요" | bri logout 후 bri connect로 다시 페어링 | | 코드가 만료됨 | bri connect를 다시 실행 | | 브라우저가 안 열림 (서버·SSH) | 터미널에 출력된 주소를 다른 기기 브라우저에서 연다 | | 재부팅 후 offline | bri service install | | Windows: PowerShell에서 "이 시스템에서 스크립트를 실행할 수 없으므로…"(npx.ps1) | 실행 정책 때문. npx.cmd @csm-kr/agents-bridge connect --app <URL>로 실행하거나, Set-ExecutionPolicy -Scope CurrentUser RemoteSigned 후 다시 실행 | | 한 메시지에 답이 두 개씩 달림 | 같은 PC에서 bri가 두 개 실행 중(예전 창·자동 연결 서비스). 하나만 남기고 끈다. 0.3.1부터는 두 번째 bri가 "이미 실행 중이에요"로 거부한다 | | 웹의 모델 선택에 "PC 기본값"만 나옴 | bri 창의 "모델 목록을 받지 못했어요: <이유>" 줄을 확인한다. 60초 간격으로 3번까지 다시 시도하고, 그래도 안 되면 bri를 다시 켠다. bri 0.2.2 이상 | | 웹 칩의 사용량이 안 보임 ("대화를 한 번 하면 / 사용량이 보여요.") | bri는 턴에서 받은 값만 알아 켠 직후에는 없다. 그 PC로 대화를 한 번 하면 보인다. 그래도 없으면 bri --version이 0.3.0 이상인지 확인 | | Windows: npx·node를 찾을 수 없음 | Node.js 20 이상을 설치하고 PowerShell 창을 새로 연다(PATH 반영). where.exe npx로 확인 | | Windows: 설치·로그인했는데 칩이 "미설치" | bri는 PATH에서 claude·codex(.exe·.cmd)를 찾는다. 새 PowerShell에서 where.exe claude가 경로를 보여야 한다. npm 전역 폴더(npm prefix -g)가 PATH에 있는지 확인 후 bri connect 재실행 |

개발 중 실행

npm 배포 전에는 저장소 루트에서 pnpm bri <명령>으로 실행한다.