문서

Guildlings 가 하는 일 전부를 한 장에.

설치 — Windows, macOS, 그리고 Linux 서버.
훅 켜기 — 체크하면 무엇이 쓰이는지, Codex 의 한 번 승인, 도로 빼기.
캐릭터가 말하는 것 — 걷기, 서 있기, 부르기, 회색.
다른 기기 곧 — 같은 계정의 기기 전부를 한 화면에.
사용량 대시보드 — 단축키, 카드, 숫자가 뜻하는 것.
도움받을 곳 — 환불, 문제 알리기.

설치

Windows

Windows 10(1809 이상) 또는 11, 64비트. 다운로드에서 설치 파일을 받아 실행하세요. 지금 Windows 사용자에게만 설치되므로 관리자 권한을 묻지 않습니다. Windows 빌드에는 코드서명이 아직 없어서 처음 실행할 때 파란 "Windows의 PC 보호" 화면이 뜹니다 — 추가 정보 → 실행을 누르세요. 그다음부터는 시계 옆 트레이에 삽니다 — Windows 11 에서 아이콘이 숨겨져 있으면 ^ 아래에 있습니다. 누르면 캐릭터가 나오고, 우클릭하면 메뉴와 설정…이 있습니다. 설정 창을 닫아도 계속 돕니다.

macOS

macOS 11 이상, Apple 실리콘과 Intel 이 한 파일입니다. .dmg 를 열어 Guildlings 를 응용 프로그램 폴더로 끌어다 놓고 거기서 여세요. Apple 의 공증을 받아 경고 없이 열립니다. 화면 위 메뉴 막대에 삽니다 — 누르면 캐릭터가 나오고, 우클릭하면 메뉴입니다.

둘 다 처음 켜면 설정 → 기기가 열리고, 거기서 지켜볼 도구를 고릅니다(다음 절). 컴퓨터에 로그인하면 Guildlings 도 함께 켜집니다 — 직접 켜고 싶으면 설정 → 일반의 버전 아래 체크를 끄세요. 업데이트는 몇 시간마다, 그리고 설정을 열 때마다 확인해 뒤에서 내려받아 두었다가 다음에 켤 때, 트레이에서 종료할 때, 또는 설정 → 일반의 설치를 누르면 바로 설치됩니다. 창이 따로 뜨지는 않고, 업데이트한 뒤에는 설정 → 일반에 …로 업데이트됐다가 한 번 표시됩니다.

Linux 서버 곧

화면이 없는 머신에서는 중계 노드가 돌면서 그 머신의 세션을 내 다른 기기로 보냅니다. x86-64 Linux, 루트 권한 없이:

curl -fsSL https://github.com/poorants/guildlings/releases/latest/download/install-node.sh | sh

~/.local/bin 에 guildlings-node 를 두고, 아무 브라우저에서나 낮달 계정으로 승인할 링크를 보여 준 뒤, systemd 사용자 서비스로 돌립니다. 다시 실행하면 업그레이드됩니다. 그다음 guildlings-node hooks on 으로 훅을 켜세요. 로그아웃한 뒤에도 계속 돌게 하려면 스크립트가 알려 주는 loginctl enable-linger 한 줄을 실행하면 됩니다.

훅 켜기

Guildlings 는 코딩 도구가 이미 쓰고 있는 파일에서 세션을 찾습니다. 훅은 파일로는 알 수 없는 것을 더합니다 — 세션이 내 허락을 기다리며 멈춘 순간, 지금 쓰는 도구, 방금 내린 지시. 훅이 없어도 캐릭터는 서고 걷지만, 나를 기다리는 세션이 그냥 쉬는 세션과 똑같아 보입니다 — 막힘 알림에는 훅이 필요합니다.

설정 → 기기를 여세요. 이 PC(Mac 에서는 이 Mac) 아래에 이 컴퓨터에서 찾은 코딩 도구마다 한 줄이 있습니다: Claude Code · Codex CLI · Antigravity(agy) · Cursor · Gemini CLI · Copilot CLI · Windsurf.
지켜볼 도구에 체크하세요. 체크하면 그 도구의 설정 파일에 Guildlings 의 줄이 더해지고, 나머지는 건드리지 않습니다. 저절로 체크되는 것은 없고, 나중에 설치한 도구도 체크 없이 나타납니다.
그 도구에서 세션을 하나 띄우세요. 훅이 한 번 들리면 줄에 붙음이 뜨고, 캐릭터가 작업표시줄(Mac 은 Dock 가장자리)로 걸어 나옵니다.

Claude Code: ~/.claude/settings.json 에 줄이 더해지고, 그 전에 파일 사본을 옆에 남깁니다. 세션의 비용과 한도를 읽으려고 상태줄 자리에도 서는데, 원래 쓰던 상태줄을 그대로 이어 보여 주므로 겉모습은 전과 같습니다.

Codex: ~/.codex/hooks.json 에 줄이 더해지고, Codex 는 새 훅을 한 번 승인해야 돌립니다. 그 전까지 줄에 Codex 에서 한 번 승인 필요라고 뜹니다. Codex 에서 /hooks 를 치고 Trust 를 고르세요 — 그 줄의 /hooks 복사 버튼이 명령을 클립보드에 넣어 줍니다.

줄에 설정이 바뀜이 뜨면 그 도구의 파일에서 Guildlings 의 줄 일부가 빠진 것입니다. 다시 넣기를 누르면 돌아옵니다. 훅을 빼려면 체크를 끄세요 — Guildlings 가 자기 줄만 빼고, Claude Code 에는 원래 상태줄을 돌려줍니다. Windows 에서는 제거할 때 훅을 전부 빼 줍니다. Mac 에서는 Guildlings 를 휴지통에 넣기 전에 체크를 먼저 끄세요. 그래야 사라진 앱을 부르는 도구가 남지 않습니다.

