Skip to content
RockheungPublic

About

Multi-session browser automation CLI on raw CDP — agent self-journaling

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

tirno

ci node license

여러 Chrome 을 세션으로 굴리는 CLI. raw CDP 위에 얹혀 있고, 안에 LLM 이 없다 — 보고, 적고, 다시 꺼내 준다. 무엇을 할지는 부르는 쪽이 정한다.

에이전트가 사이트를 돌아다니며 알아낸 것을 적어두고, 다음 시도에 다시 꺼내 쓰자는 게 목표다. 어디까지 왔는지는 아직 구현이 아닌 것에 적어뒀다.

# 받아서 바로 — Node 없이 돈다 (macOS arm64; 다른 타깃은 릴리즈 페이지에)
mkdir -p ~/.local/bin && curl -fsSL https://github.com/Rockheung/tirno/releases/latest/download/tirno-bun-darwin-arm64 -o ~/.local/bin/tirno
chmod +x ~/.local/bin/tirno       # PATH 에 없으면: export PATH="$HOME/.local/bin:$PATH"

tirno new demo https://example.com --headless   # 세션 하나 — 0.6초
tirno snapshot                                  # a11y 트리를 @ref 로
tirno click @7                                  # 셀렉터를 몰라도 누른다
tirno kill demo --clean

필요한 것: Chrome 하나뿐이다. 기본은 Chrome for Testing 이고, tirno setup 이 ~/.tirno/chrome/ 에 받아온다(sudo 불필요). 받아 두지 않았으면 agent-browser 가 받아 둔 빌드, 그다음 설치된 Google Chrome 순으로 쓴다. 어디를 보는지·무엇을 고르는지는 tirno setup --check 가 그대로 보여준다. 이미 있는 것을 쓰려면 tirno chrome set <path> (또는 $TIRNO_CHROME). linux-arm64 에는 Google Chrome 이 아예 없다 — 구글이 amd64 만 배포한다. 그 플랫폼에서는 Playwright 가 빌드한 chromium 을 받아온다. 바이너리에 런타임이 들어 있어 Node 를 안 깔아도 된다.

sudo 를 쓰는 자리가 없다 — 도구도 ~/.local/bin, 브라우저도 ~/.tirno/chrome/ 이다. 시스템 경로에 넣고 싶으면 sudo mv ~/.local/bin/tirno /usr/local/bin/ 로 옮기면 되지만, 그것은 선택이지 전제가 아니다.

바이너리는 넷이다 — darwin-arm64 · darwin-x64 · linux-x64 · linux-arm64. Windows 는 대상이 아니다: 소유권 판정이 lsof 와 ps 를 읽는다. 릴리즈의 SHA256SUMS 로 검증할 수 있다.

소스에서 (고칠 사람)
git clone https://github.com/Rockheung/tirno.git && cd tirno
npm install && npm run build && npm link

Node 22+ 가 필요하다. npm 레지스트리에는 올라가 있지 않다.


Firefox — tirno new x --browser firefox 는 geckodriver 없이 Marionette 와 WebDriver BiDi 를 직접 말한다. 지금은 nav · eval · screenshot · snapshot · click · fill · type · press · wait-for · pages · new-tab · select · close-tab · ls · restart · kill 이 되고, 다른 명령은 capability_unsupported 로 거절한다. snapshot 의 역할과 이름은 페이지 안에서 HTML 암묵 역할과 ARIA 속성으로 계산한다 — 브라우저의 접근성 트리가 아니라 Chrome 과 다르게 나올 수 있다. snapshot 의 옵션, fill --batch, wait-for --network-idle 은 아직 Chrome 전용이다. --port · --extensions · 정책도 아직 쓸 수 없다.

Safari — tirno new x <url> --browser safari 는 Safari Technology Preview 의 safaridriver 를 띄우고 그 WebDriver BiDi 를 직접 말한다. 사용자가 쓰는 Safari 와 따로 떠서, Safari 가 열려 있어도 된다. 되는 명령은 Firefox 와 같다. safaridriver 는 세션을 하나만 열고, headless 모드와 -- 뒤의 브라우저 플래그가 없다. 입력은 classic WebDriver 로 보낸다 — STP 의 BiDi 는 포인터 입력을 받지 않고, 키 입력은 OS 입력기를 타서 한글 입력 소스에서 a 가 ㅁ 이 된다. Web Inspector 프로토콜은 Apple 비공개 권한이 있는 프로그램만 붙을 수 있어 쓰지 않는다. STP 가 없으면 --executable-path /usr/bin/safaridriver(Safari 를 닫아야 한다) 또는 $TIRNO_SAFARI.

왜 다른가

세션이 여럿이고 서로 격리된다 user-data-dir 이 따로라 쿠키·로그인이 섞이지 않는다. 한 번 로그인해두면 그 세션에 계속 붙는다
소유권을 관찰로 판정한다 pid 생존 ∧ 그 pid 가 그 포트를 청취 ∧ --user-data-dir 일치. 셋이 안 맞으면 붙지도 죽이지도 않는다 — 남의 브라우저를 조종하거나 죽이는 사고를 구조적으로 막는다. 못 봤으면 못 봤다고 한다(unknown) — linux 는 /proc 을 직접 읽어 lsof 없이도 본다
셀렉터를 몰라도 조작한다 snapshot 이 a11y 트리에 @1 @2 … 를 붙인다. click @7 · fill @39 "..."
본 것을 적어둔다 snapshot 이 URL × viewport 키로 a11y(role·name)·selector·bbox·화면 지문을 저장한다. 재방문 시 cache load 가 지금 화면과 대보고(낡았으면 STALE), ref 를 되찾아(selector → a11y → bbox) 채워 준다 — 새 세션에서 cache load 뒤 바로 click @7. 못 찾은 것은 UNRESOLVED 로 이름을 댄다
여러 대에 동시에 broadcast … --group <g> — 세션들에 순차가 아니라 동시에 나간다
이야기가 남는다 journal — 명령마다 어떻게 끝났고 무엇이 변했는지 한 줄. --as-recipe 로 레시피 추출. TIRNO_JSON=1 이면 성공도 실패도 {ok, cmd, data|output, delta} 봉투 하나
바이너리에 든 것은 tirno 뿐 받은 파일 하나로 돈다 — Node·npm 설치가 필요 없다. audit(lighthouse)만 tirno plugin install audit 로 따로 붙이고, 그것은 PATH 의 Node 로 돈다
MCP 서버가 내장 tirno mcp — 툴이 tirno schema 에서 자동 생성되어 명령을 추가하면 툴이 생긴다. readOnlyHint 는 effects 에서, destructiveHint 는 destructive 에서. 앵커 우회가 필요 없다
정책은 세션에 선언한다 new --allow bank.com(CLI 사전검사 + 확장의 요청 차단, WebRTC 까지) · --read-only(관측만) · --confirm destructive(delete·pay·삭제·결제… 이름은 --confirm 없이 안 누름). 거부는 code: policy_denied
목적을 말하면 그것만 낸다 snapshot --interactive · forms · links · table · read · explain @7(왜 안 눌리나 — 가림·보임·enabled·필드 상태·캐시 이력 한 화면) · watch(이벤트 NDJSON 스트림)
파일에 선언하고, 실행 전에 판정한다 plan checkout.json 이 지금 페이지·캐시로 단계마다 될지(found · ambiguous · missing · unknown until N)를 말하고, apply 가 친다. apply --group qa 는 세션 × 단계 매트릭스 — broadcast 의 선언형
절차를 기억한다 recipe begin login … recipe end 가 이 세션에서 친 행동 명령을 적고, recipe run login EMAIL=… 이 그대로 다시 친다 — 두 번째 방문부터 판단 없이. @N 은 role+이름으로 바뀌어 적히고, --var 로 준 비밀은 $VAR 로만 남는다. 실패하면 그 단계에서 멈추고 무엇이 달랐는지 말한다
접근성을 검증한다 — 의존 0 a11y 가 10개 규칙(이름·라벨·alt·헤딩·대비·lang·title·tabindex·aria 참조·id 중복)을 a11y 트리와 페이지 안 계산으로 돌리고 위반마다 @N 을 붙인다. --tab-order 는 Tab 을 실제로 눌러 포커스 순서·갇힘·보이지 않는 포커스를 잡는다 — 정적 분석은 못 하는 것. expect a11y clean 이 게이트
실패는 전부 exit 1 — 종류는 code: 거부된 kill, broadcast 의 부분 실패, eval 이 페이지에서 받은 예외까지 $? 는 1 하나. 종류는 stderr 마지막 줄 code: session_not_owned 처럼 붙고, --json/TIRNO_JSON=1 이면 {ok:false, code, message, data} 한 줄이다 — 재시도해도 되는 실패와 안 되는 실패를 문장 파싱 없이 가른다

스킬 — 에이전트에게 시키려면

이 레포는 자기 스킬의 마켓플레이스이기도 하다.

claude plugin marketplace add Rockheung/tirno
claude plugin install tirno@tirno

다섯이 들어온다 — tirno(명령 레퍼런스) · tirno-runbook(작업 절차) · tirno-mcp(chrome-devtools-mcp 대응) · tirno-sw-override(배포 전 빌드를 진짜 origin 에 얹기) · tirno-origin-relay(서비스워커 없이 host-resolver 상주 + origin fallback 릴레이 — 지연 등록 SW·로그인 뒤 화면용).