캐릭터가 말하는 것

살아 있는 세션 하나가 캐릭터 하나입니다. 몸이 곧 상태입니다:

걷는다, 가끔 무기를 휘두른다 — 일하는 중.
멈춰 서 있다 — 생각하는 중.
멈춰 서 있고 머리 위로 작은 zZ 가 떠오른다 — 할 일을 마치고 내 다음 말을 기다리는 중.
빨간 테두리, 사라지지 않는 말풍선 — 나를 기다린다. 쓰려는 도구를 밝히는 권한 확인이나 질문이고, 답할 때까지 부릅니다. 훅이 있어야 합니다.
회색으로 바랬다 — 관측 안 됨. 세션은 있는데 무엇을 하는지 아직 아는 것이 없습니다.
뒤따라 걷는 작은 캐릭터들 — 그 세션이 띄운 서브에이전트(동료)이고, 각자 상태를 가집니다. 다섯까지 따라오고 나머지는 "+n" 으로 셉니다.

말풍선은 캐릭터 자신의 대사이지 내가 쓴 글이 아닙니다. 캐릭터를 누르면 그 턴의 전부가 나옵니다 — 받은 지시, 지금 하는 일, 최근 여덟 가지와 각각 걸린 시간, 브랜치, 권한 모드, 모델과 토큰, 그리고 서브에이전트마다 탭 하나. Esc, 바깥 클릭, 또는 캐릭터를 다시 누르면 닫힙니다. 우클릭하면 캐릭터의 얼굴을 고릅니다. 끌어서 다른 모니터로 옮길 수 있고, 어느 모니터에 설지는 설정 → 일반에서 정합니다. 잠깐 전부 치워 두려면 Ctrl+Alt+H(Mac 은 Ctrl+Option+H)를 누르거나 트레이 메뉴의 캐릭터 체크를 끄세요. 한 번 더 하면 돌아옵니다.

다른 기기 곧

Guildlings 는 얼리 액세스 중이고 Plus 는 팔지 않습니다. 지금 버전은 이 기능과 Linux 서버의 중계 노드를 아직 Plus 에 묶어 두고 있습니다 — 다음 버전에서 누구에게나 열립니다.

컴퓨터마다 Guildlings 를, Linux 서버에는 중계 노드를 설치하세요.
각 기기의 설정 → 요금제에서 로그인을 누르고, 브라우저에서 같은 Google 또는 GitHub 계정으로 승인하세요. 그 컴퓨터는 계속 로그인된 채로 있고, 우리 쪽 비밀번호는 없습니다.
다른 기기가 설정 → 기기에 나타나고, 그 세션들이 기기 이름을 달고 이 컴퓨터의 세션 옆에 섭니다. 기기끼리 직접, 종단 간 암호화로 연결됩니다.

기기의 체크를 끄면 쉬게 됩니다 — 연결하지 않고, 이미 받아 온 사용량은 남습니다. 훅은 기기마다 따로 켭니다. 제거를 누르고 확인하면 그 기기가 계정에서 빠지고 즉시 끊깁니다 — 팔았거나 잃어버린 컴퓨터는 이렇게 하세요. 개인 사용엔 사실상 기기 수 제한이 없고, 한 계정에서 동시에 쓰는 기기는 20대까지입니다.

사용량 대시보드

에이전트가 쓴 양과 대략의 비용을 한 패널에. Ctrl+Alt+G(Mac 은 Ctrl+Option+G)를 누르거나 설정 → 대시보드의 지금 열기를 누르세요. 커서가 있는 모니터에 열리고, 단축키를 다시 누르거나 Esc, 바깥 클릭으로 닫힙니다.

두 단축키 — 대시보드의 Ctrl+Alt+G 와 캐릭터의 Ctrl+Alt+H — 는 처음부터 켜져 있습니다. 설정 → 대시보드 맨 위의 단축키에서 바꾸거나 지울 수 있습니다. 다른 앱이 이미 쓰는 키면 그 줄에 그렇게 나오니, 다른 키를 고르세요.

기간: 오늘, 이번 주, 이번 달.
기기마다 카드 하나, 이 컴퓨터 포함, 합계는 맨 끝. 이어진 다른 기기가 없으면 이 컴퓨터의 카드 하나입니다. 응답하지 않는 기기도 카드가 남고, 숫자가 언제 것인지 표시됩니다.
카드마다: 비용, 입력 · 출력 · 캐시를 나눠 센 토큰, 캐시 적중률, 모델, 도구, 턴, 그리고 5시간 창 — 남은 시간과 쓰는 속도.
달러는 정가 기준 추정치입니다(~$). 값을 모르는 모델은 비용에서 빠지고 ·? 로 표시됩니다. Cursor 는 토큰 수를 남기지 않아서 그 세션은 ·? 로 나옵니다.

기록은 내 컴퓨터의 파일이고 설치한 날부터 쌓입니다. 무료이고 계속 보관되므로, 코딩 도구가 자기 기록을 지운 뒤에도 지난달이 그대로 있습니다.

도움받을 곳

환불: 결제일부터 14일 안에 설정 → 요금제 → 환불 요청. 환불 정책을 참고하세요.
그 밖의 것: 설정 → 일반의 지원에 문의를 누르면 시스템과 앱 버전이 적힌 메일이 guildlings@natdal.app 앞으로 열립니다. 앱이 열리지 않으면 직접 메일을 주세요 — Windows 인지 macOS 인지와 그 버전, Guildlings 버전, 그리고 일이 생기기 직전에 무엇을 했는지 적어 주시면 됩니다. 스크린샷이 있으면 큰 도움이 됩니다.
버그는 GitHub 이슈에 남겨도 됩니다.