갱신은 tirno update, 또는 claude plugin marketplace update tirno && claude plugin update tirno. 마켓플레이스를 먼저 당기지 않으면 옛 매니페스트를 보고 "최신" 이라고 답한다.

스킬 본문은 .claude/skills/ 가 정본이고 plugins/tirno/skills/ 는 실물 복사본이다. 심링크로 두면 GitHub 설치에서 깨진다 — 플러그인 하위트리만 캐시로 가므로 레포 루트로 올라가는 링크가 밖을 가리킨다. 사본이 낡지 않는 것은 링크여서가 아니라 test/plugin-skills.test.ts 가 둘이 다르면 깨뜨리기 때문이다.

어디부터 볼까

문서 무엇
docs/ONBOARDING.md 처음이라면 여기. 설치부터 첫 세션까지, 자주 걸리는 자리와 그 메시지
docs/COMMANDS.md 명령 reference · 소유권 · 앵커 · 데이터 위치 · 환경변수. 개수는 tirno schema | jq '.commands|length'
AGENTS.md 에이전트가 읽을 것 — 명령·경계·함정
CONTRIBUTING.md 개발 · 테스트 · CI
docs/research-sw-cdn-proxy.md 배포 전 빌드를 진짜 origin 위에 얹기 — 서비스워커 오버레이 설계
docs/JOURNAL.md · docs/RESEARCH.md 작업 일지 · 비교 도구 리서치

명령 표면의 정본은 tirno schema 다. commander 트리에서 실행 시점에 뽑으므로 문서보다 늦지 않고, 명령마다 effects 와 destructive 가 붙어 있어 실행 전에 무엇이 지워지는지 알 수 있다.

tirno schema | jq '.commands[] | select(.destructive) | .name'

핵심 개념

개념 설명
Multi-session tirno new <name> 으로 독립 Chrome. tmux 스타일
Stateless CLI 명령마다 connect/disconnect. daemon 없음 — ~/.tirno/sessions/<name>.json 에서 메타 복원
a11y @ref snapshot 이 붙인 번호. 세션마다·페이지마다 다시 찍는다
Visual cache URL 과 viewport 둘 다가 키다. bbox 는 viewport 종속이라 분리가 필수
다채널 fallback cache load 가 dom.selector → a11y → bbox 로, replay·trail replay 가 거기에 기록 좌표 를 더해 대상을 다시 찾는다
Emulation 영속 device/network/cpu/dpr 을 한 번 적용하면 다음 명령에도 유지된다
앵커 브라우저 MCP 가 붙을 대상을 포트가 아니라 디렉터리로 고정

기본 viewport 는 1920x1080 으로 고정된다 — 스크린샷 재현성과 캐시의 viewport 키 정합성 때문이다. 바꾸려면 tirno emulate --viewport <wxh>.

이름은 요정어로 지켜보는 자 (tir- — 보다·지키다). 개명 내력은 docs/JOURNAL.md.

아직 구현이 아닌 것 (drift)

목표는 여전하지만 지금 코드는 여기까지다.

하고 싶은 것 지금 근거
캐시에 selector 를 더 자주 담기 snapshot 은 id·data-testid·aria-label·name 이 있을 때만 dom.selector 를 적는다(안정적인 것만). 그 외 요소는 a11y(role·name)와 bbox 로 되찾는다 — HN 971개 중 dom 32 · a11y 770 · bbox 128 · 미해결 41(5px 스페이서 행) 실측. 짧은 CSS 경로 같은 덜 안정적인 selector 를 담을지는 미정 cache load 요약 줄

캐시 경로는 기록 좌표 를 뺀 세 채널로 되찾는다. 남은 차이는 selector 를 적는 범위(위 표)다.

장애·불편은 이슈로

막히거나 이상하면 바로 이슈를 올려라. 자잘한 불편, 헷갈린 출력, "이건 왜 이렇게 동작하지" 전부 환영이다 — 대부분의 개선이 그 자리에서 나온다.

포맷은 강제가 아니지만, 다음 네 토막이면 재현과 판정이 빠르다:

## 현상
무엇이 어떻게 어긋났나. 한두 줄.

## 재현
$ tirno ...
<실제 출력>
버전도 적는다 — `tirno --version` (예: 0.2.4).

## 원인 (짐작 가면)
어느 코드/동작이 원인 같은지. 모르면 비워도 된다.

## 제안 (있으면)
이렇게 되면 좋겠다. 없으면 "기록만 남긴다" 라고 적어도 된다.

추측과 실측을 나눠 적어라. "~로 확인했다" 와 "~로 보인다" 는 다르다 — 재현 로그가 붙은 이슈가 가장 빨리 닫힌다.

라이선스

ISC

About

Multi-session browser automation CLI on raw CDP — agent self-journaling

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages